open-multi-agent-kit 0.96.2 → 0.98.0

package/docs/sdk.md

@@ -565,12 +565,12 @@ The `edit` tool returns `details.diff` for OMK's TUI display and `details.patch`
 
 The `diagnostics` tool runs the project's own checkers and normalizes the result — `tsc --noEmit` for TypeScript, `pyright`/`ruff` for Python, `go vet` for Go, `cargo check` for Rust. Missing checkers or project markers are reported as `skipped` in the tool result instead of failing. Output is capped at 50 diagnostics and cached for 5 s.
 
-With default OMP seams, truncated `read` output does not create a sidecar. With `OMK_OMP_SEAMS=0`, legacy truncation may write the selected window to `<absolute-source-path>.omk-spill.txt`; `ReadToolDetails.fullOutputPath` reports the path when present. A first line that alone exceeds the byte cap is clipped without a sidecar. The exported `spillTruncatedOutput()` helper provides the preview-plus-path contract for custom tools.
+Truncated `read` output may spill the selected window to a randomly named `omk-spill-*` directory under the OS temporary directory; `ReadToolDetails.fullOutputPath` reports the path when present. The directory is owner-only (`0700`) and the spill file is exclusive and owner-readable (`0600`) on POSIX. A first line that alone exceeds the byte cap is clipped without a spill. The exported `spillTruncatedOutput()` helper provides the same preview-plus-path contract for custom tools.
 
 ```typescript
 import { createAgentSession } from "open-multi-agent-kit";
 
-// Enable inspection tools; legacy read mode may create a spill sidecar
+// Enable inspection tools; a long read may create a private temp spill
 const { session } = await createAgentSession({
   tools: ["read", "grep", "find", "ls"],
 });

package/docs/settings.md

@@ -138,7 +138,7 @@ All numeric token reserves must be non-negative safe integers. Ratios must be fi
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `contextBudget.enabled` | boolean | `false` | Globally enable prompt resource budgeting and its in-memory, session-scoped plan/representation cache |
+| `contextBudget.enabled` | boolean | `false` | Globally enable prompt resource budgeting; representation entries persist per workspace by default while plan entries stay in session memory |
 
 ```json
 {
@@ -146,7 +146,7 @@ All numeric token reserves must be non-negative safe integers. Ratios must be fi
 }
 ```
 
-This setting is global-only: `.omk/settings.json` cannot enable or disable it. Use `OMK_CONTEXT_GOVERNOR=1` to force it on for one process or `OMK_CONTEXT_GOVERNOR=0` to force it off for a baseline run. The cache is never persisted or shared between sessions.
+This setting is global-only: `.omk/settings.json` cannot enable or disable it. Use `OMK_CONTEXT_GOVERNOR=1` to force it on for one process or `OMK_CONTEXT_GOVERNOR=0` to force it off for a baseline run. When enabled, content-addressed representation and negative-result entries persist under `.omk/cache/context-budget-v2`; plan entries stay in session memory. Set `OMK_CONTEXT_GOVERNOR_CACHE=memory` to keep every entry in session memory or `OMK_CONTEXT_GOVERNOR_CACHE_DIR` to relocate the representation snapshot.
 
 ### Agent Tool Execution
 
@@ -182,7 +182,7 @@ The DAG preserves source-order result artifacts. `bash`, unknown tools, and exte
 
 ### Resource Governor
 
-The governor probes host capacity (memory, workspace disk, V8 heap, system CPU) and evaluates a resource admission decision, surfaced through `/resource [probe|policy]` in the TUI and `omk doctor resources [--json]` headless. In `observe` mode (default) it records decisions without changing behavior; in `adaptive`/`strict` modes each top-level prompt runs a bounded preflight probe and throttles the effective tool concurrency for that run (never above `agent.maxToolConcurrency`), restoring it when the run settles. Heavy-process caps are enforced at the governed bash boundary; the internal subagent-lane launcher is not wired into live child dispatch. Absent settings keep prior behavior unchanged.
+The governor probes host capacity (memory, workspace disk, V8 heap, system CPU) and evaluates a resource admission decision, surfaced through `/resource [probe|policy]` in the TUI and `omk doctor resources [--json]` headless. `omk doctor resources --report [--json]` aggregates bounded, identifier-free admission counts from local run journals without probing the current host. Only reason-qualified records count toward the 30-record floor; legacy/malformed reason coverage remains diagnostic. The floor is only a sample signal, always requires human review, and never promotes the mode. In `observe` mode (default) it records decisions without changing behavior; in `adaptive`/`strict` modes each top-level prompt runs a bounded preflight probe and throttles the effective tool concurrency for that run (never above `agent.maxToolConcurrency`), restoring it when the run settles. Heavy-process caps are enforced at the governed bash boundary; the internal subagent-lane launcher is not wired into live child dispatch. Absent settings keep prior behavior unchanged.
 
 | Setting | Type | Default | Description |
 | --------- | ------ | --------- | ------------- |
@@ -213,20 +213,21 @@ Validation is explicit and fail-closed: invalid values are reported (in `/resour
 
 ### Completion Sound
 
