@dreb/coding-agent 1.16.0

package/examples/extensions/doom-overlay/wad-finder.ts

@@ -0,0 +1,51 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Get the bundled WAD path (relative to this module)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_WAD = join(__dirname, "doom1.wad");
+const WAD_URL = "https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad";
+
+const DEFAULT_WAD_PATHS = ["./doom1.wad", "./DOOM1.WAD", "~/doom1.wad", "~/.doom/doom1.wad"];
+
+export function findWadFile(customPath?: string): string | null {
+	if (customPath) {
+		const resolved = resolve(customPath.replace(/^~/, process.env.HOME || ""));
+		if (existsSync(resolved)) return resolved;
+		return null;
+	}
+
+	// Check bundled WAD first
+	if (existsSync(BUNDLED_WAD)) {
+		return BUNDLED_WAD;
+	}
+
+	// Fall back to default paths
+	for (const p of DEFAULT_WAD_PATHS) {
+		const resolved = resolve(p.replace(/^~/, process.env.HOME || ""));
+		if (existsSync(resolved)) return resolved;
+	}
+
+	return null;
+}
+
+/** Download the shareware WAD if not present. Returns path or null on failure. */
+export async function ensureWadFile(): Promise<string | null> {
+	// Check if already exists
+	const existing = findWadFile();
+	if (existing) return existing;
+
+	// Download to bundled location
+	try {
+		const response = await fetch(WAD_URL);
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status}`);
+		}
+		const buffer = await response.arrayBuffer();
+		writeFileSync(BUNDLED_WAD, Buffer.from(buffer));
+		return BUNDLED_WAD;
+	} catch {
+		return null;
+	}
+}

package/examples/extensions/dynamic-resources/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: dynamic-resources
+description: Example skill loaded from resources_discover
+---
+
+# Dynamic Resources Skill
+
+This skill is provided by the dynamic-resources extension.

package/examples/extensions/dynamic-resources/dynamic.json

@@ -0,0 +1,79 @@
+{
+	"$schema": "https://raw.githubusercontent.com/aebrer/dreb/master/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "dynamic-resources",
+	"vars": {
+		"cyan": "#00d7ff",
+		"blue": "#5f87ff",
+		"green": "#b5bd68",
+		"red": "#cc6666",
+		"yellow": "#ffff00",
+		"gray": "#808080",
+		"dimGray": "#666666",
+		"darkGray": "#505050",
+		"accent": "#8abeb7",
+		"selectedBg": "#3a3a4a",
+		"userMsgBg": "#343541",
+		"toolPendingBg": "#282832",
+		"toolSuccessBg": "#283228",
+		"toolErrorBg": "#3c2828",
+		"customMsgBg": "#2d2838"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "blue",
+		"borderAccent": "cyan",
+		"borderMuted": "darkGray",
+		"success": "green",
+		"error": "red",
+		"warning": "yellow",
+		"muted": "gray",
+		"dim": "dimGray",
+		"text": "",
+		"thinkingText": "gray",
+		"selectedBg": "selectedBg",
+		"userMessageBg": "userMsgBg",
+		"userMessageText": "",
+		"customMessageBg": "customMsgBg",
+		"customMessageText": "",
+		"customMessageLabel": "#9575cd",
+		"toolPendingBg": "toolPendingBg",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "",
+		"toolOutput": "gray",
+		"mdHeading": "#f0c674",
+		"mdLink": "#81a2be",
+		"mdLinkUrl": "dimGray",
+		"mdCode": "accent",
+		"mdCodeBlock": "green",
+		"mdCodeBlockBorder": "gray",
+		"mdQuote": "gray",
+		"mdQuoteBorder": "gray",
+		"mdHr": "gray",
+		"mdListBullet": "accent",
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "gray",
+		"syntaxComment": "#6A9955",
+		"syntaxKeyword": "#569CD6",
+		"syntaxFunction": "#DCDCAA",
+		"syntaxVariable": "#9CDCFE",
+		"syntaxString": "#CE9178",
+		"syntaxNumber": "#B5CEA8",
+		"syntaxType": "#4EC9B0",
+		"syntaxOperator": "#D4D4D4",
+		"syntaxPunctuation": "#D4D4D4",
+		"thinkingOff": "darkGray",
+		"thinkingMinimal": "#6e6e6e",
+		"thinkingLow": "#5f87af",
+		"thinkingMedium": "#81a2be",
+		"thinkingHigh": "#b294bb",
+		"thinkingXhigh": "#d183e8",
+		"bashMode": "green"
+	},
+	"export": {
+		"pageBg": "#18181e",
+		"cardBg": "#1e1e24",
+		"infoBg": "#3c3728"
+	}
+}

package/examples/extensions/dynamic-resources/dynamic.md

@@ -0,0 +1,5 @@
+---
+description: Example prompt template loaded from resources_discover
+---
+
+Summarize the current repository structure and mention any build or test commands.

package/examples/extensions/dynamic-resources/index.ts

@@ -0,0 +1,15 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+export default function (dreb: ExtensionAPI) {
+	dreb.on("resources_discover", () => {
+		return {
+			skillPaths: [join(baseDir, "SKILL.md")],
+			promptPaths: [join(baseDir, "dynamic.md")],
+			themePaths: [join(baseDir, "dynamic.json")],
+		};
+	});
+}

package/examples/extensions/dynamic-tools.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ */
+
+import type { ExtensionAPI } from "@dreb/coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const ECHO_PARAMS = Type.Object({
+	message: Type.String({ description: "Message to echo" }),
+});
+
+function normalizeToolName(input: string): string | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (!trimmed) return undefined;
+	if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export default function dynamicToolsExtension(dreb: ExtensionAPI) {
+	const registeredToolNames = new Set<string>();
+
+	const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+		if (registeredToolNames.has(name)) {
+			return false;
+		}
+
+		registeredToolNames.add(name);
+		dreb.registerTool({
+			name,
+			label,
+			description: `Echo a message with prefix: ${prefix}`,
+			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+			promptGuidelines: ["Use this tool when the user asks for exact echo output."],
+			parameters: ECHO_PARAMS,
+			async execute(_toolCallId, params) {
+				return {
+					content: [{ type: "text", text: `${prefix}${params.message}` }],
+					details: { tool: name, prefix },
+				};
+			},
+		});
+
+		return true;
+	};
+
+	dreb.on("session_start", (_event, ctx) => {
+		registerEchoTool("echo_session", "Echo Session", "[session] ");
+		ctx.ui.notify("Registered dynamic tool: echo_session", "info");
+	});
+
+	dreb.registerCommand("add-echo-tool", {
+		description: "Register a new echo tool dynamically: /add-echo-tool <tool_name>",
+		handler: async (args, ctx) => {
+			const toolName = normalizeToolName(args);
+			if (!toolName) {
+				ctx.ui.notify("Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)", "warning");
+				return;
+			}
+
+			const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+			if (!created) {
+				ctx.ui.notify(`Tool already registered: ${toolName}`, "warning");
+				return;
+			}
+
+			ctx.ui.notify(`Registered dynamic tool: ${toolName}`, "info");
+		},
+	});
+}

package/examples/extensions/event-bus.ts

@@ -0,0 +1,43 @@
+/**
+ * Inter-extension event bus example.
+ *
+ * Shows dreb.events for communication between extensions. One extension
+ * can emit events that other extensions listen to.
+ *
+ * Usage: /emit [event-name] [data] - emit an event on the bus
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	// Store ctx for use in event handler
+	let currentCtx: ExtensionContext | undefined;
+
+	dreb.on("session_start", async (_event, ctx) => {
+		currentCtx = ctx;
+	});
+
+	// Listen for events from other extensions
+	dreb.events.on("my:notification", (data) => {
+		const { message, from } = data as { message: string; from: string };
+		currentCtx?.ui.notify(`Event from ${from}: ${message}`, "info");
+	});
+
+	// Command to emit events (emits "my:notification" which the listener above receives)
+	dreb.registerCommand("emit", {
+		description: "Emit my:notification event (usage: /emit message)",
+		handler: async (args, _ctx) => {
+			const message = args.trim() || "hello";
+			dreb.events.emit("my:notification", { message, from: "/emit command" });
+			// Listener above will show the notification
+		},
+	});
+
+	// Example: emit on session start
+	dreb.on("session_start", async () => {
+		dreb.events.emit("my:notification", {
+			message: "Session started",
+			from: "event-bus-example",
+		});
+	});
+}

package/examples/extensions/file-trigger.ts

@@ -0,0 +1,41 @@
+/**
+ * File Trigger Extension
+ *
+ * Watches a trigger file and injects its contents into the conversation.
+ * Useful for external systems to send messages to the agent.
+ *
+ * Usage:
+ *   echo "Run the tests" > /tmp/agent-trigger.txt
+ */
+
+import * as fs from "node:fs";
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	dreb.on("session_start", async (_event, ctx) => {
+		const triggerFile = "/tmp/agent-trigger.txt";
+
+		fs.watch(triggerFile, () => {
+			try {
+				const content = fs.readFileSync(triggerFile, "utf-8").trim();
+				if (content) {
+					dreb.sendMessage(
+						{
+							customType: "file-trigger",
+							content: `External trigger: ${content}`,
+							display: true,
+						},
+						{ triggerTurn: true }, // triggerTurn - get LLM to respond
+					);
+					fs.writeFileSync(triggerFile, ""); // Clear after reading
+				}
+			} catch {
+				// File might not exist yet
+			}
+		});
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Watching ${triggerFile}`, "info");
+		}
+	});
+}

