@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/event-bus/plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "agent-forge.example.event-bus",
+  "version": "0.1.0",
+  "hostVersion": ">=0.84.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": [
+    "commands"
+  ],
+  "optionalCapabilities": [
+    "interaction"
+  ]
+}

package/examples/extensions/file-trigger/index.ts

@@ -0,0 +1,65 @@
+/**
+ * File Trigger Extension (capability plugin form)
+ *
+ * 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
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ *
+ * Migrated to the capability plugin form (D-056 session-surface batch, 2026-09-21):
+ * `pi.on("session_start")` maps to `api.lifecycle.registerObserve("session.start",
+ * handler, 1)` (the catalog's SESSION_START_EVENT_ID/SESSION_START_EVENT_VERSION pair),
+ * `pi.sendMessage(message, { triggerTurn })` to `SessionAPI.sendMessage?(message,
+ * { triggerTurn })` — the host forwards both arguments verbatim to
+ * AgentSession.sendCustomMessage, so `customType`, `display` and the triggerTurn option
+ * keep their meaning — and `ctx.hasUI` + `ctx.ui.notify` to the optional
+ * `api.interaction` surface.
+ *
+ * The legacy face's own binding reported a failed send through the extension runner
+ * (agent-session-extensions.ts `sendMessage` → `runner.emitError`); the capability face's
+ * equivalent is the plugin logger, so the same failure stays visible instead of turning
+ * into an unhandled rejection in the fs.watch callback.
+ */
+
+import * as fs from "node:fs";
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+
+export default function fileTriggerExample(api: CapabilityAPI): void {
+	api.lifecycle.registerObserve(
+		"session.start",
+		() => {
+			const triggerFile = "/tmp/agent-trigger.txt";
+
+			fs.watch(triggerFile, () => {
+				try {
+					const content = fs.readFileSync(triggerFile, "utf-8").trim();
+					if (content) {
+						const sent = api.session?.sendMessage?.(
+							{
+								customType: "file-trigger",
+								content: `External trigger: ${content}`,
+								display: true,
+							},
+							{ triggerTurn: true }, // triggerTurn - get LLM to respond
+						);
+						sent?.catch((error: unknown) => {
+							api.logger?.error("file-trigger could not inject the trigger message", undefined, error);
+						});
+						fs.writeFileSync(triggerFile, ""); // Clear after reading
+					}
+				} catch {
+					// File might not exist yet
+				}
+			});
+
+			// The legacy `ctx.hasUI` guard maps to the presence of the host's
+			// interaction surface (a host declares `interaction` only when it has one).
+			api.interaction?.notify({ message: `Watching ${triggerFile}`, level: "info" });
+		},
+		1,
+	);
+}

package/examples/extensions/file-trigger/plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "agent-forge.example.file-trigger",
+  "version": "0.1.0",
+  "hostVersion": ">=0.84.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": [
+    "session"
+  ],
+  "optionalCapabilities": [
+    "interaction"
+  ]
+}

package/examples/extensions/goal/README.md

@@ -0,0 +1,16 @@
+# Goal 示例插件
+
+单一职责的 Goal 示例：只提供 `goal_set` 一个工具，通过 `CapabilityAPI` 注册，通过 `SessionAPI` 把 branch-local 状态写入 `goal.state` custom entry，并通过 `publish()` 发送 `goal.changed` 结构化变更事件。
+
+内核不认识 Goal 业务对象，也不强制模型使用计划。revision、证据引用和状态转换由插件自行定义；是否加载、是否允许写入由宿主选择 `readonly` 或 `full-control` 以及用户安装的外部策略决定。
+
+状态机为 `open → completed / cancelled`。`completed` 是终态：写入必须至少提供一条证据引用（`evidence`），终态不允许通过更高 revision 回退；`revision` 必须递增。校验失败不会追加 session 条目。
+
+该目录包含可直接加载的 `plugin.json`。将整个目录复制到以下任一位置，新的 `AgentSession` 会自动加载它：
+
+- `<agentDir>/plugins/goal`
+- `<project>/.agent-forge/plugins/goal`
+
+加载顺序固定为用户目录、项目目录、显式 manifest 路径。两个副本使用同一 plugin ID 时会明确失败，不会按目录优先级静默覆盖。
+
+计划（`../plan`）与待办（`../todo-set`）是独立插件，可单独安装；它们通过字符串软引用 `goalId` / `planId` 关联记录，不依赖本插件存在。

