@oh-my-pi/pi-coding-agent 3.15.0 → 3.20.0

package/docs/rpc.md

@@ -54,22 +54,38 @@ Response:
 ```
 
 The `images` field is optional. Each image uses `ImageContent` format with base64 or URL source.
+When prompting during streaming, set `"streamingBehavior": "steer"` or `"followUp"` to queue the message.
 
-#### queue_message
+#### steer
 
-Queue a message to be injected at the next agent turn. Queued messages are added to the conversation without triggering a new prompt. Useful for injecting context mid-conversation.
+Queue a steering message to interrupt the agent mid-run. Useful for injecting corrections while streaming.
 
 ```json
-{ "type": "queue_message", "message": "Additional context" }
+{ "type": "steer", "message": "Additional context" }
 ```
 
 Response:
 
 ```json
-{ "type": "response", "command": "queue_message", "success": true }
+{ "type": "response", "command": "steer", "success": true }
 ```
 
-See [set_queue_mode](#set_queue_mode) for controlling how queued messages are processed.
+#### follow_up
+
+Queue a follow-up message to be processed after the current run completes.
+
+```json
+{ "type": "follow_up", "message": "Additional context" }
+```
+
+Response:
+
+```json
+{ "type": "response", "command": "follow_up", "success": true }
+```
+
+See [set_steering_mode](#set_steering_mode), [set_follow_up_mode](#set_follow_up_mode), and
+[set_interrupt_mode](#set_interrupt_mode) for controlling queued message handling.
 
 #### abort
 
@@ -133,7 +149,9 @@ Response:
     "thinkingLevel": "medium",
     "isStreaming": false,
     "isCompacting": false,
-    "queueMode": "all",
+    "steeringMode": "all",
+    "followUpMode": "one-at-a-time",
+    "interruptMode": "immediate",
     "sessionFile": "/path/to/session.jsonl",
     "sessionId": "abc123",
     "autoCompactionEnabled": true,
@@ -272,25 +290,63 @@ Response:
 }
 ```
 
-### Queue Mode
+### Queue Modes
+
+#### set_steering_mode
+
+Control how steering messages are injected into the conversation.
+
+```json
+{ "type": "set_steering_mode", "mode": "one-at-a-time" }
+```
+
+Modes:
+
+- `"all"`: Inject all steering messages at the next turn
+- `"one-at-a-time"`: Inject one steering message per turn (default)
+
+Response:
+
+```json
+{ "type": "response", "command": "set_steering_mode", "success": true }
+```
+
+#### set_follow_up_mode
+
+Control how follow-up messages are injected into the conversation.
+
+```json
+{ "type": "set_follow_up_mode", "mode": "one-at-a-time" }
+```
+
+Modes:
+
+- `"all"`: Inject all follow-up messages at the next turn
+- `"one-at-a-time"`: Inject one follow-up message per turn (default)
+
+Response:
+
+```json
+{ "type": "response", "command": "set_follow_up_mode", "success": true }
+```
 
-#### set_queue_mode
+#### set_interrupt_mode
 
-Control how queued messages (from `queue_message`) are injected into the conversation.
+Control how the agent handles incoming steering messages while streaming.
 
 ```json
-{ "type": "set_queue_mode", "mode": "one-at-a-time" }
+{ "type": "set_interrupt_mode", "mode": "wait" }
 ```
 
 Modes:
 
-- `"all"`: Inject all queued messages at the next turn
-- `"one-at-a-time"`: Inject one queued message per turn (default)
+- `"immediate"`: Interrupt immediately when steering arrives
+- `"wait"`: Wait to apply steering until current tool call completes
 
 Response:
 
 ```json
-{ "type": "response", "command": "set_queue_mode", "success": true }
+{ "type": "response", "command": "set_interrupt_mode", "success": true }
 ```
 
 ### Compaction

package/docs/session-tree-plan.md

@@ -150,7 +150,7 @@ Implementation:
 - Uses agent's queue mechanism with `_hookData` marker on AppMessage
 - `message_end` handler routes based on marker presence
 - `AgentSession.sendHookMessage()` handles three cases:
