Documentation
¶
Overview ¶
Package acpserver will adapt Suga's personal agent to ACP over stdio.
Index ¶
- Variables
- func Serve(ctx context.Context, input io.Reader, output io.Writer, open OpenRuntime, ...) error
- type Agent
- func (*Agent) Authenticate(context.Context, acp.AuthenticateRequest) (acp.AuthenticateResponse, error)
- func (a *Agent) Cancel(_ context.Context, req acp.CancelNotification) error
- func (a *Agent) CloseSession(ctx context.Context, req acp.CloseSessionRequest) (acp.CloseSessionResponse, error)
- func (a *Agent) Initialize(_ context.Context, req acp.InitializeRequest) (acp.InitializeResponse, error)
- func (a *Agent) ListSessions(ctx context.Context, req acp.ListSessionsRequest) (acp.ListSessionsResponse, error)
- func (a *Agent) LoadSession(ctx context.Context, req acp.LoadSessionRequest) (acp.LoadSessionResponse, error)
- func (*Agent) Logout(context.Context, acp.LogoutRequest) (acp.LogoutResponse, error)
- func (a *Agent) NewSession(ctx context.Context, req acp.NewSessionRequest) (acp.NewSessionResponse, error)
- func (a *Agent) Prompt(ctx context.Context, req acp.PromptRequest) (acp.PromptResponse, error)
- func (a *Agent) ResumeSession(ctx context.Context, req acp.ResumeSessionRequest) (acp.ResumeSessionResponse, error)
- func (a *Agent) SetConnection(conn *acp.AgentSideConnection)
- func (a *Agent) SetSessionConfigOption(ctx context.Context, req acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error)
- func (a *Agent) SetSessionMode(_ context.Context, req acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error)
- type ModelOption
- type OpenRuntime
- type PolicyDecision
- type Runtime
- type ServeOption
- type TurnGate
Constants ¶
This section is empty.
Variables ¶
var ErrMemoryWriteRejected = errors.New("用户拒绝写入记忆")
ErrMemoryWriteRejected is the refusal of a memory write confirmation.
var ErrPermissionDenied = errors.New("ACP tool permission denied")
var ErrReadOnly = errors.New("tool is unavailable in read_only mode")
Functions ¶
func Serve ¶
func Serve(ctx context.Context, input io.Reader, output io.Writer, open OpenRuntime, promptImage bool, opts ...ServeOption) error
Serve uses stdout exclusively for ACP JSON-RPC frames. promptImage declares the image content block capability of session/prompt (this configuration's initialization has no session yet, so the caller decides from configuration).
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent owns ACP connection state; personal.Runner owns persisted conversation state.
func New ¶
func New(open OpenRuntime, promptImage bool, opts ...ServeOption) *Agent
func (*Agent) Authenticate ¶
func (*Agent) Authenticate(context.Context, acp.AuthenticateRequest) (acp.AuthenticateResponse, error)
func (*Agent) CloseSession ¶
func (a *Agent) CloseSession(ctx context.Context, req acp.CloseSessionRequest) (acp.CloseSessionResponse, error)
CloseSession answers session/close (SDK contract): a running turn of the session is cancelled — as if session/cancel had been called — and this process waits for it to wind down before the session state is released. The session itself is not deleted (data governance stays with `suga data gc`); a prompt on the closed session is refused with invalid params.
func (*Agent) Initialize ¶
func (a *Agent) Initialize(_ context.Context, req acp.InitializeRequest) (acp.InitializeResponse, error)
func (*Agent) ListSessions ¶
func (a *Agent) ListSessions(ctx context.Context, req acp.ListSessionsRequest) (acp.ListSessionsResponse, error)
ListSessions answers session/list: the sessions of the requested directory (the request's cwd, else this process's working directory — the directory the client started suga in; design 2026-10-20 会话列表默认当前目录), newest first, listPageSize per page. Sub-agent sessions and archived ones stay hidden. _meta.suga/all lists every directory instead; the response's _meta reports how many sessions the other directories hold, and names the way out on an empty result (suga/hint). Only metadata is returned — never the conversation content of another directory's session.
func (*Agent) LoadSession ¶
func (a *Agent) LoadSession(ctx context.Context, req acp.LoadSessionRequest) (acp.LoadSessionResponse, error)
func (*Agent) Logout ¶
func (*Agent) Logout(context.Context, acp.LogoutRequest) (acp.LogoutResponse, error)
func (*Agent) NewSession ¶
func (a *Agent) NewSession(ctx context.Context, req acp.NewSessionRequest) (acp.NewSessionResponse, error)
func (*Agent) Prompt ¶
func (a *Agent) Prompt(ctx context.Context, req acp.PromptRequest) (acp.PromptResponse, error)
func (*Agent) ResumeSession ¶
func (a *Agent) ResumeSession(ctx context.Context, req acp.ResumeSessionRequest) (acp.ResumeSessionResponse, error)
ResumeSession answers session/resume: the same checks as session/load (the session exists, its directory is this request's directory, no turn is running) and no history is replayed — the client asked for the session without its messages. The response carries the initial modes and the config options like new/load do.
func (*Agent) SetConnection ¶
func (a *Agent) SetConnection(conn *acp.AgentSideConnection)
SetConnection runs after the connection has started serving requests, so conn is guarded by mu like the rest of the shared state.
func (*Agent) SetSessionConfigOption ¶
func (a *Agent) SetSessionConfigOption(ctx context.Context, req acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error)
SetSessionConfigOption applies one select's value to the session: the model select switches the main model for the next turn (refused while a turn runs), the mode select is session/set_mode under another id. Both return the full, up-to-date option list.
func (*Agent) SetSessionMode ¶
func (a *Agent) SetSessionMode(_ context.Context, req acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error)
type ModelOption ¶
type ModelOption struct {
Ref string // provider/model, as chat's :model accepts it
Name string // human label: the configured model id
// Thinking is the model's effective thinking level ("" = provider default).
Thinking string
}
ModelOption is one selectable main model of the configuration: its canonical provider/model ref (the value ACP clients pick) and the pieces the response shows beside it.
type OpenRuntime ¶
type OpenRuntime func(ctx context.Context, cwd string, readOnly bool, servers []mcp.ServerSettings, gate TurnGate) (Runtime, error)
OpenRuntime assembles a turn with the selected workspace, tool mode and turn gate. gate is nil when the runtime only creates or loads a session (no turn runs); the factory must then fail closed (deny every tool call).
type PolicyDecision ¶
type PolicyDecision func(call agentcore.ToolCall, tool agentcore.Tool) (action, rule, scope string, clamped, pathProtected bool)
PolicyDecision is the wiring-neutral result of the shared approval policy. action is one of allow, ask, or deny; rule is the representative rule summary, and scope is the stable key used by ACP session rules. clamped reports an allow downgraded by ClampAllow (always false until trust mode reads it); pathProtected reports that the target is a protected control-plane path, so an always session rule must not allow it silently.
type Runtime ¶
type Runtime struct {
Runner *personal.Runner
Close func() error
// ContextWindow is the model context size in tokens; wiring.Runtime supplies the
// effective model's window; 0 falls back to appconfig.DefaultContextWindow.
ContextWindow int
// LookupTool resolves a tool name to the registered tool, nil when
// unknown. Permission handling classifies calls by the tool's tools.Meta,
// never by name, so an MCP tool always needs permission.
LookupTool func(name string) agentcore.Tool
// Policy is the shared wiring policy. ACP adds session-level always rules
// around this immutable per-runtime decision function.
Policy PolicyDecision
// Vision is the live capability of the current model (nil = can see, the
// convention of personal.Config): an ACP prompt that brought image blocks
// tells the client once that they turn into text notes on this model.
Vision *tools.VisionGate
// Models are the selectable main models of this runtime's configuration
// (session/set_config_option's model select, design 2026-10-20); empty in
// runtimes built without a catalog (tests).
Models []ModelOption
// CurrentModel returns the provider/model ref a turn of this runtime uses
// ("" unknown).
CurrentModel func() string
// SwitchModel activates ref as sessionID's main model for the next turn
// (wiring.Runtime.SwitchModel); nil makes the select's application refused.
SwitchModel func(ctx context.Context, sessionID, ref string) (string, error)
// Translator is the startup-resolved host UI catalog of this runtime's
// client-facing notices; nil keeps the historical Chinese text.
Translator i18n.Translator
}
Runtime is one opening of the shared personal session store and Agent core.
type ServeOption ¶
type ServeOption func(*Agent)
ServeOption configures the agent Serve builds; the host assembly passes the startup-resolved catalog it resolved once, so client-facing notices read the same language as the rest of the process.
func WithApprovalMode ¶ added in v0.55.0
func WithApprovalMode(mode tools.ApprovalMode) ServeOption
WithApprovalMode fixes the approval tier of the whole ACP process (suga acp --approve/--yolo). A client cannot change it; each prompt's permission hook reads it, and trust only releases asks that were not downgraded for a protected path.
func WithTranslator ¶
func WithTranslator(tr i18n.Translator) ServeOption
WithTranslator installs the host UI catalog of the ACP server. Without it the historical Chinese text stays (compatibility runtimes built by tests).
type TurnGate ¶
type TurnGate interface {
agentcore.Hook
tools.Approver
ConfirmMemory(ctx context.Context, s memory.Scope, op memory.Op) error
}
TurnGate is the per-prompt ACP policy handed to the runtime factory. Its Hook side sends tool_call notifications and collects usage; its Approver side is installed as the approval layer of the tool stack (observe -> visibility -> approval -> base) and asks the client via session/request_permission. ConfirmMemory asks the client (also via session/request_permission) to approve a memory write from a tainted session: nil allows it, a refusal returns an error, a cancelled request returns context.Canceled.