@ai-agent-forge/agent-forge 0.85.0

package/examples/extensions/send-user-message/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Send User Message Example (capability plugin form)
+ *
+ * Shows the SessionAPI user-message surface: `prompt()` sends a message that
+ * enters the conversation as if typed by the user (and triggers a turn),
+ * `steer?()` queues a steering message for an active run, and `queueFollowUp?()`
+ * queues a message that waits for the active run instead of interrupting it.
+ * Unlike custom messages, these enter the conversation as real user messages.
+ *
+ * Usage:
+ *   /ask What is 2+2?     - Sends a user message (always triggers a turn)
+ *   /steer Focus on X     - Sends while streaming with steer delivery
+ *   /followup And then?   - Sends while streaming with followUp delivery
+ *   /askwith <message>    - Sends a message composed from several text parts
+ *
+ * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
+ * or <cwd>/.agent-forge/plugins for auto-discovery.
+ */
+
+import type { CapabilityAPI, CapabilityCommandResult } from "@agent-forge/agent-forge";
+
+function usage(command: string): CapabilityCommandResult {
+	return { status: "error", message: `Usage: ${command} <message>` };
+}
+
+export default function sendUserMessageExample(api: CapabilityAPI): void {
+	// Simple command that sends a user message
+	api.registerCommand({
+		name: "ask",
+		description: "Send a user message to the agent",
+		execute: async (args) => {
+			const message = args.trim();
+			if (!message) return usage("/ask");
+
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			// prompt() always triggers a turn when the session is idle; while a run
+			// is active it rejects, so route through /steer or /followup instead.
+			if (!session.isIdle()) {
+				return { status: "error", message: "Agent is busy. Use /steer or /followup instead." };
+			}
+
+			await session.prompt(message);
+			return undefined;
+		},
+	});
+
+	// Command that steers the agent mid-conversation
+	api.registerCommand({
+		name: "steer",
+		description: "Send a steering message (interrupts current processing)",
+		execute: async (args) => {
+			const message = args.trim();
+			if (!message) return usage("/steer");
+
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			if (session.isIdle()) {
+				// Not streaming, just send normally
+				await session.prompt(message);
+			} else {
+				// Streaming - queue as steering
+				await session.steer?.(message);
+			}
+			return undefined;
+		},
+	});
+
+	// Command that queues a follow-up message
+	api.registerCommand({
+		name: "followup",
+		description: "Queue a follow-up message (waits for current processing)",
+		execute: async (args) => {
+			const message = args.trim();
+			if (!message) return usage("/followup");
+
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			if (session.isIdle()) {
+				// Not streaming, just send normally
+				await session.prompt(message);
+				return undefined;
+			}
+
+			// Streaming - queue as follow-up; the host renders the result
+			await session.queueFollowUp?.(message);
+			return { status: "success", message: "Follow-up queued" };
+		},
+	});
+
+	// Command that sends content assembled from several parts
+	api.registerCommand({
+		name: "askwith",
+		description: "Send a user message with structured content",
+		execute: async (args) => {
+			const message = args.trim();
+			if (!message) return usage("/askwith");
+
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			if (!session.isIdle()) {
+				return { status: "error", message: "Agent is busy" };
+			}
+
+			// The legacy face accepted a (TextContent | ImageContent)[] here and the
+			// host normalizes a content array to its text parts joined with "\n"
+			// before sending (agent-session.ts:2236). prompt() takes plain text, so
+			// joining the same text parts the same way reproduces the same user
+			// message. Multimodal user content has no capability channel yet.
+			await session.prompt([`User request: ${message}`, "Please respond concisely."].join("\n"));
+			return undefined;
+		},
+	});
+}

package/examples/extensions/send-user-message/plugin.json

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

