Bridges

Chio mediates several upstream protocols through bridge and edge crates. Each surface routes invocations through the kernel guard pipeline, produces a signed receipt, and reports a fidelity rating so clients can tell whether the projection is lossless, adapted, or unsupported.

Source

This page normatively reflects spec/BRIDGES.md in the chio repository. Status: Normative companion to PROTOCOL.md. Version 3.0.

Bridge Model

Two integration shapes appear in the spec:

• Bridges map an upstream protocol surface inward to MCP-style Chio tools. The OpenAPI-to-MCP bridge takes an OpenAPI spec and exposes each operation as an MCP tool.
• Edges project Chio kernel-governed tools outward to a different protocol. The A2A and ACP edges serve Chio tools to A2A and ACP clients respectively. The OpenAI adapter wraps OpenAI-style function calls.

In every case the kernel evaluates the invocation, signs the receipt, and emits the result through the originating surface.

Fidelity Levels

All edges classify each tool projection at registration time using a three-level rating. The rating is reported to clients in discovery metadata so they can decide whether the surface is sufficient for their needs.

Per-Protocol Fidelity Matrix

The matrix below summarizes how each surface handles common Chio feature requirements. Cells reflect the rules in the per-protocol sections that follow.

OpenAPI-to-MCP Bridge

Crate: chio-openapi-mcp-bridge. The bridge presents a Chio-governed HTTP API as an MCP tool surface. Given an OpenAPI 3.x specification, it produces a manifest, exposes each operation as an MCP tool, and routes invocations through the kernel before dispatching to the upstream HTTP API.

Scope

• Parses the spec via chio-openapi to produce ToolDefinition values.
• Wraps each HTTP operation as an MCP-visible tool via chio-mcp-edge.
• Routes invocations through the kernel for capability validation and receipt signing before dispatch.

tools/list Generation

Each (method, path) pair becomes one entry in the MCP tools/list response.

The bridge MUST set has_side_effects to false for GET, HEAD, and OPTIONS operations and true for all other HTTP methods. When x-chio-* extensions are present, they propagate to the corresponding ToolDefinition fields per the rules on the OpenAPI Integration page.

Invocation Flow

The bridge MUST resolve the route binding from the tool name before dispatching. If the tool name does not match any known route binding, the bridge MUST return a ToolNotFound error without contacting the upstream API.

The structuredContent field in the MCP response MUST include:

• httpStatus: HTTP status from the upstream response
• method: HTTP method used
• path: URL path template
• body: parsed response body

Receipt Generation

Every bridged invocation that reaches the upstream HTTP API MUST produce a signed Chio receipt. The receipt MUST include:

• tool_name: the MCP tool name (derived from operationId)
• server_id: the bridge's configured server ID
• decision: allow for successful invocations; deny if the guard pipeline rejects

Kernel Integration

The bridge implements ToolServerConnection, allowing direct registration with a kernel instance. Two variants exist:

• BridgeToolServer<'a>: borrows the bridge for scoped registration.
• OwnedBridgeToolServer: consumes the bridge for long-lived registration.

Both delegate invoke() to the bridge's internal dispatch logic, mapping BridgeError to KernelError::ToolServerError. See the bridge OpenAPI to MCP guide and the OpenAPI sidecar example.

A2A Edge

Crate: chio-a2a-edge. The A2A edge exposes Chio kernel-governed tools as A2A skills. This is the reverse of chio-a2a-adapter: instead of consuming a remote A2A server, this crate serves Chio tools to external A2A clients. Every invocation flows through the kernel guard pipeline, producing a signed receipt.

Agent Card Generation

The edge MUST serve an Agent Card at /.well-known/agent-card.json. The card is generated from the edge configuration and registered tool manifests.

Each interface entry MUST include:

• url: A2A endpoint URL
• protocolBinding: protocol binding (default "JSONRPC")
• protocolVersion: "1.0"

Skill Projection

Each Chio ToolDefinition from registered manifests becomes one A2A skill entry.

SendMessage and SendStreamingMessage

message/send is a blocking request. The edge resolves the target skill from params.metadata.chio.targetSkillId. If only one skill is registered, the edge MAY infer the target. With multiple skills and no target, the edge MUST return JSON-RPC error code -32602.

The task response MUST include:

• id: monotonically increasing identifier (format a2a-task-{n})
• status: completed on success; failed on tool server error
• message: present when status is completed; carries the converted tool result
• statusMessage: present when status is failed; carries the error description

