acpx

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

acpx

An Agent Client Protocol client layer for Go, on top of github.com/coder/acp-go-sdk v0.13.5. It adds ready-made calls for protocol features and agent extensions that the SDK does not type yet. The agents it was checked against are claude-agent-acp 0.100.0, codex-acp 2.5.0, OpenCode 1.19.5 and Hermes Agent 0.22.7.

It was written for a headless client that drives agents in sandboxes (k1dory/cluster-agent-k8s, cmd/agent-runner), but it does not depend on that project.

conn := acpx.Dial(client, agentStdin, agentStdout, acpx.WireOptions{
	Notices: true, Compaction: true,
	OnUpdate: func(u acpx.ExtraUpdate) { /* notice, compaction_update, compaction_summary_chunk */ },
})
init, _ := conn.Initialize(ctx, acp.InitializeRequest{ProtocolVersion: acp.ProtocolVersionNumber})

var meta map[string]any
if conn.Wire.SystemPrompt() { // sessionCapabilities.systemPrompt
	meta = acpx.SessionMeta(nil, "Follow the repository's conventions.")
}
s, _ := conn.NewSession(ctx, acp.NewSessionRequest{Cwd: dir, McpServers: []acp.McpServer{}, Meta: meta})
st := acpx.SessionState{Modes: s.Modes, Options: s.ConfigOptions}
_ = acpx.Configure(ctx, conn, s.SessionId, st, acpx.ModeSetting, "agent-full-access")
_ = acpx.Configure(ctx, conn, s.SessionId, st, acpx.ThoughtLevelSetting, "high")

// Later, while a prompt turn runs:
out, _ := conn.Steer(ctx, s.SessionId, "also update the tests") // injected | promptRequired

What it adds

Wire A JSON-RPC layer between the connection and the agent's stdio. The SDK drops some fields from initialize; Wire reads two of them, sessionCapabilities.systemPrompt and _meta.steering.supported. It advertises clientCapabilities.session.notices / .compaction, which ClientCapabilities cannot express. It carries a session's client system prompt (systemPrompt, mode append). It also decodes notice, compaction_update and compaction_summary_chunk, which the SDK silently zeroes. Lines are handled up to the SDK's own 10 MiB limit, the same way however the agent's output is split into reads.
Conn The SDK's ClientSideConnection over a Wire. Adds Steer: the _session/steering extension (claude-agent-acp, codex-acp), which puts a message into the turn in progress. It uses idleBehavior: promptRequired, so the client still owns every turn.
Configure Selects a session's mode, model or reasoning level (thought_level) through the agent's configuration options. Mode falls back to session/set_mode. It matches the agent's own values: the exact value, a provider-qualified value (anthropic/claude-…), or a display name. Anything it cannot apply comes back as an error to report.
SessionMeta Builds a session request's _meta from your metadata (for example claude-agent-acp's claudeCode.options) plus the system prompt.

When the SDK gains these fields, the wire-level parts can be removed.

Development

go vet ./... && go test -race ./...

Apache-2.0.

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

View Source
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 an empty update for them). The Wire decodes them for the client that advertised them (WireOptions).

View Source
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.

View Source
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.

View Source
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

View Source
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

ConfigOption is the first select option of the category, nil when there is none.

func Configure

func Configure(ctx context.Context, cf Configurer, sid acp.SessionId, st SessionState, s Setting, want string) error

Configure selects want for the setting in a session. It changes nothing when the session already has it; what cannot be applied (no such option, a value the agent does not offer, a refusal) is returned as an error to report, and the session keeps the agent's own value.

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

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

func SessionMeta(meta map[string]any, systemPrompt string) map[string]any

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

type CompactionSummaryChunk struct {
	ID   string `json:"compactionId"`
	Text string `json:"-"`
}

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

func Dial(client acp.Client, agentStdin io.Writer, agentStdout io.Reader, opts WireOptions) *Conn

Dial connects client to an agent over its stdin and stdout through a Wire.

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.

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 NewWire

func NewWire(agentStdin io.Writer, agentStdout io.Reader, opts WireOptions) *Wire

NewWire layers a Wire over the agent's stdin (w) and stdout (r).

func (*Wire) Read

func (x *Wire) Read(p []byte) (int, error)

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

func (x *Wire) Steering() bool

Steering reports whether the agent takes _session/steering (initialize _meta.steering.supported).

func (*Wire) SystemPrompt

func (x *Wire) SystemPrompt() bool

SystemPrompt reports whether the agent takes the client's system prompt (sessionCapabilities.systemPrompt in its initialize response).

func (*Wire) Write

func (x *Wire) Write(b []byte) (int, error)

Write passes the client's messages to the agent. The connection writes one whole message per call; initialize and a session request with the system prompt marker are rewritten.

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.
	Notices, Compaction bool
	// OnUpdate receives those updates. It runs on the reading goroutine, before the SDK has
	// processed the lines that came earlier: an update's place among the SDK's own is not exact.
	OnUpdate func(ExtraUpdate)
}

WireOptions says what the client advertises beyond the SDK's ClientCapabilities and where the session updates the SDK cannot decode go.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL