acpserver

package
v0.54.7 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package acpserver will adapt Suga's personal agent to ACP over stdio.

Index

Constants

This section is empty.

Variables

View Source
var ErrMemoryWriteRejected = errors.New("用户拒绝写入记忆")

ErrMemoryWriteRejected is the refusal of a memory write confirmation.

View Source
var ErrPermissionDenied = errors.New("ACP tool permission denied")
View Source
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) Cancel

func (a *Agent) Cancel(_ context.Context, req acp.CancelNotification) error

func (*Agent) CloseSession

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 (*Agent) ListSessions

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 (*Agent) Logout

func (*Agent) NewSession

func (*Agent) Prompt

func (a *Agent) Prompt(ctx context.Context, req acp.PromptRequest) (acp.PromptResponse, error)

func (*Agent) ResumeSession

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

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

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)

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.

Jump to

Keyboard shortcuts

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