@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/subagent/plugin.json

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

package/examples/extensions/subagent/prompts/implement-and-review.md

@@ -0,0 +1,10 @@
+---
+description: Worker implements, reviewer reviews, worker applies feedback
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "worker" agent to implement: $@
+2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/examples/extensions/subagent/prompts/implement.md

@@ -0,0 +1,10 @@
+---
+description: Full implementation workflow - scout gathers context, planner creates plan, worker implements
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to implement the plan from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/examples/extensions/subagent/prompts/scout-and-plan.md

@@ -0,0 +1,9 @@
+---
+description: Scout gathers context, planner creates implementation plan (no implementation)
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.

package/examples/extensions/suite-manager/README.md

@@ -0,0 +1,45 @@
+# Suite Manager Extension (方案管理插件)
+
+Brings the suite (方案) lifecycle from `方案系统设计.md` §9 into the interactive session,
+on top of the public lifecycle API (`createSuite`/`deleteSuite`/`resetSuite`/
+`findSuiteSessionRefs`/`clearDanglingSuiteSettings`/`listSuiteIds`) that the
+`--suite-create`/`--suite-delete`/`--suite-reset` CLI one-shots also use. It is a
+capability plugin (`plugin.json` + `CapabilityAPI` factory); commands return
+`CapabilityCommandResult` and destructive ones ask for confirmation through
+`InteractionAPI.request`.
+
+## Install
+
+Capability plugins are discovered below `<agentDir>/plugins` and
+`<cwd>/.agent-forge/plugins` (a plugin is a directory holding `plugin.json`).
+Suite association (设计 §4) filters the user-scope pool: plugins below
+`<cwd>/.agent-forge/plugins` stay available in every suite, while the ones below
+`<agentDir>/plugins` must be declared in the suite's `associations.plugins` (by
+manifest id). Because suite management is a meta-capability, install it at the
+project scope:
+
+```
+<cwd>/.agent-forge/plugins/suite-manager/
+```
+
+(or add `"agent-forge.example.suite-manager"` to a suite's
+`associations.plugins` when installing to `<agentDir>/plugins/`), then run
+`/reload` (or restart).
+
+## Commands
+
+Switching suites stays on the builtin `/suite` command; this plugin covers the
+management surface:
+
+- `/suite-list` — list suite ids; builtin ones are marked.
+- `/suite-create <id> [from <sourceId>]` — create a user suite with a fresh
+  skeleton, or clone an existing suite workspace (identity rewritten, profile
+  lock never copied).
+- `/suite-delete <id>` — delete a user suite: refuses while sessions reference
+  it, asks for confirmation, moves the workspace to the trash, and clears
+  dangling project/global `suite` settings keys.
+- `/suite-reset <id>` — builtin suites only: shows the factory diff, asks for
+  confirmation, then applies the reset (profile lock generation increments).
+
+Destructive commands require a dialog-capable UI and are refused otherwise,
+mirroring the CLI's non-interactive refusal (设计 §9 安全默认).

package/examples/extensions/suite-manager/index.ts

