{"id":47962986,"url":"https://github.com/effectorhq/effector-spec","last_synced_at":"2026-04-04T10:03:39.825Z","repository":{"id":344478498,"uuid":"1177022704","full_name":"effectorHQ/effector-spec","owner":"effectorHQ","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-14T22:15:52.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T07:45:59.017Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/effectorHQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T16:05:11.000Z","updated_at":"2026-03-14T22:15:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/effectorHQ/effector-spec","commit_stats":null,"previous_names":["effectorhq/effector-spec"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/effectorHQ/effector-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/effectorHQ","download_url":"https://codeload.github.com/effectorHQ/effector-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31395450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T09:13:02.600Z","status":"ssl_error","status_checked_at":"2026-04-04T09:13:01.683Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T10:03:39.082Z","updated_at":"2026-04-04T10:03:39.810Z","avatar_url":"https://github.com/effectorHQ.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# effector-spec\n\n[![Status: Draft](https://img.shields.io/badge/status-draft-orange.svg)](spec/00-overview.md)\n[![Version: 0.2.0](https://img.shields.io/badge/version-0.2.0-blue.svg)](CHANGELOG.md)\n[![License: CC-BY-4.0](https://img.shields.io/badge/license-CC--BY--4.0-green.svg)](LICENSE.md)\n[![RFC: 0001](https://img.shields.io/badge/RFC-0001-E03E3E.svg)](https://github.com/effectorHQ/rfcs/blob/main/text/0001-effector-spec.md)\n\n**The first type system for AI agent capabilities.**\n\n---\n\n\u003e An **Effector** is any unit of capability that enables an AI agent to act on the world.\n\u003e The **Effector Spec** defines how those capabilities declare typed interfaces, compose safely, and form a discoverable capability graph.\n\n## The Problem\n\nAI agent capabilities in 2026 are where JavaScript modules were in 2012 — fragmented, untyped, and impossible to compose safely.\n\nYou have MCP tools (JSON-RPC functions), SKILL.md files (YAML + markdown instructions), LangChain `@tool` decorators, CrewAI BaseTool classes, Semantic Kernel plugins, OpenAI Function Calling schemas, AGENTS.md project guidance. Every framework defines capabilities differently. None of them compose.\n\nThe consequences are measurable:\n\n- **67% of multi-agent system failures** stem from inter-agent interaction errors, not individual agent bugs ([Multi-Agent Collaboration Mechanisms Survey, arXiv:2501.06322](https://arxiv.org/abs/2501.06322))\n- **3–15% tool calling failure rate** in production due to type mismatches and malformed interfaces ([n8n community reports](https://community.n8n.io/t/i-get-error-received-tool-input-did-not-match-expected-schema-before-the-agent-attempts-to-use-any-tools/179933))\n- **36% of ClawHub skills** contained prompt injection or malicious payloads before the February 2026 cleanup ([Snyk ToxicSkills Report](https://snyk.io/blog/toxicskills/))\n- **Token consumption doubles** when loading multiple MCP servers, with no dependency awareness or intelligent composition ([MCP Limitations Analysis](https://superface.ai/blog/mcp-today-protocol-limitations))\n\nThe root cause is simple: **there is no type system for AI agent capabilities.** You chain two skills and hope the output of one matches the input of the other. You combine three MCP tools and discover at runtime they conflict. You install a community skill and trust it blindly because there's no way to verify its interface contract.\n\n## What This Spec Defines\n\nThe Effector Spec is not a manifest format (that was v0.1 — we've moved beyond it). It's a **type system and composition algebra for AI agent capabilities**, consisting of three primitives:\n\n### Primitive 1: Capability Type Language\n\nA formal type language for describing what an Effector accepts, produces, and requires:\n\n```\neffector \"code-review\" {\n  type: Skill\n\n  interface {\n    input:   CodeDiff\n    output:  ReviewReport\n    context: [Repository, CodingStandards]\n  }\n}\n```\n\nCore concepts:\n- **Input types** — what the capability receives (CodeDiff, TextDocument, ImageSet, DataTable...)\n- **Output types** — what the capability produces (ReviewReport, Summary, TranslatedText, PatchSet...)\n- **Context types** — what environment the capability needs (Repository, UserPreferences, APICredentials...)\n- **Structural subtyping** — if Effector A's output is a structural supertype of Effector B's input, they compose automatically. Like TypeScript, not like Java.\n\n### Primitive 2: Composition Algebra\n\nFormal rules for combining capabilities:\n\n```\n# Sequential: A's output type must be compatible with B's input type\ncode-change → code-review → merge-decision\n\n# Parallel: Independent execution, results merge into tuple type\n(security-scan ‖ type-check ‖ lint) → aggregate-report\n\n# Conditional: Branch on output type\ncode-review → quality-high ? auto-merge : human-review\n\n# Fallback: Type-compatible substitute on failure\nprimary-review | fallback-review\n```\n\nThe composition graph is **type-checked before execution.** If two Effectors don't compose (output type incompatible with input type), the system rejects the pipeline at definition time — not at runtime, not after burning tokens and API calls.\n\n### Primitive 3: Typed Discovery Protocol\n\nSearch capabilities by interface type, not keywords:\n\n```\n# \"Find any Effector that takes a CodeDiff and produces any kind of Report\"\ndiscover(input: CodeDiff, output: *Report)\n\n# \"Find substitutes for this skill\"\nsubstitutes(effector: \"code-review@1.2.0\")\n\n# \"What can I compose after a security-scan?\"\nchains-after(effector: \"security-scan@2.0.0\")\n```\n\nStructural subtype matching returns all compatible Effectors, ranked by precision. This enables a capability graph where N typed Effectors produce O(N²) or more valid compositions — the combinatorial surface grows with every new Effector published.\n\n## Why This Is a Paradigm, Not a Feature\n\nParadigm shifts change how things compose:\n\n| Paradigm | What changed | Composability before | Composability after |\n|----------|-------------|---------------------|-------------------|\n| Unix pipes | Program I/O | Monolithic binaries | `stdout → stdin`, infinite chaining |\n| URL + HTTP | Document access | Protocol-specific clients | Universal addressing, hyperlinks create the web |\n| npm + package.json | Code modules | Script tags, global variables | Dependency resolution, semantic versioning |\n| TypeScript | JavaScript types | Runtime errors, manual checking | Compile-time verification, IDE intelligence |\n| Docker + OCI | Software distribution | \"Works on my machine\" | Portable, composable containers |\n| **Effector Spec** | **AI capabilities** | **Untyped, framework-locked, pray-and-chain** | **Typed interfaces, verified composition, cross-runtime portability** |\n\nThe Effector Spec sits in the same position TypeScript occupied in 2012 relative to JavaScript:\n\n- It **doesn't replace** existing formats (SKILL.md, MCP tools, LangChain tools still work)\n- It **adds a type layer** that enables safe composition, intelligent discovery, and verified pipelines\n- It **works across runtimes** (not locked to OpenClaw, MCP, or any single framework)\n- It **grows through community annotation** (like DefinitelyTyped gave types to existing npm packages)\n\n## Spec Documents\n\n| Document | Contents |\n|----------|----------|\n| [00 — Overview](spec/00-overview.md) | What an Effector is, the type system paradigm, scope, terminology |\n| [01 — Type Language](spec/01-type-language.md) | Capability types, structural subtyping, type inference rules |\n| [02 — Composition Algebra](spec/02-composition.md) | Sequential, parallel, conditional, fallback — formal composition rules |\n| [03 — Discovery Protocol](spec/03-discovery.md) | Typed search, substitutability queries, capability graph construction |\n| [04 — Manifest Format](spec/04-manifest.md) | The `effector.toml` manifest — type annotations, runtime bindings, metadata |\n| [05 — Type Taxonomy](spec/05-types.md) | Canonical Effector types: skill, extension, workflow, workspace, bridge, prompt |\n| [06 — Runtime Binding](spec/06-runtime-binding.md) | How runtimes consume typed Effectors (OpenClaw, MCP, Claude Agent SDK, generic) |\n| [07 — Security Model](spec/07-security.md) | Permission types, trust levels, sandbox constraints, signing |\n| [08 — Lifecycle](spec/08-lifecycle.md) | Create → Type → Validate → Package → Publish → Discover → Compose → Execute |\n\n## Schemas \u0026 Tooling\n\n- [`schemas/effector.schema.json`](schemas/effector.schema.json) — JSON Schema for `effector.toml` manifest validation\n- [`schemas/types/`](schemas/types/) — Machine-readable definitions of standard capability types\n- [`schemas/examples/`](schemas/examples/) — Example typed manifests for every Effector type\n\n**Companion projects:**\n\n| Project | What it does |\n|---------|-------------|\n| [`effector-types`](https://github.com/effectorHQ/effector-types) | Standard library of capability types — the `lib.d.ts` for Effectors |\n| [`effector-compose`](https://github.com/effectorHQ/effector-compose) | Composition engine — build and type-check Effector pipelines |\n| [`effector-audit`](https://github.com/effectorHQ/effector-audit) | Security audit + cryptographic signing for Effector packages |\n| [`effector-graph`](https://github.com/effectorHQ/effector-graph) | Interactive visualization of the capability graph |\n\n## Research Foundation\n\nThis spec is grounded in active research across multiple domains:\n\n**Capability-based computing** — The concept of unforgeable capability tokens originates with Dennis \u0026 Van Horn (1966) and runs through Capsicum, WASI, and the WASM Component Model's WIT interface system. We extend capability-based reasoning from code modules to AI agent capabilities.\n\n**Agent composition research** — The GAP framework (NeurIPS 2025, [arXiv:2510.25320](https://arxiv.org/abs/2510.25320)) demonstrated that graph-based planning with explicit dependency modeling outperforms sequential tool execution. Our composition algebra formalizes this insight. DALIA ([arXiv:2601.17435](https://arxiv.org/abs/2601.17435)) proposed formal semantic models for capabilities — we provide the concrete type system.\n\n**Cost-aware agent execution** — Google's BATS framework ([arXiv:2511.17006](https://arxiv.org/abs/2511.17006)) proved that agents without budget awareness waste resources. Our resource typing (cost-estimate, token-budget) makes cost a first-class citizen in capability declarations.\n\n**Tool discovery at scale** — The Tool-to-Agent Retrieval framework ([arXiv:2511.01854](https://arxiv.org/abs/2511.01854)) showed that embedding tools and agents in a shared vector space enables semantic discovery. Our typed discovery protocol provides the formal interface for this, moving beyond keyword search to structural type matching.\n\n**Security** — The Snyk ToxicSkills audit (February 2026) and the ClawHavoc campaign revealed systemic trust failures in capability registries. Our security model (07-security.md) defines permission types, trust levels, and signing requirements as part of the type system — not as an afterthought.\n\n## Design Principles\n\n1. **Types over conventions** — Formal interfaces replace hope-and-pray composition\n2. **Structural, not nominal** — Compatibility is determined by shape, not by name or inheritance\n3. **Additive, not replacing** — Works with existing SKILL.md, MCP tools, LangChain tools — adds types on top\n4. **Progressive disclosure** — A simple Effector needs 5 lines. A fully-typed one can express complex interface contracts.\n5. **Runtime-agnostic** — The type system is independent of any specific runtime or framework\n6. **Community-extensible** — Domain-specific types are defined by communities, not by us\n\n## Quick Start\n\nA minimal typed Effector manifest (`effector.toml`):\n\n```toml\n[effector]\nname = \"github-pr-review\"\nversion = \"1.2.0\"\ntype = \"skill\"\ndescription = \"Automated pull request review with code analysis\"\n\n[effector.interface]\ninput = \"CodeDiff\"\noutput = \"ReviewReport\"\ncontext = [\"Repository\", \"CodingStandards\"]\n\n[effector.compose]\nchains-after = [\"code-change\", \"pull-request\"]\nchains-before = [\"merge-decision\", \"notify-team\"]\nparallel-with = [\"security-scan\", \"type-check\"]\n\n[effector.resources]\nrequires = [\"github-api\", \"llm-inference\"]\npermissions = [\"read:repository\", \"write:comments\"]\ncost-estimate = \"~0.02 USD\"\n\n[runtime.openclaw]\nformat = \"skill.md\"\nentry = \"SKILL.md\"\n```\n\n## Versioning\n\nThis spec follows [Semantic Versioning](https://semver.org/).\n\n- **0.1.x** — Manifest-only format (deprecated, superseded by v0.2)\n- **0.2.x** — Type system + composition algebra (current draft)\n- **1.0.0** — Stable. Backward compatibility guaranteed.\n\n## Contributing\n\nThis is a living specification. Changes go through the [RFC process](https://github.com/effectorHQ/rfcs).\n\n- For clarifications and typo fixes: open a PR directly\n- For substantive changes: submit an RFC first\n- For questions: open an issue or start a [Discussion](https://github.com/orgs/effectorHQ/discussions)\n\n## License\n\nThis project is currently licensed under the [Apache License, Version 2.0](LICENSE.md) 。\n\n[CC-BY-4.0](./LICENSE.md)\n\n---\n\n\u003csub\u003ePart of the \u003ca href=\"https://github.com/effectorHQ\"\u003eeffectorHQ\u003c/a\u003e studio. We build hands for AI that moves first.\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feffectorhq%2Feffector-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feffectorhq%2Feffector-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feffectorhq%2Feffector-spec/lists"}