@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/minimal-mode/index.ts

@@ -0,0 +1,447 @@
+/**
+ * Minimal Mode Example - Demonstrates a "minimal" tool display mode
+ *
+ * This extension overrides built-in tools to provide custom rendering:
+ * - Collapsed mode: Only shows the tool call (command/path), no output
+ * - Expanded mode: Shows full output like the built-in renderers
+ *
+ * This demonstrates how a "minimal mode" could work, where ctrl+o cycles through:
+ * - Standard: Shows truncated output (current default)
+ * - Expanded: Shows full output (current expanded)
+ * - Minimal: Shows only tool call, no output (this extension's collapsed mode)
+ *
+ * Usage:
+ *   Copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ *   or <cwd>/.agent-forge/plugins for auto-discovery.
+ *
+ * Then use ctrl+o to toggle between minimal (collapsed) and full (expanded) views.
+ *
+ * Migrated to the capability plugin form (D-056 tool-surface batch, 2026-09-21):
+ * the seven same-name overrides ride the capability replacement contract (last
+ * load wins, restore on dispose); the execute `ctx.cwd` maps to the context
+ * parameter's cwd (the host-injected CapabilityToolContext on the runtime face).
+ */
+
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+import {
+	createBashTool,
+	createEditTool,
+	createFindTool,
+	createGrepTool,
+	createLsTool,
+	createReadTool,
+	createWriteTool,
+	defineTool,
+} from "@agent-forge/agent-forge";
+import { Text } from "@agent-forge/tui";
+import { homedir } from "os";
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+function shortenPath(path: string): string {
+	const home = homedir();
+	if (path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+// Cache for built-in tools by cwd
+const toolCache = new Map<string, ReturnType<typeof createBuiltInTools>>();
+
+function createBuiltInTools(cwd: string) {
+	return {
+		read: createReadTool(cwd),
+		bash: createBashTool(cwd),
+		edit: createEditTool(cwd),
+		write: createWriteTool(cwd),
+		find: createFindTool(cwd),
+		grep: createGrepTool(cwd),
+		ls: createLsTool(cwd),
+	};
+}
+
+function getBuiltInTools(cwd: string) {
+	let tools = toolCache.get(cwd);
+	if (!tools) {
+		tools = createBuiltInTools(cwd);
+		toolCache.set(cwd, tools);
+	}
+	return tools;
+}
+
+export default function (api: CapabilityAPI) {
+	// =========================================================================
+	// Read Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "read",
+			label: "read",
+			description:
+				"Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files.",
+			parameters: getBuiltInTools(process.cwd()).read.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.read.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const path = shortenPath(args.path || "");
+				let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+				// Show line range if specified
+				if (args.offset !== undefined || args.limit !== undefined) {
+					const startLine = args.offset ?? 1;
+					const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+					pathDisplay += theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+				}
+
+				return new Text(`${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				// Minimal mode: show nothing in collapsed state
+				if (!expanded) {
+					return new Text("", 0, 0);
+				}
+
+				// Expanded mode: show full output
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				const lines = textContent.text.split("\n");
+				const output = lines.map((line) => theme.fg("toolOutput", line)).join("\n");
+				return new Text(`\n${output}`, 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Bash Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "bash",
+			label: "bash",
+			description:
+				"Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first).",
+			parameters: getBuiltInTools(process.cwd()).bash.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.bash.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const command = args.command || "...";
+				const timeout = args.timeout as number | undefined;
+				const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
+
+				return new Text(theme.fg("toolTitle", theme.bold(`$ ${command}`)) + timeoutSuffix, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				// Minimal mode: show nothing in collapsed state
+				if (!expanded) {
+					return new Text("", 0, 0);
+				}
+
+				// Expanded mode: show full output
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				const output = textContent.text
+					.trim()
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n");
+
+				if (!output) {
+					return new Text("", 0, 0);
+				}
+
+				return new Text(`\n${output}`, 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Write Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "write",
+			label: "write",
+			description:
+				"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+			parameters: getBuiltInTools(process.cwd()).write.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.write.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const path = shortenPath(args.path || "");
+				const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+				const lineCount = args.content ? args.content.split("\n").length : 0;
+				const lineInfo = lineCount > 0 ? theme.fg("muted", ` (${lineCount} lines)`) : "";
+
+				return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				// Minimal mode: show nothing (file was written)
+				if (!expanded) {
+					return new Text("", 0, 0);
+				}
+
+				// Expanded mode: show error if any
+				if (result.content.some((c) => c.type === "text" && c.text)) {
+					const textContent = result.content.find((c) => c.type === "text");
+					if (textContent?.type === "text" && textContent.text) {
+						return new Text(`\n${theme.fg("error", textContent.text)}`, 0, 0);
+					}
+				}
+
+				return new Text("", 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Edit Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "edit",
+			label: "edit",
+			description:
+				"Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits.",
+			parameters: getBuiltInTools(process.cwd()).edit.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.edit.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const path = shortenPath(args.path || "");
+				const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+				return new Text(`${theme.fg("toolTitle", theme.bold("edit"))} ${pathDisplay}`, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				// Minimal mode: show nothing in collapsed state
+				if (!expanded) {
+					return new Text("", 0, 0);
+				}
+
+				// Expanded mode: show diff or error
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				// For errors, show the error message
+				const text = textContent.text;
+				if (text.includes("Error") || text.includes("error")) {
+					return new Text(`\n${theme.fg("error", text)}`, 0, 0);
+				}
+
+				// Otherwise show the text (would be nice to show actual diff here)
+				return new Text(`\n${theme.fg("toolOutput", text)}`, 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Find Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "find",
+			label: "find",
+			description:
+				"Find files by name pattern (glob). Searches recursively from the specified path. Output limited to 200 results.",
+			parameters: getBuiltInTools(process.cwd()).find.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.find.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const pattern = args.pattern || "";
+				const path = shortenPath(args.path || ".");
+				const limit = args.limit;
+
+				let text = `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}`;
+				text += theme.fg("toolOutput", ` in ${path}`);
+				if (limit !== undefined) {
+					text += theme.fg("toolOutput", ` (limit ${limit})`);
+				}
+
+				return new Text(text, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				if (!expanded) {
+					// Minimal: just show count
+					const textContent = result.content.find((c) => c.type === "text");
+					if (textContent?.type === "text") {
+						const count = textContent.text.trim().split("\n").filter(Boolean).length;
+						if (count > 0) {
+							return new Text(theme.fg("muted", ` → ${count} files`), 0, 0);
+						}
+					}
+					return new Text("", 0, 0);
+				}
+
+				// Expanded: show full results
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				const output = textContent.text
+					.trim()
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n");
+
+				return new Text(`\n${output}`, 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Grep Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "grep",
+			label: "grep",
+			description:
+				"Search file contents by regex pattern. Uses ripgrep for fast searching. Output limited to 200 matches.",
+			parameters: getBuiltInTools(process.cwd()).grep.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.grep.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const pattern = args.pattern || "";
+				const path = shortenPath(args.path || ".");
+				const glob = args.glob;
+				const limit = args.limit;
+
+				let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${pattern}/`)}`;
+				text += theme.fg("toolOutput", ` in ${path}`);
+				if (glob) {
+					text += theme.fg("toolOutput", ` (${glob})`);
+				}
+				if (limit !== undefined) {
+					text += theme.fg("toolOutput", ` limit ${limit}`);
+				}
+
+				return new Text(text, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				if (!expanded) {
+					// Minimal: just show match count
+					const textContent = result.content.find((c) => c.type === "text");
+					if (textContent?.type === "text") {
+						const count = textContent.text.trim().split("\n").filter(Boolean).length;
+						if (count > 0) {
+							return new Text(theme.fg("muted", ` → ${count} matches`), 0, 0);
+						}
+					}
+					return new Text("", 0, 0);
+				}
+
+				// Expanded: show full results
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				const output = textContent.text
+					.trim()
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n");
+
+				return new Text(`\n${output}`, 0, 0);
+			},
+		}),
+	);
+
+	// =========================================================================
+	// Ls Tool
+	// =========================================================================
+	api.registerTool(
+		defineTool({
+			name: "ls",
+			label: "ls",
+			description:
+				"List directory contents with file sizes. Shows files and directories with their sizes. Output limited to 500 entries.",
+			parameters: getBuiltInTools(process.cwd()).ls.parameters,
+
+			async execute(toolCallId, params, signal, onUpdate, context) {
+				const tools = getBuiltInTools(context?.cwd ?? process.cwd());
+				return tools.ls.execute(toolCallId, params, signal, onUpdate);
+			},
+
+			renderCall(args, theme, _context) {
+				const path = shortenPath(args.path || ".");
+				const limit = args.limit;
+
+				let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", path)}`;
+				if (limit !== undefined) {
+					text += theme.fg("toolOutput", ` (limit ${limit})`);
+				}
+
+				return new Text(text, 0, 0);
+			},
+
+			renderResult(result, { expanded }, theme, _context) {
+				if (!expanded) {
+					// Minimal: just show entry count
+					const textContent = result.content.find((c) => c.type === "text");
+					if (textContent?.type === "text") {
+						const count = textContent.text.trim().split("\n").filter(Boolean).length;
+						if (count > 0) {
+							return new Text(theme.fg("muted", ` → ${count} entries`), 0, 0);
+						}
+					}
+					return new Text("", 0, 0);
+				}
+
+				// Expanded: show full listing
+				const textContent = result.content.find((c) => c.type === "text");
+				if (!textContent || textContent.type !== "text") {
+					return new Text("", 0, 0);
+				}
+
+				const output = textContent.text
+					.trim()
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n");
+
+				return new Text(`\n${output}`, 0, 0);
+			},
+		}),
+	);
+}