package/examples/extensions/git-checkpoint.ts

@@ -0,0 +1,53 @@
+/**
+ * Git Checkpoint Extension
+ *
+ * Creates git stash checkpoints at each turn so /fork can restore code state.
+ * When forking, offers to restore code to that point in history.
+ */
+
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	const checkpoints = new Map<string, string>();
+	let currentEntryId: string | undefined;
+
+	// Track the current entry ID when user messages are saved
+	dreb.on("tool_result", async (_event, ctx) => {
+		const leaf = ctx.sessionManager.getLeafEntry();
+		if (leaf) currentEntryId = leaf.id;
+	});
+
+	dreb.on("turn_start", async () => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await dreb.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref && currentEntryId) {
+			checkpoints.set(currentEntryId, ref);
+		}
+	});
+
+	dreb.on("session_before_fork", async (event, ctx) => {
+		const ref = checkpoints.get(event.entryId);
+		if (!ref) return;
+
+		if (!ctx.hasUI) {
+			// In non-interactive mode, don't restore automatically
+			return;
+		}
+
+		const choice = await ctx.ui.select("Restore code state?", [
+			"Yes, restore code to that point",
+			"No, keep current code",
+		]);
+
+		if (choice?.startsWith("Yes")) {
+			await dreb.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+	});
+
+	dreb.on("agent_end", async () => {
+		// Clear checkpoints after agent completes
+		checkpoints.clear();
+	});
+}

