98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
---
|
|
title: "RPC Mode"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/pi-agent/references/rpc.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-27
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: false
|
|
---
|
|
|
|
# RPC Mode
|
|
|
|
Source: https://pi.dev/docs/latest/rpc
|
|
|
|
RPC mode runs Pi headlessly over stdin/stdout JSONL. Use it for language-agnostic clients, IDE integrations, custom UIs, or subprocess isolation.
|
|
|
|
```bash
|
|
pi --mode rpc [options]
|
|
```
|
|
|
|
Common options: `--provider`, `--model`, `--name/-n`, `--no-session`, `--session-dir`.
|
|
|
|
For Node/TypeScript in-process apps, prefer the SDK unless subprocess isolation is desired.
|
|
|
|
## Framing
|
|
|
|
Commands are JSON objects sent to stdin, one per line. Responses and events are JSON objects streamed to stdout, one per line. Use LF (`
|
|
`) as the only record delimiter; strip trailing `
|
|
` for CRLF input. Do not use generic line readers that split on Unicode separators. Node `readline` is not protocol-compliant because it also splits on U+2028/U+2029.
|
|
|
|
Commands can include optional `id`; corresponding responses echo it. Events do not include `id`.
|
|
|
|
## Prompting Commands
|
|
|
|
`prompt`: send a user prompt. Response means accepted, queued, or handled; later failures come through events.
|
|
|
|
```json
|
|
{"id":"req-1","type":"prompt","message":"Hello"}
|
|
```
|
|
|
|
Add images with `images: [{"type":"image","data":"base64...","mimeType":"image/png"}]`.
|
|
|
|
If streaming, include `streamingBehavior: "steer"` or `"followUp"`. Extension commands execute immediately; skills and prompt templates expand before sending/queueing.
|
|
|
|
`steer`: queue a steering message delivered after current assistant turn tool calls.
|
|
|
|
`follow_up`: queue a message delivered after the agent is fully done.
|
|
|
|
`abort`: abort current agent operation.
|
|
|
|
`new_session`: start fresh, optionally with `parentSession`; can be cancelled by extension.
|
|
|
|
## State and Model Commands
|
|
|
|
- `get_state`: returns model, thinkingLevel, streaming/compacting state, queue modes, session info, message counts, auto-compaction.
|
|
- `get_messages`: returns all `AgentMessage` objects.
|
|
- `set_model`: switch model.
|
|
- `cycle_model`: cycle next available/scoped model.
|
|
- `get_available_models`: list configured models.
|
|
- `set_thinking_level`: set `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
|
|
- `cycle_thinking_level`: cycle supported levels.
|
|
|
|
## Queue, Compaction, Retry
|
|
|
|
- `set_steering_mode`: `all` or `one-at-a-time`.
|
|
- `set_follow_up_mode`: `all` or `one-at-a-time`.
|
|
- `compact`: manually compact; accepts `customInstructions`.
|
|
- `set_auto_compaction`: enable/disable auto compaction.
|
|
- `set_auto_retry`: enable/disable transient-error retry.
|
|
- `abort_retry`: cancel retry delay and stop retrying.
|
|
|
|
## Bash
|
|
|
|
`bash` executes immediately and returns output. A `BashExecutionMessage` is stored in agent state but no event is emitted for it. The output reaches the LLM on the next `prompt`.
|
|
|
|
`abort_bash` aborts a running bash command.
|
|
|
|
## Session Commands
|
|
|
|
- `get_session_stats`: token totals, cost, context usage.
|
|
- `export_html`: export current session.
|
|
- `switch_session`: load another session; extension can cancel.
|
|
- `fork`: create a new fork from an earlier user message.
|
|
- `clone`: duplicate active branch into a new session.
|
|
- `get_fork_messages`: list forkable user messages.
|
|
- `get_last_assistant_text`: last assistant text or null.
|
|
- `set_session_name`: set display name.
|
|
|
|
## Commands Discovery
|
|
|
|
`get_commands` lists extension commands, prompt templates, and skills. Built-in TUI commands such as `/settings` are interactive-only and are not included.
|
|
|
|
## Events
|
|
|
|
RPC streams the same major events as the SDK/JSON mode: agent, turn, message, tool execution, queue, compaction, retry, and extension errors.
|