Documentation
¶
Index ¶
- func DiscoverAvailableCommands(cwd string) []acp.AvailableCommand
- func Serve(ctx context.Context, cfg ServeConfig) error
- func StoreSessionID(id string) string
- type Agent
- func (a *Agent) Authenticate(context.Context, acp.AuthenticateRequest) (acp.AuthenticateResponse, error)
- func (a *Agent) Cancel(_ context.Context, params acp.CancelNotification) error
- func (a *Agent) CloseSession(ctx context.Context, params acp.CloseSessionRequest) (acp.CloseSessionResponse, error)
- func (a *Agent) Initialize(_ context.Context, _ acp.InitializeRequest) (acp.InitializeResponse, error)
- func (a *Agent) ListSessions(ctx context.Context, params acp.ListSessionsRequest) (acp.ListSessionsResponse, error)
- func (a *Agent) LoadSession(ctx context.Context, params acp.LoadSessionRequest) (acp.LoadSessionResponse, error)
- func (a *Agent) Logout(context.Context, acp.LogoutRequest) (acp.LogoutResponse, error)
- func (a *Agent) NewSession(_ context.Context, params acp.NewSessionRequest) (acp.NewSessionResponse, error)
- func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.PromptResponse, error)
- func (a *Agent) ResumeSession(ctx context.Context, params acp.ResumeSessionRequest) (acp.ResumeSessionResponse, error)
- func (a *Agent) SetAgentConnection(conn *acp.AgentSideConnection)
- func (a *Agent) SetSessionConfigOption(context.Context, acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error)
- func (a *Agent) SetSessionMode(context.Context, acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error)
- type FileSessionStore
- type PromptHandler
- type PromptResult
- type PromptTurn
- type RuntimeConfig
- type ServeConfig
- type SessionStore
- type SessionSummary
- type SessionUpdater
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiscoverAvailableCommands ¶ added in v0.0.25
func DiscoverAvailableCommands(cwd string) []acp.AvailableCommand
DiscoverAvailableCommands resolves slash commands for a specific session cwd. User skills are always included, while project skills are discovered from the nearest ancestor directories of the session working directory.
func Serve ¶
func Serve(ctx context.Context, cfg ServeConfig) error
Serve runs pi as an ACP agent over the given byte streams and returns when the peer disconnects or ctx is canceled. Serve does not close In or Out; callers own the streams.
func StoreSessionID ¶ added in v0.0.92
StoreSessionID maps an ACP session id to the id its transcript is persisted under. Safe ids pass through unchanged, so the on-disk session carries the id the client knows and `pi --session <id>` can reopen it. Anything else — path separators, a leading dot, control characters, an over-long string — is replaced by a stable hash, so a hostile id cannot name a path outside the sessions directory and the same id still resolves to the same transcript.
Types ¶
type Agent ¶
type Agent struct {
// AgentInfo advertises pi to the peer during initialize.
AgentInfo acp.Implementation
// Handler processes one prompt turn. If nil, EchoPromptHandler is used.
Handler PromptHandler
// AvailableCommandsResolver resolves slash commands for a session cwd.
// If nil, the agent falls back to the static Skills/Subagents slices.
AvailableCommandsResolver func(cwd string) []acp.AvailableCommand
// Skills are the loaded skill definitions used to populate AvailableCommands.
Skills []extension.Skill
// Subagents are the loaded sub-agent definitions used to populate AvailableCommands.
Subagents []subagent.AgentConfig
// Logger is used for diagnostic output. If nil, a discard logger is used.
Logger *slog.Logger
// Sessions persists transcripts across processes and backs session/load,
// session/resume and session/list. Nil keeps sessions in memory only.
Sessions SessionStore
// contains filtered or unexported fields
}
Agent implements acp.Agent for pi. The zero value is a usable skeleton that accepts prompts and echoes them back through EchoPromptHandler.
func (*Agent) Authenticate ¶
func (a *Agent) Authenticate(context.Context, acp.AuthenticateRequest) (acp.AuthenticateResponse, error)
Authenticate always succeeds; pi does not require ACP-level authentication.
func (*Agent) Cancel ¶
Cancel routes an ACP cancel notification to the in-flight Prompt for the session, if any, by canceling the context passed to its PromptHandler. If no prompt is running for the id, the notification is silently dropped — ACP cancellation is best-effort per spec.
func (*Agent) CloseSession ¶ added in v0.0.31
func (a *Agent) CloseSession(ctx context.Context, params acp.CloseSessionRequest) (acp.CloseSessionResponse, error)
CloseSession closes a session and cancels any in-flight prompt work.
func (*Agent) Initialize ¶
func (a *Agent) Initialize(_ context.Context, _ acp.InitializeRequest) (acp.InitializeResponse, error)
Initialize advertises pi's baseline capabilities. EmbeddedContext is on so Zed can inline file context; Image defaults to false until zed-09 wires the provider gate. session/load and session/resume are always offered; session/list only when a SessionStore can answer it.
func (*Agent) ListSessions ¶
func (a *Agent) ListSessions(ctx context.Context, params acp.ListSessionsRequest) (acp.ListSessionsResponse, error)
ListSessions reports the sessions the SessionStore has transcripts for, newest first, optionally narrowed to one working directory. Without a store there is nothing to list, and method-not-found tells the client so.
func (*Agent) LoadSession ¶
func (a *Agent) LoadSession(ctx context.Context, params acp.LoadSessionRequest) (acp.LoadSessionResponse, error)
LoadSession binds the supplied session id to this agent with the given cwd and, when a persisted transcript exists for it, replays that transcript to the client before responding — the protocol's contract for session/load, and what lets an editor show the conversation it is about to continue. Loading is idempotent: repeated loads refresh the session's cwd and replay again. See bindSession for how unknown ids are treated with and without a store.
func (*Agent) Logout ¶ added in v0.0.33
func (a *Agent) Logout(context.Context, acp.LogoutRequest) (acp.LogoutResponse, error)
Logout terminates the current authenticated session. Pi has no auth state, so this is a no-op required by the acp.Agent interface.
func (*Agent) NewSession ¶
func (a *Agent) NewSession(_ context.Context, params acp.NewSessionRequest) (acp.NewSessionResponse, error)
NewSession registers a new session and returns its identifier.
func (*Agent) Prompt ¶
func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.PromptResponse, error)
Prompt bridges a prompt request through the configured handler. Handlers own all session-update emission through turn.Updater; Prompt itself does not emit an AgentMessageText summary, avoiding the duplicate-message bug. The handler runs under a cancelable context registered on the session so an inbound ACP Cancel notification can abort the in-flight turn. When the request carries a MessageId it is echoed back as UserMessageId.
func (*Agent) ResumeSession ¶ added in v0.0.31
func (a *Agent) ResumeSession(ctx context.Context, params acp.ResumeSessionRequest) (acp.ResumeSessionResponse, error)
ResumeSession binds an existing session id to this agent without replaying its transcript — the client already shows it and only needs the next prompt to continue the conversation. The pi runtime picks the persisted history up under the same id on that prompt.
func (*Agent) SetAgentConnection ¶
func (a *Agent) SetAgentConnection(conn *acp.AgentSideConnection)
SetAgentConnection wires the agent-side connection after construction so Prompt handlers can stream updates. Called from Serve; tests may skip it.
func (*Agent) SetSessionConfigOption ¶
func (a *Agent) SetSessionConfigOption(context.Context, acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error)
SetSessionConfigOption is not yet supported.
func (*Agent) SetSessionMode ¶
func (a *Agent) SetSessionMode(context.Context, acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error)
SetSessionMode is not yet supported; Slice 10 wires mode flows.
type FileSessionStore ¶ added in v0.0.92
type FileSessionStore struct {
// contains filtered or unexported fields
}
FileSessionStore is a SessionStore over pi's on-disk session store — the same JSONL directory the CLI writes to, so a transcript an editor started over ACP is resumable from the terminal and vice versa.
func NewFileSessionStore ¶ added in v0.0.92
func NewFileSessionStore(svc *pisession.FileService) *FileSessionStore
NewFileSessionStore wraps svc as a SessionStore.
func (*FileSessionStore) Exists ¶ added in v0.0.92
func (s *FileSessionStore) Exists(ctx context.Context, sessionID string) bool
Exists implements SessionStore.
func (*FileSessionStore) List ¶ added in v0.0.92
func (s *FileSessionStore) List(_ context.Context) ([]SessionSummary, error)
List implements SessionStore.
func (*FileSessionStore) Replay ¶ added in v0.0.92
func (s *FileSessionStore) Replay(ctx context.Context, sessionID string, updater SessionUpdater) error
Replay implements SessionStore.
type PromptHandler ¶
type PromptHandler func(ctx context.Context, turn PromptTurn) (PromptResult, error)
PromptHandler runs one ACP prompt turn for a session. The skeleton uses EchoPromptHandler; the real pi runtime is plugged in behind this seam by later slices.
func NewPromptHandler ¶
func NewPromptHandler(rt RuntimeConfig) PromptHandler
NewPromptHandler returns a real pi-backed ACP prompt handler. It maintains a per-ACP-session cache so the pi agent (and its ADK session history) is reused across turns rather than re-created on every prompt.
type PromptResult ¶
type PromptResult struct {
FinalText string
StopReason acp.StopReason
}
PromptResult is the adapter output returned from a PromptHandler.
func EchoPromptHandler ¶
func EchoPromptHandler(ctx context.Context, turn PromptTurn) (PromptResult, error)
EchoPromptHandler is the default PromptHandler used when none is configured. It streams a deterministic "echo: <prompt>" reply through the turn's updater and returns the same text as PromptResult.FinalText. The stream is the sole emission surface so Prompt no longer needs to re-send FinalText.
type PromptTurn ¶
type PromptTurn struct {
SessionID string
CWD string
Prompt string
Updater SessionUpdater
}
PromptTurn is the adapter input handed to a PromptHandler.
type RuntimeConfig ¶
type RuntimeConfig struct {
Model string
BaseURL string
Headers []string
Insecure bool
System string
Version string
LoadConfig func() (config.Config, error)
SandboxRootFunc func(turn PromptTurn) string
// SessionService, when set, persists each ACP session's transcript under
// its ACP session id (see StoreSessionID), so a session survives the
// process that started it: the next process to see the same id — after
// an editor restart, or after Substrate replaces an actor — continues
// the conversation instead of starting over. Nil keeps transcripts in
// memory for the life of the process.
SessionService adksession.Service
}
RuntimeConfig controls how the ACP prompt handler resolves and builds the pi runtime.
type ServeConfig ¶
type ServeConfig struct {
// Agent is the pi ACP agent. Required.
Agent *Agent
// In is the byte stream from the ACP client. Typically os.Stdin.
In io.Reader
// Out is the byte stream to the ACP client. Typically os.Stdout.
Out io.Writer
// Logger receives diagnostic output from the ACP connection. Optional.
Logger *slog.Logger
}
ServeConfig configures a server.Serve run.
type SessionStore ¶ added in v0.0.92
type SessionStore interface {
// Exists reports whether a transcript is persisted for the session.
Exists(ctx context.Context, sessionID string) bool
// Replay re-emits the persisted transcript through updater as ACP
// session updates, in order. session/load calls it before responding.
Replay(ctx context.Context, sessionID string, updater SessionUpdater) error
// List returns every persisted session, newest first.
List(ctx context.Context) ([]SessionSummary, error)
}
SessionStore is the persistence seam behind session/load, session/resume and session/list. Ids are the ACP session ids the client knows; the store maps them to whatever it keeps on disk (see StoreSessionID). A nil store leaves the agent with in-memory sessions only: every id is accepted on load and resume because there is nothing to check it against, and session/list is not advertised.
type SessionSummary ¶ added in v0.0.92
SessionSummary describes one persisted session, as reported by session/list.
type SessionUpdater ¶
type SessionUpdater interface {
Update(ctx context.Context, update acp.SessionUpdate) error
}
SessionUpdater streams session updates back to the ACP peer. A nil Updater silently discards updates so PromptHandlers work both with and without a live connection (tests vs. live serve).