-Plays a short system sound when a long prompt finally settles (all retries and continuations drained), only in the interactive TUI on a real TTY — never in RPC, JSON, print mode, or CI. Default off. Backends use fixed executables with fixed arguments (macOS `afplay`, Windows/WSL PowerShell system sound, Linux `canberra-gtk-play`/`paplay`/`aplay`), falling back to the terminal bell. Sound failures are diagnostics only and never affect the prompt outcome.
+Plays a short system sound only after the top-level prompt settles: retries, continuations, and tools must be drained first. Current subagent work is awaited inside its tool call, so that tool boundary also covers those children. The settlement contract reserves direct child/shard counters for future live wiring; those paths must connect the counters before activation. Sound is enabled by default only in the interactive TUI on a real TTY—never in RPC, JSON, print mode, or CI. Successful prompts honor `minDurationMs`; failed and aborted prompts notify immediately. Backends use fixed absolute executables and arguments (macOS `afplay`, Windows system PowerShell, Linux `canberra-gtk-play`/`paplay`/`aplay`), an allowlisted environment with no inherited `PATH` or credentials, and the OS temporary directory as cwd. WSL uses terminal BEL because Windows executable mounts have no fixed trusted path. Sound failures are diagnostics only and never affect the prompt outcome.
 
 | Setting | Type | Default | Description |
 | --------- | ------ | --------- | ------------- |
-| `notifications.completionSound.enabled` | boolean | `false` | Master switch; env `OMK_COMPLETION_SOUND` set to `0` or `1` overrides per process |
-| `notifications.completionSound.minDurationMs` | number | `5000` | Only chime for prompts that ran at least this long |
-| `notifications.completionSound.onSuccess` | boolean | `true` | Chime on completed prompts |
-| `notifications.completionSound.onFailure` | boolean | `true` | Chime on failed prompts (user aborts never chime) |
-| `notifications.completionSound.terminalBellFallback` | boolean | `true` | Fall back to the terminal BEL when no sound backend works |
+| `notifications.completionSound.enabled` | boolean | `true` | Master switch; `OMK_COMPLETION_SOUND=0` disables and `=1` enables it for one process |
+| `notifications.completionSound.minDurationMs` | number | `5000` | Minimum duration for successful-completion sounds; failed/aborted outcomes bypass it |
+| `notifications.completionSound.onSuccess` | boolean | `true` | Notify after a completed prompt that meets the duration floor |
+| `notifications.completionSound.onFailure` | boolean | `true` | Notify immediately after a failed terminal outcome |
+| `notifications.completionSound.onAbort` | boolean | `true` | Notify immediately after an aborted/stopped terminal outcome |
+| `notifications.completionSound.terminalBellFallback` | boolean | `true` | Fall back to terminal BEL when no sound backend works |
 
 ```json
 {
   "notifications": {
-    "completionSound": { "enabled": true, "minDurationMs": 10000 }
+    "completionSound": { "minDurationMs": 10000, "onAbort": false }
   }
 }
 ```

package/docs/usage.md

