Raxol.AgentClientProtocol.Schema.SessionUpdate (Raxol Agent Client Protocol v0.1.0)

Copy Markdown View Source

The session/update notification's sessionUpdate-discriminated union: real-time feedback the agent streams back to the client during a prompt turn (message/thought chunks, tool call lifecycle, the execution plan, available-command changes, mode changes, and the unstable config-option/ session-info updates).

Every variant's payload is a plain wire object carrying its own fields alongside a "sessionUpdate" discriminator key set to the variant's tag (snakecase, matching the tag atom exactly) -- there is no separate nesting level for the payload, mirroring how McpServer tags its http/ sse variants with a sibling "type" key. Discriminator dispatch on decode uses explicit, whitelisted "sessionUpdate" string clauses (never String.to_atom/1); an unrecognized or missing discriminator is a `{:error, }`, not a raise or a silent default.

from_json/1 is total: it never raises, always returning {:ok, t} or {:error, reason}. to_json/1 delegates to each variant payload module's own to_json/1 and adds the "sessionUpdate" tag; per package convention, tagged-tuple unions like this one (see also ContentBlock, McpServer, ToolCallContent) do not get a Jason.Encoder impl of their own -- only genuine structs do.

Variants ported (all ten f1729 defines, plus the oracle's eleventh)

Closed gap: ContentChunk.messageId

The pinned oracle documents an additional optional messageId wire field on ContentChunk (groups chunks belonging to the same streamed message) that f1729's ACP.ContentChunk lacked; it is now ported below as ContentChunk.message_id (optional, absent-safe on both decode and encode).

The {"sessionId", "update", "_meta"} envelope that wraps a SessionUpdate for the wire is Raxol.AgentClientProtocol.Schema.LifecycleExtras.SessionNotification. There is no AgentNotification routing union: "session/update" is routed by its Raxol.AgentClientProtocol.MethodTable row.

Ported from the MIT f1729/agent_client_protocol (c) 2025 f1729; see NOTICE.md.

Summary

Types

t()

Functions

from_json(map)

Total: never raises. Dispatches on the "sessionUpdate" discriminator via explicit whitelisted string clauses (no String.to_atom/1); an unrecognized discriminator value, a map with none at all, or a non-map argument all return a descriptive {:error, _}. "sessionUpdate" is stripped before delegating to the variant payload's own from_json/1 so it never leaks into that payload's _meta.

to_json(arg)

Types

t()

@type t() ::
  {:user_message_chunk, Raxol.AgentClientProtocol.Schema.ContentChunk.t()}
  | {:agent_message_chunk, Raxol.AgentClientProtocol.Schema.ContentChunk.t()}
  | {:agent_thought_chunk, Raxol.AgentClientProtocol.Schema.ContentChunk.t()}
  | {:tool_call, Raxol.AgentClientProtocol.Schema.ToolCall.t()}
  | {:tool_call_update, Raxol.AgentClientProtocol.Schema.ToolCallUpdate.t()}
  | {:plan, Raxol.AgentClientProtocol.Schema.Plan.t()}
  | {:available_commands_update,
     Raxol.AgentClientProtocol.Schema.AvailableCommandsUpdate.t()}
  | {:current_mode_update,
     Raxol.AgentClientProtocol.Schema.CurrentModeUpdate.t()}
  | {:config_option_update,
     Raxol.AgentClientProtocol.Schema.Unstable.ConfigOptionUpdate.t()}
  | {:session_info_update,
     Raxol.AgentClientProtocol.Schema.Unstable.SessionInfoUpdate.t()}
  | {:usage_update, Raxol.AgentClientProtocol.Schema.UsageUpdate.t()}

Functions

from_json(map)

@spec from_json(term()) :: {:ok, t()} | {:error, term()}

Total: never raises. Dispatches on the "sessionUpdate" discriminator via explicit whitelisted string clauses (no String.to_atom/1); an unrecognized discriminator value, a map with none at all, or a non-map argument all return a descriptive {:error, _}. "sessionUpdate" is stripped before delegating to the variant payload's own from_json/1 so it never leaks into that payload's _meta.

to_json(arg)

@spec to_json(t()) :: map()