@ai-agent-forge/agent-forge 0.87.0 → 0.88.1

package/docs/mcp.md

@@ -0,0 +1,103 @@
+> Agent Forge has no core MCP. MCP servers are configured, not compiled in; each one becomes a generated capability plugin.
+
+# MCP
+
+Agent Forge connects to [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers through configuration. Each configured server is materialized at session start as a generated capability plugin with a validated `plugin.json` manifest, loaded through the same path as any third-party plugin, and every remote tool is registered on the same tool surface as built-in tools.
+
+## Table of Contents
+
+- [Configuration Files](#configuration-files)
+- [Server Entries](#server-entries)
+- [stdio Servers](#stdio-servers)
+- [Remote HTTP Servers](#remote-http-servers)
+- [How Tools Load](#how-tools-load)
+- [Diagnostics](#diagnostics)
+
+## Configuration Files
+
+MCP servers come from two `mcp.json` files.
+
+| Level | Path | Injection |
+| --- | --- | --- |
+| Project | `<cwd>/.agent-forge/mcp.json` | Always injected; project definitions win name collisions over user definitions. |
+| User | `~/.agent-forge/agent/mcp.json` (the agent dir, overridable with `AGENT_FORGE_DIR`) | Injected only when the active suite's `associations.mcp` lists the server name. The factory suites ship with an empty `associations.mcp`, so user-level servers are not injected until a suite associates them — the same two-pool semantics as Skills. |
+
+To associate a user-level server, add its name to `associations.mcp` in the active suite's `suite.json` (below `<agentDir>/suites/<id>/`). Built-in suites keep their on-disk file until `--suite-reset` restores factory contents; suites created with `--suite-create` own theirs.
+
+Both files use the same shape:
+
+```json
+{
+  "mcpServers": {
+    "<name>": { }
+  }
+}
+```
+
+Configuration is read at session startup: the pool is re-materialized on every session, so restart the session to pick up changes. Generated pool files live under `<agentDir>/mcp/pool/` — do not edit them by hand.
+
+## Server Entries
+
+Each entry under `mcpServers` is one server. `<name>` is the associations key, the pool directory name, and the generated plugin id (`agent-forge.mcp.<name>`); it must match `^[A-Za-z0-9][A-Za-z0-9._-]*$`.
+
+An entry carries exactly one of `command` (stdio server) and `url` (remote HTTP server), never both:
+
+| Field | Type | Applies to | Meaning |
+| --- | --- | --- | --- |
+| `command` | non-empty string | stdio | The executable to launch. |
+| `args` | string array | stdio | Arguments passed to the command. |
+| `url` | non-empty string | HTTP | The server endpoint; only `http://` and `https://` are accepted. |
+| `headers` | object of non-empty strings | HTTP | Extra request headers sent verbatim on every request (for example `Authorization: Bearer ...`). On a stdio entry `headers` is ignored with a diagnostic. |
+| `deferredTools` | boolean | both | Keep the server's tools out of the default active set; the built-in `tool_search` tool activates them on demand. |
+
+## stdio Servers
+
+A stdio server is a local process speaking JSON-RPC over stdin/stdout. Example — the reference filesystem server:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    }
+  }
+}
+```
+
+On Windows, a bare command name (no path separator) is resolved against `PATH` with `.cmd`/`.bat` shim probing, so `npx` and other npm-installed servers work without spelling out `cmd.exe`. An explicit `.cmd`/`.bat` suffix is wrapped the same way; `.exe`/`.com` executables and non-Windows platforms launch directly.
+
+## Remote HTTP Servers
+
+A remote server is reached over HTTP: each JSON-RPC request is one POST and the transport reads a single JSON response body, so the server must answer with `application/json` — responses delivered only as an SSE stream (`text/event-stream`) are not consumed. Example:
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+Header values are sent verbatim: there is no environment-variable expansion and no shell interpolation, so put the literal value in the file. A token in `mcp.json` is copied into the generated plugin below `<agentDir>/mcp/pool/`, which sits in the same local-machine data boundary as `auth.json`. Treat the file as a credential store.
+
+Transient HTTP failures are retried with backoff only when the server could not have started the request (connection errors, 5xx, 429); a completed JSON-RPC response is never re-sent.
+
+## How Tools Load
+
+At session startup the generated plugin performs the MCP handshake (`initialize`, `notifications/initialized`, `tools/list`) and registers one tool per remote tool with its name, description, and input schema. Tool calls are forwarded through `tools/call` and their results mapped back to the session. The current integration surface is tools; resources and prompts are not consumed by the host.
+
+The server's tools behave like any other tool: they flow through the same loop hooks (a `beforeToolCall` gate plugin sees them), and they can be deferred with `deferredTools` when a server exposes many tools.
+
+## Diagnostics
+
+MCP configuration never fails a session. Problems are reported as startup diagnostics and the affected server is skipped:
+
+- A malformed or unreadable `mcp.json`, or an invalid entry (both `command` and `url`, neither, a bad `args`/`headers`/`deferredTools` shape, a non-http(s) URL), is ignored with a diagnostic naming the file.
+- A user-level server not listed in the active suite's `associations.mcp` is skipped with a diagnostic.
+- An `associations.mcp` name with no matching server is reported as a dangling association.
+- A project definition overriding a user definition of the same name is reported.
+- A server that fails to load (bad launch command, unreachable endpoint) surfaces as a plugin load failure for `agent-forge.mcp.<name>`; the rest of the session continues.

package/docs/models.md

@@ -24,7 +24,6 @@ For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
     "ollama": {
       "baseUrl": "http://localhost:11434/v1",
       "api": "openai-completions",
-      "apiKey": "ollama",
       "models": [
         { "id": "llama3.1:8b" },
         { "id": "qwen2.5-coder:7b" }
@@ -34,7 +33,7 @@ For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
 }
 ```
 
-The `apiKey` value is a placeholder because Ollama ignores it. pi still treats models as requiring auth before they appear in `/model`, so keyless local servers should keep a dummy value, save a key for that provider with `/login`, or pass `--api-key` when selecting the model.
+pi still requires a provider to have credentials before its models appear in `/model`. Keyless local servers such as Ollama (which ignores the key entirely) need any placeholder key saved for the provider with `/login` (for example `ollama`) or `--api-key` at startup for the models to become available.
 
 Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so pi sends the system prompt as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too.
 
@@ -46,7 +45,6 @@ You can set `compat` at the provider level to apply to all models, or at the mod
     "ollama": {
       "baseUrl": "http://localhost:11434/v1",
       "api": "openai-completions",
-      "apiKey": "ollama",
       "compat": {
         "supportsDeveloperRole": false,
         "supportsReasoningEffort": false
@@ -72,7 +70,6 @@ Override defaults when you need specific values:
     "ollama": {
       "baseUrl": "http://localhost:11434/v1",
       "api": "openai-completions",
-      "apiKey": "ollama",
       "models": [
         {
           "id": "llama3.1:8b",
@@ -101,7 +98,6 @@ Use `google-generative-ai` with a `baseUrl` to add models from Google AI Studio,
     "my-google": {
       "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
       "api": "google-generative-ai",
-      "apiKey": "$GEMINI_API_KEY",
       "models": [
         {
           "id": "gemma-4-31b-it",
@@ -135,41 +131,42 @@ Set `api` at provider level (default for all models) or model level (override pe
 |-------|-------------|
 | `baseUrl` | API endpoint URL |
 | `api` | API type (see above) |
-| `apiKey` | Optional API key config (see value resolution below). Omit it when auth is provided by `/login`/`auth.json` or CLI `--api-key`. |
 | `oauth` | Dynamic OAuth provider type. Currently supports `"radius"`; requires the gateway `baseUrl`. |
 | `headers` | Custom headers (see value resolution below) |
-| `authHeader` | Set `true` to add `Authorization: Bearer <apiKey>` automatically |
+| `authHeader` | Set `true` to add `Authorization: Bearer <resolved API key>` automatically |
 | `models` | Array of model configurations |
 | `modelOverrides` | Per-model overrides for built-in or models.json-declared models on this provider |
 
-For providers with `models`, non-built-in provider configs need `baseUrl` and an `api` value at either provider or model level. `apiKey` is not required to load the file: models become available when auth is configured through `/login`/`auth.json`, CLI `--api-key`, or provider `apiKey`. If no auth is configured, the models load but stay unavailable in `/model` and `--list-models`.
+For providers with `models`, non-built-in provider configs need `baseUrl` and an `api` value at either provider or model level. models.json cannot hold keys: auth is configured through `/login` (stored in `auth.json`) or CLI `--api-key`, and a models.json containing an `apiKey` field is rejected at load with guidance to store the key in `auth.json`. The `key` field in `auth.json` supports the same value syntax as headers below (literal, `$ENV_VAR`, `!command`). If no auth is configured, the models load but stay unavailable in `/model` and `--list-models`.
 
 ### Value Resolution
 
-The `apiKey` and `headers` fields support command execution, environment interpolation, and literals:
+Header values in models.json (`headers`) and the `key` field of an `auth.json` credential share one value syntax: command execution, environment interpolation, and literals:
 
 - **Shell command:** `"!command"` at the start executes the whole value as a command and uses stdout
   ```json
-  "apiKey": "!security find-generic-password -ws 'anthropic'"
-  "apiKey": "!op read 'op://vault/item/credential'"
+  "key": "!security find-generic-password -ws 'anthropic'"
+  "x-secret": "!op read 'op://vault/item/secret'"
   ```
 - **Environment interpolation:** `"$ENV_VAR"` or `"${ENV_VAR}"` uses the value of the named variable. Interpolation works inside larger literals.
   ```json
-  "apiKey": "$MY_API_KEY"
-  "apiKey": "${KEY_PREFIX}_${KEY_SUFFIX}"
+  "key": "$MY_API_KEY"
+  "x-key": "${KEY_PREFIX}_${KEY_SUFFIX}"
   ```
   `$FOO_BAR` is the variable `FOO_BAR`; use `${FOO}_BAR` when `BAR` is literal text. Missing environment variables make the value unresolved.
 - **Escapes:** `"$$"` emits a literal `"$"`; `"$!"` emits a literal `"!"` without triggering command execution.
   ```json
-  "apiKey": "$$literal-dollar-prefix"
-  "apiKey": "$!literal-bang-prefix"
+  "key": "$$literal-dollar-prefix"
+  "x-secret": "$!literal-bang-prefix"
   ```
 - **Literal value:** Used directly. Plain uppercase strings such as `MY_API_KEY` are literals; use `$MY_API_KEY` for environment variables.
   ```json
-  "apiKey": "sk-..."
+  "key": "sk-..."
   ```
 
-For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
+Command values in models.json `headers` are resolved on every request. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
+
+A command in an `auth.json` credential `key` is resolved when the credential is first read and reused for the process lifetime (failures included); restart the host to pick up a changed value.
 
 If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
 
@@ -182,7 +179,6 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
   "providers": {
     "custom-proxy": {
       "baseUrl": "https://proxy.example.com/v1",
-      "apiKey": "$MY_API_KEY",
       "api": "anthropic-messages",
       "headers": {
         "x-portkey-api-key": "$PORTKEY_API_KEY",
@@ -324,7 +320,6 @@ To merge custom models into a built-in provider, include the `models` array:
   "providers": {
     "anthropic": {
       "baseUrl": "https://my-proxy.example.com/v1",
-      "apiKey": "$ANTHROPIC_API_KEY",
       "api": "anthropic-messages",
       "models": [...]
     }
@@ -408,7 +403,6 @@ Built-in Anthropic models enable `supportsStrictTools` in their model metadata.
     "anthropic-proxy": {
       "baseUrl": "https://proxy.example.com",
       "api": "anthropic-messages",
-      "apiKey": "$ANTHROPIC_PROXY_KEY",
       "compat": {
         "supportsEagerToolInputStreaming": false,
         "supportsLongCacheRetention": true,
@@ -501,7 +495,6 @@ Example:
   "providers": {
     "openrouter": {
       "baseUrl": "https://openrouter.ai/api/v1",
-      "apiKey": "$OPENROUTER_API_KEY",
       "api": "openai-completions",
       "models": [
         {
@@ -551,7 +544,6 @@ Vercel AI Gateway example:
   "providers": {
     "vercel-ai-gateway": {
       "baseUrl": "https://ai-gateway.vercel.sh/v1",
-      "apiKey": "$AI_GATEWAY_API_KEY",
       "api": "openai-completions",
       "models": [
         {

package/docs/providers.md

@@ -314,4 +314,3 @@ When resolving credentials for a provider:
 1. CLI `--api-key` flag
 2. `auth.json` entry (API key or OAuth token)
 3. Environment variable
-4. Custom provider keys from `models.json`

package/docs/rpc.md

@@ -203,7 +203,6 @@ Response:
     "sessionFile": "/path/to/session.jsonl",
     "sessionId": "abc123",
     "sessionName": "my-feature-work",
-    "autoCompactionEnabled": true,
     "messageCount": 5,
     "pendingMessageCount": 0
   }
@@ -430,33 +429,9 @@ Response:
 
 `estimatedTokensAfter` is a heuristic estimate over the runtime message context immediately after compaction, including any `ContextStrategy` replacement projection; it is not a provider-exact token count. `usage` reports the LLM call or calls that generated the summary and may be omitted by custom compaction handlers.
 
-#### set_auto_compaction
-
-Enable or disable automatic compaction when context is nearly full.
-
-```json
-{"type": "set_auto_compaction", "enabled": true}
-```
-
-Response:
-```json
-{"type": "response", "command": "set_auto_compaction", "success": true}
-```
-
 ### Retry
 
-#### set_auto_retry
-
-Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).
-
-```json
-{"type": "set_auto_retry", "enabled": true}
-```
-
-Response:
-```json
-{"type": "response", "command": "set_auto_retry", "success": true}
-```
+Automatic agent-level retry applies unconditionally (the `set_auto_retry` command was removed on 2026-10-03, D-079). To stop a running retry, use `abort_retry`.
 
 #### abort_retry
 

package/docs/sdk.md

@@ -426,8 +426,8 @@ for (const diagnostic of diagnostics) {
 Authentication resolution priority (handled by `ModelRuntime`):
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
 2. Stored credentials in `auth.json` (API keys or OAuth tokens)
-3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
-4. Fallback resolver (for custom provider keys from `models.json`)
+3. Provider-registered fallback key (`apiKey` supplied programmatically by the embedding code, e.g. a provider registered with its own key — injected in memory, never persisted; when set it takes precedence over the provider's ambient environment variables)
+4. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
 
 ```typescript
 import { InMemoryCredentialStore } from "@agent-forge/ai";
@@ -796,8 +796,7 @@ const { facade } = await createStableAgentSession({
 // With overrides
 const settingsManager = SettingsManager.create();
 settingsManager.applyOverrides({
-  compaction: { enabled: false },
-  retry: { enabled: true, maxRetries: 5 },
+  retry: { maxRetries: 5 },
 });
 const { facade } = await createStableAgentSession({ settingsManager });
 
@@ -914,8 +913,7 @@ if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides
 const settingsManager = SettingsManager.inMemory({
-  compaction: { enabled: false },
-  retry: { enabled: true, maxRetries: 2 },
+  retry: { maxRetries: 2 },
 });
 
 const loader = new DefaultResourceLoader({

package/docs/settings.md

@@ -47,7 +47,7 @@ Edit directly or use `/settings` for common options. To save startup model defau
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
 | `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`PI_EXPERIMENTAL=1`) |
 | `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
-| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
+| `doubleEscapeAction` | string | `"tree"` | Action for double-escape with an empty editor: `"tree"` or `"none"` (the removed `"fork"` value reads as `"tree"`; use the `/fork` command) |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
 | `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
@@ -99,16 +99,16 @@ Agent Forge has no default version-check endpoint. A version query runs only whe
 
 ### Compaction
 
+Auto-compaction is always on; there is no toggle. The legacy keys `compaction.enabled`, `compaction.microcompactEnabled`, and `compaction.summarySelfCritique` were removed and are silently ignored if present in settings files.
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
 | `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
 
 ```json
 {
   "compaction": {
-    "enabled": true,
     "reserveTokens": 16384,
     "keepRecentTokens": 20000
   }
@@ -124,9 +124,10 @@ Agent Forge has no default version-check endpoint. A version query runs only whe
 
 ### Retry
 
+Automatic agent-level retry applies unconditionally (the `retry.enabled` switch was removed on 2026-10-03, D-079; stale keys in settings files are silently ignored).
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
 | `retry.maxRetries` | number | `5` | Maximum agent-level retry attempts |
 | `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff with ±10% jitter (~2s, ~4s, ~8s, ~16s, ~32s) |
 | `retry.maxAgentDelayMs` | number | `60000` | Max agent-level retry delay; the cap applies before jitter (60s) |
@@ -143,7 +144,6 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 ```json
 {
   "retry": {
-    "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000,
     "maxAgentDelayMs": 60000,
@@ -213,7 +213,7 @@ Windows paths in JSON must use forward slashes or escaped backslashes:
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `defaultTools` | string[] | - | 内置工具初始启用列表；省略时由首方工具插件提供默认集合。裸名为替换语义；`+name`/`-name` 在其后按序增删（如 `["-bash", "+powershell"]`），项目层 `+/-` 条目叠加在用户层之上 |
+| `defaultTools` | string[] | - | 内置工具初始启用列表；省略时由首方工具插件提供默认集合。裸名列表为白名单替换语义；`+name` 条目在其后按序添加（如 `["read", "+powershell"]`），项目层纯 `+` 列表叠加在用户层之上。`-name` 移除语法已移除，残留条目静默忽略；项目层列表含 `-` 条目时不再与用户层叠加，而是整体替换 |
 
 `defaultTools` selects the built-in tools enabled at startup. Plugin and SDK custom tools remain enabled. Available built-ins are `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`:
 
@@ -231,7 +231,7 @@ On Windows, select `powershell` instead of `bash`, or include both:
 }
 ```
 
-An empty array starts with no built-in tools while preserving plugin and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
+An empty array starts with no built-in tools while preserving plugin and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array unless it consists solely of `+name` entries, which layer on top of the resolved global selection.
 
 ### Sessions
 
@@ -276,7 +276,6 @@ Paths in `~/.agent-forge/agent/settings.json` resolve relative to `~/.agent-forg
 | `skills` | string[] | `[]` | Local skill file paths or directories |
 | `prompts` | string[] | `[]` | Local prompt template paths or directories |
 | `themes` | string[] | `[]` | Local theme file paths or directories |
-| `enableSkillCommands` | boolean | `true` | Register skills as `/skill:name` commands |
 
 Arrays support glob patterns and exclusions. Use `!pattern` to exclude. Use `+path` to force-include an exact path and `-path` to force-exclude an exact path.
 
@@ -317,12 +316,10 @@ See [packages.md](packages.md) for package management details.
   },
   "theme": "dark",
   "compaction": {
-    "enabled": true,
     "reserveTokens": 16384,
     "keepRecentTokens": 20000
   },
   "retry": {
-    "enabled": true,
     "maxRetries": 3
   },
   "enabledModels": ["claude-*", "gpt-4o"],
@@ -341,7 +338,7 @@ Project settings (`.agent-forge/settings.json`) override global settings. Nested
 // ~/.agent-forge/agent/settings.json (global)
 {
   "theme": "dark",
-  "compaction": { "enabled": true, "reserveTokens": 16384 }
+  "compaction": { "reserveTokens": 16384 }
 }
 
 // .agent-forge/settings.json (project)
@@ -352,6 +349,6 @@ Project settings (`.agent-forge/settings.json`) override global settings. Nested
 // Result
 {
   "theme": "dark",
-  "compaction": { "enabled": true, "reserveTokens": 8192 }
+  "compaction": { "reserveTokens": 8192 }
 }
 ```

package/docs/skills.md

@@ -73,7 +73,7 @@ This is progressive disclosure: only descriptions are always in context, full in
 
 ## Skill Commands
 
-Skills register as `/skill:name` commands:
+Skills register as `/skill:name` commands unconditionally (the `enableSkillCommands` switch was removed on 2026-10-03, D-079; a stale key in settings files is silently ignored):
 
 ```bash
 /skill:brave-search           # Load and execute the skill
@@ -82,14 +82,6 @@ Skills register as `/skill:name` commands:
 
 Arguments after the command are appended to the skill content as `User: <args>`.
 
-Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
-
-```json
-{
-  "enableSkillCommands": true
-}
-```
-
 ## Skill Structure
 
 A skill is a directory with a `SKILL.md` file. Everything else is freeform.

package/docs/usage.md

@@ -287,6 +287,6 @@ agent-forge --exclude-tools ask_question
 
 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.
+It intentionally does not include MCP, multi-Agent workflows, approval policy, Plan mode, to-dos, or background bash as core business branches. MCP servers are configured through `mcp.json` ([MCP](mcp.md)); the rest are added through plugins or external tools such as containers and tmux.
 
 For the architectural rationale, see the repository [核心架构宪法](../../../docs/核心架构宪法.md).

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

@@ -13,7 +13,8 @@
  */
 
 import type { CapabilityAPI } from "@agent-forge/agent-forge";
-import { createBashTool, defineTool } from "@agent-forge/agent-forge";
+import { defineTool } from "@agent-forge/agent-forge";
+import { createBashTool } from "@agent-forge/plugin-coding-tools";
 
 export default function (api: CapabilityAPI) {
 	const cwd = process.cwd();
@@ -26,9 +27,13 @@ export default function (api: CapabilityAPI) {
 		}),
 	});
 
+	// The plugin package's structural AgentTool keeps the constrained-sampling
+	// grammar arm opaque (variants: unknown); bash never sets the flag, so drop
+	// the absent member before the host-typed defineTool spread.
+	const { constrainedSampling: _omitted, ...bashToolFace } = bashTool;
 	api.registerTool(
 		defineTool({
-			...bashTool,
+			...bashToolFace,
 			execute: async (id, params, signal, onUpdate, _ctx) => {
 				return bashTool.execute(id, params, signal, onUpdate);
 			},

package/examples/extensions/built-in-tool-renderer/index.ts

@@ -30,8 +30,10 @@
  * (last load wins, restore on dispose).
  */
 
-import type { BashToolDetails, CapabilityAPI, EditToolDetails, ReadToolDetails } from "@agent-forge/agent-forge";
-import { createBashTool, createEditTool, createReadTool, createWriteTool, defineTool } from "@agent-forge/agent-forge";
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+import { defineTool } from "@agent-forge/agent-forge";
+import type { BashToolDetails, EditToolDetails, ReadToolDetails } from "@agent-forge/plugin-coding-tools";
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@agent-forge/plugin-coding-tools";
 import { Text } from "@agent-forge/tui";
 
 export default function (api: CapabilityAPI) {

package/examples/extensions/minimal-mode/index.ts

@@ -23,6 +23,7 @@
  */
 
 import type { CapabilityAPI } from "@agent-forge/agent-forge";
+import { defineTool } from "@agent-forge/agent-forge";
 import {
 	createBashTool,
 	createEditTool,
@@ -31,8 +32,7 @@ import {
 	createLsTool,
 	createReadTool,
 	createWriteTool,
-	defineTool,
-} from "@agent-forge/agent-forge";
+} from "@agent-forge/plugin-coding-tools";
 import { Text } from "@agent-forge/tui";
 import { homedir } from "os";
 

package/examples/extensions/truncated-tool/index.ts

@@ -12,7 +12,7 @@
  * 4. Custom rendering of tool calls and results
  *
  * The `rg` tool here wraps ripgrep with proper truncation. Compare this to the
- * built-in `grep` tool in src/core/tools/grep.ts for a more complete implementation.
+ * built-in `grep` tool in plugins/coding-tools/src/grep.ts for a more complete implementation.
  *
  * Install: copy this directory (with plugin.json) to ~/.agent-forge/agent/plugins
  * or <cwd>/.agent-forge/plugins for auto-discovery.

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "agent-forge-extension-with-deps",
-  "version": "0.86.0",
+  "version": "0.87.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "agent-forge-extension-with-deps",
-      "version": "0.86.0",
+      "version": "0.87.1",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-forge-extension-with-deps",
   "private": true,
-  "version": "0.86.0",
+  "version": "0.87.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.example.with-deps",
-	"version": "0.86.0",
+	"version": "0.87.1",
 	"hostVersion": ">=0.84.0",
 	"apiVersion": "1-draft",
 	"entry": "./index.ts",

package/examples/sdk/10-settings.ts

@@ -15,8 +15,7 @@ console.log("Current settings:", JSON.stringify(settingsManagerFromDisk.getGloba
 // Override specific settings
 const settingsManager = SettingsManager.create(cwd);
 settingsManager.applyOverrides({
-	compaction: { enabled: false },
-	retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },
+	retry: { maxRetries: 5, baseDelayMs: 1000 },
 });
 
 const { facade: customSettingsFacade } = await createStableAgentSession({
@@ -41,8 +40,7 @@ if (settingsErrors.length > 0) {
 
 // For testing without file I/O:
 const inMemorySettings = SettingsManager.inMemory({
-	compaction: { enabled: false },
-	retry: { enabled: false },
+	retry: { maxRetries: 0 },
 });
 
 const { facade: testFacade } = await createStableAgentSession({

package/examples/sdk/12-full-control.ts

@@ -26,8 +26,7 @@ if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides
 const settingsManager = SettingsManager.inMemory({
-	compaction: { enabled: false },
-	retry: { enabled: true, maxRetries: 2 },
+	retry: { maxRetries: 2 },
 });
 
 const cwd = process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ai-agent-forge/agent-forge",
-	"version": "0.87.0",
+	"version": "0.88.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"agentForgeConfig": {
@@ -31,6 +31,7 @@
 	},
 	"files": [
 		"dist",
+		"bundled-plugins",
 		"docs",
 		"examples",
 		"containerization.md",
@@ -39,10 +40,8 @@
 	"scripts": {
 		"clean": "shx rm -rf dist",
 		"build": "npm run build:unbundled && node ../../scripts/build-agent-forge-bundle.mjs",
-		"build:unbundled": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
-		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm --prefix ../plugin-sdk run build && npm run build && bun build --compile --no-compile-autoload-bunfig ./src/bun/cli.ts ./src/utils/image-resize-worker.ts --outfile dist/agent-forge && npm run copy-binary-assets",
+		"build:unbundled": "npm run clean && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
-		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
 		"test": "vitest --run",
 		"shrinkwrap": "node ../../scripts/generate-agent-forge-shrinkwrap.mjs",
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap",