@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/cli-bridge/index.ts

@@ -0,0 +1,320 @@
+/**
+ * Declarative CLI bridge capability plugin example.
+ *
+ * This plugin only adapts command definitions to tools. The host remains
+ * responsible for choosing readonly/full-control mode and any policy around
+ * the commands it makes available.
+ */
+
+import type { ChildProcess } 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 { Static, TSchema } from "typebox";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+
+export interface CliBridgeDetails {
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+	killed: boolean;
+}
+
+export interface CliExecutorInput {
+	command: string;
+	args: readonly string[];
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	signal: AbortSignal;
+	timeoutMs?: number;
+}
+
+export type CliExecutor = (input: CliExecutorInput) => Promise<CliBridgeDetails>;
+
+export interface CliCommandDefinition<TParams extends TSchema = TSchema> {
+	name: string;
+	command: string;
+	args?: readonly string[] | ((params: Static<TParams>) => readonly string[]);
+	parameters?: TParams;
+	label?: string;
+	description?: string;
+	cwd?: string;
+	timeoutMs?: number;
+	/** Values overlay the selected inherited environment. */
+	env?: Record<string, string>;
+	/** When set, only these inherited environment keys are passed through. */
+	envAllowlist?: readonly string[];
+}
+
+export interface CliBridgePluginOptions {
+	executor?: CliExecutor;
+}
+
+export class CliBridgeError extends Error {
+	readonly details: CliBridgeDetails;
+	readonly reason: "invalid_parameters" | "aborted" | "timed_out" | "exit" | "killed" | "spawn";
+
+	constructor(message: string, reason: CliBridgeError["reason"], details: CliBridgeDetails) {
+		super(message);
+		this.name = "CliBridgeError";
+		this.reason = reason;
+		this.details = details;
+	}
+}
+
+const emptyDetails = (killed = false): CliBridgeDetails => ({ stdout: "", stderr: "", exitCode: null, killed });
+
+function validateDefinition(definition: CliCommandDefinition): void {
+	if (!definition.name.trim()) throw new Error("CLI bridge command requires a non-empty name");
+	if (!definition.command.trim()) throw new Error(`CLI bridge command requires a command: ${definition.name}`);
+	if (definition.cwd !== undefined && typeof definition.cwd !== "string") {
+		throw new Error(`CLI bridge cwd must be a string: ${definition.name}`);
+	}
+	if (definition.timeoutMs !== undefined && (!Number.isFinite(definition.timeoutMs) || definition.timeoutMs <= 0)) {
+		throw new Error(`CLI bridge timeoutMs must be a positive number: ${definition.name}`);
+	}
+	if (
+		definition.args &&
+		typeof definition.args !== "function" &&
+		definition.args.some((arg) => typeof arg !== "string")
+	) {
+		throw new Error(`CLI bridge args must contain only strings: ${definition.name}`);
+	}
+	if (definition.envAllowlist?.some((name) => typeof name !== "string")) {
+		throw new Error(`CLI bridge envAllowlist must contain only strings: ${definition.name}`);
+	}
+	if (definition.env && Object.entries(definition.env).some(([name, value]) => !name || typeof value !== "string")) {
+		throw new Error(`CLI bridge env must contain non-empty string keys and string values: ${definition.name}`);
+	}
+}
+
+function createEnvironment(definition: CliCommandDefinition): NodeJS.ProcessEnv | undefined {
+	if (!definition.env && !definition.envAllowlist) return undefined;
+	const environment: NodeJS.ProcessEnv = {};
+	if (definition.envAllowlist) {
+		for (const name of definition.envAllowlist) {
+			const value = process.env[name];
+			if (value !== undefined) environment[name] = value;
+		}
+	} else {
+		Object.assign(environment, process.env);
+	}
+	Object.assign(environment, definition.env);
+	return environment;
+}
+
+function resolveArgs<TParams extends TSchema>(
+	definition: CliCommandDefinition<TParams>,
+	params: Static<TParams>,
+): string[] {
+	const template = typeof definition.args === "function" ? definition.args(params) : (definition.args ?? []);
+	return template.map((arg) => {
+		if (typeof arg !== "string") return arg;
+		return arg.replace(/\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}/g, (match, key: string) => {
+			const value = (params as Record<string, unknown>)[key];
+			if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return match;
+			return String(value);
+		});
+	});
+}
+
+function killProcess(processHandle: ChildProcess, isDone: () => boolean): void {
+	if (!processHandle.killed) processHandle.kill("SIGTERM");
+	setTimeout(() => {
+		if (!isDone()) processHandle.kill("SIGKILL");
+	}, 5000).unref();
+}
+
+/** Execute one argv vector without ever invoking a shell. */
+export function spawnCliExecutor(input: CliExecutorInput): Promise<CliBridgeDetails> {
+	return new Promise((resolve, reject) => {
+		if (input.signal.aborted) {
+			reject(new CliBridgeError("CLI command aborted", "aborted", emptyDetails(true)));
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timeoutHandle: NodeJS.Timeout | undefined;
+		let termination: "aborted" | "timed_out" | undefined;
+		const child = spawn(input.command, [...input.args], {
+			cwd: input.cwd,
+			env: input.env,
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const finish = (details: CliBridgeDetails): void => {
+			if (settled) return;
+			settled = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			input.signal.removeEventListener("abort", onAbort);
+			resolve(details);
+		};
+		const terminate = (reason: "aborted" | "timed_out"): void => {
+			if (settled || termination) return;
+			termination = reason;
+			killProcess(child, () => settled);
+		};
+		const onAbort = (): void => terminate("aborted");
+
+		child.stdout?.on("data", (chunk: Buffer | string) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", (error: Error) => {
+			if (settled) return;
+			settled = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			input.signal.removeEventListener("abort", onAbort);
+			reject(
+				new CliBridgeError(`Failed to spawn CLI command: ${error.message}`, "spawn", {
+					stdout,
+					stderr,
+					exitCode: null,
+					killed: false,
+				}),
+			);
+		});
+		child.once("close", (exitCode) => {
+			finish({ stdout, stderr, exitCode, killed: termination !== undefined });
+		});
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		if (input.signal.aborted) onAbort();
+		if (input.timeoutMs !== undefined) {
+			timeoutHandle = setTimeout(() => terminate("timed_out"), input.timeoutMs);
+		}
+	});
+}
+
+function resultContent(result: CliBridgeDetails): AgentToolResult<unknown>["content"] {
+	return [{ type: "text", text: `${result.stdout}${result.stderr}` }];
+}
+
+function buildTool<TParams extends TSchema>(
+	definition: CliCommandDefinition<TParams>,
+	executor: CliExecutor,
+): ToolDefinition<TParams, CliBridgeDetails> {
+	const parameters = definition.parameters ?? (Type.Object({}) as unknown as TParams);
+	const checker = Compile(parameters);
+
+	return {
+		name: definition.name,
+		label: definition.label ?? definition.name,
+		description: definition.description ?? `Run ${definition.command} with an argv array`,
+		parameters,
+		async execute(toolCallId, params, signal, _onUpdate, _ctx: ToolExecuteContext) {
+			// CapabilityRuntime.invokeTool calls handlers with only the input. The
+			// AgentTool adapter supplies the normal toolCallId + params pair.
+			const input = params === undefined && typeof toolCallId !== "string" ? toolCallId : params;
+			if (!checker.Check(input)) {
+				throw new CliBridgeError(
+					`Invalid parameters for CLI command: ${definition.name}`,
+					"invalid_parameters",
+					emptyDetails(),
+				);
+			}
+			const args = resolveArgs(definition, input as Static<TParams>);
+			if (args.some((arg) => typeof arg !== "string")) {
+				throw new CliBridgeError(
+					`CLI command args must contain only strings: ${definition.name}`,
+					"invalid_parameters",
+					emptyDetails(),
+				);
+			}
+			const runController = new AbortController();
+			let cancellation: "aborted" | "timed_out" | undefined;
+			const abortRun = (reason: "aborted" | "timed_out"): void => {
+				if (cancellation) return;
+				cancellation = reason;
+				runController.abort(reason);
+			};
+			const onCallerAbort = (): void => abortRun("aborted");
+			if (signal?.aborted) onCallerAbort();
+			else signal?.addEventListener("abort", onCallerAbort, { once: true });
+			let timeoutHandle: NodeJS.Timeout | undefined;
+			if (definition.timeoutMs !== undefined) {
+				timeoutHandle = setTimeout(() => abortRun("timed_out"), definition.timeoutMs);
+			}
+			const execution = executor({
+				command: definition.command,
+				args,
+				cwd: definition.cwd,
+				env: createEnvironment(definition),
+				signal: runController.signal,
+				timeoutMs: definition.timeoutMs,
+			});
+			try {
+				// Executors are required to observe signal and resolve with their
+				// accumulated output after termination, so failures retain stdout/stderr.
+				const result = await execution;
+				if (cancellation) {
+					throw new CliBridgeError(`CLI command ${cancellation}`, cancellation, result);
+				}
+				if (result.killed) {
+					throw new CliBridgeError("CLI command was killed", "killed", result);
+				}
+				if (result.exitCode !== 0) {
+					throw new CliBridgeError(
+						`CLI command exited with code ${result.exitCode ?? "unknown"}`,
+						result.killed ? "killed" : "exit",
+						result,
+					);
+				}
+				return { content: resultContent(result), details: result };
+			} catch (error) {
+				if (error instanceof CliBridgeError) throw error;
+				const details = emptyDetails();
+				throw new CliBridgeError(error instanceof Error ? error.message : String(error), "spawn", details);
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				signal?.removeEventListener("abort", onCallerAbort);
+			}
+		},
+	};
+}
+
+function validateDefinitions(definitions: readonly CliCommandDefinition[]): void {
+	const names = new Set<string>();
+	for (const definition of definitions) {
+		validateDefinition(definition);
+		if (names.has(definition.name)) throw new Error(`Duplicate CLI bridge command: ${definition.name}`);
+		names.add(definition.name);
+	}
+}
+
+/** Create a capability plugin factory for a declarative list of CLI commands. */
+export function createCliBridgePlugin(
+	definitions: readonly CliCommandDefinition[],
+	options: CliBridgePluginOptions = {},
+): CapabilityPluginFactory {
+	validateDefinitions(definitions);
+	const executor = options.executor ?? spawnCliExecutor;
+	return (api: CapabilityAPI): void => {
+		for (const definition of definitions) api.registerTool(buildTool(definition, executor));
+	};
+}
+
+const exampleCommands: readonly CliCommandDefinition[] = [
+	{
+		name: "cli_bridge_echo",
+		command: process.execPath,
+		args: ["-e", "process.stdout.write(process.argv[1])", "{{text}}"],
+		parameters: Type.Object({ text: Type.String() }),
+		description: "Example CLI bridge command using an argv array",
+	},
+];
+
+/** Default entry for a copied, configured CLI bridge manifest. */
+export default function cliBridgeExample(api: CapabilityAPI): void {
+	createCliBridgePlugin(exampleCommands)(api);
+}

package/examples/extensions/cli-bridge/plugin.json

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

package/examples/extensions/dynamic-resources/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: dynamic-resources
+description: Example skill loaded from resources_discover
+---
+
+# Dynamic Resources Skill
+
+This skill is provided by the dynamic-resources extension.

package/examples/extensions/dynamic-resources/dynamic.json

@@ -0,0 +1,79 @@
+{
+	"$schema": "https://raw.githubusercontent.com/agent-forge/agent-forge/main/packages/agent-forge/src/modes/interactive/theme/theme-schema.json",
+	"name": "dynamic-resources",
+	"vars": {
+		"cyan": "#00d7ff",
+		"blue": "#5f87ff",
+		"green": "#b5bd68",
+		"red": "#cc6666",
+		"yellow": "#ffff00",
+		"gray": "#808080",
+		"dimGray": "#666666",
+		"darkGray": "#505050",
+		"accent": "#8abeb7",
+		"selectedBg": "#3a3a4a",
+		"userMsgBg": "#343541",
+		"toolPendingBg": "#282832",
+		"toolSuccessBg": "#283228",
+		"toolErrorBg": "#3c2828",
+		"customMsgBg": "#2d2838"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "blue",
+		"borderAccent": "cyan",
+		"borderMuted": "darkGray",
+		"success": "green",
+		"error": "red",
+		"warning": "yellow",
+		"muted": "gray",
+		"dim": "dimGray",
+		"text": "",
+		"thinkingText": "gray",
+		"selectedBg": "selectedBg",
+		"userMessageBg": "userMsgBg",
+		"userMessageText": "",
+		"customMessageBg": "customMsgBg",
+		"customMessageText": "",
+		"customMessageLabel": "#9575cd",
+		"toolPendingBg": "toolPendingBg",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "",
+		"toolOutput": "gray",
+		"mdHeading": "#f0c674",
+		"mdLink": "#81a2be",
+		"mdLinkUrl": "dimGray",
+		"mdCode": "accent",
+		"mdCodeBlock": "green",
+		"mdCodeBlockBorder": "gray",
+		"mdQuote": "gray",
+		"mdQuoteBorder": "gray",
+		"mdHr": "gray",
+		"mdListBullet": "accent",
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "gray",
+		"syntaxComment": "#6A9955",
+		"syntaxKeyword": "#569CD6",
+		"syntaxFunction": "#DCDCAA",
+		"syntaxVariable": "#9CDCFE",
+		"syntaxString": "#CE9178",
+		"syntaxNumber": "#B5CEA8",
+		"syntaxType": "#4EC9B0",
+		"syntaxOperator": "#D4D4D4",
+		"syntaxPunctuation": "#D4D4D4",
+		"thinkingOff": "darkGray",
+		"thinkingMinimal": "#6e6e6e",
+		"thinkingLow": "#5f87af",
+		"thinkingMedium": "#81a2be",
+		"thinkingHigh": "#b294bb",
+		"thinkingXhigh": "#d183e8",
+		"bashMode": "green"
+	},
+	"export": {
+		"pageBg": "#18181e",
+		"cardBg": "#1e1e24",
+		"infoBg": "#3c3728"
+	}
+}

package/examples/extensions/dynamic-resources/dynamic.md

@@ -0,0 +1,5 @@
+---
+description: Example prompt template loaded from resources_discover
+---
+
+Summarize the current repository structure and mention any build or test commands.

package/examples/extensions/dynamic-resources/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Dynamic Resources Example (capability plugin form)
+ *
+ * Contributes a skill, a prompt template, and a theme at discovery time so
+ * they load without any static registration. The discovery stays dynamic: the
+ * paths are resolved from the plugin directory on every dispatch, so a reload
+ * (`reason: "reload"`) re-runs it.
+ *
+ * The legacy pair maps as: the `pi.on("resources_discover")` handler that
+ * returned `{ skillPaths, promptPaths, themePaths }` → the `resources.discover`@2
+ * candidate transform (`api.lifecycle.registerTransform(..., 2)`; the observe-
+ * only v1 envelope carries no contribution fields). The handler receives the v2
+ * envelope — `{ version: 2, sessionId, cwd, reason }`; this example's resources
+ * are plugin-relative, so the paths do not depend on the cwd fact — and returns
+ * the full data with the three contribution arrays attached, each entry shaped
+ * `{ path, extensionPath }` (the extensionPath is this plugin's entry file, the
+ * role the legacy extension file played). The host merges the contribution with
+ * the legacy collection result and feeds the merged set into
+ * `resource-loader.extendResources`.
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+/** Shape of the `resources.discover`@2 envelope (lifecycle catalog). */
+interface ResourcesDiscoverDataV2 {
+	version: 2;
+	sessionId: string;
+	cwd: string;
+	reason: "startup" | "reload";
+	skillPaths?: Array<{ path: string; extensionPath: string }>;
+	promptPaths?: Array<{ path: string; extensionPath: string }>;
+	themePaths?: Array<{ path: string; extensionPath: string }>;
+}
+
+export default function dynamicResourcesExample(api: CapabilityAPI): void {
+	api.lifecycle.registerTransform<ResourcesDiscoverDataV2>(
+		"resources.discover",
+		(event) => ({
+			...event.data,
+			skillPaths: [{ path: join(baseDir, "SKILL.md"), extensionPath: join(baseDir, "index.ts") }],
+			promptPaths: [{ path: join(baseDir, "dynamic.md"), extensionPath: join(baseDir, "index.ts") }],
+			themePaths: [{ path: join(baseDir, "dynamic.json"), extensionPath: join(baseDir, "index.ts") }],
+		}),
+		2,
+	);
+}

package/examples/extensions/dynamic-resources/plugin.json

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

package/examples/extensions/dynamic-tools/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ *
+ * Usage:
+ *   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 tool-surface batch, 2026-09-21):
+ * `pi.registerTool` maps to `api.registerTool` (the host's tool-registry-change
+ * wiring re-syncs the session registry, so a tool registered from the command
+ * handler is immediately visible and activatable); `pi.on("session_start")`
+ * maps to `api.lifecycle.registerObserve("session.start", handler, 1)` with the
+ * registration moved to the factory (the load boundary precedes the
+ * session.start dispatch, mirroring kimi-deferred-tools); `ctx.ui.notify` maps
+ * to `api.interaction?.notify`.
+ */
+
+import { type CapabilityAPI, defineTool } from "@agent-forge/agent-forge";
+import { Type } from "typebox";
+
+const ECHO_PARAMS = Type.Object({
+	message: Type.String({ description: "Message to echo" }),
+});
+
+function normalizeToolName(input: string): string | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (!trimmed) return undefined;
+	if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export default function dynamicToolsExtension(api: CapabilityAPI): void {
+	const registeredToolNames = new Set<string>();
+
+	const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+		if (registeredToolNames.has(name)) {
+			return false;
+		}
+
+		registeredToolNames.add(name);
+		api.registerTool(
+			defineTool({
+				name,
+				label,
+				description: `Echo a message with prefix: ${prefix}`,
+				promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+				promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
+				parameters: ECHO_PARAMS,
+				async execute(_toolCallId, params) {
+					return {
+						content: [{ type: "text", text: `${prefix}${params.message}` }],
+						details: { tool: name, prefix },
+					};
+				},
+			}),
+		);
+
+		return true;
+	};
+
+	// The load boundary registers echo_session before the session.start
+	// dispatch, so the tool is in the registry (and activatable) when the
+	// observer fires.
+	registerEchoTool("echo_session", "Echo Session", "[session] ");
+
+	api.lifecycle.registerObserve(
+		"session.start",
+		() => {
+			api.interaction?.notify({ message: "Registered dynamic tool: echo_session", level: "info" });
+		},
+		1,
+	);
+
+	api.registerCommand({
+		name: "add-echo-tool",
+		description: "Register a new echo tool dynamically: /add-echo-tool <tool_name>",
+		execute: async (args) => {
+			const toolName = normalizeToolName(args);
+			if (!toolName) {
+				api.interaction?.notify({
+					message: "Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)",
+					level: "warning",
+				});
+				return undefined;
+			}
+
+			const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+			if (!created) {
+				api.interaction?.notify({ message: `Tool already registered: ${toolName}`, level: "warning" });
+				return undefined;
+			}
+
+			api.interaction?.notify({ message: `Registered dynamic tool: ${toolName}`, level: "info" });
+			return undefined;
+		},
+	});
+}

