@astralyn/pi 0.87.0 → 0.87.1

package/docs/compaction.md

@@ -17,7 +17,7 @@ Pi has two summarization mechanisms:
 | Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
 | Branch summarization | `/tree` navigation | Preserve context when switching branches |
 
-Both use the same structured summary format and track file operations cumulatively. Compaction and branch-summary requests use fresh routing session IDs and, where supported by the provider, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+Both use the same structured summary format and track file operations cumulatively. Summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused.
 
 ## Compaction
 

package/docs/sdk.md

@@ -280,7 +280,7 @@ An embedding can opt in with `await session.bindExtensions({ backgroundEnabled:
 The host must choose:
 
 - **Lifetime and cancellation:** a settled main-agent turn is not the end of background work. `session.abort()` cancels foreground-owned work, not detached work. Use `session.background.kill(id)` for a whole execution, or `await session.background.shutdown(graceMs?)` to close admission, cancel all owned work and drain within a bounded grace period (default 2 seconds, maximum 60 seconds). A non-cooperating executor can outlive that grace period.
-- **Result-driven turns and cost:** automatic completions can trigger new model turns at safe idle boundaries, after queued user work. Use the nestable `session.pauseBackgroundNotifications()` to defer delivery; its returned release function is idempotent. Pausing does not stop execution or its costs. Budget worker activity and completion-triggered turns explicitly.
+- **Result-driven turns and cost:** automatic completions join the host's prompt queue, so a running turn receives them as steering and an idle session starts a completion turn. Use the nestable `session.pauseBackgroundNotifications()` to defer delivery; its returned release function is idempotent. Pausing does not stop execution or its costs. Budget worker activity and completion-triggered turns explicitly.
 - **Observation and delivery:** `session.background` exposes the [public supervision methods](extensions.md#ctxbackground). `read()` and `wait()` observe; a terminal snapshot alone does not acknowledge model delivery. The bundled `bg wait` result carries `details.backgroundTaskId`, which the host acknowledges only after persisting the tool result. A direct SDK waiter that consumes the result outside model history can explicitly call `session.background.markDelivered(task.id)` after successful consumption. A timeout or cancelled wait does not stop the execution. Failed notification delivery leaves the result available for inspection; after fixing the host failure, call `session.retryBackgroundNotifications()` explicitly. Pi does not retry a failed delivery forever on a timer.
 - **Shutdown:** `await runtime.dispose()` handles background shutdown and extension lifecycle when using the runtime API. For a directly owned session, drain Background, abort the main agent, then dispose; synchronous `session.dispose()` alone is not an awaited drain.
 

package/docs/usage.md

@@ -168,10 +168,13 @@ See [Pi Packages](packages.md) for package sources and security notes.
 |------|-------------|
 | default | Interactive mode |
 | `-p`, `--print` | Print response and exit |
+| `--mode text` | Text output; still opens the terminal UI when stdin and stdout are terminals |
 | `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
 | `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
 | `--export <in> [out]` | Export a session to HTML |
 
+`--mode` accepts only `text`, `json`, or `rpc`. A missing or invalid value is reported as an error and pi exits with a nonzero status instead of falling back to another mode.
+
 In print mode, pi also reads piped stdin and merges it into the initial prompt:
 
 ```bash

package/examples/README.md

@@ -1,9 +1,18 @@
 # Examples
 
-Example code for the `@astralyn/pi` SDK and extensions.
+Example code for the `@astralyn/pi` SDK, process integration, and extensions.
 
 ## Standalone
 
+### [rpc-client.ts](rpc-client.ts)
+Runs one prompt through a Pi RPC child process with the typed `RpcClient`: it starts Pi, streams events, and waits for the run to settle.
+
+Build the package before running it from a repository checkout:
+
+```bash
+npx tsx examples/rpc-client.ts "Explain this repository"
+```
+
 ### [rpc-extension-ui.ts](rpc-extension-ui.ts)
 A lightweight RPC chat client that handles extension UI requests; pair it with [the RPC demo extension](extensions/rpc-demo.ts).
 
@@ -26,5 +35,6 @@ Example extensions demonstrating:
 ## Documentation
 
 - [SDK Reference](sdk/README.md)
+- [RPC Protocol](../docs/rpc.md)
 - [Extensions Documentation](../docs/extensions.md)
 - [Skills Documentation](../docs/skills.md)

