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

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/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "agent-forge-extension-with-deps",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "agent-forge-extension-with-deps",
-      "version": "0.86.0",
+      "version": "0.87.0",
       "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.0",
   "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.0",
 	"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.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"agentForgeConfig": {
@@ -40,9 +40,7 @@
 		"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",
 		"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",

package/dist/core/extensions/microcompact.d.ts

@@ -1,80 +0,0 @@
-/**
- * Microcompact (P1 context hygiene): before spending an LLM summarization
- * call, elide the BULKY OLD tool results from the LLM context — a pure local
- * history transform with zero model cost (the codex/ZCode "microcompact"
- * layer). The session file keeps every byte (append-only marker + logical
- * transform at context build); only the model-visible context shrinks.
- *
- * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)
- * whose data names the elision point. The projection registered by the
- * bootstrap compaction policy plugin (via the PUBLIC
- * `api.registerEntryProjection` channel) replaces eligible tool-result
- * contents older than that point with a fixed placeholder, so reload and
- * token estimation stay consistent with live turns. The kernel applies
- * registered projections verbatim and knows nothing about microcompact.
- */
-import type { AgentMessage } from "@agent-forge/agent-core";
-import type { SessionEntry } from "../session-manager.ts";
-/** Custom entry type carrying the microcompact elision point. */
-export declare const MICROCOMPACT_CUSTOM_TYPE = "microcompact.v1";
-/** Replacement content for an elided tool result. */
-export declare const MICROCOMPACT_ELIDED_PLACEHOLDER = "[earlier tool result elided by microcompact]";
-/** Tool results shorter than this are not worth eliding (noise, not bulk). */
-export declare const DEFAULT_MIN_ELIDE_CHARS = 200;
-/**
- * Minimum estimated token relief for a microcompact to fire: below this the
- * churn (marker entry + context transition) cannot pay for itself and the
- * caller falls through to full LLM compaction.
- */
-export declare const MIN_MICROCOMPACT_FREED_TOKENS = 2048;
-/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */
-export interface MicrocompactMarkerData {
-    /** Entries strictly BEFORE this entry id (path order) are elision candidates. */
-    readonly elideBeforeEntryId: string;
-    /** Tool results whose serialized content is shorter are kept verbatim. */
-    readonly minChars: number;
-}
-export interface MicrocompactPlan {
-    readonly elideBeforeEntryId: string;
-    /** Estimated tokens freed by eliding the eligible tool results. */
-    readonly freedTokens: number;
-    readonly elidedCount: number;
-}
-/** Explicit plan options: `enabled` gates THIS mechanism only (microcompact relief), not compaction. */
-export interface MicrocompactPlanOptions {
-    /** Whether microcompact relief may fire at all (settings switch AND session cooldown). */
-    enabled: boolean;
-    /** Verbatim-protected recent tail budget (estimated tokens). */
-    keepRecentTokens: number;
-    /** Tool results shorter than this are not worth eliding. */
-    minElideChars?: number;
-}
-/**
- * Plan one microcompact over the branch path: protect the most recent
- * `keepRecentTokens` (estimated) as the verbatim tail, and elide the eligible
- * old tool results before that cut. Returns undefined when the caller disabled
- * the mechanism (`options.enabled === false`), when there is nothing to elide,
- * or when the relief cannot reach the minimum. Deliberately does NOT reuse
- * `CompactionSettings`: its `enabled` is the compaction master switch — a
- * different gate.
- */
-export declare function planMicrocompact(pathEntries: readonly {
-    readonly id?: string;
-    readonly type: string;
-    readonly message?: AgentMessage;
-}[], options: MicrocompactPlanOptions): MicrocompactPlan | undefined;
-/** Resolve the marker data of the LAST microcompact marker in path order. */
-export declare function lastMicrocompactMarker(pathEntries: readonly {
-    readonly type: string;
-    readonly customType?: string;
-    readonly data?: unknown;
-}[]): MicrocompactMarkerData | undefined;
-/**
- * The entry projection backing microcompact: replaces the CONTENT of eligible
- * tool results before the marker's cut point with the fixed placeholder, and
- * keeps everything else verbatim. Registered through the public
- * `api.registerEntryProjection` channel — the same channel any third-party
- * context policy uses; the kernel applies it without interpretation.
- */
-export declare function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[];
-//# sourceMappingURL=microcompact.d.ts.map