package/examples/extensions/goal/index.ts

@@ -0,0 +1,134 @@
+import type { CapabilityAPI, DisposableRegistration, EventEnvelope } from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+export interface GoalRecord {
+	id: string;
+	title: string;
+	status: "open" | "completed" | "cancelled";
+	revision: number;
+	evidence: string[];
+}
+
+export interface GoalState {
+	goals: GoalRecord[];
+}
+
+export interface GoalPluginHandle {
+	readonly tools: readonly DisposableRegistration[];
+	dispose(): Promise<void>;
+}
+
+const stateEntry = "goal.state";
+
+const goalSchema = Type.Object({
+	id: Type.String({ description: "Stable id of the goal to create or update" }),
+	title: Type.String({ description: "Human-readable goal title" }),
+	revision: Type.Integer({
+		description: "New revision counter; must be greater than the stored revision of an existing goal",
+		minimum: 0,
+	}),
+	status: Type.Optional(
+		Type.Union([Type.Literal("open"), Type.Literal("completed"), Type.Literal("cancelled")], {
+			description: "Next status; defaults to the stored status for existing goals, otherwise open",
+		}),
+	),
+	evidence: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Evidence references; at least one is required when status is completed",
+		}),
+	),
+});
+
+function objectInput(first: unknown, second: unknown): Record<string, unknown> {
+	const value = second === undefined ? first : second;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Goal input must be an object");
+	return value as Record<string, unknown>;
+}
+
+function text(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} must be a non-empty string`);
+	return value;
+}
+
+function revision(value: unknown): number {
+	if (!Number.isInteger(value) || (value as number) < 0) throw new Error("revision must be a non-negative integer");
+	return value as number;
+}
+
+function evidence(value: unknown): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+		throw new Error("evidence must be a string array");
+	}
+	return [...(value as string[])];
+}
+
+function loadState(api: CapabilityAPI): GoalState {
+	const entries = api.session?.getBranchEntries() ?? [];
+	const entry = [...entries].reverse().find((item) => item.customType === stateEntry);
+	if (!entry?.data || typeof entry.data !== "object") return { goals: [] };
+	const data = entry.data as Partial<GoalState>;
+	return { goals: Array.isArray(data.goals) ? [...data.goals] : [] };
+}
+
+export function createGoalPlugin(api: CapabilityAPI): GoalPluginHandle {
+	let state = loadState(api);
+	const tools: DisposableRegistration[] = [];
+
+	const persist = async (): Promise<GoalState> => {
+		api.session?.appendEntry(stateEntry, state);
+		await api.publish({ type: "goal.changed", version: 1, correlationId: stateEntry, data: state });
+		return state;
+	};
+
+	tools.push(
+		api.registerTool({
+			name: "goal_set",
+			label: "Set goal",
+			description: "Create or update a goal with explicit revision and evidence",
+			parameters: goalSchema,
+			execute: async (first: unknown, second?: unknown) => {
+				const input = objectInput(first, second);
+				const id = text(input.id, "id");
+				const title = text(input.title, "title");
+				const nextRevision = revision(input.revision);
+				const current = state.goals.find((item) => item.id === id);
+				if (current && nextRevision <= current.revision) throw new Error(`stale goal revision: ${id}`);
+				if (current?.status === "completed" || current?.status === "cancelled") {
+					throw new Error(`goal is terminal and cannot be updated: ${id}`);
+				}
+				const values = evidence(input.evidence);
+				const record: GoalRecord = {
+					id,
+					title,
+					status:
+						input.status === undefined
+							? (current?.status ?? "open")
+							: (text(input.status, "status") as GoalRecord["status"]),
+					revision: nextRevision,
+					evidence: values,
+				};
+				if (!["open", "completed", "cancelled"].includes(record.status)) throw new Error("invalid goal status");
+				if (record.status === "completed" && values.length === 0) {
+					throw new Error("goal completion requires at least one evidence reference");
+				}
+				state = { ...state, goals: [...state.goals.filter((item) => item.id !== id), record] };
+				return persist();
+			},
+		}),
+	);
+
+	return {
+		tools,
+		dispose: async () => {
+			for (const tool of tools) await tool.dispose();
+		},
+	};
+}
+
+/** Manifest entry for the self-contained Goal example plugin. */
+export default function goalExample(api: CapabilityAPI): GoalPluginHandle {
+	return createGoalPlugin(api);
+}
+
+export type GoalEvent = EventEnvelope<GoalState>;

package/examples/extensions/goal/plugin.json

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

package/examples/extensions/hello/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Hello Tool - Minimal custom tool example (capability plugin form)
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import { type CapabilityAPI, defineTool } from "@agent-forge/agent-forge";
+import { Type } from "@agent-forge/ai";
+
+const helloTool = defineTool({
+	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) {
+		return {
+			content: [{ type: "text", text: `Hello, ${params.name}!` }],
+			details: { greeted: params.name },
+		};
+	},
+});
+
+export default function helloExample(api: CapabilityAPI): void {
+	api.registerTool(helloTool);
+}

package/examples/extensions/hello/plugin.json

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

package/examples/extensions/kimi-deferred-tools/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Minimal Kimi deferred-tool loading demo (capability plugin form).
+ *
+ * Kimi's deferred loading protocol is expressible with the capability tools
+ * surface: every registered tool exists in the registry, and only the names in
+ * the session's active set are prompt-visible. Activation happens once per
+ * session at the `session.start` host lifecycle boundary (version 1, the
+ * catalog's `SESSION_START_EVENT_ID`/`SESSION_START_EVENT_VERSION` pair in
+ * src/core/extensions/lifecycle-catalog.ts) through
+ * `api.lifecycle.registerObserve`, replacing the legacy `pi.on("session_start")`
+ * subscription; the legacy `pi.getActiveTools`/`pi.setActiveTools` pair maps to
+ * the optional `SessionAPI.getActiveTools?`/`setActiveTools?` members.
+ *
+ *   example prompt: Use the available tools to calculate 100 + 500. Do not calculate it yourself.
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import { type CapabilityAPI, defineTool } from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+function calculate(_expr: string): string {
+	return "42";
+}
+
+/**
+ * The plugin API captured at factory time. The tool definitions are module
+ * constants (the registry entries must exist before the first turn), and their
+ * execute callbacks read the tool set lazily through this holder.
+ */
+let api: CapabilityAPI;
+
+const calculatorTool = defineTool({
+	name: "Calculator",
+	label: "Calculator",
+	description: "Evaluate a simple arithmetic expression.",
+	parameters: Type.Object({
+		expr: Type.String({ description: "An expression such as 100 + 500" }),
+	}),
+	async execute(_toolCallId, params) {
+		return {
+			content: [{ type: "text", text: calculate(params.expr) }],
+			details: {},
+		};
+	},
+});
+
+// Registered but never activated by the factory: the session.start observer
+// narrows the active set to tool_search, and tool_search adds Calculator back
+// once a query matches. Activation only accepts registered names, so the
+// deferred tool's registration is what has to precede the first turn.
+const toolSearchTool = defineTool({
+	name: "tool_search",
+	label: "Tool Search",
+	description: "Find and activate tools for a capability.",
+	promptSnippet: "Search for additional tools when the active tools cannot perform the task",
+	parameters: Type.Object({
+		query: Type.String({ description: "Capability to search for" }),
+	}),
+	async execute(_toolCallId, params) {
+		if (!params.query.toLowerCase().includes("calc")) {
+			return {
+				content: [{ type: "text", text: "The relevant tools do not exist." }],
+				details: { matches: [], added: [] },
+			};
+		}
+
+		const session = api.session;
+		const active = session?.getActiveTools?.() ?? [];
+		const added = active.includes("Calculator") ? [] : ["Calculator"];
+		if (added.length > 0) session?.setActiveTools?.([...active, ...added]);
+
+		return {
+			content: [{ type: "text", text: "Success. Found 1 matching tool(s)" }],
+			details: { matches: ["Calculator"], added },
+		};
+	},
+});
+
+export default function kimiDeferredToolsExample(capabilityApi: CapabilityAPI): void {
+	api = capabilityApi;
+	api.registerTool(calculatorTool);
+	api.registerTool(toolSearchTool);
+
+	api.lifecycle.registerObserve(
+		"session.start",
+		() => {
+			api.session?.setActiveTools?.(["tool_search"]);
+		},
+		1,
+	);
+}

package/examples/extensions/kimi-deferred-tools/plugin.json

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

package/examples/extensions/mcp-stdio/README.md

@@ -0,0 +1,19 @@
+# MCP stdio 示例插件
+
+这是一个位于插件边界的 JSON-RPC 2.0 stdio 客户端。它启动宿主明确提供的命令（固定 `shell: false`），发送 `initialize`、`notifications/initialized` 和 `tools/list`，再把远端工具映射为 `CapabilityAPI.registerTool`。本目录附带可发现的 `plugin.json`，但 `index.ts` 是故意失败的模板入口：必须先将它替换为带有 MCP Server 命令、参数和超时配置的工厂，才可安装。示例不猜测或自动发现外部服务，也不实现安全审批、allowlist、沙箱或联网策略。
+
+`createMcpStdioPlugin` 支持 `transportFactory` 注入，因此开发测试可以完全使用确定性的内存 transport，不启动进程、不访问网络。默认 transport 逐行读取 stdout JSON，保留 stderr，并可通过 `onStderr` 观察 stderr；非零退出、JSON-RPC error、畸形响应、取消和超时都会作为 `McpStdioError` 显式暴露。
+
+```ts
+import { createMcpStdioPlugin } from "./index.ts";
+
+const plugin = createMcpStdioPlugin({
+  command: "uvx",
+  args: ["mcp-server-filesystem", process.cwd()],
+  timeoutMs: 10_000,
+});
+
+// Host loads `plugin` through loadCapabilityPlugin(...).
+```
+
+远端工具的 `inputSchema` 原样作为工具参数 schema 传递；Goal、Plan、审批及其他编排仍由独立插件决定。释放插件注册时会关闭 transport。

package/examples/extensions/mcp-stdio/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MCP-like JSON-RPC 2.0 stdio bridge.
+ *
+ * This is intentionally an external capability plugin. It discovers tools
+ * from one explicitly configured process and exposes them through the public
+ * CapabilityAPI; policy, approval, and server selection remain host-owned.
+ */
+import type { CapabilityAPI, CapabilityPluginFactory } from "@agent-forge/coding-agent";
+export type McpErrorReason = "spawn" | "exit" | "malformed" | "protocol" | "remote" | "aborted" | "timed_out";
+export interface McpErrorDetails {
+    method?: string;
+    requestId?: number;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    data?: unknown;
+}
+export declare class McpStdioError extends Error {
+    readonly reason: McpErrorReason;
+    readonly details: McpErrorDetails;
+    constructor(message: string, reason: McpErrorReason, details?: McpErrorDetails);
+}
+export interface McpRequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface McpStdioTransport {
+    request(method: string, params?: unknown, options?: McpRequestOptions): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void> | void;
+    close(): Promise<void> | void;
+    readonly stderr?: string;
+}
+export interface McpStdioTransportConfig {
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    onStderr?: (text: string) => void;
+}
+export type McpStdioTransportFactory = (config: McpStdioTransportConfig) => McpStdioTransport | Promise<McpStdioTransport>;
+export interface McpStdioPluginOptions {
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    transportFactory?: McpStdioTransportFactory;
+    onStderr?: (text: string) => void;
+    protocolVersion?: string;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+}
+/** Default line-delimited stdio transport. The command is never passed to a shell. */
+export declare function spawnMcpTransport(config: McpStdioTransportConfig): McpStdioTransport;
+/** Create an asynchronously discovering MCP stdio capability plugin. */
+export declare function createMcpStdioPlugin(options: McpStdioPluginOptions): CapabilityPluginFactory;
+/**
+ * Template entry only. A working MCP transport needs a user-selected command,
+ * arguments, and timeout; never launch an unconfigured child process.
+ */
+export default function mcpStdioExample(_api: CapabilityAPI): never;
+//# sourceMappingURL=index.d.ts.map

package/examples/extensions/mcp-stdio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EACX,aAAa,EACb,uBAAuB,EAGvB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;AAE9G,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,eAAoB,EAKjF;CACD;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,wBAAwB,GAAG,CACtC,MAAM,EAAE,uBAAuB,KAC3B,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AA+CD,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,iBAAiB,CAQpF;AAmLD,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,uBAAuB,CA0D5F;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,KAAK,CAIlE","sourcesContent":["/**\n * MCP-like JSON-RPC 2.0 stdio bridge.\n *\n * This is intentionally an external capability plugin. It discovers tools\n * from one explicitly configured process and exposes them through the public\n * CapabilityAPI; policy, approval, and server selection remain host-owned.\n */\n\nimport type { ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport { spawn } from \"node:child_process\";\nimport type { AgentToolResult } from \"@agent-forge/agent-core\";\nimport type {\n\tCapabilityAPI,\n\tCapabilityPluginFactory,\n\tExtensionContext,\n\tToolDefinition,\n} from \"@agent-forge/coding-agent\";\nimport { Type } from \"typebox\";\n\nexport type McpErrorReason = \"spawn\" | \"exit\" | \"malformed\" | \"protocol\" | \"remote\" | \"aborted\" | \"timed_out\";\n\nexport interface McpErrorDetails {\n\tmethod?: string;\n\trequestId?: number;\n\tstdout?: string;\n\tstderr?: string;\n\texitCode?: number | null;\n\tdata?: unknown;\n}\n\nexport class McpStdioError extends Error {\n\treadonly reason: McpErrorReason;\n\treadonly details: McpErrorDetails;\n\n\tconstructor(message: string, reason: McpErrorReason, details: McpErrorDetails = {}) {\n\t\tsuper(message);\n\t\tthis.name = \"McpStdioError\";\n\t\tthis.reason = reason;\n\t\tthis.details = details;\n\t}\n}\n\nexport interface McpRequestOptions {\n\tsignal?: AbortSignal;\n\ttimeoutMs?: number;\n}\n\nexport interface McpStdioTransport {\n\trequest(method: string, params?: unknown, options?: McpRequestOptions): Promise<unknown>;\n\tnotify(method: string, params?: unknown): Promise<void> | void;\n\tclose(): Promise<void> | void;\n\treadonly stderr?: string;\n}\n\nexport interface McpStdioTransportConfig {\n\tcommand: string;\n\targs: readonly string[];\n\tcwd?: string;\n\tenv?: NodeJS.ProcessEnv;\n\tonStderr?: (text: string) => void;\n}\n\nexport type McpStdioTransportFactory = (\n\tconfig: McpStdioTransportConfig,\n) => McpStdioTransport | Promise<McpStdioTransport>;\n\nexport interface McpStdioPluginOptions {\n\tcommand: string;\n\targs?: readonly string[];\n\tcwd?: string;\n\tenv?: NodeJS.ProcessEnv;\n\ttimeoutMs?: number;\n\ttransportFactory?: McpStdioTransportFactory;\n\tonStderr?: (text: string) => void;\n\tprotocolVersion?: string;\n\tclientInfo?: { name: string; version: string };\n}\n\ninterface JsonRpcResponse {\n\tjsonrpc?: unknown;\n\tid?: unknown;\n\tmethod?: unknown;\n\tresult?: unknown;\n\terror?: { code?: unknown; message?: unknown; data?: unknown };\n}\n\nconst noResult = (): AgentToolResult<unknown> => ({ content: [{ type: \"text\", text: \"\" }], details: undefined });\n\nfunction asRecord(value: unknown, label: string): Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new McpStdioError(`${label} must be an object`, \"malformed\", { data: value });\n\t}\n\treturn value as Record<string, unknown>;\n}\n\nfunction validateToolList(value: unknown): readonly Record<string, unknown>[] {\n\tconst object = asRecord(value, \"MCP tools/list result\");\n\tif (!Array.isArray(object.tools)) {\n\t\tthrow new McpStdioError(\"MCP tools/list result must contain tools[]\", \"malformed\", { data: value });\n\t}\n\treturn object.tools.map((tool, index) => {\n\t\tconst record = asRecord(tool, `MCP tool at index ${index}`);\n\t\tif (typeof record.name !== \"string\" || !record.name.trim()) {\n\t\t\tthrow new McpStdioError(`MCP tool at index ${index} requires a non-empty name`, \"malformed\", { data: tool });\n\t\t}\n\t\tif (record.inputSchema !== undefined && (typeof record.inputSchema !== \"object\" || record.inputSchema === null)) {\n\t\t\tthrow new McpStdioError(`MCP tool has an invalid inputSchema: ${record.name}`, \"malformed\", { data: tool });\n\t\t}\n\t\treturn record;\n\t});\n}\n\nfunction normalizeToolResult(value: unknown): AgentToolResult<unknown> {\n\tif (value && typeof value === \"object\" && Array.isArray((value as { content?: unknown }).content)) {\n\t\treturn value as AgentToolResult<unknown>;\n\t}\n\tif (value === undefined) return noResult();\n\treturn {\n\t\tcontent: [{ type: \"text\", text: typeof value === \"string\" ? value : JSON.stringify(value) }],\n\t\tdetails: undefined,\n\t};\n}\n\n/** Default line-delimited stdio transport. The command is never passed to a shell. */\nexport function spawnMcpTransport(config: McpStdioTransportConfig): McpStdioTransport {\n\tconst child = spawn(config.command, [...config.args], {\n\t\tcwd: config.cwd,\n\t\tenv: config.env,\n\t\tshell: false,\n\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t});\n\treturn createJsonRpcTransport(child, config.onStderr);\n}\n\nfunction createJsonRpcTransport(\n\tchild: ChildProcessWithoutNullStreams,\n\tonStderr?: (text: string) => void,\n): McpStdioTransport {\n\tlet nextId = 1;\n\tlet closed = false;\n\tlet stdout = \"\";\n\tlet stderr = \"\";\n\tlet closeRequested = false;\n\tconst pending = new Map<\n\t\tnumber,\n\t\t{ method: string; resolve: (value: unknown) => void; reject: (error: unknown) => void }\n\t>();\n\tconst ignored = new Set<number>();\n\tlet fatalError: McpStdioError | undefined;\n\n\tconst failAll = (error: McpStdioError): void => {\n\t\tif (fatalError) return;\n\t\tfatalError = error;\n\t\tclosed = true;\n\t\tfor (const request of pending.values()) request.reject(error);\n\t\tpending.clear();\n\t};\n\n\tchild.stdout.setEncoding(\"utf8\");\n\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\tstdout += chunk;\n\t\tconst lines = stdout.split(/\\r?\\n/);\n\t\tstdout = lines.pop() ?? \"\";\n\t\tfor (const line of lines) {\n\t\t\tif (!line.trim()) continue;\n\t\t\tlet parsed: JsonRpcResponse;\n\t\t\ttry {\n\t\t\t\tparsed = JSON.parse(line) as JsonRpcResponse;\n\t\t\t} catch {\n\t\t\t\tfailAll(new McpStdioError(\"Malformed JSON-RPC response\", \"malformed\", { stdout: line, stderr }));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (parsed.jsonrpc !== \"2.0\") {\n\t\t\t\tfailAll(new McpStdioError(\"Invalid JSON-RPC response envelope\", \"protocol\", { data: parsed, stderr }));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (parsed.id === undefined) {\n\t\t\t\tif (typeof parsed.method === \"string\") continue;\n\t\t\t\tfailAll(new McpStdioError(\"JSON-RPC response is missing an id\", \"protocol\", { data: parsed, stderr }));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (typeof parsed.id !== \"number\" && parsed.id !== null) {\n\t\t\t\tfailAll(new McpStdioError(\"Invalid JSON-RPC response id\", \"protocol\", { data: parsed, stderr }));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (parsed.id === null) continue;\n\t\t\tconst responseId = parsed.id as number;\n\t\t\tif (ignored.delete(responseId)) continue;\n\t\t\tconst request = pending.get(responseId);\n\t\t\tif (!request) {\n\t\t\t\tfailAll(\n\t\t\t\t\tnew McpStdioError(`Unknown JSON-RPC response id: ${responseId}`, \"protocol\", { data: parsed, stderr }),\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tpending.delete(responseId);\n\t\t\tif (parsed.error) {\n\t\t\t\tconst message = typeof parsed.error.message === \"string\" ? parsed.error.message : \"MCP request failed\";\n\t\t\t\trequest.reject(\n\t\t\t\t\tnew McpStdioError(message, \"remote\", {\n\t\t\t\t\t\tmethod: request.method,\n\t\t\t\t\t\trequestId: responseId,\n\t\t\t\t\t\tdata: parsed.error,\n\t\t\t\t\t\tstderr,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} else if (!(\"result\" in parsed)) {\n\t\t\t\trequest.reject(\n\t\t\t\t\tnew McpStdioError(\"JSON-RPC response has neither result nor error\", \"protocol\", {\n\t\t\t\t\t\tmethod: request.method,\n\t\t\t\t\t\trequestId: responseId,\n\t\t\t\t\t\tdata: parsed,\n\t\t\t\t\t\tstderr,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\trequest.resolve(parsed.result);\n\t\t\t}\n\t\t}\n\t});\n\tchild.stderr.setEncoding(\"utf8\");\n\tchild.stderr.on(\"data\", (chunk: string) => {\n\t\tstderr += chunk;\n\t\tonStderr?.(chunk);\n\t});\n\tchild.once(\"error\", (error) => {\n\t\tfailAll(new McpStdioError(`Failed to spawn MCP process: ${error.message}`, \"spawn\", { stdout, stderr }));\n\t});\n\tchild.once(\"close\", (exitCode) => {\n\t\tif (closed) return;\n\t\tfailAll(\n\t\t\tnew McpStdioError(`MCP process exited with code ${exitCode ?? \"unknown\"}`, \"exit\", {\n\t\t\t\tstdout,\n\t\t\t\tstderr,\n\t\t\t\texitCode,\n\t\t\t}),\n\t\t);\n\t});\n\n\tconst request = (method: string, params?: unknown, options: McpRequestOptions = {}): Promise<unknown> => {\n\t\tif (fatalError || closed)\n\t\t\treturn Promise.reject(fatalError ?? new McpStdioError(\"MCP transport is closed\", \"exit\", { stderr }));\n\t\tif (options.signal?.aborted)\n\t\t\treturn Promise.reject(new McpStdioError(\"MCP request aborted\", \"aborted\", { method, stderr }));\n\t\tconst id = nextId++;\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tlet timeout: NodeJS.Timeout | undefined;\n\t\t\tconst abort = (): void => {\n\t\t\t\tif (!pending.delete(id)) return;\n\t\t\t\tignored.add(id);\n\t\t\t\tif (timeout) clearTimeout(timeout);\n\t\t\t\treject(new McpStdioError(\"MCP request aborted\", \"aborted\", { method, requestId: id, stderr }));\n\t\t\t};\n\t\t\tpending.set(id, {\n\t\t\t\tmethod,\n\t\t\t\tresolve: (result) => {\n\t\t\t\t\tif (timeout) clearTimeout(timeout);\n\t\t\t\t\toptions.signal?.removeEventListener(\"abort\", abort);\n\t\t\t\t\tresolve(result);\n\t\t\t\t},\n\t\t\t\treject: (error) => {\n\t\t\t\t\tif (timeout) clearTimeout(timeout);\n\t\t\t\t\toptions.signal?.removeEventListener(\"abort\", abort);\n\t\t\t\t\treject(error);\n\t\t\t\t},\n\t\t\t});\n\t\t\toptions.signal?.addEventListener(\"abort\", abort, { once: true });\n\t\t\tif (options.timeoutMs !== undefined) {\n\t\t\t\ttimeout = setTimeout(() => {\n\t\t\t\t\tif (!pending.delete(id)) return;\n\t\t\t\t\tignored.add(id);\n\t\t\t\t\toptions.signal?.removeEventListener(\"abort\", abort);\n\t\t\t\t\treject(new McpStdioError(\"MCP request timed out\", \"timed_out\", { method, requestId: id, stderr }));\n\t\t\t\t}, options.timeoutMs);\n\t\t\t}\n\t\t\tchild.stdin.write(\n\t\t\t\t`${JSON.stringify({ jsonrpc: \"2.0\", id, method, ...(params === undefined ? {} : { params }) })}\\n`,\n\t\t\t);\n\t\t});\n\t};\n\treturn {\n\t\trequest,\n\t\tnotify(method, params) {\n\t\t\tif (fatalError || closed) throw fatalError ?? new McpStdioError(\"MCP transport is closed\", \"exit\", { stderr });\n\t\t\tchild.stdin.write(\n\t\t\t\t`${JSON.stringify({ jsonrpc: \"2.0\", method, ...(params === undefined ? {} : { params }) })}\\n`,\n\t\t\t);\n\t\t},\n\t\tclose() {\n\t\t\tif (closeRequested) return;\n\t\t\tcloseRequested = true;\n\t\t\tclosed = true;\n\t\t\tfor (const request of pending.values())\n\t\t\t\trequest.reject(new McpStdioError(\"MCP transport closed\", \"exit\", { stdout, stderr }));\n\t\t\tpending.clear();\n\t\t\tchild.stdin.end();\n\t\t\tif (!child.killed) child.kill();\n\t\t},\n\t\tget stderr() {\n\t\t\treturn stderr;\n\t\t},\n\t};\n}\n\nfunction validateOptions(options: McpStdioPluginOptions): void {\n\tif (!options.command.trim()) throw new Error(\"MCP stdio command requires a non-empty command\");\n\tif (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {\n\t\tthrow new Error(\"MCP stdio timeoutMs must be a positive number\");\n\t}\n}\n\n/** Create an asynchronously discovering MCP stdio capability plugin. */\nexport function createMcpStdioPlugin(options: McpStdioPluginOptions): CapabilityPluginFactory {\n\tvalidateOptions(options);\n\tconst factory = options.transportFactory ?? spawnMcpTransport;\n\treturn async (api: CapabilityAPI) => {\n\t\tconst transport = await factory({\n\t\t\tcommand: options.command,\n\t\t\targs: options.args ?? [],\n\t\t\tcwd: options.cwd,\n\t\t\tenv: options.env,\n\t\t\tonStderr: options.onStderr,\n\t\t});\n\t\ttry {\n\t\t\tasRecord(\n\t\t\t\tawait transport.request(\n\t\t\t\t\t\"initialize\",\n\t\t\t\t\t{\n\t\t\t\t\t\tprotocolVersion: options.protocolVersion ?? \"2024-11-05\",\n\t\t\t\t\t\tcapabilities: {},\n\t\t\t\t\t\tclientInfo: options.clientInfo ?? { name: \"agent-forge-mcp-stdio\", version: \"0.1.0\" },\n\t\t\t\t\t},\n\t\t\t\t\t{ timeoutMs: options.timeoutMs },\n\t\t\t\t),\n\t\t\t\t\"MCP initialize result\",\n\t\t\t);\n\t\t\tawait transport.notify(\"notifications/initialized\");\n\t\t\tconst discovered = validateToolList(\n\t\t\t\tawait transport.request(\"tools/list\", undefined, { timeoutMs: options.timeoutMs }),\n\t\t\t);\n\t\t\tfor (const remote of discovered) {\n\t\t\t\tconst name = remote.name as string;\n\t\t\t\tconst schema = (remote.inputSchema ?? Type.Object({})) as ToolDefinition[\"parameters\"];\n\t\t\t\tconst definition: ToolDefinition = {\n\t\t\t\t\tname,\n\t\t\t\t\tlabel: name,\n\t\t\t\t\tdescription: typeof remote.description === \"string\" ? remote.description : `MCP tool: ${name}`,\n\t\t\t\t\tparameters: schema,\n\t\t\t\t\tasync execute(toolCallId, params, signal, _onUpdate, _ctx: ExtensionContext) {\n\t\t\t\t\t\tconst input = params === undefined && typeof toolCallId !== \"string\" ? toolCallId : params;\n\t\t\t\t\t\tconst result = await transport.request(\n\t\t\t\t\t\t\t\"tools/call\",\n\t\t\t\t\t\t\t{ name, arguments: input ?? {} },\n\t\t\t\t\t\t\t{ signal, timeoutMs: options.timeoutMs },\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn normalizeToolResult(result);\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t\tapi.registerTool(definition);\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tdispose: async () => {\n\t\t\t\t\tawait transport.close();\n\t\t\t\t},\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tawait transport.close();\n\t\t\tthrow error;\n\t\t}\n\t};\n}\n\n/**\n * Template entry only. A working MCP transport needs a user-selected command,\n * arguments, and timeout; never launch an unconfigured child process.\n */\nexport default function mcpStdioExample(_api: CapabilityAPI): never {\n\tthrow new Error(\n\t\t\"Configure createMcpStdioPlugin({ command, args, timeoutMs }) before installing this MCP stdio example.\",\n\t);\n}\n"]}