@@ -22,7 +22,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 | 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 |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Images | Paste with Ctrl+V (Alt+V on Windows) or drag into the terminal; pastes attach as preview chips above the editor and send with your next prompt |
 | Skill/bash launcher | `!` opens skill completion; `!skill:name prompt` invokes a skill; `!omk <role-or-request>` routes through OMK role hubs |
 | Shell command | `! command` runs and sends output to the model |
 | Hidden shell command | `!! command` runs without sending output to the model |
@@ -45,6 +45,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |
+| `/resource [probe\|policy]` | Show resource pressure and effective concurrency for this run |
 | `/goal [objective]` | Show or set the durable goal for the current working directory |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
@@ -261,6 +262,21 @@ Diagnoses one provider and prints a single sanitized JSON document. Exit codes a
 
 Config sources, highest precedence first: `models.json`, `KIMI_BASE_URL`/`KIMI_MODEL_NAME` env, `~/.kimi/config.toml` root keys, then `[providers.<name>]` TOML tables with `type = "openai_legacy"` — the last are classified `custom-openai-compatible`, so native-only checks (login, native config) are skipped and endpoint reachability is checked instead. Credentials, URL userinfo/query/fragment, request bodies, and response bodies never appear in the output; malformed TOML is reported by line number only.
 
+### Resource Doctor
+
+```bash
+omk doctor resources [--json]
+omk doctor resources --report [--json]
+```
+
+The first form probes current host pressure. `--report` does not probe the host;
+it scans at most 500 bounded local resource-observation journals and emits only
+aggregate pressure/action/probe-health counts. It opens bounded regular files
+without following symlinks and never includes paths, prompt or decision IDs,
+digests, a command field, or raw capacity. Only reason-qualified records count
+toward the 30-record floor; the report always requires human false-positive
+review and never promotes `adaptive`.
+
 ### Modes
 
 | Flag | Description |
@@ -311,7 +327,7 @@ cat README.md | omk -p "Summarize this text"
 
 Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
 
-With default OMP seams, a long text `read` returns a bounded window and continuation marker without creating a sidecar. With `OMK_OMP_SEAMS=0`, legacy truncation may write the selected window to `<absolute-source-path>.omk-spill.txt` and report that path. A first line that alone exceeds the byte cap is clipped without a sidecar. An inspection-only tool allowlist is therefore not a strict no-write filesystem boundary in legacy read mode.
+A long text `read` returns a bounded window and continuation marker. Truncation may spill the selected window to a randomly named owner-only directory under the OS temporary directory and report that path; the directory uses mode `0700` and the file `0600` on POSIX. A first line that alone exceeds the byte cap is clipped without a spill. An inspection-only tool allowlist is therefore not a strict no-write filesystem boundary.
 
 ### Resource Options
 
@@ -380,7 +396,7 @@ omk --model sonnet:high "Solve this complex problem"
 # Limit model cycling
 omk --models "claude-*,gpt-4o"
 
