print and rpc Modes

源码版本v0.73.1

pi has two non-interactive modes: print (one-shot, text or JSON output) and rpc (long-lived connection, JSON-RPC over stdin/stdout). print is for scripted invocations like pi -p "fix this bug"; rpc is for embedding pi into other GUI apps (VS Code extensions, web frontends). Both share AgentSessionRuntime, but their event subscription, output format, and extension UI integration are completely different.

Responsibilities

1. print mode: runPrintMode takes mode: "text" | "json". text mode outputs only the final assistant message text; json mode streams all AgentSessionEvents. See packages/coding-agent/src/modes/print-mode.ts:32-66.
2. rpc mode: runRpcMode uses attachJsonlLineReader to read JSON commands from stdin, dispatches 29 command types via handleCommand, and writes events and responses to stdout. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:48-70 and packages/coding-agent/src/modes/rpc/rpc-mode.ts:371-625.
3. Signal handling: both modes register SIGTERM / SIGHUP handlers that killTrackedDetachedChildren before disposeRuntime, so bash subprocesses don't leak. See packages/coding-agent/src/modes/print-mode.ts:47-63 and packages/coding-agent/src/modes/rpc/rpc-mode.ts:351-365.
4. Extension UI bridge: rpc mode implements createExtensionUIContext, forwarding extension dialog/widget requests to the client via extension_ui_request events, with the client responding via extension_ui_response. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:83-130.
5. Session replacement hooks: both modes register a rebind callback via runtimeHost.setRebindSession, which re-runs bindExtensions and resubscribes to events after a session switch. See packages/coding-agent/src/modes/print-mode.ts:67-108 and packages/coding-agent/src/modes/rpc/rpc-mode.ts:306-349.

Design Motivation

Why don't print and rpc share code? Their output contracts differ: print's stdout is one-way (either text or JSON lines), while rpc's stdin/stdout is bidirectional (commands in, events and responses out). rpc also has to manage a pending-Promise map for extension UI requests (waiting on client responses), a mechanism print doesn't need at all. Sharing would introduce unnecessary complexity, so each file implements its own rebindSession and handleEvent.

The 29 rpc command types (prompt, steer, follow_up, abort, new_session, get_state, set_model, cycle_model, bash, fork, clone, export_html, etc.) are a complete mapping of AgentSession's public API. A client can invoke any method AgentSession exposes via RPC, so pi can be embedded into a GUI written in any language, as long as it speaks JSON-RPC.

The print mode: "text" path only looks at the last assistant message: on success it writes content.text to stdout; on failure (stopReason === "error" || "aborted") it writes to stderr and returns exitCode 1. Simple and direct, suited to shell usage like pi -p "..." | jq.

Key Files

• packages/coding-agent/src/modes/print-mode.ts:14-26 — PrintModeOptions: mode, messages, initialMessage, initialImages.
• packages/coding-agent/src/modes/print-mode.ts:32-70 — runPrintMode signature, disposeRuntime, registerSignalHandlers, rebindSession.
• packages/coding-agent/src/modes/print-mode.ts:110-145 — main flow: send initialMessage, loop over messages, output the last assistant message in text mode.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts:1-13 — file header comment describing the rpc protocol (commands, responses, events, extension UI).
• packages/coding-agent/src/modes/rpc/rpc-mode.ts:48-70 — runRpcMode signature, output / success / error helpers.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts:83-130 — createDialogPromise: Promise + timeout + abort management for extension UI requests.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts:306-349 — rebindSession: rebinds extensions and session.subscribe to output events.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts:371-625 — handleCommand switch, 29 command branches.
• packages/coding-agent/src/modes/rpc/rpc-types.ts — RPC protocol type definitions (RpcCommand, RpcResponse, RpcExtensionUIRequest, etc.).

print mode text path, only outputting the text content of the last assistant message:

// packages/coding-agent/src/modes/print-mode.ts:128-145
if (mode === "text") {
	const state = session.state;
	const lastMessage = state.messages[state.messages.length - 1];

	if (lastMessage?.role === "assistant") {
		const assistantMsg = lastMessage as AssistantMessage;
		if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
			console.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);
			exitCode = 1;
		} else {
			for (const content of assistantMsg.content) {
				if (content.type === "text") {
					writeRawStdout(`${content.text}\n`);
				}
			}
		}
	}
}

rpc mode prompt command, using preflightResult to send a response right after the prompt is accepted:

// packages/coding-agent/src/modes/rpc/rpc-mode.ts:379-401
case "prompt": {
	let preflightSucceeded = false;
	void session
		.prompt(command.message, {
			images: command.images,
			streamingBehavior: command.streamingBehavior,
			source: "rpc",
			preflightResult: (didSucceed) => {
				if (didSucceed) {
					preflightSucceeded = true;
					output(success(id, "prompt"));
				}
			},
		})
		.catch((e) => {
			if (!preflightSucceeded) {
				output(error(id, "prompt", e.message));
			}
		});

Data Flow

Input/output comparison of the two modes:

Edges and Failures

• rpc doesn't support @file args: main.ts checks parsed.mode === "rpc" && parsed.fileArgs.length > 0 before dispatch and fails outright. See packages/coding-agent/src/main.ts:475-478.
• rpc doesn't support theme switching: setTheme returns { success: false, error: "Theme switching not supported in RPC mode" }. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:291-294.
• rpc doesn't support tool expansion: getToolsExpanded always returns false, since the TUI concept doesn't exist in rpc. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:296-303.
• Extension UI timeout / abort: createDialogPromise supports opts.timeout and opts.signal; on timeout or abort it resolves with a default value instead of rejecting, so extension logic can continue. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:90-130.
• print mode stdout takeover: main.ts calls takeOverStdout() in non-interactive modes; all console.log calls are redirected to an internal buffer and finally flushed via flushRawStdout, to keep TUI escapes from polluting output. See packages/coding-agent/src/modes/print-mode.ts:155-157.
• Shutdown signal: the shutdownRequested flag in rpc-mode is triggered by the extension shutdownHandler; the main loop detects it and cleans up before exiting. See packages/coding-agent/src/modes/rpc/rpc-mode.ts:79-81 and packages/coding-agent/src/modes/rpc/rpc-mode.ts:337-339.

Summary

print and rpc are pi's non-interactive modes. They share AgentSessionRuntime but have different output contracts: print is one-way text or JSON event stream output, while rpc is a bidirectional JSON-RPC protocol that exposes all AgentSession methods to external clients and bridges extension UI requests. For the assembly entry, see CLI Entry and Dispatch; for runtime replacement, see Session switch/fork/import.