Documentation
¶
Overview ¶
Package pirpc implements the stdio NDJSON RPC protocol spoken by upstream pi's `--mode rpc`, so that the `pi-acp` ACP adapter (https://github.com/svkozak/pi-acp) can drive pi-go unmodified.
This is deliberately a compatibility facade, not pi-go's preferred integration path. pi-go speaks ACP natively via `pi acp-server`, which needs no Node process and no translation layer. Prefer that unless you specifically need pi-acp's adapter-side features.
Wire format ¶
Commands arrive on stdin as newline-delimited JSON objects carrying a "type" discriminator and a client-generated "id":
{"type":"prompt","id":"<uuid>","message":"hello"}
Every command is answered with exactly one response object echoing the id:
{"type":"response","id":"<uuid>","command":"prompt","success":true}
Any other object written to stdout is treated by the adapter as an asynchronous event. Non-JSON stdout lines are tolerated by pi-acp as a human-readable "prelude", so stray output is not fatal — but this server does not rely on that.
Turn lifecycle ¶
A prompt is acknowledged immediately and executed on a goroutine, so that `abort` remains readable from stdin while the model is streaming. The turn emits agent_start, then message_update / tool_execution_* events, and always terminates with agent_settled. pi-acp resolves the ACP `session/prompt` request on agent_settled and on nothing else, so failing to emit it would hang the client forever; Run guarantees it via defer.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Agent *agent.Agent
SessionID string
In io.Reader
Out io.Writer
Log *logger.Logger
Model string
// ModelSwitcher builds a replacement LLM for a model name, returning the
// resolved model and provider. When nil, set_model is rejected rather
// than silently accepted — a client that believes it switched models but
// did not is worse than one told the switch is unsupported.
//
// providerHint carries the provider the ACP client named ("" if it named
// none). Honoring it matters: pi-go otherwise infers the provider from
// the configured default role, which would route e.g. an OpenAI model
// through Ollama when the default role happens to be an Ollama model.
ModelSwitcher func(ctx context.Context, modelName, providerHint string) (adkmodel.LLM, string, string, error)
}
Config holds the stdio RPC server configuration.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves pi-compatible RPC commands over stdio.
func (*Server) Run ¶
Run reads commands until stdin closes or ctx is canceled.
Input is scanned line-by-line rather than streamed through a json.Decoder: a decoder cannot resynchronize after a syntax error, so one malformed line would spin forever. Framing is newline-delimited by definition here, which makes each line independently recoverable.