package/examples/extensions/session-name/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Session naming example (capability plugin form).
+ *
+ * Shows SessionAPI.setSessionName/getSessionName to give sessions friendly
+ * names that appear in the session selector instead of the first message.
+ * The command returns a CapabilityCommandResult; the host renders it.
+ *
+ * Usage: /session-name [name] - set or show session name
+ *
+ * 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 sessionNameExample(api: CapabilityAPI): void {
+	api.registerCommand({
+		name: "session-name",
+		description: "Set or show session name (usage: /session-name [new name])",
+		execute: async (args) => {
+			const name = args.trim();
+
+			if (name) {
+				api.session?.setSessionName?.(name);
+				return { status: "success", message: `Session named: ${name}` };
+			}
+			const current = api.session?.getSessionName?.();
+			return { status: "success", message: current ? `Session: ${current}` : "No session name set" };
+		},
+	});
+}

package/examples/extensions/session-name/plugin.json

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

package/examples/extensions/session-share/README.md

@@ -0,0 +1,15 @@
+# Session share plugin
+
+这是一个显式安装的分享插件示例。核心不再内置 `/share`，插件配置必须明确选择 `radius` 或 `gist`，不会在失败时静默切换目标。
+
+注：默认分发的第一方实现已收编为内嵌 capability `agent-forge.builtin.session-share`（随内置 suite 提供 `/share`，配置走 agent 目录的配置通道 `<agentDir>/capabilities/builtin.session-share.json`，同一 JSON 形状）。本示例保留为参考实现；若同时安装本示例，`share` 命令重名会在加载期显式失败（既有命令冲突语义），此时应改用内置实现的配置通道。
+
+```json
+{
+  "target": "radius",
+  "gateway": "http://127.0.0.1:8787",
+  "credentialProvider": "radius"
+}
+```
+
+`gist` 目标需要 `viewerUrl`，并使用本机 `gh gist create`。插件只依赖 `CapabilityAPI`；网络和进程调用均位于插件自身，测试通过注入的 mock 适配器完成。

