# Generated protocol artifacts > Harn publishes downstream protocol artifacts under spec/protocol-artifacts/ . The directory is generated by: Website: https://harnlang.com/protocol-artifacts.html This page documents Harn, which is pre-1.0. Language, standard library, and CLI APIs may change. If the intended version is unclear, clarify before using this page. --- Harn publishes downstream protocol artifacts under `spec/protocol-artifacts/`. The directory is generated by: ```sh make gen-protocol-artifacts ``` CI and `make all` verify drift with: ```sh make check-protocol-artifacts ``` The generated contract includes: - `manifest.json`: protocol versions, schema provenance, ACP method names, `sessionUpdate` discriminators, Harn extension fields, tool lifecycle metadata fields, A2A task states, MCP metadata vocabulary, and a `bindings` block enumerating the published TypeScript, Swift, Python, and Go modules with their stability tier and (for Go) the canonical module path. - `schemas/*.schema.json`: stable copies of the ACP, A2A, MCP, tool-receipt, collaborative plan-document, and `harn-tools/2.0` contracts covered by generated drift and protocol checks. The Harn tools artifact validates the catalog envelope; Harn's Rust parser validates embedded Draft 2020-12 schemas, reference closure, and cross-entry invariants. MCP publishes only the stable `2026-07-28` profile. - `harn-tools.ts`: strict TypeScript types for the transport-neutral tool catalog. The generator derives this file and `schemas/harn-tools-v2.schema.json` from the same Rust contract types. - `harn-protocol.ts`: TypeScript bindings for JSON-RPC messages, ACP `session/update`, collaborative plan documents, Harn tool lifecycle metadata, A2A task events, and MCP tool/resource/prompt metadata. - `HarnProtocol.swift`: Swift `Codable` definitions for the same host-facing surface. - `python/harn_protocol.py`: stdlib-only Python 3.9+ module with `Enum` classes for every wire vocabulary, dataclasses for the JSON-RPC envelopes, ACP session updates, Harn tool lifecycle metadata, A2A task structures, and MCP tool/resource metadata, plus `to_wire`/`from_wire` helpers that strip unset optional fields so envelopes stay byte-equivalent to the Rust adapter output. Field names match the wire JSON (camelCase). - `go/harnprotocol/`: Go module (`harnprotocol` package) mirroring the same surface with typed string aliases and `encoding/json`-tagged structs. The `go.mod` declares `github.com/burin-labs/harn/spec/protocol-artifacts/go/harnprotocol` as the canonical module path so consumers can `go get` directly from the repository. - `fixtures/round_trip.json`: representative request/response/notification envelopes, including a collaborative plan update, plus an A2A task and an MCP tool entry. `make check-bindings` decodes and re-encodes these through the Python and Go bindings on every CI run, catching wire-vocabulary drift before downstream consumers see it. MCP helpers include the stable `2026-07-28` identity, required request `_meta` keys, standard Streamable HTTP headers (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`), `server/discover`, `ttlMs`/`cacheScope` cache hints, `input_required` results, the stable tasks extension, the `-32022` unsupported-version error, and the JSON Schema 2020-12 dialect URL. Harn's runtime and generated bindings share this registry. The generated `MCPDiscoverResult` follows the released SDK shape: `ttlMs` and `cacheScope` are required, and server identity lives at `_meta["io.modelcontextprotocol/serverInfo"]`, not in a top-level `serverInfo` field. Harn's HTTP servers enforce those routing headers as well as authoring them. Missing or mismatched required headers, malformed stable request metadata, and missing required capabilities retain their JSON-RPC error body and use HTTP `400 Bad Request`. ## Stability The host-facing surface listed above is **stable**: existing wire values and field names will not change without a Harn minor-version migration note plus a regenerated artifact diff. Hosts can pin to the artifact directory for the full surface or to the `manifest.json` `bindings` block when they only need to detect generator/runtime mismatch. This release publishes `harn-tools/2.0` as the first pre-launch contract that includes declared application errors. Its discriminator versions the tool catalog independently of the Harn crate. Version 1 catalogs are intentionally rejected; producers must regenerate the catalog and language bindings together. After version 2 ships, additive optional fields keep the discriminator. Removing a field, changing a field type, or tightening an owned closed record requires a new catalog discriminator and a migration note. JSON Schema documents, `source.binding`, and namespaced `_meta` values remain intentional open extension points. VM internals (the AST, code-index, scanner schemas under `crates/harn-hostlib/schemas/**` aside from the published wire profiles) are **not** part of this surface. They evolve with the runtime and should be consumed via the Rust crates rather than vendored as bindings. ## Versioning Artifacts follow the Harn crate version in `manifest.json`. Additive changes are minor-version compatible: - new `sessionUpdate` or `_harn/agentEvent` values; - new optional fields under `_meta.harn`; - new `ToolKind`, `ToolCallStatus`, `ToolCallErrorCategory`, A2A task state, or MCP metadata values that clients can ignore safely. Breaking changes require a Harn minor-version migration note: - removing or renaming a wire value; - moving a field between canonical ACP locations and `_meta.harn`; - changing a required field's type; - tightening a schema so previously valid Harn adapter output is rejected. ## Consumer migration Hosts should consume the generated bindings or schema artifacts instead of mirroring Harn protocol enums by hand. Burin consumers can replace local `ACPSessionUpdate`, `ACPToolKind`, and `ACPToolCallStatus` mirrors with `spec/protocol-artifacts/harn-protocol.ts`, and can use `spec/protocol-artifacts/HarnProtocol.swift` as the Swift contract source for ACP session updates and tool-call metadata. Python and Go integrators can import `spec/protocol-artifacts/python/harn_protocol.py` (e.g. by vendoring the file or pinning the artifact directory) and the `harnprotocol` Go module under `spec/protocol-artifacts/go/harnprotocol` respectively. TypeScript clients that consume a catalog should import `ToolCatalog` from `harn-tools.ts`. Other language generators should consume `schemas/harn-tools-v2.schema.json`; they should not infer catalog types from MCP `tools/list` or an OpenAPI source document. See [Tool registry adapters](./tool-registry-adapters.md) for the runtime and static catalog surfaces. The generated schema is a structural gate, not a substitute for Harn's semantic catalog parser. Cross-repo release jobs can run: ```sh DOWNSTREAM_HOST_ROOT=/path/to/host-checkout make check-downstream-protocol-artifacts ``` to fail when a downstream host's vendored Swift or TypeScript protocol bindings drift from the Harn source artifacts. For ACP, clients should still follow the wire namespacing rules in [Bridge protocol](./bridge-protocol.md): canonical ACP fields remain at the session-update root, while Harn vendor fields live under `_meta.harn`. --- ## Read next - [Bridge protocol](https://harnlang.com/bridge-protocol.md) - [Host tools over the bridge](https://harnlang.com/bridge/host-tools.md)