@ai-agent-forge/agent-forge 0.85.0

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

@@ -0,0 +1,381 @@
+/**
+ * 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 { ChildProcessWithoutNullStreams } from "node:child_process";
+import { spawn } from "node:child_process";
+import type { AgentToolResult } from "@agent-forge/agent-core";
+import type {
+	CapabilityAPI,
+	CapabilityPluginFactory,
+	ToolDefinition,
+	ToolExecuteContext,
+} from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+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 class McpStdioError extends Error {
+	readonly reason: McpErrorReason;
+	readonly details: McpErrorDetails;
+
+	constructor(message: string, reason: McpErrorReason, details: McpErrorDetails = {}) {
+		super(message);
+		this.name = "McpStdioError";
+		this.reason = reason;
+		this.details = details;
+	}
+}
+
+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 };
+}
+
+interface JsonRpcResponse {
+	jsonrpc?: unknown;
+	id?: unknown;
+	method?: unknown;
+	result?: unknown;
+	error?: { code?: unknown; message?: unknown; data?: unknown };
+}
+
+const noResult = (): AgentToolResult<unknown> => ({ content: [{ type: "text", text: "" }], details: undefined });
+
+function asRecord(value: unknown, label: string): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new McpStdioError(`${label} must be an object`, "malformed", { data: value });
+	}
+	return value as Record<string, unknown>;
+}
+
+function validateToolList(value: unknown): readonly Record<string, unknown>[] {
+	const object = asRecord(value, "MCP tools/list result");
+	if (!Array.isArray(object.tools)) {
+		throw new McpStdioError("MCP tools/list result must contain tools[]", "malformed", { data: value });
+	}
+	return object.tools.map((tool, index) => {
+		const record = asRecord(tool, `MCP tool at index ${index}`);
+		if (typeof record.name !== "string" || !record.name.trim()) {
+			throw new McpStdioError(`MCP tool at index ${index} requires a non-empty name`, "malformed", { data: tool });
+		}
+		if (record.inputSchema !== undefined && (typeof record.inputSchema !== "object" || record.inputSchema === null)) {
+			throw new McpStdioError(`MCP tool has an invalid inputSchema: ${record.name}`, "malformed", { data: tool });
+		}
+		return record;
+	});
+}
+
+function normalizeToolResult(value: unknown): AgentToolResult<unknown> {
+	if (value && typeof value === "object" && Array.isArray((value as { content?: unknown }).content)) {
+		return value as AgentToolResult<unknown>;
+	}
+	if (value === undefined) return noResult();
+	return {
+		content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }],
+		details: undefined,
+	};
+}
+
+/** Default line-delimited stdio transport. The command is never passed to a shell. */
+export function spawnMcpTransport(config: McpStdioTransportConfig): McpStdioTransport {
+	const child = spawn(config.command, [...config.args], {
+		cwd: config.cwd,
+		env: config.env,
+		shell: false,
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+	return createJsonRpcTransport(child, config.onStderr);
+}
+
+function createJsonRpcTransport(
+	child: ChildProcessWithoutNullStreams,
+	onStderr?: (text: string) => void,
+): McpStdioTransport {
+	let nextId = 1;
+	let closed = false;
+	let stdout = "";
+	let stderr = "";
+	let closeRequested = false;
+	const pending = new Map<
+		number,
+		{ method: string; resolve: (value: unknown) => void; reject: (error: unknown) => void }
+	>();
+	const ignored = new Set<number>();
+	let fatalError: McpStdioError | undefined;
+
+	const failAll = (error: McpStdioError): void => {
+		if (fatalError) return;
+		fatalError = error;
+		closed = true;
+		for (const request of pending.values()) request.reject(error);
+		pending.clear();
+	};
+
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", (chunk: string) => {
+		stdout += chunk;
+		const lines = stdout.split(/\r?\n/);
+		stdout = lines.pop() ?? "";
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			let parsed: JsonRpcResponse;
+			try {
+				parsed = JSON.parse(line) as JsonRpcResponse;
+			} catch {
+				failAll(new McpStdioError("Malformed JSON-RPC response", "malformed", { stdout: line, stderr }));
+				return;
+			}
+			if (parsed.jsonrpc !== "2.0") {
+				failAll(new McpStdioError("Invalid JSON-RPC response envelope", "protocol", { data: parsed, stderr }));
+				return;
+			}
+			if (parsed.id === undefined) {
+				if (typeof parsed.method === "string") continue;
+				failAll(new McpStdioError("JSON-RPC response is missing an id", "protocol", { data: parsed, stderr }));
+				return;
+			}
+			if (typeof parsed.id !== "number" && parsed.id !== null) {
+				failAll(new McpStdioError("Invalid JSON-RPC response id", "protocol", { data: parsed, stderr }));
+				return;
+			}
+			if (parsed.id === null) continue;
+			const responseId = parsed.id as number;
+			if (ignored.delete(responseId)) continue;
+			const request = pending.get(responseId);
+			if (!request) {
+				failAll(
+					new McpStdioError(`Unknown JSON-RPC response id: ${responseId}`, "protocol", { data: parsed, stderr }),
+				);
+				return;
+			}
+			pending.delete(responseId);
+			if (parsed.error) {
+				const message = typeof parsed.error.message === "string" ? parsed.error.message : "MCP request failed";
+				request.reject(
+					new McpStdioError(message, "remote", {
+						method: request.method,
+						requestId: responseId,
+						data: parsed.error,
+						stderr,
+					}),
+				);
+			} else if (!("result" in parsed)) {
+				request.reject(
+					new McpStdioError("JSON-RPC response has neither result nor error", "protocol", {
+						method: request.method,
+						requestId: responseId,
+						data: parsed,
+						stderr,
+					}),
+				);
+			} else {
+				request.resolve(parsed.result);
+			}
+		}
+	});
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk: string) => {
+		stderr += chunk;
+		onStderr?.(chunk);
+	});
+	child.once("error", (error) => {
+		failAll(new McpStdioError(`Failed to spawn MCP process: ${error.message}`, "spawn", { stdout, stderr }));
+	});
+	child.once("close", (exitCode) => {
+		if (closed) return;
+		failAll(
+			new McpStdioError(`MCP process exited with code ${exitCode ?? "unknown"}`, "exit", {
+				stdout,
+				stderr,
+				exitCode,
+			}),
+		);
+	});
+
+	const request = (method: string, params?: unknown, options: McpRequestOptions = {}): Promise<unknown> => {
+		if (fatalError || closed)
+			return Promise.reject(fatalError ?? new McpStdioError("MCP transport is closed", "exit", { stderr }));
+		if (options.signal?.aborted)
+			return Promise.reject(new McpStdioError("MCP request aborted", "aborted", { method, stderr }));
+		const id = nextId++;
+		return new Promise((resolve, reject) => {
+			let timeout: NodeJS.Timeout | undefined;
+			const abort = (): void => {
+				if (!pending.delete(id)) return;
+				ignored.add(id);
+				if (timeout) clearTimeout(timeout);
+				reject(new McpStdioError("MCP request aborted", "aborted", { method, requestId: id, stderr }));
+			};
+			pending.set(id, {
+				method,
+				resolve: (result) => {
+					if (timeout) clearTimeout(timeout);
+					options.signal?.removeEventListener("abort", abort);
+					resolve(result);
+				},
+				reject: (error) => {
+					if (timeout) clearTimeout(timeout);
+					options.signal?.removeEventListener("abort", abort);
+					reject(error);
+				},
+			});
+			options.signal?.addEventListener("abort", abort, { once: true });
+			if (options.timeoutMs !== undefined) {
+				timeout = setTimeout(() => {
+					if (!pending.delete(id)) return;
+					ignored.add(id);
+					options.signal?.removeEventListener("abort", abort);
+					reject(new McpStdioError("MCP request timed out", "timed_out", { method, requestId: id, stderr }));
+				}, options.timeoutMs);
+			}
+			child.stdin.write(
+				`${JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) })}\n`,
+			);
+		});
+	};
+	return {
+		request,
+		notify(method, params) {
+			if (fatalError || closed) throw fatalError ?? new McpStdioError("MCP transport is closed", "exit", { stderr });
+			child.stdin.write(
+				`${JSON.stringify({ jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) })}\n`,
+			);
+		},
+		close() {
+			if (closeRequested) return;
+			closeRequested = true;
+			closed = true;
+			for (const request of pending.values())
+				request.reject(new McpStdioError("MCP transport closed", "exit", { stdout, stderr }));
+			pending.clear();
+			child.stdin.end();
+			if (!child.killed) child.kill();
+		},
+		get stderr() {
+			return stderr;
+		},
+	};
+}
+
+function validateOptions(options: McpStdioPluginOptions): void {
+	if (!options.command.trim()) throw new Error("MCP stdio command requires a non-empty command");
+	if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+		throw new Error("MCP stdio timeoutMs must be a positive number");
+	}
+}
+
+/** Create an asynchronously discovering MCP stdio capability plugin. */
+export function createMcpStdioPlugin(options: McpStdioPluginOptions): CapabilityPluginFactory {
+	validateOptions(options);
+	const factory = options.transportFactory ?? spawnMcpTransport;
+	return async (api: CapabilityAPI) => {
+		const transport = await factory({
+			command: options.command,
+			args: options.args ?? [],
+			cwd: options.cwd,
+			env: options.env,
+			onStderr: options.onStderr,
+		});
+		try {
+			asRecord(
+				await transport.request(
+					"initialize",
+					{
+						protocolVersion: options.protocolVersion ?? "2024-11-05",
+						capabilities: {},
+						clientInfo: options.clientInfo ?? { name: "agent-forge-mcp-stdio", version: "0.1.0" },
+					},
+					{ timeoutMs: options.timeoutMs },
+				),
+				"MCP initialize result",
+			);
+			await transport.notify("notifications/initialized");
+			const discovered = validateToolList(
+				await transport.request("tools/list", undefined, { timeoutMs: options.timeoutMs }),
+			);
+			for (const remote of discovered) {
+				const name = remote.name as string;
+				const schema = (remote.inputSchema ?? Type.Object({})) as ToolDefinition["parameters"];
+				const definition: ToolDefinition = {
+					name,
+					label: name,
+					description: typeof remote.description === "string" ? remote.description : `MCP tool: ${name}`,
+					parameters: schema,
+					async execute(toolCallId, params, signal, _onUpdate, _ctx: ToolExecuteContext) {
+						const input = params === undefined && typeof toolCallId !== "string" ? toolCallId : params;
+						const result = await transport.request(
+							"tools/call",
+							{ name, arguments: input ?? {} },
+							{ signal, timeoutMs: options.timeoutMs },
+						);
+						return normalizeToolResult(result);
+					},
+				};
+				api.registerTool(definition);
+			}
+			return {
+				dispose: async () => {
+					await transport.close();
+				},
+			};
+		} catch (error) {
+			await transport.close();
+			throw error;
+		}
+	};
+}
+
+/**
+ * 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 {
+	throw new Error(
+		"Configure createMcpStdioPlugin({ command, args, timeoutMs }) before installing this MCP stdio example.",
+	);
+}

package/examples/extensions/mcp-stdio/plugin.json

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

package/examples/extensions/memory-backend/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Memory Backend Example — a third-party memory backend as a same-name takeover
+ *
+ * Demonstrates the plugin path for replacing the memory backend (扩展位盘点
+ * A1/A2, plugin recipe): register tools under the CONTRACT tool names and the
+ * whole memory chain follows — the SDK's B1 auto-recall invokes
+ * `MEMORY_RECALL_TOOL_NAME`, and `registerTool` is replaceable (last load
+ * wins, restore on dispose), so loading this plugin takes the `memory_*` face
+ * over from the builtin capability (suite exclusion of `builtin.memory` is
+ * optional; same-name registration wins either way).
+ *
+ * This backend is a deterministic in-memory Map — swap the Map for your own
+ * store (SQLite, a remote service, a vault) and the session-facing contract
+ * stays identical: the builtin memory plugin's atom contract is NOT reused
+ * here; a takeover plugin owns its storage semantics end to end.
+ *
+ * For host-side component-level injection (keeping the builtin memory plugin
+ * as the orchestrator), use `CreateAgentSessionOptions.memoryCapability.storage`
+ * instead — see `docs/design/扩展位与插件边界盘点.md` A1/A2.
+ *
+ * Usage: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import { type CapabilityAPI, MEMORY_RECALL_TOOL_NAME } from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+interface StoredMemory {
+	readonly memoryId: string;
+	readonly content: string;
+	readonly kind: "fact" | "preference";
+	readonly tags: readonly string[];
+}
+
+export default function memoryBackendExample(api: CapabilityAPI): void {
+	const memories = new Map<string, StoredMemory>();
+	let counter = 0;
+
+	api.registerTool({
+		name: "memory_write",
+		label: "Remember (example backend)",
+		description: "Store one memory in the example in-memory backend.",
+		parameters: Type.Object({
+			content: Type.String({ description: "The memory content" }),
+			kind: Type.Union([Type.Literal("fact"), Type.Literal("preference")]),
+			tags: Type.Optional(Type.Array(Type.String())),
+		}),
+		execute: async (input: unknown) => {
+			const args = (input ?? {}) as { content?: unknown; kind?: unknown; tags?: unknown };
+			const content = typeof args.content === "string" ? args.content : "";
+			if (content.trim() === "") {
+				throw new Error("memory_write requires non-empty content");
+			}
+			counter += 1;
+			const memoryId = `example-mem-${counter}`;
+			memories.set(memoryId, {
+				memoryId,
+				content,
+				kind: args.kind === "preference" ? "preference" : "fact",
+				tags: Array.isArray(args.tags) ? args.tags.map((tag) => String(tag)) : [],
+			});
+			return { memoryId, kind: memories.get(memoryId)?.kind, backend: "example-in-memory" };
+		},
+	});
+
+	api.registerTool({
+		name: MEMORY_RECALL_TOOL_NAME,
+		label: "Recall memories (example backend)",
+		description:
+			"Search the example in-memory backend. The SDK's auto-recall invokes this contract tool name, so this takeover feeds it.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Query text; tokens match content or tags case-insensitively" }),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+		}),
+		execute: async (input: unknown) => {
+			const args = (input ?? {}) as { query?: unknown; limit?: unknown };
+			const query = typeof args.query === "string" ? args.query.toLowerCase() : "";
+			const limit = typeof args.limit === "number" ? args.limit : 5;
+			const tokens = query.split(/\s+/).filter((token) => token !== "");
+			const facts = [...memories.values()]
+				.filter((memory) => {
+					const haystack = `${memory.content} ${memory.tags.join(" ")}`.toLowerCase();
+					return tokens.some((token) => haystack.includes(token));
+				})
+				.slice(-limit)
+				.map((memory) => ({ memoryId: memory.memoryId, content: memory.content, kind: memory.kind }));
+			return { status: "completed", facts };
+		},
+	});
+
+	api.registerTool({
+		name: "memory_list",
+		label: "List memories (example backend)",
+		description: "List memories stored in the example backend.",
+		parameters: Type.Object({
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
+		}),
+		execute: async (input: unknown) => {
+			const args = (input ?? {}) as { limit?: unknown };
+			const limit = typeof args.limit === "number" ? args.limit : 20;
+			const memories_listed = [...memories.values()].slice(-limit);
+			return { status: "completed", memories: memories_listed };
+		},
+	});
+
+	api.registerTool({
+		name: "memory_forget",
+		label: "Forget memory (example backend)",
+		description: "Delete one memory from the example backend by id.",
+		parameters: Type.Object({
+			memoryId: Type.String({ description: "The memory id to delete" }),
+		}),
+		execute: async (input: unknown) => {
+			const args = (input ?? {}) as { memoryId?: unknown };
+			const memoryId = typeof args.memoryId === "string" ? args.memoryId : "";
+			const deleted = memories.delete(memoryId);
+			return { forgotten: deleted, memoryId };
+		},
+	});
+}

package/examples/extensions/memory-backend/plugin.json

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