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
- type Agent
- type AgentCapabilities
- type AuthMethod
- type AuthenticateParams
- type CancelParams
- type ClientCapabilities
- type Conn
- type ContentBlock
- type ContentChunk
- type Deps
- type EnvVariable
- type FileSystemCapabilities
- type Handler
- type InitializeParams
- type InitializeResult
- type LoadSessionParams
- type Location
- type McpCapabilities
- type McpServer
- type NewSessionParams
- type NewSessionResult
- type PermissionOption
- type PermissionOutcome
- type Plan
- type PlanEntry
- type PromptCapabilities
- type PromptParams
- type PromptResult
- type RPCError
- type Receiver
- type RequestPermissionParams
- type RequestPermissionResult
- type ResourceContents
- type SessionNotification
- type ToolCall
- type ToolCallContent
- type ToolCallUpdate
Constants ¶
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.
const ( StopEndTurn = "end_turn" StopMaxTokens = "max_tokens" StopMaxTurnRequests = "max_turn_requests" StopRefusal = "refusal" StopCancelled = "cancelled" )
Stop reasons.
const ( BlockText = "text" BlockImage = "image" BlockAudio = "audio" BlockResourceLink = "resource_link" BlockResource = "resource" )
Content block types.
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.
const ( ToolKindRead = "read" ToolKindEdit = "edit" ToolKindDelete = "delete" ToolKindMove = "move" ToolKindSearch = "search" ToolKindExecute = "execute" ToolKindThink = "think" ToolKindFetch = "fetch" ToolKindSwitchMode = "switch_mode" ToolKindOther = "other" )
Tool kinds.
const ( ToolStatusPending = "pending" ToolStatusInProgress = "in_progress" ToolStatusCompleted = "completed" ToolStatusFailed = "failed" )
Tool call statuses.
const ( OptionAllowOnce = "allow_once" OptionAllowAlways = "allow_always" OptionRejectOnce = "reject_once" OptionRejectAlways = "reject_always" )
Permission option kinds.
const ( OutcomeSelected = "selected" OutcomeCancelled = "cancelled" )
Permission outcomes.
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 (*Agent) Attach ¶
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.
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 (*Conn) Call ¶
Call sends a request to the client and waits for its answer, the end of ctx, or the connection closing.
func (*Conn) Serve ¶
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 (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 ¶
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 McpCapabilities ¶
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.
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.
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 ¶
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.