ExMCP.ACP.Adapters.ZCode.Protocol (ex_mcp v1.3.0)

Copy Markdown View Source

Pure helpers for ZCode's app-server stdio protocol.

ZCode Protocol v1 is NDJSON over stdio. Messages are JSON-RPC-shaped but omit the jsonrpc field — the envelope is {id?, method?, params?, result?, error?}. IDs may be strings or integers.

This module owns only wire-shape construction and parsing. Translation between ACP and ZCode message semantics lives in ZCode.Mapper.

Summary

Functions

cli_path(opts)

Returns the ZCode executable path.

command(opts)

Returns the ZCode command line used by app-server sessions.

encode_error(id, code, message)

Builds a ZCode error response.

encode_notification(method, params \\ nil)

Builds a ZCode notification (no id).

encode_request(id, method, params \\ %{})

Builds a ZCode request message.

encode_response(id, result \\ %{})

Builds a ZCode success response.

env(opts)

Environment required for ZCode app-server.

line(message)

Encodes one ZCode message as an NDJSON line.

model_ref(arg1)

Extracts the model reference from a ZCode session/snapshot.

permission_options(options)

Converts ZCode permission options into ACP permission options.

permission_result(response, options)

Converts an ACP permission outcome back into a ZCode permission response (Nv shape: decision/reason/modifiedInput/permissionUpdates).

permission_tool_call(request, cwd)

Maps a ZCode interaction/requestPermission request into an ACP tool call suitable for session/request_permission.

prompt_content(text)

Converts ACP prompt blocks into ZCode session/send content.

session_id(arg1)

Extracts the session ID from a ZCode session snapshot.

stop_reason(reason)

Maps a ZCode turn.completed resultType to an ACP stopReason.

workspace_ref(path)

Builds the workspace descriptor required by the ZCode Protocol.

Functions

cli_path(opts)

@spec cli_path(keyword()) :: String.t()

Returns the ZCode executable path.

command(opts)

@spec command(keyword()) :: {String.t(), [String.t()]}

Returns the ZCode command line used by app-server sessions.

encode_error(id, code, message)

@spec encode_error(String.t() | integer(), integer(), String.t()) :: map()

Builds a ZCode error response.

encode_notification(method, params \\ nil)

@spec encode_notification(String.t(), map() | nil) :: map()

Builds a ZCode notification (no id).

encode_request(id, method, params \\ %{})

@spec encode_request(String.t() | integer(), String.t(), map() | nil) :: map()

Builds a ZCode request message.

encode_response(id, result \\ %{})

@spec encode_response(String.t() | integer(), map() | nil) :: map()

Builds a ZCode success response.

env(opts)

@spec env(keyword()) :: map()

Environment required for ZCode app-server.

line(message)

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

Encodes one ZCode message as an NDJSON line.

model_ref(arg1)

@spec model_ref(map()) :: map() | nil

Extracts the model reference from a ZCode session/snapshot.

permission_options(options)

@spec permission_options([map()]) :: [map()]

Converts ZCode permission options into ACP permission options.

ZCode options carry a pre-resolved response field (the decision that selecting each option produces). We map the ZCode decision vocabulary (allow/deny/escalate/modify) to ACP permission option kinds.

permission_result(response, options)

@spec permission_result(map(), [map()]) :: map()

Converts an ACP permission outcome back into a ZCode permission response (Nv shape: decision/reason/modifiedInput/permissionUpdates).

The ACP client responds with {outcome: "selected", optionId: ...} or {outcome: "cancelled"}. We find the matching ZCode option's pre-resolved response and return it, falling back to a deny.

permission_tool_call(request, cwd)

@spec permission_tool_call(map(), String.t() | nil) :: map()

Maps a ZCode interaction/requestPermission request into an ACP tool call suitable for session/request_permission.

prompt_content(text)

@spec prompt_content(list() | String.t() | nil) ::
  {:ok, String.t()} | {:error, String.t()}

Converts ACP prompt blocks into ZCode session/send content.

ZCode's session/send accepts a content string. In v1 we support text-only prompts. Image/embedded-context support is a follow-up.

session_id(arg1)

@spec session_id(map()) :: String.t() | nil

Extracts the session ID from a ZCode session snapshot.

stop_reason(reason)

@spec stop_reason(String.t() | nil) :: String.t()

Maps a ZCode turn.completed resultType to an ACP stopReason.

ZCode result types: success, cancelled, error_max_turns, error_max_budget, error_during_execution, error_max_tool_calls.

workspace_ref(path)

@spec workspace_ref(String.t()) :: map()

Builds the workspace descriptor required by the ZCode Protocol.