package/examples/extensions/handoff.ts

@@ -0,0 +1,150 @@
+/**
+ * Handoff extension - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import { complete, type Message } from "@dreb/ai";
+import type { ExtensionAPI, SessionEntry } from "@dreb/coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@dreb/coding-agent";
+
+const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
+
+1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+export default function (dreb: ExtensionAPI) {
+	dreb.registerCommand("handoff", {
+		description: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			// Gather conversation context from current branch
+			const branch = ctx.sessionManager.getBranch();
+			const messages = branch
+				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+				.map((entry) => entry.message);
+
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			// Convert to LLM format and serialize
+			const llmMessages = convertToLlm(messages);
+			const conversationText = serializeConversation(llmMessages);
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Generate the handoff prompt with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+					const userMessage: Message = {
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+							},
+						],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doGenerate()
+					.then(done)
+					.catch((err) => {
+						console.error("Handoff generation failed:", err);
+						done(null);
+					});
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt", result);
+
+			if (editedPrompt === undefined) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Create new session with parent tracking
+			const newSessionResult = await ctx.newSession({
+				parentSession: currentSessionFile,
+			});
+
+			if (newSessionResult.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+				return;
+			}
+
+			// Set the edited prompt in the main editor for submission
+			ctx.ui.setEditorText(editedPrompt);
+			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
+		},
+	});
+}

package/examples/extensions/hello.ts

@@ -0,0 +1,25 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ */
+
+import { Type } from "@dreb/ai";
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	dreb.registerTool({
+		name: "hello",
+		label: "Hello",
+		description: "A simple greeting tool",
+		parameters: Type.Object({
+			name: Type.String({ description: "Name to greet" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const { name } = params as { name: string };
+			return {
+				content: [{ type: "text", text: `Hello, ${name}!` }],
+				details: { greeted: name },
+			};
+		},
+	});
+}

package/examples/extensions/inline-bash.ts

@@ -0,0 +1,94 @@
+/**
+ * Inline Bash Extension - expands inline bash commands in user prompts.
+ *
+ * Start dreb with this extension:
+ *   dreb -e ./examples/extensions/inline-bash.ts
+ *
+ * Then type prompts with inline bash:
+ *   What's in !{pwd}?
+ *   The current branch is !{git branch --show-current} and status: !{git status --short}
+ *   My node version is !{node --version}
+ *
+ * The !{command} patterns are executed and replaced with their output before
+ * the prompt is sent to the agent.
+ *
+ * Note: Regular !command syntax (whole-line bash) is preserved and works as before.
+ */
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	const PATTERN = /!\{([^}]+)\}/g;
+	const TIMEOUT_MS = 30000;
+
+	dreb.on("input", async (event, ctx) => {
+		const text = event.text;
+
+		// Don't process if it's a whole-line bash command (starts with !)
+		// This preserves the existing !command behavior
+		if (text.trimStart().startsWith("!") && !text.trimStart().startsWith("!{")) {
+			return { action: "continue" };
+		}
+
+		// Check if there are any inline bash patterns
+		if (!PATTERN.test(text)) {
+			return { action: "continue" };
+		}
+
+		// Reset regex state after test()
+		PATTERN.lastIndex = 0;
+
+		let result = text;
+		const expansions: Array<{ command: string; output: string; error?: string }> = [];
+
+		// Find all matches first (to avoid issues with replacing while iterating)
+		const matches: Array<{ full: string; command: string }> = [];
+		let match = PATTERN.exec(text);
+		while (match) {
+			matches.push({ full: match[0], command: match[1] });
+			match = PATTERN.exec(text);
+		}
+
+		// Execute each command and collect results
+		for (const { full, command } of matches) {
+			try {
+				const bashResult = await dreb.exec("bash", ["-c", command], {
+					timeout: TIMEOUT_MS,
+				});
+
+				const output = bashResult.stdout || bashResult.stderr || "";
+				const trimmed = output.trim();
+
+				if (bashResult.code !== 0 && bashResult.stderr) {
+					expansions.push({
+						command,
+						output: trimmed,
+						error: `exit code ${bashResult.code}`,
+					});
+				} else {
+					expansions.push({ command, output: trimmed });
+				}
+
+				result = result.replace(full, trimmed);
+			} catch (err) {
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				expansions.push({ command, output: "", error: errorMsg });
+				result = result.replace(full, `[error: ${errorMsg}]`);
+			}
+		}
+
+		// Show what was expanded (if UI available)
+		if (ctx.hasUI && expansions.length > 0) {
+			const summary = expansions
+				.map((e) => {
+					const status = e.error ? ` (${e.error})` : "";
+					const preview = e.output.length > 50 ? `${e.output.slice(0, 50)}...` : e.output;
+					return `!{${e.command}}${status} -> "${preview}"`;
+				})
+				.join("\n");
+
+			ctx.ui.notify(`Expanded ${expansions.length} inline command(s):\n${summary}`, "info");
+		}
+
+		return { action: "transform", text: result, images: event.images };
+	});
+}

package/examples/extensions/input-transform.ts

@@ -0,0 +1,43 @@
+/**
+ * Input Transform Example - demonstrates the `input` event for intercepting user input.
+ *
+ * Start dreb with this extension:
+ *   dreb -e ./examples/extensions/input-transform.ts
+ *
+ * Then type these inside dreb:
+ *   ?quick What is TypeScript?  → "Respond briefly: What is TypeScript?"
+ *   ping                        → "pong" (instant, no LLM)
+ *   time                        → current time (instant, no LLM)
+ */
+import type { ExtensionAPI } from "@dreb/coding-agent";
+
+export default function (dreb: ExtensionAPI) {
+	dreb.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" };
+	});
+}