package/examples/extensions/session-share/index.ts

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import type {
+	CapabilityAPI,
+	CapabilityCommandContext,
+	CapabilityCommandResult,
+	DisposableRegistration,
+	SessionExportArtifact,
+} from "@agent-forge/agent-forge";
+
+type ShareTarget = "radius" | "gist";
+
+export interface ShareProcessResult {
+	code: number | null;
+	stdout: string;
+	stderr: string;
+}
+
+export type ShareProcess = (
+	argv: readonly string[],
+	input: Uint8Array,
+	signal: AbortSignal,
+) => Promise<ShareProcessResult>;
+
+export interface SessionSharePluginOptions {
+	fetch?: typeof globalThis.fetch;
+	process?: ShareProcess;
+}
+
+export interface SessionSharePluginHandle {
+	readonly command: DisposableRegistration;
+	dispose(): void | Promise<void>;
+}
+
+function configString(api: CapabilityAPI, key: string): string | undefined {
+	const value = api.config[key];
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function targetOf(api: CapabilityAPI): ShareTarget | undefined {
+	const target = configString(api, "target");
+	return target === "radius" || target === "gist" ? target : undefined;
+}
+
+function defaultProcess(argv: readonly string[], input: Uint8Array, signal: AbortSignal): Promise<ShareProcessResult> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(argv[0] ?? "", argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const finish = (result: ShareProcessResult): void => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+		const onAbort = (): void => {
+			if (!settled) child.kill("SIGTERM");
+		};
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", reject);
+		child.once("close", (code) => finish({ code, stdout, stderr }));
+		signal.addEventListener("abort", onAbort, { once: true });
+		if (signal.aborted) onAbort();
+		child.stdin.end(input);
+	});
+}
+
+function error(message: string): CapabilityCommandResult {
+	return { status: "error", message };
+}
+
+function success(message: string, url: string, label: string): CapabilityCommandResult {
+	return { status: "success", message, links: [{ label, url }] };
+}
+
+async function shareViaRadius(
+	api: CapabilityAPI,
+	artifact: SessionExportArtifact,
+	context: CapabilityCommandContext,
+	fetchImpl: typeof globalThis.fetch,
+): Promise<CapabilityCommandResult> {
+	const gateway = configString(api, "gateway");
+	if (!gateway) return error("Session share target radius requires config.gateway");
+	if (!api.credentials) return error("Session share target radius requires the credentials capability");
+	const credential = await api.credentials.resolve({
+		providerId: configString(api, "credentialProvider") ?? "radius",
+		minValidityMs: 300_000,
+		signal: context.signal,
+	});
+	if (!credential?.apiKey) return error("No credential is available for the configured Radius provider");
+	const url = new URL("/v1/artifacts", gateway);
+	url.searchParams.set("visibility", "organization");
+	url.searchParams.set("title", "Agent Forge session");
+	const response = await fetchImpl(url, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${credential.apiKey}`,
+			"Content-Type": artifact.mediaType,
+			"Content-Length": String(artifact.bytes.byteLength),
+			...credential.headers,
+		},
+		body: artifact.bytes,
+		signal: context.signal,
+	});
+	const body = (await response.json().catch(() => null)) as {
+		artifact?: { canonical_url?: string };
+		error?: string;
+	} | null;
+	if (!response.ok || !body?.artifact?.canonical_url) {
+		return error(`Failed to upload Radius artifact: ${body?.error ?? response.statusText ?? response.status}`);
+	}
+	return success("Session shared through Radius", body.artifact.canonical_url, "Radius");
+}
+
+async function shareViaGist(
+	api: CapabilityAPI,
+	artifact: SessionExportArtifact,
+	context: CapabilityCommandContext,
+	processImpl: ShareProcess,
+): Promise<CapabilityCommandResult> {
+	const viewerUrl = configString(api, "viewerUrl");
+	if (!viewerUrl) return error("Session share target gist requires config.viewerUrl");
+	const auth = await processImpl(["gh", "auth", "status"], new Uint8Array(), context.signal);
+	if (auth.code !== 0) return error(`GitHub CLI is not logged in: ${auth.stderr.trim() || "run gh auth login first"}`);
+	const result = await processImpl(["gh", "gist", "create", "--public=false", "-"], artifact.bytes, context.signal);
+	if (result.code !== 0) return error(`Failed to create gist: ${result.stderr.trim() || "unknown error"}`);
+	const gistUrl = result.stdout.trim();
+	const gistId = gistUrl.split("/").pop();
+	if (!gistId) return error("Failed to parse gist ID from gh output");
+	const preview = new URL(viewerUrl);
+	preview.hash = gistId;
+	return {
+		status: "success",
+		message: "Session shared through GitHub gist",
+		links: [
+			{ label: "Viewer", url: preview.toString() },
+			{ label: "Gist", url: gistUrl },
+		],
+	};
+}
+
+export function createSessionSharePlugin(
+	api: CapabilityAPI,
+	options: SessionSharePluginOptions = {},
+): SessionSharePluginHandle {
+	const command = api.registerCommand({
+		name: "share",
+		description: "Share the current session using the explicitly configured target",
+		execute: async (_args, context) => {
+			const target = targetOf(api);
+			if (!target) return error("Configure plugin target as 'radius' or 'gist' before using /share");
+			if (!api.session?.exportArtifact) return error("Session export capability is unavailable");
+			api.session.appendEntry("agent-forge.share", { target, version: 1 });
+			const artifact = api.session.exportArtifact({ format: "jsonl" });
+			return target === "radius"
+				? shareViaRadius(api, artifact, context, options.fetch ?? globalThis.fetch)
+				: shareViaGist(api, artifact, context, options.process ?? defaultProcess);
+		},
+	});
+	return { command, dispose: () => command.dispose() };
+}
+
+export default function sessionShareExample(api: CapabilityAPI): SessionSharePluginHandle {
+	return createSessionSharePlugin(api);
+}

package/examples/extensions/session-share/plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "agent-forge.example.session-share",
+  "version": "0.1.0",
+  "hostVersion": ">=0.84.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": [
+    "session",
+    "session-export",
+    "commands"
+  ],
+  "optionalCapabilities": [
+    "credentials"
+  ]
+}

package/examples/extensions/structured-output/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Structured Output Tool (capability plugin form)
+ *
+ * Demonstrates `terminate: true` so the agent can end on a tool call
+ * without paying for an extra follow-up LLM turn.
+ *
+ * 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 { Text } from "@agent-forge/tui";
+import { Type } from "typebox";
+
+interface StructuredOutputDetails {
+	headline: string;
+	summary: string;
+	actionItems: string[];
+}
+
+const structuredOutputTool = defineTool({
+	name: "structured_output",
+	label: "Structured Output",
+	description:
+		"Return a final structured answer. Use this as your last action when the user asks for structured output or a machine-readable summary.",
+	promptSnippet: "Emit a final structured answer as a terminating tool result",
+	promptGuidelines: [
+		"Use structured_output as your final action when the user asks for structured output, JSON-like output, or a machine-readable summary.",
+		"After calling structured_output, do not emit another assistant response in the same turn.",
+	],
+	parameters: Type.Object({
+		headline: Type.String({ description: "Short title for the result" }),
+		summary: Type.String({ description: "One-paragraph summary" }),
+		actionItems: Type.Array(Type.String(), { description: "Concrete next steps or key bullets" }),
+	}),
+
+	async execute(_toolCallId, params) {
+		return {
+			content: [{ type: "text", text: `Saved structured output: ${params.headline}` }],
+			details: {
+				headline: params.headline,
+				summary: params.summary,
+				actionItems: params.actionItems,
+			} satisfies StructuredOutputDetails,
+			terminate: true,
+		};
+	},
+
+	renderResult(result, _options, theme) {
+		const details = result.details as StructuredOutputDetails | undefined;
+		if (!details) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "", 0, 0);
+		}
+
+		const lines = [
+			theme.fg("toolTitle", theme.bold(details.headline)),
+			theme.fg("text", details.summary),
+			"",
+			...details.actionItems.map((item, index) => theme.fg("muted", `${index + 1}. ${item}`)),
+		];
+		return new Text(lines.join("\n"), 0, 0);
+	},
+});
+
+export default function structuredOutputExample(api: CapabilityAPI): void {
+	api.registerTool(structuredOutputTool);
+}

package/examples/extensions/structured-output/plugin.json

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

package/examples/extensions/subagent/README.md

@@ -0,0 +1,177 @@
+# Subagent Example
+
+Delegate tasks to specialized subagents with isolated context windows.
+
+## Features
+
+- **Isolated context**: Each subagent runs in a separate `agent-forge` process
+- **Streaming output**: See tool calls and progress as they happen
+- **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
+- **Abort support**: Ctrl+C propagates to kill subagent processes
+
+## Structure
+
+```
+subagent/
+├── README.md            # This file
+├── index.ts             # The extension (entry point)
+├── agents.ts            # Agent discovery logic
+├── agents/              # Sample agent definitions
+│   ├── scout.md         # Fast recon, returns compressed context
+│   ├── planner.md       # Creates implementation plans
+│   ├── reviewer.md      # Code review
+│   └── worker.md        # General-purpose (full capabilities)
+└── prompts/             # Workflow presets (prompt templates)
+    ├── implement.md     # scout -> planner -> worker
+    ├── scout-and-plan.md    # scout -> planner (no implementation)
+    └── implement-and-review.md  # worker -> reviewer -> worker
+```
+
+## Installation
+
+From the repository root, symlink the files:
+
+```bash
+# Symlink the extension (must be in a subdirectory with index.ts)
+mkdir -p ~/.agent-forge/agent/extensions/subagent
+ln -sf "$(pwd)/packages/agent-forge/examples/extensions/subagent/index.ts" ~/.agent-forge/agent/extensions/subagent/index.ts
+ln -sf "$(pwd)/packages/agent-forge/examples/extensions/subagent/agents.ts" ~/.agent-forge/agent/extensions/subagent/agents.ts
+
+# Symlink agents
+mkdir -p ~/.agent-forge/agent/agents
+for f in packages/agent-forge/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$(pwd)/$f" ~/.agent-forge/agent/agents/$(basename "$f")
+done
+
+# Symlink workflow prompts
+mkdir -p ~/.agent-forge/agent/prompts
+for f in packages/agent-forge/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$(pwd)/$f" ~/.agent-forge/agent/prompts/$(basename "$f")
+done
+```
+
+## Security Model
+
+This tool executes a separate `agent-forge` subprocess with a delegated system prompt and tool/model configuration.
+
+**Project-local agents** (`.agent-forge/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
+
+**Default behavior:** Only loads **user-level agents** from `~/.agent-forge/agent/agents`.
+
+To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+
+When running interactively, the tool prompts for confirmation before running project-local agents in untrusted projects. Trusted projects skip the additional prompt. Set `confirmProjectAgents: false` to disable confirmation.
+
+## Usage
+
+### Single agent
+```
+Use scout to find all authentication code
+```
+
+### Parallel execution
+```
+Run 2 scouts in parallel: one to find models, one to find providers
+```
+
+### Chained workflow
+```
+Use a chain: first have scout find the read tool, then have planner suggest improvements
+```
+
+### Workflow prompts
+```
+/implement add Redis caching to the session store
+/scout-and-plan refactor auth to support OAuth
+/implement-and-review add input validation to API endpoints
+```
+
+## Tool Modes
+
+| Mode | Parameter | Description |
+|------|-----------|-------------|
+| Single | `{ agent, task }` | One agent, one task |
+| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
+| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
+
+## Output Display
+
+**Collapsed view** (default):
+- Status icon (✓/✗/⏳) and agent name
+- Last 5-10 items (tool calls and text)
+- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
+
+**Expanded view** (Ctrl+O):
+- Full task text
+- All tool calls with formatted arguments
+- Final output rendered as Markdown
+- Per-task usage (for chain/parallel)
+
+**Parallel mode streaming**:
+- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
+- Updates as each task makes progress
+- Shows "2/3 done, 1 running" status
+- Returns each completed task's final output to the parent model, capped at 50 KB per task
+- Returns failure diagnostics from stderr/error messages when a child exits before producing output
+
+**Tool call formatting** (mimics built-in tools):
+- `$ command` for bash
+- `read ~/path:1-10` for read
+- `grep /pattern/ in ~/path` for grep
+- etc.
+
+## Agent Definitions
+
+Agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+System prompt for the agent goes here.
+```
+
+When `model` is omitted, the subagent inherits the dispatching session's active model and thinking level.
+
+**Locations:**
+- `~/.agent-forge/agent/agents/*.md` - User-level (always loaded)
+- `.agent-forge/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Sample Agents
+
+| Agent | Purpose | Model | Tools |
+|-------|---------|-------|-------|
+| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
+| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
+| `worker` | General-purpose | Sonnet | (all default) |
+
+## Workflow Prompts
+
+| Prompt | Flow |
+|--------|------|
+| `/implement <query>` | scout → planner → worker |
+| `/scout-and-plan <query>` | scout → planner |
+| `/implement-and-review <query>` | worker → reviewer → worker |
+
+## Error Handling
+
+- **Exit code != 0**: Tool returns error with stderr/output
+- **stopReason "error"**: LLM error propagated with error message
+- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
+- **Chain mode**: Stops at first failing step, reports which step failed
+
+## Limitations
+
+- Output truncated to last 10 items in collapsed view (expand to see all)
+- Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent

package/examples/extensions/subagent/agents/planner.md

@@ -0,0 +1,37 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.