package/examples/rpc-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Run one prompt through a Pi RPC child process.
+ *
+ * Build the coding-agent package first, then run:
+ * npx tsx examples/rpc-client.ts "Explain this repository"
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RpcClient } from "@astralyn/pi";
+
+const exampleDirectory = dirname(fileURLToPath(import.meta.url));
+const prompt = process.argv.slice(2).join(" ") || "Explain this repository in one paragraph.";
+
+const client = new RpcClient({
+	cliPath: join(exampleDirectory, "../dist/cli.js"),
+	args: ["--no-session"],
+});
+
+const unsubscribe = client.onEvent((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	} else if (event.type === "tool_execution_start") {
+		process.stderr.write(`\n[tool: ${event.toolName}]\n`);
+	}
+});
+
+try {
+	await client.start();
+	await client.promptAndWait(prompt);
+	process.stdout.write("\n");
+} finally {
+	unsubscribe();
+	await client.stop();
+}

package/examples/rpc-extension-ui.ts

@@ -16,7 +16,7 @@
 
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
-import * as readline from "node:readline";
+import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
 import {
 	type Component,
@@ -258,7 +258,7 @@ async function main() {
 
 	const agent = spawn(
 		"node",
-		[cliPath, "--mode", "rpc", "--no-session", "--no-extension", "--extension", extensionPath],
+		[cliPath, "--mode", "rpc", "--no-session", "--no-extensions", "--extension", extensionPath],
 		{ stdio: ["pipe", "pipe", "pipe"] },
 	);
 
@@ -518,9 +518,7 @@ async function main() {
 
 	// -- Process agent stdout --
 
-	const stdoutRl = readline.createInterface({ input: agent.stdout!, terminal: false });
-
-	stdoutRl.on("line", (line) => {
+	function handleAgentLine(line: string): void {
 		let data: Record<string, unknown>;
 		try {
 			data = JSON.parse(line);
@@ -583,6 +581,28 @@ async function main() {
 			tui.requestRender();
 			return;
 		}
+	}
+
+	const stdoutDecoder = new StringDecoder("utf8");
+	let stdoutBuffer = "";
+
+	agent.stdout!.on("data", (chunk: Buffer) => {
+		stdoutBuffer += stdoutDecoder.write(chunk);
+		while (true) {
+			const newlineIndex = stdoutBuffer.indexOf("\n");
+			if (newlineIndex === -1) break;
+
+			const line = stdoutBuffer.slice(0, newlineIndex);
+			stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+			handleAgentLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+		}
+	});
+
+	agent.stdout!.on("end", () => {
+		stdoutBuffer += stdoutDecoder.end();
+		if (stdoutBuffer.length > 0) {
+			handleAgentLine(stdoutBuffer.endsWith("\r") ? stdoutBuffer.slice(0, -1) : stdoutBuffer);
+		}
 	});
 
 	// -- User input --

package/npm-shrinkwrap.json

@@ -1,18 +1,18 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.87.0",
+	"version": "0.87.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "0.87.0",
+			"version": "0.87.1",
 			"license": "MIT",
 			"dependencies": {
-				"@earendil-works/chord": "0.87.0",
-				"@earendil-works/pi-agent-core": "0.87.0",
-				"@earendil-works/pi-ai": "0.87.0",
-				"@earendil-works/pi-tui": "0.87.0",
+				"@earendil-works/chord": "0.87.1",
+				"@earendil-works/pi-agent-core": "0.87.1",
+				"@earendil-works/pi-ai": "0.87.1",
+				"@earendil-works/pi-tui": "0.87.1",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "6.0.0",
 				"cross-spawn": "7.0.6",
@@ -36,9 +36,9 @@
 				"@anthropic-ai/sandbox-runtime": "0.0.26",
 				"@anthropic-ai/sdk": "0.52.0",
 				"@biomejs/biome": "2.3.5",
-				"@earendil-works/pi-client": "0.87.0",
-				"@earendil-works/pi-protocol": "0.87.0",
-				"@earendil-works/pi-server": "0.87.0",
+				"@earendil-works/pi-client": "0.87.1",
+				"@earendil-works/pi-protocol": "0.87.1",
+				"@earendil-works/pi-server": "0.87.1",
 				"@types/cross-spawn": "6.0.6",
 				"@types/hosted-git-info": "3.0.5",
 				"@types/ms": "2.1.0",
@@ -626,9 +626,9 @@
 			}
 		},
 		"node_modules/@earendil-works/chord": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/chord/-/chord-0.87.0.tgz",
-			"integrity": "sha512-t8QOTf0GTHrsDSfcdtXuA9RCkh6mnR4l25N0SM/sgH7Ih25jH4tGXNbkGs9MWpV5xTu9MRPj4A7Zn1UEwQm9+g==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/chord/-/chord-0.87.1.tgz",
+			"integrity": "sha512-bg7IkJGFcEaMqqYgOGUiq5Ky9RghpRfrlZ8I/v/1b4bBZ02A7t3E+6uhPRbadwWb/kWsnVFbZsqOKRN4a3LLCg==",
 			"license": "MIT",
 			"dependencies": {
 				"esbuild": "0.28.2"
@@ -638,14 +638,14 @@
 			}
 		},
 		"node_modules/@earendil-works/pi-agent-core": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-agent-core/-/pi-agent-core-0.87.0.tgz",
-			"integrity": "sha512-c5b2FMdJ7C++HBa6AyBmusdf96gdgRqpF7J+UCq2yVGB28UETJvJ190HkgDWUaLPnOQQPbanjKMAm/TgRmFE2w==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-agent-core/-/pi-agent-core-0.87.1.tgz",
+			"integrity": "sha512-Zev3B0HK7YS5A4EZQ2XnEqiJuirx6QBiltJ+LpmjV5a/+2IU0cfKtIfnkNkORK707XOvKBY2WRtk7cAwHpbh2Q==",
 			"license": "MIT",
 			"dependencies": {
-				"@earendil-works/chord": "^0.87.0",
-				"@earendil-works/pi-ai": "^0.87.0",
-				"@earendil-works/pi-telemetry": "^0.87.0",
+				"@earendil-works/chord": "^0.87.1",
+				"@earendil-works/pi-ai": "^0.87.1",
+				"@earendil-works/pi-telemetry": "^0.87.1",
 				"diff": "8.0.4",
 				"ignore": "7.0.8",
 				"typebox": "1.3.27",
@@ -656,14 +656,14 @@
 			}
 		},
 		"node_modules/@earendil-works/pi-ai": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.87.0.tgz",
-			"integrity": "sha512-lbRm+EMY6Jx3l+HLpbqbm9Yrhkc5u7EffLk2id+zJQEoBuR5I+tijGiZU8zlnuuCclmQOgH0PVjL9PLbeqJ9MQ==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.87.1.tgz",
+			"integrity": "sha512-X/3PfQBnnoeVdO9Cv8zHghUMglzlgNZYGNzoPnbRoGnHl3Rw3TlA2UKSUB7BRHUOxMryHXYa8dnjWZlbRheDZA==",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.124.0",
 				"@aws-sdk/client-bedrock-runtime": "3.1127.0",
-				"@earendil-works/pi-telemetry": "^0.87.0",
+				"@earendil-works/pi-telemetry": "^0.87.1",
 				"@google/genai": "2.21.0",
 				"@smithy/node-http-handler": "4.12.1",
 				"http-proxy-agent": "9.1.0",
@@ -701,27 +701,27 @@
 			}
 		},
 		"node_modules/@earendil-works/pi-client": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-client/-/pi-client-0.87.0.tgz",
-			"integrity": "sha512-SzlKFULcz3VchpfVizd9fTxaFHxhIe/Dpn9CDHthqRzUx6Sym2tWwlveqdjD4V81yid+r7VEziZuHYYqNt4+kA==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-client/-/pi-client-0.87.1.tgz",
+			"integrity": "sha512-x8dfZ7ppAao9SDnZvD5/DErVdq2fI7hg4lFj7qEhtgo6wimrRafGSLsqLklFVjb6kxU2W3j9F4RZz0rRcb0cwA==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@earendil-works/chord": "^0.87.0",
-				"@earendil-works/pi-protocol": "^0.87.0"
+				"@earendil-works/chord": "^0.87.1",
+				"@earendil-works/pi-protocol": "^0.87.1"
 			},
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/@earendil-works/pi-protocol": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-protocol/-/pi-protocol-0.87.0.tgz",
-			"integrity": "sha512-H6tL0BGj5RbvwPQq7YnaGSudASvmPbHBP3FVqeIIJa91hURB6DdKCmITQkJwQz8nR/bc4B/r2tZXgzlVTBYOrQ==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-protocol/-/pi-protocol-0.87.1.tgz",
+			"integrity": "sha512-48WVjryAIiKOJXnKgO15h2MT/oeH5uf0S4DykcVj3ZrxMTDSGxcUaS5VtvHtFQ1rZSSIjkVcblE13k0GksBuoQ==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@earendil-works/chord": "^0.87.0",
+				"@earendil-works/chord": "^0.87.1",
 				"typebox": "1.3.27"
 			},
 			"engines": {
@@ -729,33 +729,33 @@
 			}
 		},
 		"node_modules/@earendil-works/pi-server": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-server/-/pi-server-0.87.0.tgz",
