@draht/coding-agent 2026.3.2-2

package/examples/extensions/ssh.ts

@@ -0,0 +1,220 @@
+/**
+ * SSH Remote Execution Example
+ *
+ * Demonstrates delegating tool operations to a remote machine via SSH.
+ * When --ssh is provided, read/write/edit/bash run on the remote.
+ *
+ * Usage:
+ *   pi -e ./ssh.ts --ssh user@host
+ *   pi -e ./ssh.ts --ssh user@host:/remote/path
+ *
+ * Requirements:
+ *   - SSH key-based auth (no password prompts)
+ *   - bash on remote
+ */
+
+import { spawn } from "node:child_process";
+import type { ExtensionAPI } from "@draht/coding-agent";
+import {
+	type BashOperations,
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	type EditOperations,
+	type ReadOperations,
+	type WriteOperations,
+} from "@draht/coding-agent";
+
+function sshExec(remote: string, command: string): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const child = spawn("ssh", [remote, command], { stdio: ["ignore", "pipe", "pipe"] });
+		const chunks: Buffer[] = [];
+		const errChunks: Buffer[] = [];
+		child.stdout.on("data", (data) => chunks.push(data));
+		child.stderr.on("data", (data) => errChunks.push(data));
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(`SSH failed (${code}): ${Buffer.concat(errChunks).toString()}`));
+			} else {
+				resolve(Buffer.concat(chunks));
+			}
+		});
+	});
+}
+
+function createRemoteReadOps(remote: string, remoteCwd: string, localCwd: string): ReadOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		readFile: (p) => sshExec(remote, `cat ${JSON.stringify(toRemote(p))}`),
+		access: (p) => sshExec(remote, `test -r ${JSON.stringify(toRemote(p))}`).then(() => {}),
+		detectImageMimeType: async (p) => {
+			try {
+				const r = await sshExec(remote, `file --mime-type -b ${JSON.stringify(toRemote(p))}`);
+				const m = r.toString().trim();
+				return ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(m) ? m : null;
+			} catch {
+				return null;
+			}
+		},
+	};
+}
+
+function createRemoteWriteOps(remote: string, remoteCwd: string, localCwd: string): WriteOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		writeFile: async (p, content) => {
+			const b64 = Buffer.from(content).toString("base64");
+			await sshExec(remote, `echo ${JSON.stringify(b64)} | base64 -d > ${JSON.stringify(toRemote(p))}`);
+		},
+		mkdir: (dir) => sshExec(remote, `mkdir -p ${JSON.stringify(toRemote(dir))}`).then(() => {}),
+	};
+}
+
+function createRemoteEditOps(remote: string, remoteCwd: string, localCwd: string): EditOperations {
+	const r = createRemoteReadOps(remote, remoteCwd, localCwd);
+	const w = createRemoteWriteOps(remote, remoteCwd, localCwd);
+	return { readFile: r.readFile, access: r.access, writeFile: w.writeFile };
+}
+
+function createRemoteBashOps(remote: string, remoteCwd: string, localCwd: string): BashOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		exec: (command, cwd, { onData, signal, timeout }) =>
+			new Promise((resolve, reject) => {
+				const cmd = `cd ${JSON.stringify(toRemote(cwd))} && ${command}`;
+				const child = spawn("ssh", [remote, cmd], { stdio: ["ignore", "pipe", "pipe"] });
+				let timedOut = false;
+				const timer = timeout
+					? setTimeout(() => {
+							timedOut = true;
+							child.kill();
+						}, timeout * 1000)
+					: undefined;
+				child.stdout.on("data", onData);
+				child.stderr.on("data", onData);
+				child.on("error", (e) => {
+					if (timer) clearTimeout(timer);
+					reject(e);
+				});
+				const onAbort = () => child.kill();
+				signal?.addEventListener("abort", onAbort, { once: true });
+				child.on("close", (code) => {
+					if (timer) clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
+					if (signal?.aborted) reject(new Error("aborted"));
+					else if (timedOut) reject(new Error(`timeout:${timeout}`));
+					else resolve({ exitCode: code });
+				});
+			}),
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerFlag("ssh", { description: "SSH remote: user@host or user@host:/path", type: "string" });
+
+	const localCwd = process.cwd();
+	const localRead = createReadTool(localCwd);
+	const localWrite = createWriteTool(localCwd);
+	const localEdit = createEditTool(localCwd);
+	const localBash = createBashTool(localCwd);
+
+	// Resolved lazily on session_start (CLI flags not available during factory)
+	let resolvedSsh: { remote: string; remoteCwd: string } | null = null;
+
+	const getSsh = () => resolvedSsh;
+
+	pi.registerTool({
+		...localRead,
+		async execute(id, params, signal, onUpdate, _ctx) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createReadTool(localCwd, {
+					operations: createRemoteReadOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localRead.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localWrite,
+		async execute(id, params, signal, onUpdate, _ctx) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createWriteTool(localCwd, {
+					operations: createRemoteWriteOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localWrite.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localEdit,
+		async execute(id, params, signal, onUpdate, _ctx) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createEditTool(localCwd, {
+					operations: createRemoteEditOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localEdit.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localBash,
+		async execute(id, params, signal, onUpdate, _ctx) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createBashTool(localCwd, {
+					operations: createRemoteBashOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localBash.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		// Resolve SSH config now that CLI flags are available
+		const arg = pi.getFlag("ssh") as string | undefined;
+		if (arg) {
+			if (arg.includes(":")) {
+				const [remote, path] = arg.split(":");
+				resolvedSsh = { remote, remoteCwd: path };
+			} else {
+				// No path given, evaluate pwd on remote
+				const remote = arg;
+				const pwd = (await sshExec(remote, "pwd")).toString().trim();
+				resolvedSsh = { remote, remoteCwd: pwd };
+			}
+			ctx.ui.setStatus("ssh", ctx.ui.theme.fg("accent", `SSH: ${resolvedSsh.remote}:${resolvedSsh.remoteCwd}`));
+			ctx.ui.notify(`SSH mode: ${resolvedSsh.remote}:${resolvedSsh.remoteCwd}`, "info");
+		}
+	});
+
+	// Handle user ! commands via SSH
+	pi.on("user_bash", (_event) => {
+		const ssh = getSsh();
+		if (!ssh) return; // No SSH, use local execution
+		return { operations: createRemoteBashOps(ssh.remote, ssh.remoteCwd, localCwd) };
+	});
+
+	// Replace local cwd with remote cwd in system prompt
+	pi.on("before_agent_start", async (event) => {
+		const ssh = getSsh();
+		if (ssh) {
+			const modified = event.systemPrompt.replace(
+				`Current working directory: ${localCwd}`,
+				`Current working directory: ${ssh.remoteCwd} (via SSH: ${ssh.remote})`,
+			);
+			return { systemPrompt: modified };
+		}
+	});
+}

package/examples/extensions/sst-resource-manager.ts

@@ -0,0 +1,203 @@
+/**
+ * SST Resource Manager Extension
+ *
+ * Provides tools for querying SST v4 resource definitions and stack state
+ * from within the coding agent. Reads local .sst/ metadata and sst.config.ts
+ * — never triggers deployments.
+ *
+ * Tools:
+ * - sst_status: Show current SST stack status from local metadata
+ * - sst_resources: Parse and list resources defined in sst.config.ts
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@draht/coding-agent";
+import { Type } from "@sinclair/typebox";
+
+/** Find the nearest directory containing sst.config.ts, walking up from cwd */
+function findSstRoot(cwd: string): string | undefined {
+	let dir = resolve(cwd);
+	while (dir !== "/") {
+		if (existsSync(join(dir, "sst.config.ts"))) return dir;
+		dir = resolve(dir, "..");
+	}
+	return undefined;
+}
+
+/** Parse resource definitions from sst.config.ts using regex (no eval) */
+function parseResources(configPath: string): Array<{ type: string; name: string; line: number }> {
+	const content = readFileSync(configPath, "utf-8");
+	const resources: Array<{ type: string; name: string; line: number }> = [];
+	const lines = content.split("\n");
+
+	const resourcePattern = /new\s+sst\.aws\.(\w+)\(\s*["']([^"']+)["']/;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(resourcePattern);
+		if (match) {
+			resources.push({ type: match[1], name: match[2], line: i + 1 });
+		}
+	}
+
+	const routePattern = /\.route\(\s*["']([^"']+)["']/;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(routePattern);
+		if (match) {
+			resources.push({ type: "Route", name: match[1], line: i + 1 });
+		}
+	}
+
+	return resources;
+}
+
+/** Read .sst/ metadata if it exists */
+function readSstMetadata(sstRoot: string): Record<string, unknown> | undefined {
+	const metaDir = join(sstRoot, ".sst");
+	if (!existsSync(metaDir)) return undefined;
+
+	const result: Record<string, unknown> = {};
+
+	const stageFile = join(metaDir, "stage");
+	if (existsSync(stageFile)) {
+		result.stage = readFileSync(stageFile, "utf-8").trim();
+	}
+
+	try {
+		const entries = readdirSync(metaDir);
+		result.files = entries;
+		result.lastModified = entries.reduce(
+			(latest, entry) => {
+				try {
+					const stat = statSync(join(metaDir, entry));
+					return stat.mtimeMs > (latest ?? 0) ? stat.mtimeMs : latest;
+				} catch {
+					return latest;
+				}
+			},
+			undefined as number | undefined,
+		);
+	} catch {
+		// ignore
+	}
+
+	return result;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "sst_status",
+		label: "SST Status",
+		description:
+			"Show the current SST stack status from local .sst/ metadata. " +
+			"Reports stage, last activity, and whether the project has been initialized. " +
+			"Does NOT deploy or connect to AWS.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx: ExtensionContext) {
+			const sstRoot = findSstRoot(ctx.cwd);
+
+			if (!sstRoot) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "No sst.config.ts found in current directory or any parent. This project may not use SST.",
+						},
+					],
+					details: undefined,
+				};
+			}
+
+			const configPath = join(sstRoot, "sst.config.ts");
+			const metadata = readSstMetadata(sstRoot);
+			const hasConfig = existsSync(configPath);
+			const hasSstDir = existsSync(join(sstRoot, ".sst"));
+
+			const lines: string[] = [];
+			lines.push(`SST Project Root: ${sstRoot}`);
+			lines.push(`Config: ${hasConfig ? "sst.config.ts found" : "MISSING"}`);
+			lines.push(
+				`Initialized: ${hasSstDir ? "yes (.sst/ exists)" : "no (.sst/ not found — run sst dev to initialize)"}`,
+			);
+
+			if (metadata) {
+				if (metadata.stage) lines.push(`Stage: ${metadata.stage}`);
+				if (metadata.lastModified) {
+					lines.push(`Last Activity: ${new Date(metadata.lastModified as number).toISOString()}`);
+				}
+				if (metadata.files) {
+					lines.push(`Metadata Files: ${(metadata.files as string[]).join(", ")}`);
+				}
+			}
+
+			return {
+				content: [{ type: "text" as const, text: lines.join("\n") }],
+				details: undefined,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "sst_resources",
+		label: "SST Resources",
+		description:
+			"Parse and list all SST resources defined in sst.config.ts. " +
+			"Shows resource types (Dynamo, ApiGatewayV2, etc.), names, and line numbers. " +
+			"Reads the config file statically — does NOT deploy or query AWS.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx: ExtensionContext) {
+			const sstRoot = findSstRoot(ctx.cwd);
+
+			if (!sstRoot) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "No sst.config.ts found in current directory or any parent.",
+						},
+					],
+					details: undefined,
+				};
+			}
+
+			const configPath = join(sstRoot, "sst.config.ts");
+			const resources = parseResources(configPath);
+
+			if (resources.length === 0) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "No SST resources found in sst.config.ts. The file may use a non-standard pattern.",
+						},
+					],
+					details: undefined,
+				};
+			}
+
+			const lines = [`SST Resources in ${configPath}:`, ""];
+			const byType = new Map<string, typeof resources>();
+			for (const r of resources) {
+				const list = byType.get(r.type) ?? [];
+				list.push(r);
+				byType.set(r.type, list);
+			}
+
+			for (const [type, items] of byType) {
+				lines.push(`${type}:`);
+				for (const item of items) {
+					lines.push(`  - ${item.name} (line ${item.line})`);
+				}
+			}
+
+			lines.push("");
+			lines.push(`Total: ${resources.length} resources`);
+
+			return {
+				content: [{ type: "text" as const, text: lines.join("\n") }],
+				details: undefined,
+			};
+		},
+	});
+}