package/dist/core/extensions/microcompact.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"microcompact.d.ts","sourceRoot":"","sources":["../../../src/core/extensions/microcompact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,iDAAiD,CAAC;AAE9F,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACtC,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAgBD,wGAAwG;AACxG,MAAM,WAAW,uBAAuB;IACvC,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,SAAS;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAAE,EAAE,EACxG,OAAO,EAAE,uBAAuB,GAC9B,gBAAgB,GAAG,SAAS,CAqC9B;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GACtG,sBAAsB,GAAG,SAAS,CAapC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAgB7E","sourcesContent":["/**\n * Microcompact (P1 context hygiene): before spending an LLM summarization\n * call, elide the BULKY OLD tool results from the LLM context — a pure local\n * history transform with zero model cost (the codex/ZCode \"microcompact\"\n * layer). The session file keeps every byte (append-only marker + logical\n * transform at context build); only the model-visible context shrinks.\n *\n * Contract: the marker is a `custom` session entry (`MICROCOMPACT_CUSTOM_TYPE`)\n * whose data names the elision point. The projection registered by the\n * bootstrap compaction policy plugin (via the PUBLIC\n * `api.registerEntryProjection` channel) replaces eligible tool-result\n * contents older than that point with a fixed placeholder, so reload and\n * token estimation stay consistent with live turns. The kernel applies\n * registered projections verbatim and knows nothing about microcompact.\n */\n\nimport type { AgentMessage } from \"@agent-forge/agent-core\";\nimport { contentText } from \"@agent-forge/ai\";\nimport { estimateTokens } from \"../compaction/index.ts\";\nimport type { SessionEntry } from \"../session-manager.ts\";\n\n/** Custom entry type carrying the microcompact elision point. */\nexport const MICROCOMPACT_CUSTOM_TYPE = \"microcompact.v1\";\n\n/** Replacement content for an elided tool result. */\nexport const MICROCOMPACT_ELIDED_PLACEHOLDER = \"[earlier tool result elided by microcompact]\";\n\n/** Tool results shorter than this are not worth eliding (noise, not bulk). */\nexport const DEFAULT_MIN_ELIDE_CHARS = 200;\n\n/**\n * Minimum estimated token relief for a microcompact to fire: below this the\n * churn (marker entry + context transition) cannot pay for itself and the\n * caller falls through to full LLM compaction.\n */\nexport const MIN_MICROCOMPACT_FREED_TOKENS = 2048;\n\n/** Data carried by a {@link MICROCOMPACT_CUSTOM_TYPE} custom entry. */\nexport interface MicrocompactMarkerData {\n\t/** Entries strictly BEFORE this entry id (path order) are elision candidates. */\n\treadonly elideBeforeEntryId: string;\n\t/** Tool results whose serialized content is shorter are kept verbatim. */\n\treadonly minChars: number;\n}\n\nexport interface MicrocompactPlan {\n\treadonly elideBeforeEntryId: string;\n\t/** Estimated tokens freed by eliding the eligible tool results. */\n\treadonly freedTokens: number;\n\treadonly elidedCount: number;\n}\n\nfunction isElidableToolResult(\n\tmessage: AgentMessage,\n\tminChars: number,\n): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\tif (message.role !== \"toolResult\") return false;\n\t// 媒体保护：含非 text part（image 等）的 tool result 不 elide——占位符替换会\n\t// 把模型可见上下文中的原图数据抹掉（会话文件虽保真，但投影按 marker 重放，\n\t// 图像不会自行回来），保持\"原图常驻直到全量压缩\"的现行裁决。\n\tif (Array.isArray(message.content) && message.content.some((part) => part.type !== \"text\")) {\n\t\treturn false;\n\t}\n\treturn contentText(message.content, \"\").length >= minChars;\n}\n\n/** Explicit plan options: `enabled` gates THIS mechanism only (microcompact relief), not compaction. */\nexport interface MicrocompactPlanOptions {\n\t/** Whether microcompact relief may fire at all (settings switch AND session cooldown). */\n\tenabled: boolean;\n\t/** Verbatim-protected recent tail budget (estimated tokens). */\n\tkeepRecentTokens: number;\n\t/** Tool results shorter than this are not worth eliding. */\n\tminElideChars?: number;\n}\n\n/**\n * Plan one microcompact over the branch path: protect the most recent\n * `keepRecentTokens` (estimated) as the verbatim tail, and elide the eligible\n * old tool results before that cut. Returns undefined when the caller disabled\n * the mechanism (`options.enabled === false`), when there is nothing to elide,\n * or when the relief cannot reach the minimum. Deliberately does NOT reuse\n * `CompactionSettings`: its `enabled` is the compaction master switch — a\n * different gate.\n */\nexport function planMicrocompact(\n\tpathEntries: readonly { readonly id?: string; readonly type: string; readonly message?: AgentMessage }[],\n\toptions: MicrocompactPlanOptions,\n): MicrocompactPlan | undefined {\n\tif (!options.enabled) return undefined;\n\tconst minChars = options.minElideChars ?? DEFAULT_MIN_ELIDE_CHARS;\n\n\t// Protect the recent tail: walk backwards accumulating estimated tokens,\n\t// cutting before the entry that crosses the budget (same walk as\n\t// findCutPoint, but without turn-boundary subtleties — elision never\n\t// removes entries, only replaces contents, so any cut point is safe).\n\tlet accumulated = 0;\n\tlet cutIndex = 0;\n\tfor (let i = pathEntries.length - 1; i >= 0; i--) {\n\t\tconst entry = pathEntries[i];\n\t\tconst messageTokens = entry.message ? estimateTokens(entry.message) : 0;\n\t\tif (messageTokens === 0) continue;\n\t\taccumulated += messageTokens;\n\t\tif (accumulated >= options.keepRecentTokens) {\n\t\t\tcutIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tlet freedTokens = 0;\n\tlet elidedCount = 0;\n\tfor (let i = 0; i < cutIndex; i++) {\n\t\tconst message = pathEntries[i].message;\n\t\tif (!message || !isElidableToolResult(message, minChars)) continue;\n\t\tfreedTokens +=\n\t\t\testimateTokens(message) -\n\t\t\testimateTokens({ ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] });\n\t\telidedCount += 1;\n\t}\n\n\tconst elideBefore = pathEntries[cutIndex];\n\tif (elidedCount === 0 || freedTokens < MIN_MICROCOMPACT_FREED_TOKENS) return undefined;\n\tconst elideBeforeEntryId = elideBefore?.id;\n\tif (!elideBeforeEntryId) return undefined;\n\treturn { elideBeforeEntryId, freedTokens, elidedCount };\n}\n\n/** Resolve the marker data of the LAST microcompact marker in path order. */\nexport function lastMicrocompactMarker(\n\tpathEntries: readonly { readonly type: string; readonly customType?: string; readonly data?: unknown }[],\n): MicrocompactMarkerData | undefined {\n\tlet marker: MicrocompactMarkerData | undefined;\n\tfor (const entry of pathEntries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== MICROCOMPACT_CUSTOM_TYPE) continue;\n\t\tconst data = entry.data as Partial<MicrocompactMarkerData> | undefined;\n\t\tif (typeof data?.elideBeforeEntryId === \"string\") {\n\t\t\tmarker = {\n\t\t\t\telideBeforeEntryId: data.elideBeforeEntryId,\n\t\t\t\tminChars: typeof data.minChars === \"number\" && data.minChars >= 0 ? data.minChars : DEFAULT_MIN_ELIDE_CHARS,\n\t\t\t};\n\t\t}\n\t}\n\treturn marker;\n}\n\n/**\n * The entry projection backing microcompact: replaces the CONTENT of eligible\n * tool results before the marker's cut point with the fixed placeholder, and\n * keeps everything else verbatim. Registered through the public\n * `api.registerEntryProjection` channel — the same channel any third-party\n * context policy uses; the kernel applies it without interpretation.\n */\nexport function applyMicrocompactElision(path: SessionEntry[]): SessionEntry[] {\n\tconst marker = lastMicrocompactMarker(path);\n\tif (marker === undefined) return path;\n\tconst cutIndex = path.findIndex((entry) => entry.id === marker.elideBeforeEntryId);\n\tif (cutIndex <= 0) return path;\n\treturn path.map((entry, index) => {\n\t\tif (index >= cutIndex || entry.type !== \"message\") return entry;\n\t\tconst message = entry.message;\n\t\t// 与 planMicrocompact 同一判定（长度阈值 + 媒体保护）：投影只 elide 规划\n\t\t// 时认定为可省的 tool result，否则计划与投影对同一历史给出不同结果。\n\t\tif (!isElidableToolResult(message, marker.minChars)) return entry;\n\t\treturn {\n\t\t\t...entry,\n\t\t\tmessage: { ...message, content: [{ type: \"text\", text: MICROCOMPACT_ELIDED_PLACEHOLDER }] },\n\t\t};\n\t});\n}\n"]}