-# Inspection-only tool allowlist; legacy read mode may create a spill sidecar
+# Inspection-only tool allowlist; a long read may create a private temp spill
 omk --tools read,grep,find,ls -p "Review the code"
 
 # Disable one extension or built-in tool while keeping the rest available

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.96.2",
+  "version": "0.98.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.96.2",
+      "version": "0.98.0",
       "dependencies": {
         "@anthropic-ai/sdk": "0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-gondolin",
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.96.2",
+			"version": "0.98.0",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-gondolin",
 	"private": true,
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.96.2",
+			"version": "0.98.0",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-sandbox",
 	"private": true,
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

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

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-with-deps",
-  "version": "0.96.2",
+  "version": "0.98.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-with-deps",
-      "version": "0.96.2",
+      "version": "0.98.0",
       "dependencies": {
         "ms": "2.1.3"
       },

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

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-with-deps",
 	"private": true,
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "open-multi-agent-kit",
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "open-multi-agent-kit",
-			"version": "0.96.2",
+			"version": "0.98.0",
 			"license": "MIT",
 			"dependencies": {
-				"omk-agent-core": "^0.96.2",
-				"omk-ai": "^0.96.2",
-				"omk-tui": "^0.96.2",
+				"omk-agent-core": "^0.98.0",
+				"omk-ai": "^0.98.0",
+				"omk-tui": "^0.98.0",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"canonicalize": "4.0.0",
 				"chalk": "5.6.2",
@@ -27,8 +27,8 @@
 				"typebox": "1.3.11",
 				"undici": "8.10.0",
 				"yaml": "2.9.0",
-				"omk-adaptorch-wpl": "^0.96.2",
-				"omk-protocol": "^0.96.2"
+				"omk-adaptorch-wpl": "^0.98.0",
+				"omk-protocol": "^0.98.0"
 			},
 			"optionalDependencies": {
 				"@mariozechner/clipboard": "0.3.9"
@@ -1285,19 +1285,19 @@
 			}
 		},
 		"node_modules/omk-adaptorch-wpl": {
-			"version": "0.96.2",
-			"resolved": "https://registry.npmjs.org/omk-adaptorch-wpl/-/omk-adaptorch-wpl-0.96.2.tgz",
+			"version": "0.98.0",
+			"resolved": "https://registry.npmjs.org/omk-adaptorch-wpl/-/omk-adaptorch-wpl-0.98.0.tgz",
 			"license": "MIT",
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/omk-agent-core": {
-			"version": "0.96.2",
-			"resolved": "https://registry.npmjs.org/omk-agent-core/-/omk-agent-core-0.96.2.tgz",
+			"version": "0.98.0",
+			"resolved": "https://registry.npmjs.org/omk-agent-core/-/omk-agent-core-0.98.0.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"omk-ai": "^0.96.2",
+				"omk-ai": "^0.98.0",
 				"ignore": "7.0.6",
 				"typebox": "1.3.11",
 				"yaml": "2.9.0"
@@ -1307,8 +1307,8 @@
 			}
 		},
 		"node_modules/omk-ai": {
-			"version": "0.96.2",
-			"resolved": "https://registry.npmjs.org/omk-ai/-/omk-ai-0.96.2.tgz",
+			"version": "0.98.0",
+			"resolved": "https://registry.npmjs.org/omk-ai/-/omk-ai-0.98.0.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -1330,16 +1330,16 @@
 			}
 		},
 		"node_modules/omk-protocol": {
-			"version": "0.96.2",
-			"resolved": "https://registry.npmjs.org/omk-protocol/-/omk-protocol-0.96.2.tgz",
+			"version": "0.98.0",
+			"resolved": "https://registry.npmjs.org/omk-protocol/-/omk-protocol-0.98.0.tgz",
 			"license": "MIT",
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/omk-tui": {
-			"version": "0.96.2",
-			"resolved": "https://registry.npmjs.org/omk-tui/-/omk-tui-0.96.2.tgz",
+			"version": "0.98.0",
+			"resolved": "https://registry.npmjs.org/omk-tui/-/omk-tui-0.98.0.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "open-multi-agent-kit",
-	"version": "0.96.2",
+	"version": "0.98.0",
 	"description": "OMK (Open Multi-Agent Kit) coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"omkConfig": {
@@ -32,7 +32,7 @@
 	],
 	"scripts": {
 		"clean": "shx rm -rf dist",
-		"build": "node ./scripts/link-workspace-deps.mjs && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && npm run copy-assets",
+		"build": "node ./scripts/link-workspace-deps.mjs && tsgo -p tsconfig.build.json && node ../../scripts/prune-dist-orphans.mjs . && shx chmod +x dist/cli.js && npm run copy-assets",
 		"build:binary": "npm --prefix ../tui run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm run build && bun build --compile ./dist/bun/cli.js ./src/utils/image-resize-worker.ts --outfile dist/omk && 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/",
@@ -42,9 +42,9 @@
 		"link-workspace-deps": "node ./scripts/link-workspace-deps.mjs"
 	},
 	"dependencies": {
-		"omk-agent-core": "^0.96.2",
-		"omk-ai": "^0.96.2",
-		"omk-tui": "^0.96.2",
+		"omk-agent-core": "^0.98.0",
+		"omk-ai": "^0.98.0",
+		"omk-tui": "^0.98.0",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"canonicalize": "4.0.0",
 		"chalk": "5.6.2",
@@ -60,8 +60,8 @@
 		"typebox": "1.3.11",
 		"undici": "8.10.0",
 		"yaml": "2.9.0",
-		"omk-adaptorch-wpl": "^0.96.2",
-		"omk-protocol": "^0.96.2"
+		"omk-adaptorch-wpl": "^0.98.0",
+		"omk-protocol": "^0.98.0"
 	},
 	"overrides": {
 		"rimraf": "6.1.2",

package/dist/core/context-budget-governor.d.ts

@@ -1,67 +0,0 @@
-import { type TokenCounterAdapter } from "./context-budget-token-counter.ts";
-export type ContextBudgetItemKind = "system" | "context-pointer" | "context-full" | "skill-header" | "skill" | "mcp" | "history" | "tool-result" | "subagent-evidence" | "budget-note";
-export type ContextBudgetPriority = "hard" | "high" | "medium" | "low";
-export type ContextBudgetDiagnosticReason = "hard_pin_over_capacity" | "item_omitted" | "invalid_budget";
-export interface ContextBudgetItem {
-    readonly id: string;
-    readonly kind: ContextBudgetItemKind;
-    readonly text: string;
-    readonly priority: ContextBudgetPriority;
-    readonly tokenEstimate?: number;
-    readonly relevance?: number;
-    readonly recency?: number;
-    readonly evidenceValue?: number;
-    readonly redundancyKey?: string;
-}
-export interface ContextBudgetGovernorInput {
-    readonly maxTokens: number;
-    readonly responseReserveTokens?: number;
-    readonly modelId?: string;
-    readonly policyVersion?: string;
-    readonly items: readonly ContextBudgetItem[];
-    readonly tokenCounter?: TokenCounterAdapter;
-}
-export interface ContextBudgetPlannedItem extends ContextBudgetItem {
-    readonly estimatedTokens: number;
-    readonly score: number;
-}
-export interface ContextBudgetDiagnostic {
-    readonly reason: ContextBudgetDiagnosticReason;
-    readonly itemId?: string;
-    readonly detail: string;
-}
-export interface ContextBudgetObservabilityCounts {
-    readonly selected: number;
-    readonly omitted: number;
-}
-export interface ContextBudgetObservabilityTokens {
-    readonly available: number;
-    readonly used: number;
-    readonly omitted: number;
-    readonly tokenSavings: number;
-}
-export interface ContextBudgetObservability {
-    readonly counts: ContextBudgetObservabilityCounts;
-    readonly diagnosticReasons: readonly ContextBudgetDiagnosticReason[];
-    readonly tokens: ContextBudgetObservabilityTokens;
-    readonly planHash: string;
-}
-export interface ContextBudgetPlan {
-    readonly policyVersion: string;
-    readonly maxTokens: number;
-    readonly responseReserveTokens: number;
-    readonly availableTokens: number;
-    readonly usedTokens: number;
-    readonly omittedTokens: number;
-    readonly emergency: boolean;
-    readonly omittedHighPriority: boolean;
-    readonly includedItems: readonly ContextBudgetPlannedItem[];
-    readonly omittedItems: readonly ContextBudgetPlannedItem[];
-    readonly diagnostics: readonly ContextBudgetDiagnostic[];
-    readonly planHash: string;
-    readonly observability: ContextBudgetObservability;
-}
-export declare const CONTEXT_BUDGET_POLICY_VERSION = "context-budget-v1";
-export declare function planContextBudget(input: ContextBudgetGovernorInput): ContextBudgetPlan;
-export declare function scoreContextBudgetItem(item: ContextBudgetItem, estimatedTokens: number): number;
-//# sourceMappingURL=context-budget-governor.d.ts.map

package/dist/core/context-budget-governor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-budget-governor.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-governor.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\n\nexport type ContextBudgetItemKind =\n\t| \"system\"\n\t| \"context-pointer\"\n\t| \"context-full\"\n\t| \"skill-header\"\n\t| \"skill\"\n\t| \"mcp\"\n\t| \"history\"\n\t| \"tool-result\"\n\t| \"subagent-evidence\"\n\t| \"budget-note\";\n\nexport type ContextBudgetPriority = \"hard\" | \"high\" | \"medium\" | \"low\";\nexport type ContextBudgetDiagnosticReason = \"hard_pin_over_capacity\" | \"item_omitted\" | \"invalid_budget\";\n\nexport interface ContextBudgetItem {\n\treadonly id: string;\n\treadonly kind: ContextBudgetItemKind;\n\treadonly text: string;\n\treadonly priority: ContextBudgetPriority;\n\treadonly tokenEstimate?: number;\n\treadonly relevance?: number;\n\treadonly recency?: number;\n\treadonly evidenceValue?: number;\n\treadonly redundancyKey?: string;\n}\n\nexport interface ContextBudgetGovernorInput {\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens?: number;\n\treadonly modelId?: string;\n\treadonly policyVersion?: string;\n\treadonly items: readonly ContextBudgetItem[];\n\treadonly tokenCounter?: TokenCounterAdapter;\n}\n\nexport interface ContextBudgetPlannedItem extends ContextBudgetItem {\n\treadonly estimatedTokens: number;\n\treadonly score: number;\n}\n\nexport interface ContextBudgetDiagnostic {\n\treadonly reason: ContextBudgetDiagnosticReason;\n\treadonly itemId?: string;\n\treadonly detail: string;\n}\n\nexport interface ContextBudgetObservabilityCounts {\n\treadonly selected: number;\n\treadonly omitted: number;\n}\n\nexport interface ContextBudgetObservabilityTokens {\n\treadonly available: number;\n\treadonly used: number;\n\treadonly omitted: number;\n\treadonly tokenSavings: number;\n}\n\nexport interface ContextBudgetObservability {\n\treadonly counts: ContextBudgetObservabilityCounts;\n\treadonly diagnosticReasons: readonly ContextBudgetDiagnosticReason[];\n\treadonly tokens: ContextBudgetObservabilityTokens;\n\treadonly planHash: string;\n}\n\nexport interface ContextBudgetPlan {\n\treadonly policyVersion: string;\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens: number;\n\treadonly availableTokens: number;\n\treadonly usedTokens: number;\n\treadonly omittedTokens: number;\n\treadonly emergency: boolean;\n\treadonly omittedHighPriority: boolean;\n\treadonly includedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedItems: readonly ContextBudgetPlannedItem[];\n\treadonly diagnostics: readonly ContextBudgetDiagnostic[];\n\treadonly planHash: string;\n\treadonly observability: ContextBudgetObservability;\n}\n\nexport const CONTEXT_BUDGET_POLICY_VERSION = \"context-budget-v1\";\n\nexport function planContextBudget(input: ContextBudgetGovernorInput): ContextBudgetPlan {\n\tconst tokenCounter = input.tokenCounter ?? createFallbackTokenCounter();\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst diagnostics: ContextBudgetDiagnostic[] = [];\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserveTokens = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst availableTokens = Math.max(0, maxTokens - responseReserveTokens);\n\tconst plannedItems = input.items.map((item) => planItem(item, tokenCounter, modelId, diagnostics));\n\tconst includedIds = new Set<string>();\n\tlet usedTokens = 0;\n\n\tfor (const item of plannedItems) {\n\t\tif (item.priority !== \"hard\") {\n\t\t\tcontinue;\n\t\t}\n\t\tincludedIds.add(item.id);\n\t\tusedTokens += item.estimatedTokens;\n\t}\n\n\tif (usedTokens > availableTokens) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${availableTokens} available tokens`,\n\t\t});\n\t}\n\n\tconst selectedRedundancyKeys = new Set<string>();\n\tconst remainingOptionalItems = plannedItems.filter((item) => item.priority !== \"hard\");\n\n\twhile (remainingOptionalItems.length > 0) {\n\t\tconst rankedItems = remainingOptionalItems\n\t\t\t.map((item) => applyRedundancyPenalty(item, selectedRedundancyKeys))\n\t\t\t.sort(comparePlannedItemsForSelection);\n\t\tconst selected = rankedItems.find((item) => usedTokens + item.estimatedTokens <= availableTokens);\n\t\tif (!selected) {\n\t\t\tbreak;\n\t\t}\n\n\t\tincludedIds.add(selected.id);\n\t\tusedTokens += selected.estimatedTokens;\n\t\tif (selected.redundancyKey) {\n\t\t\tselectedRedundancyKeys.add(selected.redundancyKey);\n\t\t}\n\n\t\tconst selectedIndex = remainingOptionalItems.findIndex((item) => item.id === selected.id);\n\t\tremainingOptionalItems.splice(selectedIndex, 1);\n\t}\n\n\tconst includedItems = plannedItems.filter((item) => includedIds.has(item.id));\n\tconst omittedItems = plannedItems.filter((item) => !includedIds.has(item.id));\n\tfor (const item of omittedItems) {\n\t\tdiagnostics.push({ reason: \"item_omitted\", itemId: item.id, detail: `${item.kind} omitted from context budget` });\n\t}\n\tconst omittedTokens = omittedItems.reduce((sum, item) => sum + item.estimatedTokens, 0);\n\tconst omittedHighPriority = omittedItems.some((item) => item.priority === \"high\");\n\tconst emergency =\n\t\tusedTokens > availableTokens || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION;\n\n\tconst planWithoutHash = {\n\t\tpolicyVersion,\n\t\tmaxTokens,\n\t\tresponseReserveTokens,\n\t\tavailableTokens,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\temergency,\n\t\tomittedHighPriority,\n\t\tincluded: includedItems.map((item) => [item.id, item.estimatedTokens, item.score]),\n\t\tomitted: omittedItems.map((item) => [item.id, item.estimatedTokens, item.score]),\n\t};\n\tconst planHash = createHash(\"sha256\").update(JSON.stringify(planWithoutHash), \"utf8\").digest(\"hex\");\n\tconst observability = buildObservability({\n\t\tavailableTokens,\n\t\tdiagnostics,\n\t\tincludedItems,\n\t\tomittedItems,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\tusedTokens,\n\t});\n\n\treturn {\n\t\tpolicyVersion,\n\t\tmaxTokens,\n\t\tresponseReserveTokens,\n\t\tavailableTokens,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\temergency,\n\t\tomittedHighPriority,\n\t\tincludedItems,\n\t\tomittedItems,\n\t\tdiagnostics,\n\t\tplanHash,\n\t\tobservability,\n\t};\n}\n\nexport function scoreContextBudgetItem(item: ContextBudgetItem, estimatedTokens: number): number {\n\tconst priorityScore = priorityWeight(item.priority);\n\tconst relevance = clampScore(item.relevance) * 20;\n\tconst recency = clampScore(item.recency) * 10;\n\tconst evidence = clampScore(item.evidenceValue) * 15;\n\t// G1: costPenalty 비례화 — sqrt 기반으로 대항목에 더 큰 불이익 부여.\n\t// log2(t)*2는 1000토큰에서 ~19.9점으로 relevance(20점)와 동급 → 대항목 생존.\n\t// sqrt(t)*0.5는 1000토큰 15.8점, 5000토큰 35.4점, 10000토큰 50점 → 비례적 증가.\n\tconst costPenalty = Math.sqrt(normalizeTokenCount(estimatedTokens)) * 0.5;\n\treturn priorityScore + relevance + recency + evidence - costPenalty;\n}\n\nfunction planItem(\n\titem: ContextBudgetItem,\n\ttokenCounter: TokenCounterAdapter,\n\tmodelId: string,\n\tdiagnostics: ContextBudgetDiagnostic[],\n): ContextBudgetPlannedItem {\n\tconst rawEstimate = item.tokenEstimate ?? tokenCounter.countText(item.text, modelId).tokens;\n\tconst estimatedTokens = normalizeItemTokenEstimate(item.id, rawEstimate, diagnostics);\n\treturn {\n\t\t...item,\n\t\testimatedTokens,\n\t\tscore: item.priority === \"hard\" ? Number.POSITIVE_INFINITY : scoreContextBudgetItem(item, estimatedTokens),\n\t};\n}\n\nconst REDUNDANCY_PENALTY_FLOOR = 10;\nconst REDUNDANCY_PENALTY_SCALE = 0.8;\n\n/**\n * W4: Adaptive redundancy penalty — proportional to token count.\n * Large duplicates waste more budget so deserve higher penalty.\n * Formula: max(floor, sqrt(tokens) * scale)\n * - 200 tokens → 11.3   (near floor — minimal waste)\n * - 1000 tokens → 25.3  (moderate waste)\n * - 5000 tokens → 56.6  (heavy waste — strongly penalized)\n * Floor ensures small duplicates are still penalized meaningfully.\n * Scale (0.8) tuned to score medium=50 so large duplicates go negative.\n */\nfunction redundancyPenalty(estimatedTokens: number): number {\n\treturn Math.max(REDUNDANCY_PENALTY_FLOOR, Math.sqrt(estimatedTokens) * REDUNDANCY_PENALTY_SCALE);\n}\n\nfunction applyRedundancyPenalty(\n\titem: ContextBudgetPlannedItem,\n\tselectedRedundancyKeys: Set<string>,\n): ContextBudgetPlannedItem {\n\tif (!item.redundancyKey || !selectedRedundancyKeys.has(item.redundancyKey)) {\n\t\treturn item;\n\t}\n\treturn { ...item, score: item.score - redundancyPenalty(item.estimatedTokens) };\n}\n\nfunction comparePlannedItemsForSelection(a: ContextBudgetPlannedItem, b: ContextBudgetPlannedItem): number {\n\t// G2: 우선순위 티어 내부에서 밀도(score/tokens) 기반 정렬.\n\t// 단위 토큰당 가치가 높은 항목을 우선 선택 → 예산 활용률 극대화.\n\tconst aTier = priorityTier(a.priority);\n\tconst bTier = priorityTier(b.priority);\n\tif (aTier !== bTier) {\n\t\treturn aTier - bTier;\n\t}\n\tconst aDensity = a.score > 0 ? a.score / Math.max(a.estimatedTokens, 1) : 0;\n\tconst bDensity = b.score > 0 ? b.score / Math.max(b.estimatedTokens, 1) : 0;\n\tif (aDensity !== bDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (a.estimatedTokens !== b.estimatedTokens) {\n\t\treturn a.estimatedTokens - b.estimatedTokens;\n\t}\n\treturn a.id.localeCompare(b.id);\n}\n\nfunction priorityTier(priority: ContextBudgetPriority): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 0;\n\t\tcase \"high\":\n\t\t\treturn 1;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 3;\n\t}\n}\n\nfunction priorityWeight(priority: ContextBudgetPriority): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 1_000_000;\n\t\tcase \"high\":\n\t\t\treturn 100;\n\t\tcase \"medium\":\n\t\t\treturn 50;\n\t\tcase \"low\":\n\t\t\treturn 10;\n\t}\n}\n\nfunction clampScore(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction normalizeBudgetTokens(\n\tfield: \"maxTokens\" | \"responseReserveTokens\",\n\tvalue: number,\n\tdiagnostics: ContextBudgetDiagnostic[],\n): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction normalizeItemTokenEstimate(itemId: string, value: number, diagnostics: ContextBudgetDiagnostic[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\titemId,\n\t\t\tdetail: `tokenEstimate must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.ceil(value);\n}\n\nfunction normalizeTokenCount(value: number): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\treturn 0;\n\t}\n\treturn value;\n}\n\nfunction buildObservability(input: {\n\treadonly availableTokens: number;\n\treadonly diagnostics: readonly ContextBudgetDiagnostic[];\n\treadonly includedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly usedTokens: number;\n}): ContextBudgetObservability {\n\treturn {\n\t\tcounts: {\n\t\t\tselected: input.includedItems.length,\n\t\t\tomitted: input.omittedItems.length,\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.availableTokens,\n\t\t\tused: input.usedTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: input.omittedTokens,\n\t\t},\n\t\tplanHash: input.planHash,\n\t};\n}\n"]}