Skip to content

Core Contract and Design

Go is the reference implementation. spec/ is the normative contract; Core implementations provide idiomatic APIs without changing its wire names or declared behavior. A disagreement between the reference and the spec is a bug, not a license to silently fork the contract.

Contract Layers

Layer Requirement
Wire Preserve field names, casing, event kinds, error codes, and envelopes
Behavior Pass the shared vectors for the declared implementation scope
API Map declared interfaces and options to idiomatic language constructs
Conformance Run vectors, parity, API checks, and language-specific tests

Preserve mixed wire casing such as image_url, runId, and plugin_id. See the event reference, shared wire artifacts, and per-language parity inventories. Do not normalize wire names for local style.

Behavior Coverage

Contract layers are not a claim that every Core implements every agent scenario. Behavior coverage has three tiers: agent-capable (Go, Python, TypeScript, Java, Rust, R, C#) targets all twenty Behavior Lab scenarios; extended (PHP, C, Fortran, COBOL, Ruby, Elixir, Erlang, C++, Lua) advances with a named consumer and maintainer; optional covers other implementations. Contract conformance does not imply behavior parity, and suite-level tests do not imply scenario-level evidence.

Language Layout

Do not copy the Go pkg/ tree into every language. Use the layout that is idiomatic for the language and package manager, while keeping the contract boundaries visible.

A Core implementation should provide:

  • a source tree with clear core modules and no product-only code;
  • README.md, LICENSE, and installation/build instructions;
  • api/ snapshots or equivalent API checks;
  • a conformance runner over spec/vectors;
  • language tests, including negative and security-sensitive paths;
  • an optional examples/ directory for language-specific runnable examples;
  • an optional adapters/ directory when the language has provider adapters.

Language examples under language/<language>/examples/ are copied into that language's discovery mirror. Cross-language and Go reference examples stay under the repository root examples/ directory.

Map contract areas to local modules and record the mapping in the parity inventory. Similar names are helpful, but physical pkg/... parity is not a requirement and must not force non-idiomatic code.

Adapters

Adapters are optional. A Core must not import its adapters, and adapters must not become required for conformance.

  • Place language-local adapters under language/<language>/adapters/<provider> or in a separately versioned module when their dependencies are heavy.
  • Keep provider SDKs, credentials, endpoints, and tenant policy out of Core.
  • Test adapter behavior separately from the Core vectors. A passing Core conformance run does not verify a live provider.
  • Do not mirror the Go root adapters/ tree or implement every Go adapter in every language. Add an adapter only with a consumer, a maintenance owner, license review, and tests.
  • A source tag for an adapter does not imply package-registry publication or live-provider verification.

Change Workflow

  1. Review the reference behavior and normative artifacts.
  2. Update wire definitions and vectors when changing the contract.
  3. Update the applicable parity inventory.
  4. Verify the reference implementation against the vectors.
  5. Implement the Core change and run its conformance and API checks.
  6. Document supported scope, version compatibility, and limitations.

Do not widen the Go pkg/... API merely to support a Core implementation. Concrete integrations are optional and do not imply cross-language availability.

Versions and Compatibility

spec/SPEC_VERSION versions the shared contract independently of Core releases. A wire field, event, stream kind, plugin envelope, or error-code change must update the specification and be evaluated as breaking for every affected Core. See compatibility policy and API stability.

The shared contract is not a promise that all Core implementations expose every reference feature. Consult the support policy and Core-specific API.

Security and Licensing

Core implementations remain MIT; dependencies require compatible licenses. Credentials and tenant data stay in caller configuration. Product-owned trust roots, deployment, and plugin materialization do not belong in framework implementations. Re-test security-sensitive behavior in each language.

See language implementation policy for implementation types and contribution gates.