Bridges

Source

This page normatively reflects spec/BRIDGES.md in the chio repository. Status: Normative companion to PROTOCOL.md for the current v1 profile. Version 1.0, dated 2026-04-14. The keywords MUST, SHOULD, and MAY are normative.

Behavior is read from the crates under crates/protocol: chio-openapi-mcp-bridge, chio-a2a-edge, chio-acp-edge, and chio-openai-adapter, with the shared hint reader in chio-cross-protocol/src/semantic_hints.rs and the OpenAPI extension parser in chio-openapi/src/extensions.rs. Where the specification and a crate differ, the page describes the crate and names the file.

Synopsis

Each integration is one crate with one entry point; the A2A and ACP edges rate every tool they publish with a BridgeFidelity value of this shape.

#[serde(rename_all = "snake_case", tag = "kind")]
pub enum BridgeFidelity {
    Lossless,
    Adapted { caveats: Vec<String> },
    Unsupported { reason: String },
}

Bridge model

Every bridge and edge holds one invariant: each mediated action flows through the Chio kernel guard pipeline and produces a signed receipt, whatever the upstream or downstream protocol. Two integration shapes carry that invariant:

• Bridges map an upstream protocol to MCP-style Chio tools. The OpenAPI-to-MCP bridge takes an OpenAPI specification and exposes each operation as an MCP tool.
• Edges expose Chio kernel-governed tools through a different protocol. The A2A and ACP edges serve Chio tools to A2A and ACP clients respectively.

The OpenAI adapter is neither: it mediates the function calls a caller executes on behalf of a model instead of publishing a catalog, so it has its own section.

Fidelity levels

Each edge classifies every tool projection at registration time with one BridgeFidelity value and reports it to clients in discovery metadata as bridgeFidelity.

BridgeFidelity::published_by_default is false only for unsupported; both edges skip such a tool when they build their published list.

Semantic hints

Both edges call semantic_hints_for_tool in chio-cross-protocol, which reads these boolean x-chio-* keys from the tool's input_schema and, when a key is absent there, from its output_schema.

The OpenAPI parser reads a different set from each operation object. ChioExtensions::from_operation in chio-openapi/src/extensions.rs accepts x-chio-sensitivity (public, internal, sensitive, or restricted; any other string is ignored), x-chio-side-effects, x-chio-approval-required, x-chio-budget-limit, and x-chio-publish. The two sets share x-chio-publish and x-chio-approval-required; the OpenAPI integration page specifies how the parser's set reaches the ToolDefinition.

OpenAPI-to-MCP bridge

Crate: chio-openapi-mcp-bridge. The bridge presents a Chio-governed HTTP API as an MCP tool interface. 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 specification 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.

The bridge MUST generate a valid chio.manifest.v1 manifest from the OpenAPI specification. If the specification contains zero publishable operations, the bridge MUST reject construction with a manifest error: OpenApiMcpBridge::from_parsed_spec returns BridgeError::Manifest(ManifestError::EmptyManifest) when the generated tool list is empty, and runs validate_manifest on the result.

tools/list generation

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

An explicit x-chio-side-effects fixes has_side_effects; without one the bridge sets it to false for GET, HEAD, and OPTIONS operations and true for every other HTTP method; mcp_tools_list() derives readOnlyHint as the negation of that flag. The bridge runs the generator with respect_publish_flag set, so an operation marked x-chio-publish: false is left out. Other x-chio-* extensions 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. A dispatcher is required for a live call: invoke_tool on a bridge with no dispatcher returns BridgeError::Kernel, so the kernel cannot sign an allow receipt for a side effect that did not happen. The dispatcher must not follow redirects; the bridge rejects a 3xx response and enforces the configured egress contract on the URL and the response size.

The structuredContent field of the MCP result MUST include:

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

bridged_tool_response builds that object beside a content text part holding the serialized body and an isError flag.

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. The variants are:

• BridgeToolServer<'a>: borrows the bridge for scoped registration; as_tool_server() returns it.
• OwnedBridgeToolServer: consumes the bridge for long-lived registration.

