@ai-agent-forge/agent-forge 0.85.0

package/docs/usage.md

@@ -0,0 +1,291 @@
+# Using Agent Forge
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and themes
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, and errors
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or `/model`.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Capability plugins can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
+| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Theme, message delivery, transport, and other preferences |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML or JSONL |
+| `/import <file>` | Import and resume a session from a JSONL file |
+| `/share` | 由显式安装的 session-share 插件提供；核心不内置 |
+| `/reload` | Reload keybindings, skills, prompts, themes, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit Agent Forge |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want Agent Forge to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.agent-forge/agent/sessions/`, organized by working directory.
+
+```bash
+agent-forge -c                  # Continue most recent session
+agent-forge -r                  # Browse and select a session
+agent-forge --no-session        # Ephemeral mode; do not save
+agent-forge --name "my task"    # Set session display name at startup
+agent-forge --session <path|id> # Use a specific session file or session ID
+agent-forge --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Agent Forge loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.agent-forge/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+If a directory contains `AGENTS.override.md`, Agent Forge loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.agent-forge/SYSTEM.md` for a project
+- `~/.agent-forge/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Install and configure the optional `session-share` plugin before using `/share`; the core does not provide a built-in sharing transport.
+
+If you publish sessions for model, prompt, tool, or evaluation research, choose a destination and publication workflow that match your own privacy requirements.
+
+## CLI Reference
+
+```bash
+agent-forge [options] [--] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+agent-forge install <source> [-l]     # Install package, -l for project-local
+agent-forge remove <source> [-l]      # Remove package
+agent-forge uninstall <source> [-l]   # Alias for remove
+agent-forge update [source|self|agent-forge] # Update Agent Forge or one package source
+agent-forge update --all              # Update Agent Forge and packages; reconcile pinned git refs
+agent-forge update --packages        # Update packages only; reconcile pinned git refs
+agent-forge update --models           # Refresh model catalogs only
+agent-forge update --self             # Update Agent Forge only
+agent-forge update --package <src>   # Update one package
+agent-forge list                      # List installed packages
+agent-forge config                    # Enable/disable package resources
+```
+
+These commands manage legacy packages. New capability plugins are discovered through `plugin.json`; see [Plugins](packages.md). To uninstall Agent Forge itself, see [Quickstart](quickstart.md#uninstall).
+
+See [Plugins](packages.md) for plugin sources and execution notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, Agent Forge also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | agent-forge -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, plugin, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, plugin, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep plugin/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+agent-forge --no-skills --no-prompt-templates
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
+| `--verbose` | Force verbose startup |
+| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, Agent Forge uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
+
+Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+agent-forge @prompt.md "Answer this"
+agent-forge -p @screenshot.png "What's in this image?"
+agent-forge @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+agent-forge "List all .ts files in src/"
+
+# Non-interactive
+agent-forge -p "Summarize this codebase"
+
+# Prompt beginning with a dash
+agent-forge -p -- "- Summarize these points"
+
+# Non-interactive with piped stdin
+cat README.md | agent-forge -p "Summarize this text"
+
+# Named one-shot session
+agent-forge --name "release audit" -p "Audit this repository"
+
+# Different model
+agent-forge --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+agent-forge --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+agent-forge --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+agent-forge --models "claude-*,gpt-4o"
+
+# Read-only mode
+agent-forge --tools read,grep,find,ls -p "Review the code"
+
+# Disable one plugin or built-in tool while keeping the rest available
+agent-forge --exclude-tools ask_question
+```
+
+## Design Principles
+
+Agent Forge keeps the core small and pushes workflow-specific behavior into plugins, Skills, prompt templates, and external tools.
+
+It intentionally does not include MCP, multi-Agent workflows, approval policy, Plan mode, to-dos, or background bash as core business branches. Add them through plugins or use external tools such as containers and tmux.
+
+For the architectural rationale, see the repository [核心架构宪法](../../../docs/核心架构宪法.md).

package/docs/windows.md

@@ -0,0 +1,39 @@
+# Windows Setup
+
+Pi uses Git Bash by default on Windows. Checked locations (in order):
+
+1. Custom path from `~/.agent-forge/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## PowerShell Tool
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+Use `defaultTools` to replace the model-facing `bash` tool:
+
+```json
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
+Or enable both while comparing behavior:
+
+```json
+{
+  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+}
+```
+
+The `!` and `!!` editor commands still use Bash.
+
+## Custom Bash Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```

package/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+Example code for the Agent Forge coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createStableAgentSession()` (the stable facade entry; session-level examples). Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Capability plugin examples (`plugin.json` manifest + `CapabilityAPI` entry) demonstrating:
+- Custom tools (minimal tools, output truncation, built-in tool overrides, subagents, agent-task dispatch)
+- Lifecycle observation and transforms (tool interception and safety gates, system prompt and resource contributions)
+- Commands and session surfaces (bookmarks, session names, user messages, suites, notifications)
+- External integrations (MCP stdio bridge, CLI bridge, trigger files, provider attribution, session sharing)
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Plugins Documentation](../docs/packages.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -0,0 +1,163 @@
+# Extension Examples
+
+Capability plugin examples for `@agent-forge/agent-forge`. Every example in this
+directory is a directory plugin: a `plugin.json` manifest plus an entry module
+that exports `default function (api: CapabilityAPI)`.
+
+## Usage
+
+A capability plugin is discovered from `plugin.json` under
+`~/.agent-forge/agent/plugins/` or `<cwd>/.agent-forge/plugins/`. Copy the whole
+directory (manifest and entry together):
+
+```bash
+cp -r hello ~/.agent-forge/agent/plugins/
+```
+
+An example that carries its own npm dependencies (`with-deps/`) needs
+`npm install` in the example directory before it is installed.
+
+See [docs/packages.md](../../docs/packages.md) for manifest fields, plugin
+discovery, lifecycle events and transforms, and package structure.
+
+## Manifest
+
+```json
+{
+  "id": "agent-forge.example.hello",
+  "version": "0.1.0",
+  "apiVersion": "1-draft",
+  "entry": "./index.ts",
+  "requiredCapabilities": ["tools"]
+}
+```
+
+`id`, `version`, `apiVersion`, and `entry` are required strings. `requiredCapabilities`
+and `optionalCapabilities` name the host capabilities the plugin needs; the host
+refuses a manifest whose required capabilities it cannot offer.
+
+## Examples
+
+### Tools
+
+| Example | Description |
+|-----------|-------------|
+| `hello/` | Minimal custom tool example |
+| `structured-output/` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
+| `truncated-tool/` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
+| `tool-override/` | Override built-in tools (e.g. add logging or access control to `read`) |
+| `dynamic-tools/` | Register tools at load and at runtime via a command, with prompt snippets |
+| `kimi-deferred-tools/` | Search for and progressively activate tools for Kimi's deferred-tool loading protocol |
+| `bash-spawn-hook/` | Adjust bash command, cwd, and env before execution |
+| `built-in-tool-renderer/` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
+| `minimal-mode/` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+| `multi-agent/` | `agent.dispatch` / `agent.status` / `agent.wait` / `agent.cancel` over the host agent-task API |
+| `with-deps/` | Plugin with its own npm dependencies resolved through the capability loader (run `npm install` first) |
+
+### Lifecycle & Safety
+
+| Example | Description |
+|-----------|-------------|
+| `permission-gate/` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, 777) via `registerLoopHook("beforeToolCall")` + `interaction.request` |
+| `protected-paths/` | Blocks write and edit operations to protected paths (.env, .git/, node_modules/) via `registerLoopHook("beforeToolCall")` |
+
+### Commands & Session UI
+
+| Example | Description |
+|-----------|-------------|
+| `bookmark/` | Bookmark entries with labels for `/tree` navigation via `SessionAPI.setLabel`/`getLabel` |
+| `session-name/` | Name sessions for the session selector via `SessionAPI.setSessionName` |
+| `send-user-message/` | The `SessionAPI` user-message surface (`prompt`, `steer`, `queueFollowUp`) |
+| `timed-confirm/` | `InteractionAPI.request` with `timeoutMs` and AbortSignal for auto-dismissing confirm/select dialogs |
+| `suite-manager/` | Suite (方案) lifecycle commands: list, create, delete, reset — destructive ones confirmed through `InteractionAPI.request` |
+| `notify/` | Desktop notifications via OSC 777 when the agent settles (Ghostty, iTerm2, WezTerm) |
+| `file-trigger/` | Watches a trigger file and injects its contents as a custom message via `SessionAPI.sendMessage` with `triggerTurn` |
+| `event-bus/` | Inter-plugin communication via `api.publish` / `api.subscribe` |
+| `goal/` | Goal records (`goal_set`) with branch-local state and change events |
+| `plan/` | Plan records (`plan_set`) with a soft goal reference, branch-local state, and change events |
+| `todo-set/` | Todo items (`todo_update`) with a soft plan reference, branch-local state, and change events |
+
+### System Prompt & Context
+
+| Example | Description |
+|-----------|-------------|
+| `pirate/` | Toggle that appends a pirate appendix to the system prompt via `lifecycle.registerTransform("before.agent.start")` |
+| `claude-rules/` | Scans `.claude/rules/` and lists rules in the system prompt |
+| `prompt-customizer/` | Context-aware tool guidance from `systemPromptOptions` via `before.agent.start` |
+| `trigger-compact/` | Auto-compacts once context usage crosses 100k tokens, plus a `/trigger-compact` command |
+| `dynamic-resources/` | Contributes a skill, a prompt template, and a theme via `resources.discover`@2 |
+
+### Integration & Sharing
+
+| Example | Description |
+|-----|-------------|
+| `cli-bridge/` | Declarative CLI command definitions adapted to tools; the host keeps mode and policy ownership |
+| `mcp-stdio/` | MCP-like JSON-RPC 2.0 stdio bridge; the manifest entry is a template that must be configured before installing |
+| `provider-attribution/` | Provider header transformations (OpenRouter, NVIDIA NIM, Cloudflare AI Gateway) |
+| `session-share/` | Explicitly installed share plugin (`/share` to `radius` or `gist`); the first-party implementation ships as the built-in `agent-forge.builtin.session-share` capability |
+
+## Writing a Plugin
+
+A plugin directory holds `plugin.json` and an entry module. The entry exports a
+default factory that receives the `CapabilityAPI`:
+
+```typescript
+import { Type } from "@agent-forge/ai";
+import { type CapabilityAPI, defineTool } from "@agent-forge/agent-forge";
+
+const helloTool = defineTool({
+  name: "hello",
+  label: "Hello",
+  description: "A simple greeting tool",
+  parameters: Type.Object({
+    name: Type.String({ description: "Name to greet" }),
+  }),
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: `Hello, ${params.name}!` }],
+      details: { greeted: params.name },
+    };
+  },
+});
+
+export default function myPlugin(api: CapabilityAPI): void {
+  api.registerTool(helloTool);
+}
+```
+
+Registering a tool, a command, a loop hook, a lifecycle observer or transform,
+or a provider header transform returns a `DisposableRegistration`; dispose it to
+withdraw the registration.
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+
+```typescript
+import { StringEnum } from "@agent-forge/ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**Branch-local state**: append a custom entry and rebuild state from the branch,
+so forking and compaction keep working:
+
+```typescript
+const STATE_ENTRY = "my-plugin.state";
+
+function loadState(api: CapabilityAPI): MyState {
+  const entries = api.session?.getBranchEntries() ?? [];
+  const entry = [...entries].reverse().find((item) => item.customType === STATE_ENTRY);
+  return entry?.data && typeof entry.data === "object" ? (entry.data as MyState) : { items: [] };
+}
+
+api.session?.appendEntry(STATE_ENTRY, nextState);
+```
+
+See `todo-set/`, `plan/`, and `goal/` for complete examples, and
+[`../sdk/README.md`](../sdk/README.md) for programmatic session usage.