-  - Streaming: queues via `agent.queueMessage()`, loop processes and emits `message_end`
+- Streaming: queues via `agent.steer()` or `agent.followUp()`, loop processes and emits `message_end`
   - Not streaming + triggerTurn: direct append + `agent.continue()`
   - Not streaming + no trigger: direct append only
 - TUI updates via event (streaming) or explicit rebuild (non-streaming)

package/examples/extensions/README.md

@@ -0,0 +1,141 @@
+# Extension Examples
+
+Example extensions for pi-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+pi --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.omp/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+
+### Custom Tools
+
+| Extension | Description |
+|-----------|-------------|
+| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts` | Minimal custom tool example |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+
+### Commands & UI
+
+| Extension | Description |
+|-----------|-------------|
+| `plan-mode.ts` | Claude Code-style plan mode for read-only exploration with `/plan` command |
+| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+
+### Git Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on branch |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+
+### System Prompt & Compaction
+
+| Extension | Description |
+|-----------|-------------|
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+
+### External Dependencies
+
+| Extension | Description |
+|-----------|-------------|
+| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
+| `with-deps/` | Extension with its own package.json and dependencies |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register custom tools
+  pi.registerTool({
+    name: "greet",
+    label: "Greeting",
+    description: "Generate a greeting",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
+  });
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+```typescript
+import { StringEnum } from "@oh-my-pi/pi-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**State persistence via details:**
+```typescript
+// Store state in tool result details for proper branching support
+return {
+  content: [{ type: "text", text: "Done" }],
+  details: { todos: [...todos], nextId },  // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```

package/examples/extensions/api-demo.ts