Both run the same route resolution and dispatch, 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. agent_card() builds it from the edge configuration and the registered tool manifests.

Each interface entry MUST include:

• url: A2A endpoint URL
• protocolBinding: protocol binding, which A2aEdgeConfig defaults to "JSONRPC"
• protocolVersion: "1.0"

Skill projection

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

When multiple manifests contain tools with the same name, the edge MUST NOT silently collapse them. The edge publishes each such tool under the server-qualified id {server_id}::{tool_name} with the tag chio:collision-qualified, and resolves the bare name to an unsupported entry whose reason lists the qualified ids. When the server-qualified id itself repeats, the edge appends an ordinal to the published id and adds the tag chio:ordinal-qualified.

message/send and message/stream

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 arguments come from the message parts: a message MUST carry at least one part and at most one data part, a data part MUST be a JSON object and is used as the arguments, and otherwise the text parts are joined with newlines and wrapped as {"message": "<text>"}.

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

The crate maps an Allow verdict with a completed terminal state to completed, an Allow verdict with any other terminal state to working with the terminal-state reason as statusMessage, and a Deny or PendingApproval verdict to failed.

message/stream is exposed as a deferred receipt-bearing task lifecycle and not as 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 a follow-up call to resolve or cancel the task.

task/get MUST execute the deferred request through the authoritative Chio path the first time it is called for a working task and then persist the terminal result. Terminal task results MUST carry the same signed receipt metadata as message/send. Unknown methods return JSON-RPC error code -32601.

Result conversion

Fidelity evaluation

The edge evaluates fidelity per tool at registration time from the semantic hints and has_side_effects.

evaluate_bridge_fidelity returns unsupported when publish is false, when the tool's target protocol has no registered executor, or when approvalRequired is true. It then collects caveats in this order: one for has_side_effects, two for streamsOutput, one for partialOutput, and one for supportsCancellation. It returns adapted with those caveats or lossless when there are none. The bridgeFidelity field is included in each skill entry; clients SHOULD use it to assess whether the A2A interface is sufficient. unsupported skills are withheld from the Agent Card entirely. See the A2A adapter integration page and the hello-a2a example.

Kernel-mediated receipts

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

• tool_name: the bare Chio tool name, which a collision-qualified or ordinal-qualified skill id does not match
• server_id: from the manifest that owns the tool
• decision: the receipt metadata records allow, deny, or pending_approval, one per kernel verdict

A Deny or PendingApproval verdict sets the task status to failed, puts the kernel reason in status_message, and still carries the signed receipt in the task metadata. An orchestration error returns a JSON-RPC error instead of a task.

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 the categories filesystem, terminal, browser, and the generic tool. The edge maps Chio tools into this model with category inference and fidelity assessment.

Capability mapping

When two manifests contribute a tool with the same name, the edge MUST NOT silently collapse them. It removes the capability from the published set and records it as unsupported with a reason that names each {server_id}/{tool_name} source; it publishes no qualified identifier for the collision.

Category inference

infer_acp_category lowercases the tool name and applies these rules 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. On the kernel path, evaluate_permission_with_kernel returns deny when the execution context is invalid, when the capability ID has no binding, when the capability token's signature fails or the token is outside its validity window, when the token's subject is not the calling agent, when the token does not match the bound tool, server, and arguments, or when the request requires a DPoP proof that is missing or does not match the kernel's preview. Otherwise it returns allow. The response metadata marks the decision previewOnly with receiptBearing: false: the preview does not itself produce a receipt, and enforcement happens on the invocation. The compatibility passthrough path, compiled under the compatibility-surface feature and in test builds, never reaches the kernel: it denies an unknown capability id, then answers from requiresPermission alone, deny when it is true and allow otherwise.

Fidelity assessment

The edge evaluates fidelity from the inferred category, the semantic hints, and has_side_effects.

