Help us shape the future of Go! Take the 2026 Go Developer Survey

acp

package
v2.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package acp is celeste's Agent Client Protocol agent (2.0 W4): JSON-RPC 2.0 over newline-delimited JSON on stdio, for editors such as Zed.

Index

Constants

View Source
const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeInvalidParams  = -32602
	CodeMethodNotFound = -32601
	CodeInternal       = -32603
	// CodeBusy is implementation-defined; ACP v1 already uses -32000 (auth
	// required), -32002 (resource not found) and -32800 (cancelled).
	CodeBusy = -32001
)

JSON-RPC error codes celeste answers with.

View Source
const (
	StopEndTurn         = "end_turn"
	StopMaxTokens       = "max_tokens"
	StopMaxTurnRequests = "max_turn_requests"
	StopRefusal         = "refusal"
	StopCancelled       = "cancelled"
)

Stop reasons.

View Source
const (
	BlockText         = "text"
	BlockImage        = "image"
	BlockAudio        = "audio"
	BlockResourceLink = "resource_link"
	BlockResource     = "resource"
)

Content block types.

View Source
const (
	UpdateUserMessageChunk  = "user_message_chunk"
	UpdateAgentMessageChunk = "agent_message_chunk"
	UpdateAgentThoughtChunk = "agent_thought_chunk"
	UpdateToolCall          = "tool_call"
	UpdateToolCallUpdate    = "tool_call_update"
	UpdatePlan              = "plan"
)

Session update kinds.

View Source
const (
	ToolKindRead       = "read"
	ToolKindEdit       = "edit"
	ToolKindDelete     = "delete"
	ToolKindMove       = "move"
	ToolKindSearch     = "search"
	ToolKindExecute    = "execute"
	ToolKindThink      = "think"
	ToolKindFetch      = "fetch"
	ToolKindSwitchMode = "switch_mode"
	ToolKindOther      = "other"
)

Tool kinds.

View Source
const (
	ToolStatusPending    = "pending"
	ToolStatusInProgress = "in_progress"
	ToolStatusCompleted  = "completed"
	ToolStatusFailed     = "failed"
)

Tool call statuses.

View Source
const (
	OptionAllowOnce    = "allow_once"
	OptionAllowAlways  = "allow_always"
	OptionRejectOnce   = "reject_once"
	OptionRejectAlways = "reject_always"
)

Permission option kinds.

View Source
const (
	OutcomeSelected  = "selected"
	OutcomeCancelled = "cancelled"
)

Permission outcomes.

View Source
const ProtocolVersion = 1

ProtocolVersion is the ACP version this agent speaks (and its latest).

Variables

This section is empty.

Functions

This section is empty.

Types

type Agent

type Agent struct {
	// contains filtered or unexported fields
}

Agent is celeste's ACP agent: the Handler of a Conn.

func NewAgent

func NewAgent(deps Deps) *Agent

NewAgent returns an agent; Attach gives it the connection it answers on.

func (*Agent) Attach

func (a *Agent) Attach(c *Conn)

Attach sets the connection the agent sends its requests and notifications on.

func (*Agent) Close

func (a *Agent) Close()

Close shuts the agent down: later requests are answered with an internal error, running prompts are cancelled (and waited for, briefly), and every session's Env is closed. Nothing is logged once it returns.

func (*Agent) Notify

func (a *Agent) Notify(method string, params json.RawMessage)

Notify implements Handler. It runs on the read loop and never blocks.

func (*Agent) Received

func (a *Agent) Received(method string, params json.RawMessage)

Received implements Receiver: a session/prompt is counted as arrived before its goroutine starts, so a session/cancel read right after it cancels it even if it has not started yet.

func (*Agent) Request

func (a *Agent) Request(ctx context.Context, method string, params json.RawMessage) (any, *RPCError)

Request implements Handler.

type AgentCapabilities

