Documentation
¶
Overview ¶
Package acpx is an Agent Client Protocol (https://agentclientprotocol.com) client layer on top of github.com/coder/acp-go-sdk: ready calls for what the protocol and today's agents (claude-agent-acp, codex-acp, OpenCode, Hermes) offer beyond what the SDK (v0.13.5) types. It was written for a headless client that drives agents in sandboxes (k1dory/cluster-agent-k8s).
What it adds:
- Wire, a JSON-RPC level layer between the connection and the agent's stdio. It reads the agent's capabilities the SDK drops from the initialize response (the client system prompt, steering), advertises the client's session capabilities the SDK cannot express (live notices, compaction updates), carries a session's system prompt, and hands over the session updates the SDK silently zeroes (notice, compaction_update, compaction_summary_chunk).
- Conn: the SDK's client-side connection over a Wire, with Steer (_session/steering: a message joins the turn in progress) and the agent's capabilities.
- Config options: select a session's mode, model or reasoning level by category (Configure), matching the agent's own values.
- SessionMeta: a session request's _meta from the caller's free-form metadata and the system prompt.
Everything here is a client-side convenience over published ACP surfaces; when the SDK gains a field (systemPrompt, notices), the wire-level part of it can go.
Index ¶
- Constants
- Variables
- func ConfigOption(options []acp.SessionConfigOption, cat acp.SessionConfigOptionCategory) *acp.SessionConfigOptionSelect
- func KindOf(u acp.SessionUpdate) string
- func MatchModel(options []acp.SessionConfigSelectOption, model string) string
- func MatchValueOrName(options []acp.SessionConfigSelectOption, want string) string
- func SelectOptions(opt *acp.SessionConfigOptionSelect) []acp.SessionConfigSelectOption
- func SelectValues(opt *acp.SessionConfigOptionSelect) []string
- func SessionMeta(meta map[string]any, systemPrompt string) map[string]any
- type Compaction
- type CompactionSummaryChunk
- type Configurer
- type Conn
- type ExtraUpdate
- type Notice
- type SessionState
- type Setting
- type SteerOutcome
- type Wire
- type WireOptions
Constants ¶
const ( UpdateNotice = "notice" UpdateCompaction = "compaction_update" UpdateCompactionSummaryChunk = "compaction_summary_chunk" )
Session update kinds acp-go-sdk v0.13.5 does not decode (it hands its client another kind's update for them, see Wire.Classify). The Wire decodes them for the client.
const MaxLine = 10 << 20
MaxLine is the longest line the Wire looks at: the connection's own limit (acp-go-sdk reads lines with a 10 MiB bufio.Scanner and cannot take a longer one). However the agent's output is cut into reads, a line up to it is looked at whole and a longer one not at all.
const SteerMethod = "_session/steering"
SteerMethod is the steering extension (claude-agent-acp, codex-acp): a message joins the turn in progress instead of waiting for it to end.
const SystemPromptMetaKey = "acpx/systemPrompt"
SystemPromptMetaKey marks a session request's system prompt: the text, in the request's _meta. The Wire moves it to the request's systemPrompt (append) and it never reaches the agent as metadata. acp-go-sdk v0.13.5 has no systemPrompt field.
Variables ¶
var ( ModeSetting = Setting{Name: "mode", Category: acp.SessionConfigOptionCategoryMode, Modes: true} // ModelSetting matches the model's name, a provider-qualified value (OpenCode's // anthropic/claude-…) or an option of that display name. ModelSetting = Setting{Name: "model", Category: acp.SessionConfigOptionCategoryModel, Match: MatchModel} // ThoughtLevelSetting is the reasoning level (codex-acp reasoning_effort, OpenCode effort, // Hermes reasoning_effort): its value or display name. ThoughtLevelSetting = Setting{Name: "thought_level", Category: acp.SessionConfigOptionCategoryThoughtLevel, Match: MatchValueOrName} )
The settings a client can make; copy one and change Name to report it under the client's own name.
Functions ¶
func ConfigOption ¶
func ConfigOption(options []acp.SessionConfigOption, cat acp.SessionConfigOptionCategory) *acp.SessionConfigOptionSelect
ConfigOption is the first select option of the category, nil when there is none.
func KindOf ¶ added in v0.2.0
func KindOf(u acp.SessionUpdate) string
KindOf is the sessionUpdate kind of an update as the SDK decoded it ("" for none).
func MatchModel ¶
func MatchModel(options []acp.SessionConfigSelectOption, model string) string
MatchModel picks the value that is the model's name, else one that ends in /<name>, else one whose display name is it.
func MatchValueOrName ¶
func MatchValueOrName(options []acp.SessionConfigSelectOption, want string) string
MatchValueOrName picks the value that is want, else one whose display name is it.
func SelectOptions ¶
func SelectOptions(opt *acp.SessionConfigOptionSelect) []acp.SessionConfigSelectOption
SelectOptions lists a select option's values, grouped or not.
func SelectValues ¶
func SelectValues(opt *acp.SessionConfigOptionSelect) []string
SelectValues lists a select option's value ids.
func SessionMeta ¶
SessionMeta is the _meta of a session request (new, load, resume): the caller's free-form metadata (claude-agent-acp reads claudeCode.options from it: maxTurns, maxBudgetUsd…) and, when the agent takes one, the system prompt (moved to the request's systemPrompt by the Wire). nil when there is neither.
Types ¶
type Compaction ¶
type Compaction struct {
ID string `json:"compactionId"`
Status string `json:"status"`
Summary string `json:"-"`
Error string `json:"error,omitempty"`
}
Compaction is the state of one compaction of the session's context: in_progress, completed, failed or cancelled. Summary is the text of its summary, when the update carries one.
type CompactionSummaryChunk ¶
CompactionSummaryChunk is a piece of a compaction's summary as it is written.
type Configurer ¶
type Configurer interface {
SetSessionMode(ctx context.Context, params acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error)
SetSessionConfigOption(ctx context.Context, params acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error)
}
Configurer is what changing a session's configuration needs of a connection.
type Conn ¶
type Conn struct {
*acp.ClientSideConnection
Wire *Wire
}
Conn is the client side of one ACP connection: the SDK's connection (every method it has is Conn's) over a Wire, plus the calls the SDK does not type.
func Dial ¶
Dial connects client to an agent over its stdin and stdout through a Wire. A client that calls Wire.Classify needs the Wire before the connection starts delivering updates: it makes the Wire with NewWire and connects with Wire.Connect instead.
func (*Conn) Steer ¶
func (c *Conn) Steer(ctx context.Context, sessionID acp.SessionId, text string) (SteerOutcome, error)
Steer sends text into the turn in progress of a session. It asks the agent not to start a turn of its own when none is running (idleBehavior promptRequired), so the client keeps every turn a prompt it sent. An agent without steering (Wire.Steering false) is not asked: the result is SteerPromptRequired.
type ExtraUpdate ¶
type ExtraUpdate struct {
SessionID string
Notice *Notice
Compaction *Compaction
SummaryChunk *CompactionSummaryChunk
}
ExtraUpdate is one of those updates; exactly one of its pointers is set.
type Notice ¶
type Notice struct {
Severity string `json:"severity"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
}
Notice is a user-facing notice from the agent: a limit reached, a degraded service, an error it recovered from. Severity is info, warning, error or the agent's own.
type SessionState ¶
type SessionState struct {
Modes *acp.SessionModeState
Options []acp.SessionConfigOption
}
SessionState is what the agent said about a session when it opened (new, load, resume): its modes and its configuration options. Either may be absent.
func Configure ¶
func Configure(ctx context.Context, cf Configurer, sid acp.SessionId, st SessionState, s Setting, want string) (SessionState, error)
Configure selects want for the setting in a session and returns the session's state after it: selecting one option may change the others (codex-acp offers other reasoning levels for another model), so the next Configure is to be given that state. It changes nothing when the session already has the value; what cannot be applied (no such option, a value the agent does not offer, a refusal) is returned as an error to report, with the state unchanged, and the session keeps the agent's own value.
type Setting ¶
type Setting struct {
Name string // for messages: "mode", "model"… (a caller may name its own setting)
Category acp.SessionConfigOptionCategory // mode, model, thought_level
// Modes: fall back to the session's modes (session/set_mode) when the agent has no config
// option of the category. Only for the mode.
Modes bool
// Match picks the agent's value for want among its options; nil: the value itself.
Match func(options []acp.SessionConfigSelectOption, want string) string
}
Setting names what to select and how a wanted value matches the agent's own.
type SteerOutcome ¶
type SteerOutcome string
SteerOutcome is what became of a steered message.
const ( // SteerInjected: the message joined the turn in progress. SteerInjected SteerOutcome = "injected" // SteerPromptRequired: no turn was running; the message was not taken and is to be sent as a // prompt of its own. SteerPromptRequired SteerOutcome = "promptRequired" // SteerStartedNewTurn: the agent started a turn with the message itself (an agent that ignores // idleBehavior). Its end is not the end of any prompt the client sent. SteerStartedNewTurn SteerOutcome = "startedNewTurn" )
type Wire ¶
type Wire struct {
// contains filtered or unexported fields
}
Wire sits between the SDK's connection and the agent's stdio (Writer: to the agent, Reader: from it). Every byte passes through unchanged except the client's initialize request (the session capabilities) and a session request carrying SystemPromptMetaKey.
func (*Wire) Classify ¶ added in v0.2.0
func (x *Wire) Classify(u acp.SessionUpdate) (extra *ExtraUpdate, sdk bool)
Classify says what a session update the SDK hands its client really is. The client calls it once for every SessionUpdate, in order (the SDK delivers notifications in the order they came).
acp-go-sdk v0.13.5 does not know every kind of update: one it does not know is not dropped but decoded as whichever known kind its fields fit (a notice with a title arrives as a session_info_update). Classify matches the call with the notification the Wire read: sdk is true for an update the SDK decoded as what it is; otherwise the SDK's update is to be ignored, and extra is what acpx decoded of it (a notice, a compaction update or summary chunk; nil for a kind acpx does not decode either).
func (*Wire) Connect ¶ added in v0.2.0
Connect starts the SDK's client-side connection for client over the Wire.
func (*Wire) Read ¶
Read passes the agent's output to the connection, looking at every line on the way. A line is looked at before the bytes that end it are returned, so what initialize declared is known by the time Initialize returns.
func (*Wire) Steering ¶
Steering reports whether the agent takes _session/steering (initialize _meta.steering.supported).
func (*Wire) SystemPrompt ¶
SystemPrompt reports whether the agent takes the client's system prompt (sessionCapabilities.systemPrompt in its initialize response).
type WireOptions ¶
type WireOptions struct {
// Notices and Compaction advertise clientCapabilities.session.notices / .compaction in
// initialize: an agent sends notice, compaction_update and compaction_summary_chunk only to a
// client that does. The client then gets them from Classify, in its SessionUpdate.
Notices, Compaction bool
}
WireOptions says what the client advertises beyond the SDK's ClientCapabilities.