MingaClaudeBridge.Wire (minga_claude_bridge v0.1.0)

Copy Markdown View Source

Codec for Claude Code's stream-json protocol.

Claude Code started with --input-format stream-json --output-format stream-json --verbose --include-partial-messages reads and writes newline-delimited JSON (one JSON object per line) on stdin and stdout. This module decodes one output line into a typed frame and encodes the frames the bridge writes to stdin.

Decoding

decode/1 never raises. It returns:

  • {:ok, frame} where frame is one of the structs in frame/0. A frame with a type this module does not model, or a system frame other than init, decodes to MingaClaudeBridge.Wire.Unknown.
  • {:error, {:invalid_json, {kind, offset}}} when the line is not valid JSON. The reason holds only the error kind and byte offset, never line content.
  • {:error, :not_a_frame} when the JSON value is not an object with a string type.
  • {:error, {:invalid_frame, type}} when a modeled frame lacks a required field or has a field of the wrong JSON type.

Enumerated strings (stop reasons, result subtypes, rate-limit status) decode to atoms from closed tables. Unknown values decode to {:other, string}; the codec never creates atoms from input.

Encoding

Each encoder returns one complete line, newline included, ready to write to the Port. Optional fields that are nil are omitted from the JSON.

Payloads

Decoded frames hold conversation content. This module does not log or store anything, and callers must not log frame contents or Unknown.raw.

Field-name sources

Field names were checked against @anthropic-ai/claude-agent-sdk 0.3.330 (sdk.d.ts types and the sdk.mjs control-protocol implementation): SDKSystemMessage, SDKPartialAssistantMessage, SDKAssistantMessage, SDKUserMessage, SDKResultSuccess/SDKResultError, SDKRateLimitEvent/SDKRateLimitInfo, SDKControlRequest, SDKControlResponse (ControlResponse/ControlErrorResponse), SDKControlCancelRequest, SDKControlInitializeRequest, SDKControlInterruptRequest, SDKControlMcpMessageRequest, and SDKControlPermissionRequest. Stream events follow the Anthropic Messages API streaming events, which the SDK embeds as BetaRawMessageStreamEvent.

Unverified

  • resetsAt units: Unix seconds per pi-claude-bridge observation, not stated in the SDK types. See MingaClaudeBridge.Wire.RateLimit.
  • The user input frame: the SDK type marks session_id and uuid optional, and pi-claude-bridge sends neither. Whether a given CLI version requires them on stdin is not confirmed; user_message/2 omits them unless given.
  • The success reply to an mcp_message request wraps the JSON-RPC reply as response.mcp_response. This is confirmed from sdk.mjs but not from a typed declaration.

Summary

Types

The id of a JSON-RPC 2.0 error reply. It is nil (JSON null) when the request id could not be read.

A JSON-RPC 2.0 request id.

One encoded frame: a JSON object followed by a newline.

Functions

Encodes a client-initiated control request, for example %{"subtype" => "get_usage", "skip_behaviors" => true}. request must hold a string "subtype".

Encodes a control_response that rejects a control request with an error message.

Decodes one stream-json line. A trailing newline is allowed.

Encodes the initialize control request, which the bridge sends before the first prompt.

Encodes the interrupt control request, which stops the current turn.

Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is an error, for example code -32800 for a cancelled request.

Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is a result.

Encodes a user frame that sends a prompt or tool results to Claude Code.

Types

decode_error()

@type decode_error() ::
  {:invalid_json, {kind :: atom(), offset :: non_neg_integer()}}
  | :not_a_frame
  | {:invalid_frame, type :: String.t()}

error_id()

@type error_id() :: jsonrpc_id() | nil

The id of a JSON-RPC 2.0 error reply. It is nil (JSON null) when the request id could not be read.

frame()

jsonrpc_id()

@type jsonrpc_id() :: String.t() | integer()

A JSON-RPC 2.0 request id.

line()

@type line() :: String.t()

One encoded frame: a JSON object followed by a newline.

Functions

control(request_id, request)

@spec control(String.t(), map()) :: line()

Encodes a client-initiated control request, for example %{"subtype" => "get_usage", "skip_behaviors" => true}. request must hold a string "subtype".

control_error(request_id, message)

@spec control_error(String.t(), String.t()) :: line()

Encodes a control_response that rejects a control request with an error message.

decode(line)

@spec decode(binary()) :: {:ok, frame()} | {:error, decode_error()}

Decodes one stream-json line. A trailing newline is allowed.

initialize(request_id, opts \\ [])

@spec initialize(String.t(), keyword()) :: line()

Encodes the initialize control request, which the bridge sends before the first prompt.

Options:

  • :sdk_mcp_servers - names of the MCP servers the bridge hosts over the control channel, for example ["minga"].
  • :system_prompt - the system prompt, as a string or a list of strings. The wire field is a list; a string is sent as a one-element list.
  • :append_system_prompt - text appended to the system prompt.

interrupt(request_id)

@spec interrupt(String.t()) :: line()

Encodes the interrupt control request, which stops the current turn.

mcp_error(request_id, jsonrpc_id, code, message)

@spec mcp_error(String.t(), error_id(), integer(), String.t()) :: line()

Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is an error, for example code -32800 for a cancelled request.

The control request itself succeeds; the JSON-RPC error tells the MCP client that the call failed. jsonrpc_id is nil when the request id could not be read, which encodes as JSON null.

mcp_result(request_id, jsonrpc_id, result)

@spec mcp_result(String.t(), jsonrpc_id(), map()) :: line()

Encodes a successful answer to an mcp_message control request whose JSON-RPC reply is a result.

jsonrpc_id is the id of the JSON-RPC request inside the mcp_message. request_id is the control request's id.

user_message(content, opts \\ [])

@spec user_message(String.t() | [MingaClaudeBridge.Wire.Block.t()], keyword()) ::
  line()

Encodes a user frame that sends a prompt or tool results to Claude Code.

content is a string or a list of MingaClaudeBridge.Wire.Block values. A string is sent as one text block.

Options:

  • :session_id - the Claude Code session id. Omitted when absent.
  • :uuid - a client message uuid that Claude Code echoes back on the reply. Omitted when absent.