Bridges

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.

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

BridgeFidelity::published_by_default is false only for unsupported; both edges skip such a tool when they build their published list. The two edges reach a level by different rules, set out in A2A fidelity evaluation and ACP fidelity assessment.

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; OpenAPI integration 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, and 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 in OpenAPI integration.

Invocation flow

For a governed call, register the bridge as a tool server and submit the request to the kernel. The kernel owns admission and execution; the bridge translates the dispatched call into HTTP, so a call the kernel refuses never becomes an HTTP request. Calling invoke_tool directly runs the bridge’s route and egress checks without the kernel and issues no Chio receipt.

1. Kernel admission. Validate authority and run configured input checks before dispatch.
2. Bridge dispatch. Resolve the tool’s method and URL, enforce the egress contract, then call the configured HTTP dispatcher.
3. Bridge return. Reject redirects and oversized responses, then package the HTTP result for the kernel.
4. Kernel completion. Apply the relevant output checks and produce the mediated result and receipt.

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 live call needs a dispatcher: invoke_tool on a bridge with no dispatcher returns BridgeError::Kernel. 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

In the kernel-integrated path, the kernel produces the Chio receipt and the bridge returns an HTTP-shaped tool result. The receipt identifies the mediated call through:

• tool_name: the MCP tool name (derived from operationId)
• server_id: the bridge's configured server ID
• decision: the kernel’s recorded policy decision; read the tool result and terminal evidence as well to learn whether the HTTP operation succeeded

Kernel integration

The bridge implements ToolServerConnection, so it registers directly with a kernel instance in one of two forms:

• 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. The Bridge OpenAPI to MCP guide and the OpenAPI sidecar example run it end to end.

A2A edge

Crate: chio-a2a-edge. The A2A edge serves kernel-governed Chio tools to external A2A clients as A2A skills, the reverse direction of chio-a2a-adapter, which consumes a remote A2A server. Every invocation flows through the kernel guard pipeline and produces 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 a deferred, receipt-bearing task lifecycle; it carries no push stream. 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. A task canceled before execution never reaches the kernel and has no tool execution receipt. 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.

• lossless: the tool is publishable and depends on no approval, deferred-stream, cancellation, or partial-output caveat. The A2A edge projects it without semantic loss.
• adapted: the tool is publishable, but its side-effect, deferred-stream, cancellation, or partial-output semantics require explicit caveats. The edge preserves the tool through A2A and surfaces the caveats in discovery metadata.
• unsupported: the tool requires interactive approval or carries explicit publication suppression (x-chio-publish: false). The tool MUST NOT be auto-published on the A2A surface.

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. The A2A adapter integration and the hello-a2a example serve a tool through this edge.

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 kernel-governed Chio tools as ACP (Agent Client Protocol) capabilities, so ACP-compatible editors and IDEs 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 evaluates permission fail-closed against 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. A preview signs no receipt and runs nothing; enforcement happens on the invocation, which checks again before dispatch. The compatibility passthrough path, compiled under the compatibility-surface feature and in test builds, answers without 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.

• lossless: the category is filesystem or terminal and no caveated semantic hint is present. ACP supports the projection natively, without caveats.
• adapted: the capability is publishable but depends on permission-preview, collected streaming, partial-output, cancellation, or generic-tool-category caveats. It remains discoverable, and the caveats MUST be surfaced in bridgeFidelity.
• unsupported: the category is browser, the category is generic mutating tool, or publication is disabled with x-chio-publish: false. The capability MUST NOT be auto-published on the ACP surface.

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

The edge validates execution context and resolves the capability binding, then submits a cross-protocol request to the authoritative orchestrator. Native targets enter kernel execution directly; registered MCP and OpenAI target executors provide the other supported paths. The edge maps the resulting verdict, terminal state, and receipt into the ACP response. Edge validation and orchestration errors return before the kernel produces a receipt. A permission preview leaves invocation-time enforcement in place.

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. The Wrap an ACP server guide and the hello-acp example run this path.

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 adapter mediates function calls the caller executes. OpenAI hosted tools, connectors, remote MCP execution, and provider-reported tool activity run inside the provider, outside the kernel path, 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.

For the pricing server’s quote tool, the bridge emits the Chat Completions tool envelope that section 4.2 of the specification defines:

[
  {
    "type": "function",
    "function": {
      "name": "quote",
      "description": "Quote a price for a SKU at a percentage discount",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "percent": { "type": "number" }
        },
        "required": ["sku", "percent"]
      }
    }
  }
]

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.

The result's denied flag is false only for an Allow verdict that is not a nonce preflight, and its 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 leaves the calls after it to run. 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

Every bridge, edge, and adapter shares two requirements: it fails closed, and its receipts join the native receipt log.

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.