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 ¶
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.
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 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.