@@ -0,0 +1,182 @@
+/**
+ * Suite Manager Extension (方案管理插件, 方案系统设计.md §9) — capability plugin form
+ *
+ * Brings the suite lifecycle into the interactive session: list, create
+ * (fresh or cloned), delete (trash + settings cleanup), and reset (builtin
+ * factory restore). It calls the same public lifecycle API the CLI one-shots
+ * use (`createSuite`/`deleteSuite`/`resetSuite`/... exported from the package
+ * root) — no hidden channels. Destructive operations require a UI confirm
+ * dialog through `api.interaction.request({ kind: "confirm" })` and are refused
+ * when the host declares no `interaction` capability (no dialog-capable UI),
+ * mirroring the CLI's non-interactive refusal (设计 §9 安全默认).
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ *
+ * Commands (switching stays on the builtin `/suite`):
+ *   /suite-list               List suite ids, marking builtin ones
+ *   /suite-create <id> [from <sourceId>]
+ *                             Create a user suite (fresh skeleton or clone)
+ *   /suite-delete <id>        Delete a user suite after confirmation
+ *   /suite-reset <id>         Restore a builtin suite to factory contents
+ */
+
+import type { CapabilityAPI, CapabilityCommandContext, CapabilityCommandResult } from "@agent-forge/agent-forge";
+import {
+	clearDanglingSuiteSettings,
+	createSuite,
+	deleteSuite,
+	findSuiteSessionRefs,
+	getAgentDir,
+	isBuiltinSuiteId,
+	listSuiteIds,
+	resetSuite,
+	SettingsManager,
+	SUITE_DELETE_CONFIRM_TOKEN,
+	type SuiteSessionRef,
+} from "@agent-forge/agent-forge";
+
+function text(value: unknown): string {
+	return typeof value === "string" ? value.trim() : "";
+}
+
+function errorResult(message: string): CapabilityCommandResult {
+	return { status: "error", message };
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Clear the dangling settings "suite" key after a delete. The project scope is
+ * located through the command context's cwd; a host that reports none leaves
+ * that scope unchecked, and the result says so instead of skipping silently.
+ */
+function cleanupNote(context: CapabilityCommandContext, id: string): string {
+	const cwd = context.cwd;
+	if (cwd === undefined) {
+		return " Project settings were not checked: the host reported no working directory.";
+	}
+	const cleanup = clearDanglingSuiteSettings(SettingsManager.create(cwd, getAgentDir()), id);
+	return cleanup.clearedScopes.length > 0
+		? ` Cleared the ${cleanup.clearedScopes.join(" and ")} settings "suite" key.`
+		: "";
+}
+
+export default function suiteManagerPlugin(api: CapabilityAPI): void {
+	api.registerCommand({
+		name: "suite-list",
+		description: "List suites (方案); builtin ones are marked",
+		execute: async () => {
+			const ids = listSuiteIds(getAgentDir());
+			const lines = ids.map((id) => (isBuiltinSuiteId(id) ? `${id}  (builtin)` : id));
+			return { status: "success", message: lines.length > 0 ? lines.join("\n") : "No suites found" };
+		},
+	});
+
+	api.registerCommand({
+		name: "suite-create",
+		description: "Create a user suite: /suite-create <id> [from <sourceId>]",
+		execute: async (args) => {
+			const parts = text(args).split(/\s+/).filter(Boolean);
+			const id = parts[0];
+			if (!id) return errorResult("Usage: /suite-create <id> [from <sourceId>]");
+			const fromIndex = parts.indexOf("from");
+			const cloneFrom = fromIndex >= 0 ? parts[fromIndex + 1] : undefined;
+			if (fromIndex >= 0 && !cloneFrom) {
+				return errorResult("Usage: /suite-create <id> [from <sourceId>]");
+			}
+			try {
+				const result = createSuite({
+					agentDir: getAgentDir(),
+					id,
+					...(cloneFrom === undefined ? {} : { cloneFrom }),
+				});
+				return {
+					status: "success",
+					message: `Created suite "${result.suiteId}" at ${result.suiteDir}. Use /suite ${result.suiteId} to apply it to new sessions.`,
+				};
+			} catch (error: unknown) {
+				return errorResult(messageOf(error));
+			}
+		},
+	});
+
+	api.registerCommand({
+		name: "suite-delete",
+		description: "Delete a user suite (confirmation required)",
+		execute: async (args, context) => {
+			const id = text(args).split(/\s+/)[0];
+			if (!id) return errorResult("Usage: /suite-delete <id>");
+			const interaction = api.interaction;
+			if (!interaction) {
+				return errorResult(`Refusing to delete suite "${id}" without a dialog-capable UI.`);
+			}
+			try {
+				const refs: SuiteSessionRef[] = findSuiteSessionRefs(getAgentDir(), id);
+				if (refs.length > 0) {
+					return errorResult(
+						`Suite "${id}" is referenced by ${refs.length} existing session(s); deletion refused:\n` +
+							refs.map((ref) => `${ref.sessionId}  ${ref.path}`).join("\n"),
+					);
+				}
+				const suiteDir = `${getAgentDir().replace(/\\/g, "/")}/suites/${id}`;
+				const outcome = await interaction.request({
+					kind: "confirm",
+					title: "Delete suite",
+					message: `The workspace ${suiteDir} will be moved to the trash and released. Delete suite "${id}"?`,
+				});
+				if (outcome.status !== "answered" || outcome.value !== true) {
+					return { status: "success", message: `Aborted: suite "${id}" was not deleted.` };
+				}
+				const result = deleteSuite({
+					agentDir: getAgentDir(),
+					id,
+					refs,
+					confirmToken: SUITE_DELETE_CONFIRM_TOKEN,
+				});
+				return {
+					status: "success",
+					message: `Deleted suite "${id}"; the workspace was moved to ${result.trashPath}.${cleanupNote(context, id)}`,
+				};
+			} catch (error: unknown) {
+				return errorResult(messageOf(error));
+			}
+		},
+	});
+
+	api.registerCommand({
+		name: "suite-reset",
+		description: "Restore a builtin suite to factory contents (confirmation required)",
+		execute: async (args) => {
+			const id = text(args).split(/\s+/)[0];
+			if (!id) return errorResult("Usage: /suite-reset <id>");
+			const interaction = api.interaction;
+			if (!interaction) {
+				return errorResult(`Refusing to reset suite "${id}" without a dialog-capable UI.`);
+			}
+			try {
+				const plan = resetSuite({ agentDir: getAgentDir(), id });
+				if (plan.diffText.length === 0) {
+					return { status: "success", message: `Suite "${id}" already matches the factory contents.` };
+				}
+				const outcome = await interaction.request({
+					kind: "confirm",
+					title: "Reset suite",
+					message: `Builtin suite "${id}" will be restored to the factory contents. Diff:\n${plan.diffText}`,
+				});
+				if (outcome.status !== "answered" || outcome.value !== true) {
+					return { status: "success", message: `Aborted: suite "${id}" was not reset.` };
+				}
+				const result = plan.apply();
+				return {
+					status: "success",
+					message: `Suite "${id}" was reset to the factory contents (profile lock generation ${result.lock.generation}).`,
+				};
+			} catch (error: unknown) {
+				return errorResult(messageOf(error));
+			}
+		},
+	});
+}

package/examples/extensions/suite-manager/plugin.json

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

package/examples/extensions/timed-confirm/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Timed dialogs example (capability plugin form).
+ *
+ * Shows InteractionAPI.request with timeoutMs and AbortSignal for
+ * auto-dismissing confirm/select dialogs with live countdown.
+ *
+ * Commands:
+ * - /timed - Shows confirm dialog that auto-cancels after 5 seconds
+ * - /timed-select - Shows select dialog that auto-cancels after 10 seconds
+ * - /timed-signal - Shows confirm using AbortSignal (manual approach)
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+
+export default function timedConfirmExample(api: CapabilityAPI): void {
+	// Simple approach: use timeoutMs option (recommended)
+	api.registerCommand({
+		name: "timed",
+		description: "Show a timed confirmation dialog (auto-cancels in 5s with countdown)",
+		execute: async () => {
+			const outcome = await api.interaction?.request(
+				{
+					kind: "confirm",
+					title: "Timed Confirmation",
+					message: "This dialog will auto-cancel in 5 seconds. Confirm?",
+				},
+				{ timeoutMs: 5000 },
+			);
+
+			if (outcome?.status === "answered" && outcome.value === true) {
+				api.interaction?.notify({ message: "Confirmed by user!", level: "info" });
+				return { status: "success", message: "Confirmed by user!" };
+			}
+			api.interaction?.notify({ message: "Cancelled or timed out", level: "info" });
+			return { status: "success", message: "Cancelled or timed out" };
+		},
+	});
+
+	api.registerCommand({
+		name: "timed-select",
+		description: "Show a timed select dialog (auto-cancels in 10s with countdown)",
+		execute: async () => {
+			const outcome = await api.interaction?.request(
+				{ kind: "select", title: "Pick an option", options: ["Option A", "Option B", "Option C"] },
+				{ timeoutMs: 10000 },
+			);
+
+			if (outcome?.status === "answered" && typeof outcome.value === "string") {
+				api.interaction?.notify({ message: `Selected: ${outcome.value}`, level: "info" });
+				return { status: "success", message: `Selected: ${outcome.value}` };
+			}
+			api.interaction?.notify({ message: "Selection cancelled or timed out", level: "info" });
+			return { status: "success", message: "Selection cancelled or timed out" };
+		},
+	});
+
+	// Manual approach: use AbortSignal for more control
+	api.registerCommand({
+		name: "timed-signal",
+		description: "Show a timed confirm using AbortSignal (manual approach)",
+		execute: async () => {
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+			api.interaction?.notify({ message: "Dialog will auto-cancel in 5 seconds...", level: "info" });
+
+			const outcome = await api.interaction?.request(
+				{
+					kind: "confirm",
+					title: "Timed Confirmation",
+					message: "This dialog will auto-cancel in 5 seconds. Confirm?",
+				},
+				{ signal: controller.signal },
+			);
+
+			clearTimeout(timeoutId);
+
+			if (outcome?.status === "answered" && outcome.value === true) {
+				api.interaction?.notify({ message: "Confirmed by user!", level: "info" });
+				return { status: "success", message: "Confirmed by user!" };
+			}
+			if (controller.signal.aborted) {
+				api.interaction?.notify({ message: "Dialog timed out (auto-cancelled)", level: "warning" });
+				return { status: "success", message: "Dialog timed out (auto-cancelled)" };
+			}
+			api.interaction?.notify({ message: "Cancelled by user", level: "info" });
+			return { status: "success", message: "Cancelled by user" };
+		},
+	});
+}

package/examples/extensions/timed-confirm/plugin.json

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

package/examples/extensions/todo-set/README.md

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

package/examples/extensions/todo-set/index.ts

@@ -0,0 +1,133 @@
+import type { CapabilityAPI, DisposableRegistration, EventEnvelope } from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+export interface TodoRecord {
+	id: string;
+	/** Soft reference: a plain string, not validated against any plan plugin. */
+	planId: string;
+	title: string;
+	status: "pending" | "done" | "blocked";
+	revision: number;
+	evidence: string[];
+}
+
+export interface TodoState {
+	todos: TodoRecord[];
+}
+
+export interface TodoSetPluginHandle {
+	readonly tools: readonly DisposableRegistration[];
+	dispose(): Promise<void>;
+}
+
+const stateEntry = "todo.state";
+
+const todoSchema = Type.Object({
+	id: Type.String({ description: "Stable id of the todo to create or update" }),
+	planId: Type.String({
+		description: "Soft reference: a plain plan id string, never validated against the plan plugin's state",
+	}),
+	title: Type.String({ description: "Human-readable todo title" }),
+	revision: Type.Integer({
+		description: "New revision counter; must be greater than the stored revision of an existing todo",
+		minimum: 0,
+	}),
+	status: Type.Optional(
+		Type.Union([Type.Literal("pending"), Type.Literal("done"), Type.Literal("blocked")], {
+			description: "Next status; defaults to the stored status for existing todos, otherwise pending",
+		}),
+	),
+	evidence: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Evidence references; at least one is required when status is done",
+		}),
+	),
+});
+
+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("Todo 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): TodoState {
+	const entries = api.session?.getBranchEntries() ?? [];
+	const entry = [...entries].reverse().find((item) => item.customType === stateEntry);
+	if (!entry?.data || typeof entry.data !== "object") return { todos: [] };
+	const data = entry.data as Partial<TodoState>;
+	return { todos: Array.isArray(data.todos) ? [...data.todos] : [] };
+}
+
+export function createTodoSetPlugin(api: CapabilityAPI): TodoSetPluginHandle {
+	let state = loadState(api);
+	const tools: DisposableRegistration[] = [];
+
+	const persist = async (): Promise<TodoState> => {
+		api.session?.appendEntry(stateEntry, state);
+		await api.publish({ type: "todo.changed", version: 1, correlationId: stateEntry, data: state });
+		return state;
+	};
+
+	tools.push(
+		api.registerTool({
+			name: "todo_update",
+			label: "Update todo",
+			description: "Update a todo that softly references a plan by id",
+			parameters: todoSchema,
+			execute: async (first: unknown, second?: unknown) => {
+				const input = objectInput(first, second);
+				const id = text(input.id, "id");
+				const planId = text(input.planId, "planId");
+				const title = text(input.title, "title");
+				const nextRevision = revision(input.revision);
+				const current = state.todos.find((item) => item.id === id);
+				if (current && nextRevision <= current.revision) throw new Error(`stale todo revision: ${id}`);
+				if (current?.status === "done") throw new Error(`todo is terminal and cannot be updated: ${id}`);
+				const status =
+					input.status === undefined
+						? (current?.status ?? "pending")
+						: (text(input.status, "status") as TodoRecord["status"]);
+				if (!["pending", "done", "blocked"].includes(status)) throw new Error("invalid todo status");
+				const values = evidence(input.evidence);
+				if (status === "done" && values.length === 0) {
+					throw new Error("todo completion requires at least one evidence reference");
+				}
+				const record: TodoRecord = { id, planId, title, status, revision: nextRevision, evidence: values };
+				state = { ...state, todos: [...state.todos.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 Todo example plugin. */
+export default function todoSetExample(api: CapabilityAPI): TodoSetPluginHandle {
+	return createTodoSetPlugin(api);
+}
+
+export type TodoEvent = EventEnvelope<TodoState>;

package/examples/extensions/todo-set/plugin.json

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