@mariozechner/pi-coding-agent 0.46.0 → 0.47.0

package/docs/rpc.md

@@ -52,9 +52,9 @@ With images:
 
 If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.
 
-**Extension commands**: If the message is a hook command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.
+**Extension commands**: If the message is an extension command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.
 
-**Prompt templates**: File-based prompt templates (from `.md` files) are expanded before sending/queueing.
+**Input expansion**: Skill commands (`/skill:name`) and prompt templates (`/template`) are expanded before sending/queueing.
 
 Response:
 ```json
@@ -65,7 +65,7 @@ The `images` field is optional. Each image uses `ImageContent` format with base6
 
 #### steer
 
-Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. File-based prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
+Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
 
 ```json
 {"type": "steer", "message": "Stop and do this instead"}
@@ -80,7 +80,7 @@ See [set_steering_mode](#set_steering_mode) for controlling how steering message
 
 #### follow_up
 
-Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. File-based prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
+Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
 
 ```json
 {"type": "follow_up", "message": "After you're done, also do this"}
@@ -108,7 +108,7 @@ Response:
 
 #### new_session
 
-Start a fresh session. Can be cancelled by a `session_before_switch` hook.
+Start a fresh session. Can be cancelled by a `session_before_switch` extension event handler.
 
 ```json
 {"type": "new_session"}
@@ -124,7 +124,7 @@ Response:
 {"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}
 ```
 
-If a hook cancelled:
+If an extension cancelled:
 ```json
 {"type": "response", "command": "new_session", "success": true, "data": {"cancelled": true}}
 ```
@@ -525,7 +525,7 @@ Response:
 
 #### switch_session
 
-Load a different session file. Can be cancelled by a `before_switch` hook.
+Load a different session file. Can be cancelled by a `session_before_switch` extension event handler.
 
 ```json
 {"type": "switch_session", "sessionPath": "/path/to/session.jsonl"}
@@ -536,14 +536,14 @@ Response:
 {"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": false}}
 ```
 
-If a hook cancelled the switch:
+If an extension cancelled the switch:
 ```json
 {"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
 ```
 
 #### fork
 
-Create a new fork from a previous user message. Can be cancelled by a `before_fork` hook. Returns the text of the message being forked from.
+Create a new fork from a previous user message. Can be cancelled by a `session_before_fork` extension event handler. Returns the text of the message being forked from.
 
 ```json
 {"type": "fork", "entryId": "abc123"}
@@ -559,7 +559,7 @@ Response:
 }
 ```
 
-If a hook cancelled the fork:
+If an extension cancelled the fork:
 ```json
 {
   "type": "response",
@@ -634,7 +634,7 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `auto_compaction_end` | Auto-compaction completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
-| `hook_error` | Hook threw an error |
+| `extension_error` | Extension threw an error |
 
 ### agent_start
 
@@ -827,14 +827,14 @@ On final failure (max retries exceeded):
 }
 ```
 
-### hook_error
+### extension_error
 
-Emitted when a hook throws an error.
+Emitted when an extension throws an error.
 
 ```json
 {
-  "type": "hook_error",
-  "hookPath": "/path/to/hook.ts",
+  "type": "extension_error",
+  "extensionPath": "/path/to/extension.ts",
   "event": "tool_call",
   "error": "Error message..."
 }

package/docs/tui.md

@@ -26,6 +26,32 @@ interface Component {
 
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
+## Focusable Interface (IME Support)
+
+Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
+
+```typescript
+import { CURSOR_MARKER, type Component, type Focusable } from "@mariozechner/pi-tui";
+
+class MyInput implements Component, Focusable {
+  focused: boolean = false;  // Set by TUI when focus changes
+  
+  render(width: number): string[] {
+    const marker = this.focused ? CURSOR_MARKER : "";
+    // Emit marker right before the fake cursor
+    return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
+  }
+}
+```
+
+When a `Focusable` component has focus, TUI:
+1. Sets `focused = true` on the component
+2. Scans rendered output for `CURSOR_MARKER` (a zero-width APC escape sequence)
+3. Positions the hardware terminal cursor at that location
+4. Shows the hardware cursor
+
+This enables IME candidate windows to appear at the correct position for CJK input methods. The `Editor` and `Input` built-in components already implement this interface.
+
 ## Using Components
 
 **In hooks** via `ctx.ui.custom()`:

package/examples/extensions/input-transform.ts

@@ -0,0 +1,43 @@
+/**
+ * Input Transform Example - demonstrates the `input` event for intercepting user input.
+ *
+ * Start pi with this extension:
+ *   pi -e ./examples/extensions/input-transform.ts
+ *
+ * Then type these inside pi:
+ *   ?quick What is TypeScript?  → "Respond briefly: What is TypeScript?"
+ *   ping                        → "pong" (instant, no LLM)
+ *   time                        → current time (instant, no LLM)
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("input", async (event, ctx) => {
+		// Source-based logic: skip processing for extension-injected messages
+		if (event.source === "extension") {
+			return { action: "continue" };
+		}
+
+		// Transform: ?quick prefix for brief responses
+		if (event.text.startsWith("?quick ")) {
+			const query = event.text.slice(7).trim();
+			if (!query) {
+				ctx.ui.notify("Usage: ?quick <question>", "warning");
+				return { action: "handled" };
+			}
+			return { action: "transform", text: `Respond briefly in 1-2 sentences: ${query}` };
+		}
+
+		// Handle: instant responses without LLM (extension shows its own feedback)
+		if (event.text.toLowerCase() === "ping") {
+			ctx.ui.notify("pong", "info");
+			return { action: "handled" };
+		}
+		if (event.text.toLowerCase() === "time") {
+			ctx.ui.notify(new Date().toLocaleString(), "info");
+			return { action: "handled" };
+		}
+
+		return { action: "continue" };
+	});
+}

package/examples/extensions/modal-editor.ts

@@ -80,6 +80,6 @@ class ModalEditor extends CustomEditor {
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
-		ctx.ui.setEditorComponent((_tui, theme, kb) => new ModalEditor(theme, kb));
+		ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb));
 	});
 }

package/examples/extensions/overlay-test.ts

@@ -9,7 +9,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
-import { matchesKey, visibleWidth } from "@mariozechner/pi-tui";
+import { CURSOR_MARKER, type Focusable, matchesKey, visibleWidth } from "@mariozechner/pi-tui";
 
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("overlay-test", {
@@ -28,9 +28,12 @@ export default function (pi: ExtensionAPI) {
 	});
 }
 
-class OverlayTestComponent {
+class OverlayTestComponent implements Focusable {
 	readonly width = 70;
 
+	/** Focusable interface - set by TUI when focus changes */
+	focused = false;
+
 	private selected = 0;
 	private items = [
 		{ label: "Search", hasInput: true, text: "", cursor: 0 },
@@ -123,7 +126,9 @@ class OverlayTestComponent {
 					const before = inputDisplay.slice(0, item.cursor);
 					const cursorChar = item.cursor < inputDisplay.length ? inputDisplay[item.cursor] : " ";
 					const after = inputDisplay.slice(item.cursor + 1);
-					inputDisplay = `${before}\x1b[7m${cursorChar}\x1b[27m${after}`;
+					// Emit hardware cursor marker for IME support when focused
+					const marker = this.focused ? CURSOR_MARKER : "";
+					inputDisplay = `${before}${marker}\x1b[7m${cursorChar}\x1b[27m${after}`;
 				}
 				content = `${prefix + label} ${inputDisplay}`;
 			} else {

package/examples/extensions/question.ts

@@ -90,7 +90,7 @@ export default function question(pi: ExtensionAPI) {
 							noMatch: (t) => theme.fg("warning", t),
 						},
 					};
-					const editor = new Editor(editorTheme);
+					const editor = new Editor(tui, editorTheme);
 
 					editor.onSubmit = (value) => {
 						const trimmed = value.trim();

package/examples/extensions/questionnaire.ts

@@ -119,7 +119,7 @@ export default function questionnaire(pi: ExtensionAPI) {
 						noMatch: (t) => theme.fg("warning", t),
 					},
 				};
-				const editor = new Editor(editorTheme);
+				const editor = new Editor(tui, editorTheme);
 
 				// Helpers
 				function refresh() {

package/examples/extensions/rainbow-editor.ts

@@ -4,8 +4,7 @@
  * Usage: pi --extension ./examples/extensions/rainbow-editor.ts
  */
 
-import { CustomEditor, type ExtensionAPI, type KeybindingsManager } from "@mariozechner/pi-coding-agent";
-import type { EditorTheme, TUI } from "@mariozechner/pi-tui";
+import { CustomEditor, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 // Base colors (coral → yellow → green → teal → blue → purple → pink)
 const COLORS: [number, number, number][] = [
@@ -44,14 +43,8 @@ function colorize(text: string, shinePos: number): string {
 
 class RainbowEditor extends CustomEditor {
 	private animationTimer?: ReturnType<typeof setInterval>;
-	private tui: TUI;
 	private frame = 0;
 
-	constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
-		super(theme, keybindings);
-		this.tui = tui;
-	}
-
 	private hasUltrathink(): boolean {
 		return /ultrathink/i.test(this.getText());
 	}

package/examples/extensions/subagent/agents.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -23,36 +24,6 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
-function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
-	const frontmatter: Record<string, string> = {};
-	const normalized = content.replace(/\r\n/g, "\n");
-
-	if (!normalized.startsWith("---")) {
-		return { frontmatter, body: normalized };
-	}
-
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) {
-		return { frontmatter, body: normalized };
-	}
-
-	const frontmatterBlock = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
-
-	for (const line of frontmatterBlock.split("\n")) {
-		const match = line.match(/^([\w-]+):\s*(.*)$/);
-		if (match) {
-			let value = match[2].trim();
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			frontmatter[match[1]] = value;
-		}
-	}
-
-	return { frontmatter, body };
-}
-
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -79,7 +50,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter(content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
 
 		if (!frontmatter.name || !frontmatter.description) {
 			continue;
@@ -87,7 +58,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 
 		const tools = frontmatter.tools
 			?.split(",")
-			.map((t) => t.trim())
+			.map((t: string) => t.trim())
 			.filter(Boolean);
 
 		agents.push({

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "1.10.0",
+      "version": "1.11.0",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mariozechner/pi-coding-agent",
-	"version": "0.46.0",
+	"version": "0.47.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -40,9 +40,10 @@
 	"dependencies": {
 		"@mariozechner/clipboard": "^0.3.0",
 		"@mariozechner/jiti": "^2.6.2",
-		"@mariozechner/pi-agent-core": "^0.46.0",
-		"@mariozechner/pi-ai": "^0.46.0",
-		"@mariozechner/pi-tui": "^0.46.0",
+		"@mariozechner/pi-agent-core": "^0.47.0",
+		"@mariozechner/pi-ai": "^0.47.0",
+		"@mariozechner/pi-tui": "^0.47.0",
+		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",
 		"diff": "^8.0.2",
@@ -51,7 +52,7 @@
 		"marked": "^15.0.12",
 		"minimatch": "^10.1.1",
 		"proper-lockfile": "^4.1.2",
-		"@silvia-odwyer/photon-node": "^0.3.4"
+		"yaml": "^2.8.2"
 	},
 	"devDependencies": {
 		"@types/diff": "^7.0.2",