package/examples/extensions/minimal-mode/plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "agent-forge.example.minimal-mode",
+  "version": "0.1.0",
+  "hostVersion": ">=0.84.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": [
+    "tools"
+  ]
+}

package/examples/extensions/multi-agent/README.md

@@ -0,0 +1,7 @@
+# Multi-Agent 示例插件
+
+该示例通过公开 `CapabilityAPI`、`SessionAPI` 和 `api.agents` 注册 `agent.dispatch`、`agent.status`、`agent.wait`、`agent.cancel` 四个工具。`agent.dispatch` 先创建隔离 child session，再显式调用 `run()`；内核不会在 `create()` 时自动执行。任务记录包含 `id`、`parentSessionId`、可选 `goalId/planId`、`prompt`、可选 `deadlineMs/budget`、`status`、`revision` 以及受大小限制的 `result/error`。
+
+插件把每次状态变化作为 `multi-agent.state` branch-local custom entry 保存，并发布 `agent.task.changed` 结构化事件。取消、失败、重复 task id、未知 task、终态重复操作和过大的 dispatch result 都会显式报错；取消后 transport 仍返回的结果会发布 `agent.task.late_completion`，不会覆盖取消状态。
+
+该示例不创建进程、不联网、不调用真实 AI，也不实现安全、审批、沙箱、队列、并发限制或预算策略。`deadlineMs` 只负责取消超期任务，`budget` 只保留声明；真正的 token/cost 计量、外部 transport 和写入协调仍由可替换插件实现。插件销毁会中止并销毁活动 child session，并拒绝尚未完成的等待。