type AgentCapabilities struct {
	LoadSession        bool               `json:"loadSession"`
	PromptCapabilities PromptCapabilities `json:"promptCapabilities"`
	McpCapabilities    McpCapabilities    `json:"mcpCapabilities"`
}

AgentCapabilities are what the agent supports.

type AuthMethod

type AuthMethod struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

AuthMethod is one way to authenticate (celeste advertises none).

type AuthenticateParams

type AuthenticateParams struct {
	MethodID string `json:"methodId"`
}

AuthenticateParams is the client's authenticate request.

type CancelParams

type CancelParams struct {
	SessionID string `json:"sessionId"`
}

CancelParams is the session/cancel notification.

type ClientCapabilities

type ClientCapabilities struct {
	FS       FileSystemCapabilities `json:"fs"`
	Terminal bool                   `json:"terminal"`
}

ClientCapabilities are what the editor offers the agent.

type Conn

type Conn struct {
	// Logf, when set before Serve, logs lines the connection drops (their
	// length and why, never their content) and recovered Notify panics.
	Logf func(format string, args ...any)
	// contains filtered or unexported fields
}

Conn is a bidirectional JSON-RPC 2.0 connection over newline-delimited JSON (ACP's framing): it serves incoming requests and notifications to a Handler and lets the agent send its own requests and notifications.

func NewConn

func NewConn(r io.Reader, w io.Writer, h Handler) *Conn

NewConn returns a connection that reads r and writes w; Serve starts it.

func (*Conn) Call

func (c *Conn) Call(ctx context.Context, method string, params, result any) error

Call sends a request to the client and waits for its answer, the end of ctx, or the connection closing.

func (*Conn) Notify

func (c *Conn) Notify(method string, params any) error

Notify sends a notification to the client.

func (*Conn) Serve

func (c *Conn) Serve(ctx context.Context) error

Serve reads messages until EOF or ctx ends; requests run on their own goroutines (ruling 2). Pending Calls fail once it returns. When ctx ends Serve returns at once; its read goroutine exits when the reader next returns (the caller closes it, or the process exits). A line longer than the 64 MiB cap is dropped, answered -32600 if its id can be found, and the connection keeps serving.

type ContentBlock

type ContentBlock struct {
	Type     string            `json:"type"`
	Text     string            `json:"text,omitempty"`
	Data     string            `json:"data,omitempty"`
	MimeType string            `json:"mimeType,omitempty"`
	URI      string            `json:"uri,omitempty"`
	Name     string            `json:"name,omitempty"`
	Resource *ResourceContents `json:"resource,omitempty"`
}

ContentBlock is one block of a prompt or a message: text, image, audio, resource_link (uri, name) or an embedded resource.

func TextBlock

func TextBlock(text string) ContentBlock

TextBlock is a text content block.

func (ContentBlock) MarshalJSON

func (b ContentBlock) MarshalJSON() ([]byte, error)

MarshalJSON always writes a text block's text: the schema requires it, also when it is empty.

type ContentChunk

type ContentChunk struct {
	SessionUpdate string       `json:"sessionUpdate"`
	Content       ContentBlock `json:"content"`
}

ContentChunk is a user_message_chunk, agent_message_chunk or agent_thought_chunk update.

func AgentMessageChunk

func AgentMessageChunk(text string) ContentChunk

AgentMessageChunk is an agent_message_chunk update with text.

func AgentThoughtChunk

func AgentThoughtChunk(text string) ContentChunk

AgentThoughtChunk is an agent_thought_chunk update with text.

func UserMessageChunk

func UserMessageChunk(text string) ContentChunk

UserMessageChunk is a user_message_chunk update with text.

type Deps

type Deps struct {
	// Config loads celeste's configuration (the agent uses celeste's own
	// config and keys, never the editor's).
	Config func() (*config.Config, error)
	// Sessions is the session store ACP sessions map onto.
	Sessions *config.SessionManager
	// Home is the user's home directory (hooks trust store).
	Home string
	// Logf logs to the log file; never to stdout, which is the protocol.
	Logf func(format string, args ...any)
}

Deps are what the agent needs from the celeste process.

type EnvVariable

type EnvVariable struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

EnvVariable is one environment variable of a stdio MCP server.

type FileSystemCapabilities

type FileSystemCapabilities struct {
	ReadTextFile  bool `json:"readTextFile"`
	WriteTextFile bool `json:"writeTextFile"`
}

FileSystemCapabilities are the editor's fs/* methods.

type Handler

type Handler interface {
	// Request answers a request; return (nil, nil) for a null result.
	// Each request runs on its own goroutine.
	Request(ctx context.Context, method string, params json.RawMessage) (any, *RPCError)
	// Notify handles a notification. It runs on the read loop, so it must
	// not block (session/cancel has to get through while prompts run).
	Notify(method string, params json.RawMessage)
}

Handler serves the requests and notifications a Conn reads.

type InitializeParams

type InitializeParams struct {
	ProtocolVersion    int                `json:"protocolVersion"`
	ClientCapabilities ClientCapabilities `json:"clientCapabilities"`
}

InitializeParams is the client's initialize request.

type InitializeResult

type InitializeResult struct {
	ProtocolVersion   int               `json:"protocolVersion"`
	AgentCapabilities AgentCapabilities `json:"agentCapabilities"`
	AuthMethods       []AuthMethod      `json:"authMethods"`
}

InitializeResult is the agent's answer to initialize.

type LoadSessionParams

type LoadSessionParams struct {
	SessionID  string      `json:"sessionId"`
	Cwd        string      `json:"cwd"`
	McpServers []McpServer `json:"mcpServers"`
	// AdditionalDirectories are extra workspace roots (W4f reads only cwd).
	AdditionalDirectories []string `json:"additionalDirectories,omitempty"`
}

LoadSessionParams is session/load. Its answer is an object (the schema's LoadSessionResponse, all fields optional), not null.

type Location

type Location struct {
	Path string `json:"path"`
	Line *int   `json:"line,omitempty"`
}

Location is a file a tool call touches.

type McpCapabilities

type McpCapabilities struct {
	HTTP bool `json:"http"`
	SSE  bool `json:"sse"`
}

McpCapabilities are the MCP transports the agent accepts from the client besides stdio.

type McpServer

type McpServer struct {
	Type    string        `json:"type,omitempty"`
	Name    string        `json:"name"`
	Command string        `json:"command,omitempty"`
	Args    []string      `json:"args,omitempty"`
	Env     []EnvVariable `json:"env,omitempty"`
	URL     string        `json:"url,omitempty"`
}

McpServer is an MCP server the client asks the agent to connect. Stdio servers carry no type; http and sse ones do.

type NewSessionParams

type NewSessionParams struct {
	Cwd        string      `json:"cwd"`
	McpServers []McpServer `json:"mcpServers"`
	// AdditionalDirectories are extra workspace roots (W4f reads only cwd).
	AdditionalDirectories []string `json:"additionalDirectories,omitempty"`
}

NewSessionParams is session/new.

type NewSessionResult

type NewSessionResult struct {
	SessionID string `json:"sessionId"`
}

NewSessionResult is session/new's answer.

type PermissionOption

type PermissionOption struct {
	OptionID string `json:"optionId"`
	Name     string `json:"name"`
	Kind     string `json:"kind"`
}

PermissionOption is one choice offered in a permission prompt.

type PermissionOutcome

type PermissionOutcome struct {
	Outcome  string `json:"outcome"`
	OptionID string `json:"optionId,omitempty"`
}

PermissionOutcome is {outcome: "selected", optionId} or {outcome: "cancelled"}.

type Plan

type Plan struct {
	SessionUpdate string      `json:"sessionUpdate"`
	Entries       []PlanEntry `json:"entries"`
}

Plan is a plan update; it replaces the whole plan.

func NewPlan

func NewPlan(entries []PlanEntry) Plan

NewPlan is a plan update with entries ([] when there are none).

type PlanEntry

type PlanEntry struct {
	Content  string `json:"content"`
	Priority string `json:"priority"`
	Status   string `json:"status"`
}

PlanEntry is one plan entry. Priority is high, medium or low; Status is pending, in_progress or completed.

type PromptCapabilities

type PromptCapabilities struct {
	Image           bool `json:"image"`
	Audio           bool `json:"audio"`
	EmbeddedContext bool `json:"embeddedContext"`
}

PromptCapabilities are the content blocks a prompt may carry beyond text and resource links.

type PromptParams

type PromptParams struct {
	SessionID string         `json:"sessionId"`
	Prompt    []ContentBlock `json:"prompt"`
}

PromptParams is session/prompt.

type PromptResult

type PromptResult struct {
	StopReason string `json:"stopReason"`
}

PromptResult is session/prompt's answer.

type RPCError

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

RPCError is a JSON-RPC 2.0 error object.

func (*RPCError) Error

func (e *RPCError) Error() string

type Receiver

type Receiver interface {
	Received(method string, params json.RawMessage)
}

Receiver is an optional Handler hook: Received runs on the read loop when a request arrives, before the goroutine that serves it starts, so a notification read after the request (session/cancel) is handled knowing the request came first. It must not block.

type RequestPermissionParams

type RequestPermissionParams struct {
	SessionID string             `json:"sessionId"`
	ToolCall  ToolCallUpdate     `json:"toolCall"`
	Options   []PermissionOption `json:"options"`
}

RequestPermissionParams is the agent's session/request_permission.

type RequestPermissionResult

type RequestPermissionResult struct {
	Outcome PermissionOutcome `json:"outcome"`
}

RequestPermissionResult is the client's answer.

type ResourceContents

type ResourceContents struct {
	URI      string `json:"uri"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
	MimeType string `json:"mimeType,omitempty"`
}

ResourceContents is an embedded resource: text or a base64 blob.

type SessionNotification

type SessionNotification struct {
	SessionID string `json:"sessionId"`
	Update    any    `json:"update"`
}

SessionNotification is the session/update notification.

type ToolCall

type ToolCall struct {
	SessionUpdate string            `json:"sessionUpdate"`
	ToolCallID    string            `json:"toolCallId"`
	Title         string            `json:"title"`
	Name          string            `json:"name,omitempty"`
	Kind          string            `json:"kind,omitempty"`
	Status        string            `json:"status,omitempty"`
	Content       []ToolCallContent `json:"content,omitempty"`
	Locations     []Location        `json:"locations,omitempty"`
	RawInput      any               `json:"rawInput,omitempty"`
	RawOutput     any               `json:"rawOutput,omitempty"`
}

ToolCall is a tool_call update: a new tool call.

type ToolCallContent

type ToolCallContent struct {
	Type    string        `json:"type"`
	Content *ContentBlock `json:"content,omitempty"`
}

ToolCallContent is content a tool call produced; celeste sends the "content" type (a content block).

func TextToolContent

func TextToolContent(text string) ToolCallContent

TextToolContent is a tool call's text content.

type ToolCallUpdate

type ToolCallUpdate struct {
	SessionUpdate string            `json:"sessionUpdate,omitempty"`
	ToolCallID    string            `json:"toolCallId"`
	Title         string            `json:"title,omitempty"`
	Name          string            `json:"name,omitempty"`
	Kind          string            `json:"kind,omitempty"`
	Status        string            `json:"status,omitempty"`
	Content       []ToolCallContent `json:"content,omitempty"`
	Locations     []Location        `json:"locations,omitempty"`
	RawInput      any               `json:"rawInput,omitempty"`
	RawOutput     any               `json:"rawOutput,omitempty"`
}

ToolCallUpdate changes a tool call. As a session update its SessionUpdate is "tool_call_update"; inside session/request_permission it is left empty and omitted.

Jump to

Keyboard shortcuts

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