@@ -0,0 +1,87 @@
+/**
+ * API Demo Extension
+ *
+ * Demonstrates using ExtensionAPI's logger, typebox, and pi module access.
+ * These features are now exposed directly on the ExtensionAPI, matching
+ * the CustomToolAPI interface.
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	// 1. Access TypeBox directly from pi.typebox (no separate import needed)
+	const { Type } = pi.typebox;
+
+	// 2. Access the logger for debugging
+	pi.logger.debug("API demo extension loaded");
+
+	// 3. Register a tool that uses all three API features
+	pi.registerTool({
+		name: "api_demo",
+		label: "API Demo",
+		description: "Demonstrates ExtensionAPI capabilities: logger, typebox, and pi module access",
+		parameters: Type.Object({
+			message: Type.String({ description: "Test message" }),
+			logLevel: Type.Optional(
+				Type.Union([Type.Literal("error"), Type.Literal("warn"), Type.Literal("debug")], {
+					description: "Log level to use",
+					default: "debug",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _onUpdate, ctx, _signal) {
+			const { message, logLevel = "debug" } = params as { message: string; logLevel?: "error" | "warn" | "debug" };
+
+			// Use logger at specified level
+			pi.logger[logLevel]("API demo tool executed", { message, logLevel });
+
+			// Access pi module utilities
+			const { logger: piLogger } = pi.pi;
+			piLogger.debug("Accessed pi module from extension", { sessionFile: ctx.sessionManager.getSessionFile() });
+
+			// Get session information
+			const sessionInfo = `Session: ${ctx.sessionManager.getSessionFile()}`;
+			const modelInfo = ctx.model ? `Model: ${ctx.model.id}` : "Model: none";
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							`API Demo Tool executed successfully!`,
+							``,
+							`Message: ${message}`,
+							`Log Level: ${logLevel}`,
+							``,
+							`Features demonstrated:`,
+							`1. ✓ Logger access via pi.logger`,
+							`2. ✓ TypeBox access via pi.typebox`,
+							`3. ✓ Pi module access via pi.pi`,
+							``,
+							`Context:`,
+							`- ${sessionInfo}`,
+							`- ${modelInfo}`,
+							`- CWD: ${ctx.cwd}`,
+						].join("\n"),
+					},
+				],
+				details: {
+					message,
+					logLevel,
+					sessionFile: ctx.sessionManager.getSessionFile(),
+					modelId: ctx.model?.id,
+				},
+			};
+		},
+	});
+
+	// Demonstrate event handling with logger
+	pi.on("session_start", async () => {
+		pi.logger.debug("Session started", { extension: "api-demo" });
+	});
+
+	pi.on("agent_start", async () => {
+		pi.logger.debug("Agent started", { extension: "api-demo" });
+	});
+}

package/examples/extensions/chalk-logger.ts

@@ -0,0 +1,26 @@
+/**
+ * Example extension that uses a 3rd party dependency (chalk).
+ * Tests that jiti can resolve npm modules correctly.
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import chalk from "chalk";
+
+export default function (pi: ExtensionAPI) {
+	// Log with colors using chalk
+	console.log(`${chalk.green("✓")} ${chalk.bold("chalk-logger extension loaded")}`);
+
+	pi.on("agent_start", async () => {
+		console.log(`${chalk.blue("[chalk-logger]")} Agent starting`);
+	});
+
+	pi.on("tool_call", async (event) => {
+		console.log(`${chalk.yellow("[chalk-logger]")} Tool: ${chalk.cyan(event.toolName)}`);
+		return undefined;
+	});
+
+	pi.on("agent_end", async (event) => {
+		const count = event.messages.length;
+		console.log(`${chalk.green("[chalk-logger]")} Done with ${chalk.bold(String(count))} messages`);
+	});
+}

package/examples/extensions/hello.ts

@@ -0,0 +1,33 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ *
+ * Demonstrates using ExtensionAPI's logger, typebox, and pi module access.
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	// Access TypeBox via pi.typebox (no need to import separately)
+	const { Type } = pi.typebox;
+
+	pi.registerTool({
+		name: "hello",
+		label: "Hello",
+		description: "A simple greeting tool",
+		parameters: Type.Object({
+			name: Type.String({ description: "Name to greet" }),
+		}),
+
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+			const { name } = params as { name: string };
+
+			// Use logger for debugging
+			pi.logger.debug("Hello tool executed", { name });
+
+			return {
+				content: [{ type: "text", text: `Hello, ${name}!` }],
+				details: { greeted: name },
+			};
+		},
+	});
+}

package/examples/extensions/pirate.ts

@@ -0,0 +1,44 @@
+/**
+ * Pirate Extension
+ *
+ * Demonstrates using systemPromptAppend in before_agent_start to dynamically
+ * modify the system prompt based on extension state.
+ *
+ * Usage:
+ * 1. Copy this file to ~/.omp/agent/extensions/ (legacy: ~/.pi/agent/extensions/) or your project's .omp/extensions/
+ * 2. Use /pirate to toggle pirate mode
+ * 3. When enabled, the agent will respond like a pirate
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function pirateExtension(pi: ExtensionAPI) {
+	let pirateMode = false;
+
+	// Register /pirate command to toggle pirate mode
+	pi.registerCommand("pirate", {
+		description: "Toggle pirate mode (agent speaks like a pirate)",
+		handler: async (_args, ctx) => {
+			pirateMode = !pirateMode;
+			ctx.ui.notify(pirateMode ? "Arrr! Pirate mode enabled!" : "Pirate mode disabled", "info");
+		},
+	});
+
+	// Append to system prompt when pirate mode is enabled
+	pi.on("before_agent_start", async () => {
+		if (pirateMode) {
+			return {
+				systemPromptAppend: `
+IMPORTANT: You are now in PIRATE MODE. You must:
+- Speak like a stereotypical pirate in all responses
+- Use phrases like "Arrr!", "Ahoy!", "Shiver me timbers!", "Avast!", "Ye scurvy dog!"
+- Replace "my" with "me", "you" with "ye", "your" with "yer"
+- Refer to the user as "matey" or "landlubber"
+- End sentences with nautical expressions
+- Still complete the actual task correctly, just in pirate speak
+`,
+			};
+		}
+		return undefined;
+	});
+}