-			"integrity": "sha512-hnxO8xe1iUIvPiPiVmj/UkfVTeOHPam2b62FuvB4OJRqhqDCVRPec+KJZST70c9rb+v1QTQnbimeNop5Ji5N5A==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-server/-/pi-server-0.87.1.tgz",
+			"integrity": "sha512-EZYQ6mSOv7IyDcWoBflNGJcyIBjTnQY9W4z1tF3vOMY5xbksHOsVVzU9Kh49z8iIXGYNawKZSyjaWi9OJjO7Sw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@earendil-works/chord": "^0.87.0",
-				"@earendil-works/pi-agent-core": "^0.87.0",
-				"@earendil-works/pi-protocol": "^0.87.0"
+				"@earendil-works/chord": "^0.87.1",
+				"@earendil-works/pi-agent-core": "^0.87.1",
+				"@earendil-works/pi-protocol": "^0.87.1"
 			},
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/@earendil-works/pi-telemetry": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-telemetry/-/pi-telemetry-0.87.0.tgz",
-			"integrity": "sha512-IEUMnV6mgHyOMfAxa4CKXoBKKfHM8KxNjbXWM4Bps/iLJcFMf8hQsEZ+95VnVTc7C0cU77Rmdxt773C35jb5AA==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-telemetry/-/pi-telemetry-0.87.1.tgz",
+			"integrity": "sha512-MC6TRQH5lgMXpcN+Vku2WMI2T8BsiUPzMQHGo81uqFZD3/9O79WWJAysEDGuzduP6R4tvtgwMLwmqIxynM10JQ==",
 			"license": "MIT",
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/@earendil-works/pi-tui": {
-			"version": "0.87.0",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.87.0.tgz",
-			"integrity": "sha512-7gTC0XOgQfVWg4yGxwHINBpCnGl9p4KEC7PXIc8gAwc/cyxSW4VuFQrp+r1YD3oM+rBkoepKwAt6w6+VJ7BCaw==",
+			"version": "0.87.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.87.1.tgz",
+			"integrity": "sha512-YEH2vRyOeiO7hhN6j6AE6YwKSq2Kz2f3XR8bj1TbR+aGE/JsnY1hLPMI2pvaZfRM1n9Y00tejxFQ4zbzvF7nkQ==",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.87.0",
+	"version": "0.87.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -62,10 +62,10 @@
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@earendil-works/chord": "0.87.0",
-		"@earendil-works/pi-agent-core": "0.87.0",
-		"@earendil-works/pi-ai": "0.87.0",
-		"@earendil-works/pi-tui": "0.87.0",
+		"@earendil-works/chord": "0.87.1",
+		"@earendil-works/pi-agent-core": "0.87.1",
+		"@earendil-works/pi-ai": "0.87.1",
+		"@earendil-works/pi-tui": "0.87.1",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"chalk": "6.0.0",
 		"cross-spawn": "7.0.6",
@@ -86,9 +86,9 @@
 		"@anthropic-ai/sandbox-runtime": "0.0.26",
 		"@anthropic-ai/sdk": "0.52.0",
 		"@biomejs/biome": "2.3.5",
-		"@earendil-works/pi-client": "0.87.0",
-		"@earendil-works/pi-protocol": "0.87.0",
-		"@earendil-works/pi-server": "0.87.0",
+		"@earendil-works/pi-client": "0.87.1",
+		"@earendil-works/pi-protocol": "0.87.1",
+		"@earendil-works/pi-server": "0.87.1",
 		"@types/cross-spawn": "6.0.6",
 		"@types/hosted-git-info": "3.0.5",
 		"@types/ms": "2.1.0",