@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/multi-agent/index.ts

@@ -0,0 +1,592 @@
+import type { AgentTaskHandle, CapabilityAPI, DisposableRegistration, SessionAPI } from "@agent-forge/agent-forge";
+
+export type MultiAgentTaskStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+
+export interface MultiAgentTaskRequest {
+	id: string;
+	parentSessionId: string;
+	goalId?: string;
+	planId?: string;
+	prompt: string;
+	deadlineMs?: number;
+	budget?: { maxTokens?: number; maxCost?: number };
+}
+
+export interface MultiAgentTaskRecord extends MultiAgentTaskRequest {
+	status: MultiAgentTaskStatus;
+	revision: number;
+	result?: unknown;
+	error?: string;
+}
+
+export interface MultiAgentPluginOptions {
+	/** Maximum UTF-8 bytes retained for a successful result. Defaults to 16 KiB. */
+	maxResultBytes?: number;
+	/** Maximum UTF-8 bytes retained for a task error. Defaults to 4 KiB. */
+	maxErrorBytes?: number;
+}
+
+export interface MultiAgentPluginHandle {
+	readonly tools: readonly DisposableRegistration[];
+	readonly registrations: readonly DisposableRegistration[];
+	readonly backgroundErrors: readonly unknown[];
+	dispose(): Promise<void>;
+}
+
+interface MultiAgentState {
+	tasks: MultiAgentTaskRecord[];
+}
+
+interface TaskWaiter {
+	resolve: (task: MultiAgentTaskRecord) => void;
+	reject: (error: unknown) => void;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+interface TaskInput {
+	id?: unknown;
+	parentSessionId?: unknown;
+	goalId?: unknown;
+	planId?: unknown;
+	prompt?: unknown;
+	reason?: unknown;
+	deadlineMs?: unknown;
+	timeoutMs?: unknown;
+	budget?: unknown;
+}
+
+const stateEntry = "multi-agent.state";
+const changedEvent = "agent.task.changed";
+const lateEvent = "agent.task.late_completion";
+const defaultMaxResultBytes = 16 * 1024;
+const defaultMaxErrorBytes = 4 * 1024;
+
+function inputOf(first: unknown, second: unknown): unknown {
+	return second === undefined ? first : second;
+}
+
+function objectInput(first: unknown, second: unknown, allowMissing = false): TaskInput {
+	const value = inputOf(first, second);
+	if (value === undefined && allowMissing) return {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("Multi-agent input must be an object");
+	}
+	return value as TaskInput;
+}
+
+function requiredText(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} must be a non-empty string`);
+	return value;
+}
+
+function optionalText(value: unknown, name: string): string | undefined {
+	if (value === undefined) return undefined;
+	return requiredText(value, name);
+}
+
+function positiveLimit(value: number | undefined, name: string, fallback: number): number {
+	const limit = value ?? fallback;
+	if (!Number.isInteger(limit) || limit <= 0) throw new Error(`${name} must be a positive integer`);
+	return limit;
+}
+
+function optionalPositiveInteger(value: unknown, name: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (!Number.isInteger(value) || (value as number) <= 0) throw new Error(`${name} must be a positive integer`);
+	return value as number;
+}
+
+function parseBudget(value: unknown): { maxTokens?: number; maxCost?: number } | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("budget must be an object");
+	const input = value as Record<string, unknown>;
+	const maxTokens = optionalPositiveInteger(input.maxTokens, "budget.maxTokens");
+	const maxCost = input.maxCost;
+	if (maxCost !== undefined && (typeof maxCost !== "number" || !Number.isFinite(maxCost) || maxCost <= 0)) {
+		throw new Error("budget.maxCost must be a positive number");
+	}
+	if (maxTokens === undefined && maxCost === undefined) throw new Error("budget must define maxTokens or maxCost");
+	return { ...(maxTokens === undefined ? {} : { maxTokens }), ...(maxCost === undefined ? {} : { maxCost }) };
+}
+
+function byteLength(value: string): number {
+	return new TextEncoder().encode(value).byteLength;
+}
+
+function truncate(value: string, maxBytes: number): string {
+	if (byteLength(value) <= maxBytes) return value;
+	const suffix = "… [truncated]";
+	if (byteLength(suffix) >= maxBytes)
+		return new TextDecoder().decode(new TextEncoder().encode(value).slice(0, maxBytes));
+	let result = value;
+	while (result.length > 0 && byteLength(`${result}${suffix}`) > maxBytes) result = result.slice(0, -1);
+	return `${result}${suffix}`;
+}
+
+function errorText(error: unknown, maxErrorBytes: number): string {
+	const text = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
+	return truncate(text || "Unknown dispatch error", maxErrorBytes);
+}
+
+function boundedResult(value: unknown, maxResultBytes: number): unknown {
+	let encoded: string | undefined;
+	try {
+		encoded = JSON.stringify(value);
+	} catch (error) {
+		throw new Error(`Dispatch result is not JSON-serializable: ${errorText(error, maxResultBytes)}`);
+	}
+	if (encoded === undefined) return undefined;
+	if (byteLength(encoded) > maxResultBytes) {
+		throw new Error(`Dispatch result exceeds ${maxResultBytes} UTF-8 bytes`);
+	}
+	return JSON.parse(encoded) as unknown;
+}
+
+function status(value: unknown): MultiAgentTaskStatus {
+	if (
+		value !== "queued" &&
+		value !== "running" &&
+		value !== "succeeded" &&
+		value !== "failed" &&
+		value !== "cancelled"
+	) {
+		throw new Error(`Invalid multi-agent task status: ${String(value)}`);
+	}
+	return value;
+}
+
+function revision(value: unknown): number {
+	if (!Number.isInteger(value) || (value as number) < 0)
+		throw new Error("Task revision must be a non-negative integer");
+	return value as number;
+}
+
+function persistedTask(value: unknown, maxResultBytes: number, maxErrorBytes: number): MultiAgentTaskRecord {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error("Persisted multi-agent task must be an object");
+	const item = value as Record<string, unknown>;
+	const task: MultiAgentTaskRecord = {
+		id: requiredText(item.id, "Persisted task id"),
+		parentSessionId: requiredText(item.parentSessionId, "Persisted parentSessionId"),
+		goalId: optionalText(item.goalId, "Persisted goalId"),
+		planId: optionalText(item.planId, "Persisted planId"),
+		prompt: requiredText(item.prompt, "Persisted prompt"),
+		status: status(item.status),
+		revision: revision(item.revision),
+		deadlineMs: optionalPositiveInteger(item.deadlineMs, "Persisted task deadlineMs"),
+		budget: parseBudget(item.budget),
+	};
+	if (Object.hasOwn(item, "result")) task.result = boundedResult(item.result, maxResultBytes);
+	if (Object.hasOwn(item, "error"))
+		task.error = truncate(requiredText(item.error, "Persisted task error"), maxErrorBytes);
+	return task;
+}
+
+function loadState(session: SessionAPI, maxResultBytes: number, maxErrorBytes: number): MultiAgentState {
+	const entry = [...session.getBranchEntries()].reverse().find((item) => item.customType === stateEntry);
+	if (!entry) return { tasks: [] };
+	if (!entry.data || typeof entry.data !== "object" || Array.isArray(entry.data)) {
+		throw new Error("Persisted multi-agent state must be an object");
+	}
+	const data = entry.data as { tasks?: unknown };
+	if (!Array.isArray(data.tasks)) throw new Error("Persisted multi-agent state must contain tasks[]");
+	const tasks = data.tasks.map((item) => persistedTask(item, maxResultBytes, maxErrorBytes));
+	const ids = new Set<string>();
+	for (const task of tasks) {
+		if (ids.has(task.id)) throw new Error(`Persisted multi-agent state contains duplicate task id: ${task.id}`);
+		ids.add(task.id);
+	}
+	return { tasks };
+}
+
+function taskRequest(input: TaskInput, defaultParentSessionId: string): MultiAgentTaskRequest {
+	return {
+		id: requiredText(input.id, "id"),
+		parentSessionId: requiredText(input.parentSessionId ?? defaultParentSessionId, "parentSessionId"),
+		goalId: optionalText(input.goalId, "goalId"),
+		planId: optionalText(input.planId, "planId"),
+		prompt: requiredText(input.prompt, "prompt"),
+		deadlineMs: optionalPositiveInteger(input.deadlineMs, "deadlineMs"),
+		budget: parseBudget(input.budget),
+	};
+}
+
+function taskById(tasks: readonly MultiAgentTaskRecord[], id: string): MultiAgentTaskRecord {
+	const task = tasks.find((item) => item.id === id);
+	if (!task) throw new Error(`Unknown multi-agent task: ${id}`);
+	return task;
+}
+
+function canTransition(from: MultiAgentTaskStatus, to: MultiAgentTaskStatus): boolean {
+	return (
+		(from === "queued" && (to === "running" || to === "cancelled")) ||
+		(from === "running" && (to === "succeeded" || to === "failed" || to === "cancelled"))
+	);
+}
+
+/**
+ * Register a small, transport-neutral multi-agent coordinator.
+ *
+ * The host owns transport, scheduling, security, approval, and write
+ * coordination. This plugin only tracks task state and delegates dispatch.
+ */
+export function createMultiAgentPlugin(api: CapabilityAPI, options: MultiAgentPluginOptions): MultiAgentPluginHandle {
+	if (!api.session) throw new Error("Multi-agent plugin requires a SessionAPI");
+	if (!api.agents) throw new Error("Multi-agent plugin requires the agents capability");
+	const maxResultBytes = positiveLimit(options.maxResultBytes, "maxResultBytes", defaultMaxResultBytes);
+	const maxErrorBytes = positiveLimit(options.maxErrorBytes, "maxErrorBytes", defaultMaxErrorBytes);
+	const session = api.session;
+	let state = loadState(session, maxResultBytes, maxErrorBytes);
+	const controllers = new Map<string, AbortController>();
+	const childTasks = new Map<string, AgentTaskHandle>();
+	const waiters = new Map<string, Set<TaskWaiter>>();
+	const deadlineTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	const tools: DisposableRegistration[] = [];
+	const backgroundErrors: unknown[] = [];
+	let disposed = false;
+
+	const persist = (tasks: MultiAgentTaskRecord[]): void => {
+		if (disposed) return;
+		session.appendEntry(stateEntry, { tasks });
+		state = { tasks };
+	};
+
+	const publishChanged = async (changed: MultiAgentTaskRecord): Promise<void> => {
+		await api.publish({ type: changedEvent, version: 1, correlationId: changed.id, data: changed });
+	};
+
+	const settleTerminal = async (next: MultiAgentTaskRecord): Promise<void> => {
+		if (next.status !== "succeeded" && next.status !== "failed" && next.status !== "cancelled") return;
+		const childTask = childTasks.get(next.id);
+		if (childTask) {
+			childTasks.delete(next.id);
+			try {
+				await childTask.dispose();
+			} catch (error) {
+				backgroundErrors.push(error);
+			}
+		}
+		const listeners = waiters.get(next.id);
+		if (listeners) {
+			waiters.delete(next.id);
+			for (const waiter of listeners) {
+				if (waiter.timer) clearTimeout(waiter.timer);
+				waiter.resolve({ ...next });
+			}
+		}
+		const timer = deadlineTimers.get(next.id);
+		if (timer) {
+			clearTimeout(timer);
+			deadlineTimers.delete(next.id);
+		}
+		controllers.delete(next.id);
+	};
+
+	const lateCompletion = async (
+		task: MultiAgentTaskRecord,
+		outcome: "succeeded" | "failed",
+		error?: unknown,
+	): Promise<void> => {
+		await api.publish({
+			type: lateEvent,
+			version: 1,
+			correlationId: task.id,
+			data: {
+				id: task.id,
+				status: task.status,
+				outcome,
+				...(error === undefined ? {} : { error: errorText(error, maxErrorBytes) }),
+			},
+		});
+	};
+
+	const transition = async (
+		id: string,
+		nextStatus: MultiAgentTaskStatus,
+		patch: { result?: unknown; error?: string } = {},
+		options: { publish?: boolean } = {},
+	): Promise<MultiAgentTaskRecord> => {
+		if (disposed) throw new Error("Multi-agent plugin is disposed");
+		const current = taskById(state.tasks, id);
+		if (!canTransition(current.status, nextStatus)) {
+			throw new Error(`Invalid task transition ${current.status} -> ${nextStatus}: ${id}`);
+		}
+		const next: MultiAgentTaskRecord = {
+			...current,
+			status: nextStatus,
+			revision: current.revision + 1,
+			...(patch.result === undefined ? {} : { result: patch.result }),
+			...(patch.error === undefined ? {} : { error: patch.error }),
+		};
+		const tasks = state.tasks.map((task) => (task.id === id ? next : task));
+		persist(tasks);
+		await settleTerminal(next);
+		if (options.publish !== false) await publishChanged(next);
+		return next;
+	};
+
+	const waitForTask = (id: string, timeoutMs?: number): Promise<MultiAgentTaskRecord> => {
+		const current = taskById(state.tasks, id);
+		if (current.status === "succeeded" || current.status === "failed" || current.status === "cancelled") {
+			return Promise.resolve({ ...current });
+		}
+		return new Promise<MultiAgentTaskRecord>((resolve, reject) => {
+			const waiter: TaskWaiter = { resolve, reject };
+			const listeners = waiters.get(id) ?? new Set<TaskWaiter>();
+			listeners.add(waiter);
+			waiters.set(id, listeners);
+			if (timeoutMs === undefined) return;
+			waiter.timer = setTimeout(() => {
+				listeners.delete(waiter);
+				if (listeners.size === 0) waiters.delete(id);
+				reject(new Error(`Timed out waiting for multi-agent task: ${id}`));
+			}, timeoutMs);
+		});
+	};
+
+	const runTask = async (request: MultiAgentTaskRequest, controller: AbortController): Promise<void> => {
+		if (disposed) return;
+		const queued = taskById(state.tasks, request.id);
+		if (queued.status !== "queued") return;
+		let result: unknown;
+		try {
+			await transition(request.id, "running");
+			if (disposed) return;
+			const agents = api.agents;
+			if (!agents) throw new Error("Multi-agent plugin requires the agents capability");
+			const task = await agents.create!({
+				prompt: request.prompt,
+				metadata: {
+					id: request.id,
+					parentSessionId: request.parentSessionId,
+					...(request.goalId === undefined ? {} : { goalId: request.goalId }),
+					...(request.planId === undefined ? {} : { planId: request.planId }),
+					...(request.deadlineMs === undefined ? {} : { deadlineMs: request.deadlineMs }),
+					...(request.budget === undefined ? {} : { budget: request.budget }),
+				},
+			});
+			childTasks.set(request.id, task);
+			// A deadline or explicit cancellation can win while the host creates its
+			// child session. Do not start a task after its coordinator record is
+			// terminal; release the just-created child immediately.
+			if (taskById(state.tasks, request.id).status !== "running") {
+				childTasks.delete(request.id);
+				await task.dispose();
+				return;
+			}
+			const cancel = () => {
+				void task
+					.cancel(typeof controller.signal.reason === "string" ? controller.signal.reason : "cancelled")
+					.catch((error: unknown) => backgroundErrors.push(error));
+			};
+			if (controller.signal.aborted) cancel();
+			else controller.signal.addEventListener("abort", cancel, { once: true });
+			try {
+				await task.run();
+				// Cancellation disposes the child handle immediately. The underlying
+				// run promise still settles, so do not query the revoked handle here;
+				// the coordinator records that completion as a late result below.
+				if (!controller.signal.aborted) result = await task.wait();
+			} finally {
+				controller.signal.removeEventListener("abort", cancel);
+				childTasks.delete(request.id);
+				await task.dispose();
+			}
+		} catch (error) {
+			if (disposed) return;
+			const current = taskById(state.tasks, request.id);
+			if (current.status === "succeeded" || current.status === "failed") {
+				backgroundErrors.push(error);
+				return;
+			}
+			if (current.status === "cancelled") {
+				try {
+					await lateCompletion(current, "failed", error);
+				} catch (publishError) {
+					backgroundErrors.push(publishError);
+				}
+				return;
+			}
+			try {
+				const failed = await transition(
+					request.id,
+					"failed",
+					{ error: errorText(error, maxErrorBytes) },
+					{ publish: false },
+				);
+				try {
+					await publishChanged(failed);
+				} catch (publishError) {
+					backgroundErrors.push(publishError);
+				}
+			} catch (stateError) {
+				backgroundErrors.push(error, stateError);
+			}
+			return;
+		}
+
+		if (disposed) return;
+		const current = taskById(state.tasks, request.id);
+		if (current.status !== "running") {
+			await lateCompletion(current, "succeeded");
+			return;
+		}
+		try {
+			await transition(request.id, "succeeded", { result: boundedResult(result, maxResultBytes) });
+		} catch (error) {
+			if (disposed) return;
+			const latest = taskById(state.tasks, request.id);
+			if (latest.status === "succeeded" || latest.status === "failed") {
+				backgroundErrors.push(error);
+				return;
+			}
+			if (latest.status === "cancelled") {
+				try {
+					await lateCompletion(latest, "succeeded", error);
+				} catch (publishError) {
+					backgroundErrors.push(publishError);
+				}
+				return;
+			}
+			try {
+				const failed = await transition(
+					request.id,
+					"failed",
+					{ error: errorText(error, maxErrorBytes) },
+					{ publish: false },
+				);
+				try {
+					await publishChanged(failed);
+				} catch (publishError) {
+					backgroundErrors.push(publishError);
+				}
+			} catch (stateError) {
+				backgroundErrors.push(error, stateError);
+			}
+		}
+	};
+
+	tools.push(
+		api.registerTool({
+			name: "agent.dispatch",
+			label: "Dispatch agent task",
+			description: "Queue a task for the externally supplied multi-agent transport",
+			parameters: {},
+			execute: async (first: unknown, second?: unknown): Promise<MultiAgentTaskRecord> => {
+				const request = taskRequest(objectInput(first, second), session.getSessionId());
+				if (state.tasks.some((task) => task.id === request.id))
+					throw new Error(`Task id already exists: ${request.id}`);
+				const controller = new AbortController();
+				const queued: MultiAgentTaskRecord = { ...request, status: "queued", revision: 0 };
+				persist([...state.tasks, queued]);
+				await publishChanged(queued);
+				controllers.set(request.id, controller);
+				if (request.deadlineMs !== undefined) {
+					const timer = setTimeout(() => {
+						const current = taskById(state.tasks, request.id);
+						if (current.status !== "queued" && current.status !== "running") return;
+						controller.abort("deadline exceeded");
+						void transition(request.id, "cancelled", { error: "deadline exceeded" }).catch((error: unknown) => {
+							const latest = taskById(state.tasks, request.id);
+							if (latest.status !== "succeeded" && latest.status !== "failed" && latest.status !== "cancelled") {
+								backgroundErrors.push(error);
+							}
+						});
+					}, request.deadlineMs);
+					deadlineTimers.set(request.id, timer);
+				}
+				void runTask(request, controller).catch((error: unknown) => backgroundErrors.push(error));
+				return queued;
+			},
+		}),
+	);
+
+	tools.push(
+		api.registerTool({
+			name: "agent.wait",
+			label: "Wait for agent task",
+			description: "Wait for one externally dispatched task to reach a terminal state",
+			parameters: {},
+			execute: async (first: unknown, second?: unknown): Promise<MultiAgentTaskRecord> => {
+				const input = objectInput(first, second);
+				const id = requiredText(input.id, "id");
+				const timeoutMs = optionalPositiveInteger(input.timeoutMs, "timeoutMs");
+				return waitForTask(id, timeoutMs);
+			},
+		}),
+	);
+
+	tools.push(
+		api.registerTool({
+			name: "agent.status",
+			label: "Agent task status",
+			description: "Read one externally dispatched task or all tasks in this session branch",
+			parameters: {},
+			execute: async (
+				first: unknown,
+				second?: unknown,
+			): Promise<MultiAgentTaskRecord | readonly MultiAgentTaskRecord[]> => {
+				const input = objectInput(first, second, true);
+				if (input.id === undefined) return state.tasks.map((task) => ({ ...task }));
+				return { ...taskById(state.tasks, requiredText(input.id, "id")) };
+			},
+		}),
+	);
+
+	tools.push(
+		api.registerTool({
+			name: "agent.cancel",
+			label: "Cancel agent task",
+			description: "Cancel a queued or running externally dispatched task",
+			parameters: {},
+			execute: async (first: unknown, second?: unknown): Promise<MultiAgentTaskRecord> => {
+				const input = objectInput(first, second);
+				const id = requiredText(input.id, "id");
+				const current = taskById(state.tasks, id);
+				if (current.status !== "queued" && current.status !== "running") {
+					throw new Error(`Task is already terminal: ${id} (${current.status})`);
+				}
+				const reason = input.reason === undefined ? "cancelled" : requiredText(input.reason, "reason");
+				controllers.get(id)?.abort(reason);
+				await childTasks.get(id)?.cancel(reason);
+				return transition(id, "cancelled", { error: errorText(reason, maxErrorBytes) });
+			},
+		}),
+	);
+
+	return {
+		tools,
+		registrations: tools,
+		backgroundErrors,
+		dispose: async () => {
+			disposed = true;
+			for (const controller of controllers.values()) controller.abort("plugin disposed");
+			// CapabilityRuntime revokes the API before instance cleanup. dispose() is
+			// deliberately usable after revocation and cancels the host task itself.
+			const childDisposals = Array.from(childTasks.values(), (task) => task.dispose());
+			await Promise.all(childDisposals);
+			childTasks.clear();
+			for (const timer of deadlineTimers.values()) clearTimeout(timer);
+			deadlineTimers.clear();
+			for (const [id, listeners] of waiters) {
+				for (const waiter of listeners) {
+					if (waiter.timer) clearTimeout(waiter.timer);
+					waiter.reject(new Error(`Multi-agent plugin disposed while waiting for task: ${id}`));
+				}
+			}
+			waiters.clear();
+			for (const tool of tools) await tool.dispose();
+		},
+	};
+}
+
+export { stateEntry as MULTI_AGENT_STATE_ENTRY };
+export { changedEvent as MULTI_AGENT_CHANGED_EVENT, lateEvent as MULTI_AGENT_LATE_EVENT };
+
+/**
+ * Manifest entry for the in-process child-session coordinator. Scheduling,
+ * budgets, and any external transport remain replaceable plugin policy.
+ */
+export default function multiAgentExample(api: CapabilityAPI): MultiAgentPluginHandle {
+	return createMultiAgentPlugin(api, {});
+}

package/examples/extensions/multi-agent/plugin.json

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

package/examples/extensions/notify/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Notify Example (capability plugin form)
+ *
+ * Sends a native terminal notification when the Agent Forge agent is done and
+ * waiting for input. Supports multiple terminal protocols:
+ * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
+ * - OSC 99: Kitty
+ * - Windows toast: Windows Terminal (WSL)
+ *
+ * The subscription is the `agent.settled` host lifecycle event (version 1),
+ * whose id/version pair is the lifecycle catalog's
+ * `AGENT_SETTLED_EVENT_ID`/`AGENT_SETTLED_EVENT_VERSION`
+ * (src/core/extensions/lifecycle-catalog.ts). `agent.end` fires after each
+ * low-level run, while `agent.settled` is the settled-run boundary: the agent
+ * may still retry, compact, or continue with queued follow-ups before it.
+ *
+ * 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";
+
+function windowsToastScript(title: string, body: string): string {
+	const type = "Windows.UI.Notifications";
+	const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`;
+	const template = `[${type}.ToastTemplateType]::ToastText01`;
+	const toast = `[${type}.ToastNotification]::new($xml)`;
+	return [
+		`${mgr} > $null`,
+		`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,
+		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${body}')) > $null`,
+		`[${type}.ToastNotificationManager]::CreateToastNotifier('${title}').Show(${toast})`,
+	].join("; ");
+}
+
+function notifyOSC777(title: string, body: string): void {
+	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+}
+
+function notifyOSC99(title: string, body: string): void {
+	// Kitty OSC 99: i=notification id, d=0 means not done yet, p=body for second part
+	process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`);
+	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
+}
+
+function notifyWindows(title: string, body: string): void {
+	const { execFile } = require("child_process");
+	execFile("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)]);
+}
+
+function notify(title: string, body: string): void {
+	if (process.env.WT_SESSION) {
+		notifyWindows(title, body);
+	} else if (process.env.KITTY_WINDOW_ID) {
+		notifyOSC99(title, body);
+	} else {
+		notifyOSC777(title, body);
+	}
+}
+
+export default function notifyExample(api: CapabilityAPI): void {
+	// Notify only after the full run settles.
+	api.lifecycle.registerObserve(
+		"agent.settled",
+		async () => {
+			notify("Pi", "Ready for input");
+		},
+		1,
+	);
+}

package/examples/extensions/notify/plugin.json

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