package/examples/extensions/bash-spawn-hook/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Bash Spawn Hook Example
+ *
+ * Adjusts command, cwd, and env before execution.
+ *
+ * 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):
+ * the same-name bash override rides the capability replacement contract
+ * (last load wins, restore on dispose).
+ */
+
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+import { createBashTool, defineTool } from "@agent-forge/agent-forge";
+
+export default function (api: CapabilityAPI) {
+	const cwd = process.cwd();
+
+	const bashTool = createBashTool(cwd, {
+		spawnHook: ({ command, cwd, env }) => ({
+			command: `source ~/.profile\n${command}`,
+			cwd,
+			env: { ...env, PI_SPAWN_HOOK: "1" },
+		}),
+	});
+
+	api.registerTool(
+		defineTool({
+			...bashTool,
+			execute: async (id, params, signal, onUpdate, _ctx) => {
+				return bashTool.execute(id, params, signal, onUpdate);
+			},
+		}),
+	);
+}

package/examples/extensions/bash-spawn-hook/plugin.json

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

package/examples/extensions/bookmark/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Entry bookmarking example (capability plugin form).
+ *
+ * Shows setLabel to mark entries with labels for easy navigation in /tree.
+ * Labels appear in the tree view and help you find important points.
+ *
+ * Usage: /bookmark [label] - bookmark the last assistant message
+ *
+ * Install: 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 session-surface batch, 2026-09-21):
+ * `pi.registerCommand` maps to `api.registerCommand`, the `ctx.sessionManager.getEntries`
+ * read maps to `SessionAPI.getBranchEntries` (the current branch, whose view now carries
+ * the `message` role projection the example filters on), `ctx.sessionManager.getLabel` to
+ * `SessionAPI.getLabel?`, `pi.setLabel` to `SessionAPI.setLabel?`, and the `ctx.ui.notify`
+ * texts to the `CapabilityCommandResult` message the host renders (same words as before).
+ */
+
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+
+export default function bookmarkExample(api: CapabilityAPI): void {
+	api.registerCommand({
+		name: "bookmark",
+		description: "Bookmark last message (usage: /bookmark [label])",
+		execute: (args) => {
+			const label = args.trim() || `bookmark-${Date.now()}`;
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			// Find the last assistant message entry on the current branch. The entry
+			// view carries the role projection (`SessionEntryView.message`), so the
+			// legacy `entry.message.role === "assistant"` filter has the same read.
+			const entries = session.getBranchEntries();
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i];
+				if (entry.type === "message" && entry.message?.role === "assistant") {
+					session.setLabel?.(entry.id, label);
+					return { status: "success", message: `Bookmarked as: ${label}` };
+				}
+			}
+
+			return { status: "error", message: "No assistant message to bookmark" };
+		},
+	});
+
+	// Remove bookmark
+	api.registerCommand({
+		name: "unbookmark",
+		description: "Remove bookmark from last labeled entry",
+		execute: () => {
+			const session = api.session;
+			if (!session) return { status: "error", message: "Session capability is unavailable" };
+
+			const entries = session.getBranchEntries();
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i];
+				const label = session.getLabel?.(entry.id);
+				if (label) {
+					session.setLabel?.(entry.id, undefined);
+					return { status: "success", message: `Removed bookmark: ${label}` };
+				}
+			}
+			return { status: "error", message: "No bookmarked entry found" };
+		},
+	});
+}

package/examples/extensions/bookmark/plugin.json

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