evaluate_bridge_fidelity returns unsupported when publish is false, when the target protocol has no registered executor, when the category is browser, or when the category is tool and the tool has side effects. It then collects a caveat for each of approvalRequired, streamsOutput, partialOutput, supportsCancellation, and the generic tool category. unsupported capabilities are withheld from session/list_capabilities.

JSON-RPC interface

handle_jsonrpc on the kernel path dispatches these methods:

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

Invocation flow

tool/invoke returns an AcpInvocationResult with the fields success, data, an optional error, and optional metadata that carries the signed receipt when the kernel path ran. success is true only when the kernel verdict is Allow and the terminal state is completed; otherwise error carries the kernel's reason or the terminal-state reason. Every authoritative invocation that reaches the tool server MUST produce a signed receipt. A failed invocation (a tool server error) MUST return { success: false, error: "<message>" } and still produce a receipt. A deferred task created through tool/stream carries receiptPending: true and decision: pending in its metadata, and stays receipt-pending until tool/resume resolves it or tool/cancel marks it cancelled before execution. See the wrap an ACP server guide and the hello-acp example.

OpenAI adapter

Crate: chio-openai-adapter. ChioOpenAiAdapter intercepts OpenAI-style function calls and routes each one through the Chio kernel for capability validation and receipt signing, in both the Chat Completions format and the Responses API format. The v1 contract in spec/PROTOCOL.md does not claim OpenAI hosted-tool mediation or OpenAI remote MCP execution, and section 4 of spec/BRIDGES.md places this caller-executed function-tool surface outside the current v1 execution surface. The crate has no path for hosted tools, connectors, or provider-reported tool activity, and the specification forbids mapping a provider-reported observation to an authorization receipt.

Function definitions

openai_tools() turns each ToolDefinition of the adapter's manifest into one function entry with type: function; openai_tools_json() returns the same array as a JSON value.

Section 4.2 of the specification gives this Chat Completions tool envelope for a single function:

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

Extracting and executing calls

extract_tool_calls reads the tool_calls array of a Chat Completions message into OpenAiToolCall values and rejects a malformed entry with InvalidRequest. extract_responses_api_calls reads the output array of a Responses API result and keeps the items whose type is function_call.

execute_tool_call returns a denied result with no receipt reference, without contacting the kernel, when the approval inputs on the execution context are inconsistent, when the function name has no binding in the manifest, when the arguments do not parse as JSON, or when the authoritative route cannot be planned or serialized. Otherwise it builds a ToolCallRequest whose request_id is openai-{tool_call.id}, evaluates it through the kernel's blocking entry point, and returns a ToolCallResult whose denied flag is false only for an Allow verdict that is not a nonce preflight, and whose receipt_ref is the id of the receipt the kernel signed. A kernel error also yields a denied result with no receipt reference.

On a denied result content carries the error text. The result type is:

pub struct ToolCallResult {
    /// The tool call ID (matches the request).
    pub tool_call_id: String,
    /// The function name.
    pub name: String,
    /// The result content.
    pub content: String,
    /// Whether the call was denied by the kernel.
    pub denied: bool,
    /// Whether this result is a nonce preflight instead of executed tool output.
    #[serde(default)]
    pub preflight: bool,
    /// Signed nonce to present on the retry path when `preflight` is true.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub execution_nonce: Option<SignedExecutionNonce>,
    /// Receipt reference (if generated).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub receipt_ref: Option<String>,
    /// Signed receipt returned by the kernel (if generated).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub receipt: Option<ChioReceipt>,
}

Batches and result conversion

execute_tool_calls() runs a batch sequentially in input order and returns one ToolCallResult per call; a denied call does not stop the calls after it. When the batch holds more than one call and the execution context carries a request-bound authorization input (an approval token, a threshold approval set or proposal, or a supplemental authorization), every call in the batch is denied with the message that such inputs require a single call. results_to_messages() converts the results to role: tool messages for the next Chat Completions request, and results_to_responses_api() converts them to function_call_output items; both skip preflight results.

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 in the protocol reference:

• 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 query one receipt log for invocations from each supported protocol.

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.