# `MingaClaudeBridge.Wire`
[🔗](https://github.com/jsmestad/minga-claude-bridge/blob/main/lib/minga_claude_bridge/wire.ex#L1)

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 `t: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.

# `decode_error`

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

# `error_id`

```elixir
@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`

```elixir
@type frame() ::
  MingaClaudeBridge.Wire.SystemInit.t()
  | MingaClaudeBridge.Wire.StreamEvent.t()
  | MingaClaudeBridge.Wire.Assistant.t()
  | MingaClaudeBridge.Wire.User.t()
  | MingaClaudeBridge.Wire.Result.t()
  | MingaClaudeBridge.Wire.RateLimit.t()
  | MingaClaudeBridge.Wire.ControlRequest.t()
  | MingaClaudeBridge.Wire.ControlResponse.t()
  | MingaClaudeBridge.Wire.ControlCancel.t()
  | MingaClaudeBridge.Wire.Unknown.t()
```

# `jsonrpc_id`

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

A JSON-RPC 2.0 request id.

# `line`

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

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

# `control`

```elixir
@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`

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

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

# `decode`

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

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

# `initialize`

```elixir
@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`

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

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

# `mcp_error`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