package/examples/extensions/dynamic-tools/plugin.json

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

package/examples/extensions/event-bus/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Inter-extension event bus example (capability plugin form).
+ *
+ * Shows `api.publish`/`api.subscribe` for communication between plugins: one
+ * plugin publishes an event that other plugins subscribe to. The legacy
+ * `pi.events` bus is the same plugin-to-plugin channel (the host never feeds
+ * it), so it maps directly onto the capability directory primitives; host
+ * lifecycle events are a different channel (`api.lifecycle.registerObserve`).
+ *
+ * A subscriber receives the full `EventEnvelope`, so payload travels in
+ * `event.data`; the publisher supplies `type`/`version`/`correlationId` and the
+ * runtime fills in `id`/`source`/`timestamp`.
+ *
+ * Usage: /emit [event-name] [data] - emit an event on the bus
+ *
+ * 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";
+
+const NOTIFICATION_EVENT_TYPE = "my:notification";
+
+interface NotificationPayload {
+	message: string;
+	from: string;
+}
+
+export default function eventBusExample(api: CapabilityAPI): void {
+	// The legacy example kept the session ctx for the notification surface; the
+	// capability form only needs a readiness flag, since the plugin API itself
+	// stays valid after the session.start boundary.
+	let sessionStarted = false;
+
+	// Listen for events from other plugins
+	api.subscribe<NotificationPayload>(NOTIFICATION_EVENT_TYPE, (event) => {
+		const { message, from } = event.data;
+		if (!sessionStarted) return;
+		api.interaction?.notify({ message: `Event from ${from}: ${message}`, level: "info" });
+	});
+
+	// Command to publish events (publishes "my:notification" which the listener above receives)
+	api.registerCommand({
+		name: "emit",
+		description: "Emit my:notification event (usage: /emit message)",
+		execute: async (args) => {
+			const message = args.trim() || "hello";
+			await api.publish({
+				type: NOTIFICATION_EVENT_TYPE,
+				version: 1,
+				correlationId: NOTIFICATION_EVENT_TYPE,
+				data: { message, from: "/emit command" } satisfies NotificationPayload,
+			});
+			// Listener above will show the notification
+			return undefined;
+		},
+	});
+
+	// One observer for the session boundary: mark the session ready first, then
+	// publish the sample event (the legacy face stored ctx and published in the
+	// same session_start handler, so the listener always saw the ready state).
+	api.lifecycle.registerObserve(
+		"session.start",
+		async () => {
+			sessionStarted = true;
+			await api.publish({
+				type: NOTIFICATION_EVENT_TYPE,
+				version: 1,
+				correlationId: NOTIFICATION_EVENT_TYPE,
+				data: { message: "Session started", from: "event-bus-example" } satisfies NotificationPayload,
+			});
+		},
+		1,
+	);
+}