message/stream is exposed as a deferred receipt-bearing task lifecycle rather than a push-stream transport. It MUST resolve the target skill using the same rules, create a working TaskResponse with signed-authority metadata and receiptPending = true, persist the deferred execution request under the returned task ID, and require follow-up task/get or task/cancel calls to resolve or cancel the task. task/get MUST execute the deferred request through the authoritative path the first time it is called for a working task. Terminal task results MUST carry the same signed receipt metadata as message/send.

Result Conversion

A2A BridgeFidelity Evaluation

The bridgeFidelity field is included in each skill entry. Clients SHOULD use this field to assess whether the A2A interface is sufficient. unsupported skills are withheld from the Agent Card entirely. The implementation reads these semantic hints when present on the tool schema:

• x-chio-publish
• x-chio-approval-required
• x-chio-streaming
• x-chio-cancellation
• x-chio-partial-output

See the A2A adapter integration page and the hello-a2a example.

Kernel-Mediated Receipts

Every SendMessage invocation that reaches the tool server MUST flow through the kernel guard pipeline. The signed receipt includes:

• tool_name: matches the A2A skill ID
• server_id: from the manifest that owns the tool
• decision: allow for completed tasks; deny for guard rejections

When the tool server returns an error, the task status is failed but a receipt is still generated with the deny or incomplete decision as appropriate.

ACP Edge

Crate: chio-acp-edge. The edge exposes Chio kernel-governed tools as ACP (Agent Client Protocol) capabilities so ACP-compatible editors and IDEs can reach Chio tools through the ACP permission model.

ACP organizes tools around four categories: filesystem, terminal, browser, and generic tool. The edge maps Chio tools into this model with category inference and fidelity assessment.

Capability Mapping

Category Inference and Routing

The edge infers the ACP category from the tool name using keyword matching, applied in order:

When no pattern matches, the edge MUST fall back to AcpEdgeConfig.default_category, which defaults to tool.

Permission Evaluation

The edge implements fail-closed permission evaluation backed by Chio capabilities. It handles session/request_permission requests by:

1. Looking up the capability by ID. If unknown, the edge MUST return deny.
2. If requiresPermission is true, the edge MUST return deny by default. Explicit permission grants require kernel capability token validation (full integration deferred to Phase 324).
3. If requiresPermission is false, the edge MUST return allow.

ACP BridgeFidelity Assessment

unsupported capabilities are withheld from session/list_capabilities.

JSON-RPC Interface

Unknown methods MUST return JSON-RPC error code -32601.

See the wrap an ACP server guide and the hello-acp example.

OpenAI Adapter

Crate: chio-openai. The adapter intercepts OpenAI-style tool_use / function-calling requests and routes them through the Chio kernel for capability validation and receipt signing. It supports both the Chat Completions API format and the Responses API format. Every function call produces a signed receipt; guards fail closed by default.

Function Definition Generation

Chat Completions tool envelope:

[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  }
]

Receipt Behavior

Every function call MUST produce a signed receipt. The receipt MUST include tool_name, server_id, the kernel-issued receipt_ref, and the signed ChioReceipt object when the call reached the kernel.

Batch Execution

execute_tool_calls() processes calls sequentially in input order. A failure in one call MUST NOT prevent execution of subsequent calls. The caller receives the full results array and inspects each entry's denied field individually. Each call that reaches the kernel returns the kernel-issued receipt.id as its receipt_ref.

Cross-Cutting Requirements

Fail-Closed Invariant

All bridges and edges MUST maintain the fail-closed invariant:

• If the kernel is unreachable, requests MUST be denied.
• If a capability token is invalid or expired, requests MUST be denied.
• If guard evaluation produces an error, the request MUST be denied.
• Unknown tools, capabilities, or functions MUST be rejected before any upstream dispatch occurs.
• Unknown JSON-RPC methods MUST return error code -32601.

Receipt Chain Continuity

Signed receipts from bridged invocations MUST be compatible with the core receipt contract defined in protocol section 6:

• Receipts use the same chio.receipt.v1 schema.
• Receipts join the same Merkle-committed receipt log.
• Bridged receipts are indistinguishable from native Chio receipts to downstream consumers (trust-control, evidence export, federation).

Auditors and operators see one unified evidence trail regardless of the protocol surface that originated the invocation.

Related

• OpenAPI integration: extension vocabulary and the chio api protect contract.
• Protocol: core capability, receipt, and manifest contract.
• Wire protocol: native framed transport.
• Wrap an MCP server.
• Wrap an ACP server.
• A2A adapter.
• hello-a2a and hello-acp examples.