package/examples/extensions/status-line.ts

@@ -0,0 +1,40 @@
+/**
+ * Status Line Extension
+ *
+ * Demonstrates ctx.ui.setStatus() for displaying persistent status text in the footer.
+ * Shows turn progress with themed colors.
+ */
+
+import type { ExtensionAPI } from "@draht/coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	let turnCount = 0;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+	});
+
+	pi.on("turn_start", async (_event, ctx) => {
+		turnCount++;
+		const theme = ctx.ui.theme;
+		const spinner = theme.fg("accent", "●");
+		const text = theme.fg("dim", ` Turn ${turnCount}...`);
+		ctx.ui.setStatus("status-demo", spinner + text);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		const theme = ctx.ui.theme;
+		const check = theme.fg("success", "✓");
+		const text = theme.fg("dim", ` Turn ${turnCount} complete`);
+		ctx.ui.setStatus("status-demo", check + text);
+	});
+
+	pi.on("session_switch", async (event, ctx) => {
+		if (event.reason === "new") {
+			turnCount = 0;
+			const theme = ctx.ui.theme;
+			ctx.ui.setStatus("status-demo", theme.fg("dim", "Ready"));
+		}
+	});
+}

package/examples/extensions/subagent/README.md

@@ -0,0 +1,172 @@
+# Subagent Example
+
+Delegate tasks to specialized subagents with isolated context windows.
+
+## Features
+
+- **Isolated context**: Each subagent runs in a separate `pi` process
+- **Streaming output**: See tool calls and progress as they happen
+- **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
+- **Abort support**: Ctrl+C propagates to kill subagent processes
+
+## Structure
+
+```
+subagent/
+├── README.md            # This file
+├── index.ts             # The extension (entry point)
+├── agents.ts            # Agent discovery logic
+├── agents/              # Sample agent definitions
+│   ├── scout.md         # Fast recon, returns compressed context
+│   ├── planner.md       # Creates implementation plans
+│   ├── reviewer.md      # Code review
+│   └── worker.md        # General-purpose (full capabilities)
+└── prompts/             # Workflow presets (prompt templates)
+    ├── implement.md     # scout -> planner -> worker
+    ├── scout-and-plan.md    # scout -> planner (no implementation)
+    └── implement-and-review.md  # worker -> reviewer -> worker
+```
+
+## Installation
+
+From the repository root, symlink the files:
+
+```bash
+# Symlink the extension (must be in a subdirectory with index.ts)
+mkdir -p ~/.pi/agent/extensions/subagent
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
+
+# Symlink agents
+mkdir -p ~/.pi/agent/agents
+for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+# Symlink workflow prompts
+mkdir -p ~/.pi/agent/prompts
+for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+## Security Model
+
+This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration.
+
+**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
+
+**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+
+To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+
+When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
+
+## Usage
+
+### Single agent
+```
+Use scout to find all authentication code
+```
+
+### Parallel execution
+```
+Run 2 scouts in parallel: one to find models, one to find providers
+```
+
+### Chained workflow
+```
+Use a chain: first have scout find the read tool, then have planner suggest improvements
+```
+
+### Workflow prompts
+```
+/implement add Redis caching to the session store
+/scout-and-plan refactor auth to support OAuth
+/implement-and-review add input validation to API endpoints
+```
+
+## Tool Modes
+
+| Mode | Parameter | Description |
+|------|-----------|-------------|
+| Single | `{ agent, task }` | One agent, one task |
+| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
+| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
+
+## Output Display
+
+**Collapsed view** (default):
+- Status icon (✓/✗/⏳) and agent name
+- Last 5-10 items (tool calls and text)
+- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
+
+**Expanded view** (Ctrl+O):
+- Full task text
+- All tool calls with formatted arguments
+- Final output rendered as Markdown
+- Per-task usage (for chain/parallel)
+
+**Parallel mode streaming**:
+- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
+- Updates as each task makes progress
+- Shows "2/3 done, 1 running" status
+
+**Tool call formatting** (mimics built-in tools):
+- `$ command` for bash
+- `read ~/path:1-10` for read
+- `grep /pattern/ in ~/path` for grep
+- etc.
+
+## Agent Definitions
+
+Agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+System prompt for the agent goes here.
+```
+
+**Locations:**
+- `~/.pi/agent/agents/*.md` - User-level (always loaded)
+- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Sample Agents
+
+| Agent | Purpose | Model | Tools |
+|-------|---------|-------|-------|
+| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
+| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
+| `worker` | General-purpose | Sonnet | (all default) |
+
+## Workflow Prompts
+
+| Prompt | Flow |
+|--------|------|
+| `/implement <query>` | scout → planner → worker |
+| `/scout-and-plan <query>` | scout → planner |
+| `/implement-and-review <query>` | worker → reviewer → worker |
+
+## Error Handling
+
+- **Exit code != 0**: Tool returns error with stderr/output
+- **stopReason "error"**: LLM error propagated with error message
+- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
+- **Chain mode**: Stops at first failing step, reports which step failed
+
+## Limitations
+
+- Output truncated to last 10 items in collapsed view (expand to see all)
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent

package/examples/extensions/subagent/agents/planner.md

@@ -0,0 +1,37 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.