open-multi-agent-kit 0.95.2 → 0.96.1

package/docs/sessions.md

@@ -17,8 +17,25 @@ omk --fork <path|id>    # Fork a session file or partial session ID into a new s
 
 Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
 
+Stored sessions can also be inspected or appended from scripts:
+
+```bash
+omk sdk session status [id] [--json]
+omk sdk session tail [id] [--limit 20]
+omk sdk session inspect [id]
+omk sdk session send <id> "message"
+```
+
+`send` requires an exact session ID and appends only when the session has no active owner; it does not connect to a running process or execute the message. See [SDK](sdk.md#inspect-persisted-sessions-from-the-cli) for full flags and exit codes.
+
 For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
 
+## Retries and Termination Events
+
+Each provider attempt writes its own `run_started`/`run_finished` journal pair and emits `session_termination`. A retryable termination is attempt-level when `auto_retry_start` follows it; consumers should not treat that event alone as the end of the outer `prompt()` call.
+
+If a retry or failover succeeds, the later attempt emits `completed` and becomes `session.lastTermination`. If retry budget is exhausted, the last provider failure remains final. Quota and billing-cycle exhaustion are classified as `provider.rate_limit` and can switch through the configured provider-resilience chain before retrying. See [Provider Resilience](provider-resilience.md).
+
 ## Session Commands
 
 | Command | Description |
@@ -27,6 +44,7 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 | `/new` | Start a new session |
 | `/name <name>` | Set the current session display name |
 | `/session` | Show session info |
+| `/goal [objective]` | Show or set the durable goal; `checkpoint <json>` records Goal/Core/Verified/Open/Next continuity |
 | `/tree` | Navigate the current session tree |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
@@ -34,6 +52,8 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
+`/goal` state lives under the working directory, not in one session file. Seam checkpoints are digest-correlated revisions in the same goal journal; session entries contain only their goal ID, revision, and digest. The unkeyed digest is not workspace authentication, so checkpoint prose loaded on resume is not promoted to user authority. See [Run Protocol](run-protocol.md#durable-goal-lifecycle).
+
 ## Resuming and Deleting Sessions
 
 `/resume` opens an interactive session picker for the current project. `omk -r` opens the same picker at startup.

package/docs/settings.md

@@ -202,6 +202,8 @@ When a provider requests a retry delay longer than `retry.provider.maxRetryDelay
 
 Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before OMK sees them, which may block the agent until the provider quota resets in some circumstances.
 
+At the agent level, recognized quota and billing-cycle failures are retryable so OMK can first switch to an authenticated `providerResilience.failoverCandidates` entry. If no candidate qualifies, normal retry backoff applies. See [Provider Resilience](provider-resilience.md).
+
 ```json
 {
   "retry": {

package/docs/skills.md

@@ -11,6 +11,7 @@ OMK implements the [Agent Skills standard](https://agentskills.io/specification)
 ## Table of Contents
 
 - [Locations](#locations)
+- [Optional Document Compiler](#optional-document-compiler)
 - [How Skills Work](#how-skills-work)
 - [Skill Commands](#skill-commands)
 - [Skill Structure](#skill-structure)
@@ -42,6 +43,10 @@ Discovery rules:
 
 Disable discovery with `--no-skills` (explicit `--skill` paths still load).
 
+## Optional Document Compiler
+
+Install [`omk-book-to-skill`](book-to-skill.md) to compile PDF, EPUB, DOCX, HTML, Markdown, text, RTF, MOBI, and AZW sources into generated skills. It is an optional OMK package, not a built-in skill, and keeps Python extractors outside OMK core.
+
 ### Using Skills from Other Harnesses
 
 To use skills from Claude Code or OpenAI Codex, add their directories to settings:
@@ -88,7 +93,7 @@ Arguments after the command are appended after the skill content for the current
 
 `!omk <role-or-request>` is a deterministic OMK hub router. Exact role aliases such as `frontend`, `backend`, `loop`, and `plan` select `omk-frontend`, `omk-backend-data`, `omk-loop`, and `omk-plan`; free-form prompts are scored against the same hub vocabulary and fall back to `omk-skills` when no role is clear.
 
-In interactive mode, type `!` to open skill autocomplete. Selecting a skill inserts the explicit `!skill:name ` form, and `!omk` is offered when the OMK skill hub index is available. Bash remains available as `! command`, and `!! command` runs bash without sending output to the model. If `!token` is not a known skill, it falls back to bash; use `! command` when a command name might collide with a skill. `!omk` is reserved for OMK hub routing and never falls through to bash.
+In interactive mode, type `!` to open skill autocomplete. Selecting a skill inserts the explicit `!skill:name` form, and `!omk` is offered when the OMK skill hub index is available. Bash remains available as `! command`, and `!! command` runs bash without sending output to the model. If `!token` is not a known skill, it falls back to bash; use `! command` when a command name might collide with a skill. `!omk` is reserved for OMK hub routing and never falls through to bash.
 
 Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
 
@@ -173,11 +178,13 @@ Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
 The description determines when the agent loads the skill. Be specific.
 
 Good:
+
 ```yaml
 description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
 ```
 
 Poor:
+
 ```yaml
 description: Helps with PDFs.
 ```
@@ -206,6 +213,7 @@ brave-search/
 ```
 
 **SKILL.md:**
+
 ````markdown
 ---
 name: brave-search

package/docs/usage.md

@@ -45,12 +45,14 @@ 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 |
+| `/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 |
 | `/clone` | Duplicate the current active branch into a new session |
 | `/compact [prompt]` | Manually compact context, optionally with custom instructions |
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML |
+| `/import <path.jsonl>` | Import a JSONL session and continue it |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
 | `/hotkeys` | Show all keyboard shortcuts |
@@ -58,6 +60,25 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/star` | Open the OMK GitHub repository |
 | `/quit` | Quit omk |
 
+### Durable Goals
+
+Use `/goal <objective>` to create or update the durable goal for the current working directory; `/goal` without arguments shows its status. See [Run Protocol](run-protocol.md#durable-goal-lifecycle) for the authoritative persistence, round-limit, continuation, and SDK lifecycle rules.
+
+## Built-in Harness Safeguards
+
+`DefaultResourceLoader` enables these first-party safeguards:
+
+| Safeguard | Behavior | Opt out |
+| --- | --- | --- |
+| Identical-loop guard | Warns from the third consecutive identical tool call and blocks the sixth | `OMK_IDENTICAL_LOOP=0` |
+| Tool-pair repair | Removes unmatched tool-use and tool-result blocks from outbound context | `OMK_TOOL_PAIR_REPAIR=0` |
+| Model prompt presets | Adds model-specific execution guidance for supported Claude, Kimi, GLM, and Grok models | `OMK_PROMPT_PRESET=0` |
+| Goal controller | Registers `/goal` and continues active goals within their round limit | `OMK_GOAL_CONTROLLER=0` |
+
+These built-ins remain active with `--no-extensions`. A custom `ResourceLoader` owns its own extension set and does not receive them automatically.
+
+Claude models use a clean prompt context by default: OMK keeps tools, skills, and the Claude preset but omits discovered `AGENTS.md` and `CLAUDE.md` files. This avoids provider false positives caused by unrelated instruction text. Set `OMK_CLAUDE_CONTEXT_FILES=1` to restore those files for Claude.
+
 ## Automatic Thinking Level Routing
 
 `/think <level>` sets the thinking level manually. Manual levels always win: choosing a concrete level leaves auto routing, so no auto router runs.
@@ -135,6 +156,17 @@ Useful session commands:
 - `/clone` duplicates the current active branch into a new session file.
 - `/compact` summarizes older messages to free context.
 
+External controllers can inspect stored sessions without starting the TUI:
+
+```bash
+omk sdk session status [id] [--json]
+omk sdk session tail [id] [--limit 20]
+omk sdk session inspect [id]
+omk sdk session send <id> "message"
+```
+
+`send` appends a user-message entry; it does not wake or execute an agent. See [SDK](sdk.md#inspect-persisted-sessions-from-the-cli) for flags and output formats.
+
 See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
 
 ### Session Doctor and Recovery
@@ -150,7 +182,7 @@ The doctor verifies the session's complete JSONL prefix, run journal, compaction
 
 Session and journal bytes after the final newline are copied byte-for-byte to a `.quarantine-*` file before the original is atomically rewritten to its valid complete prefix. Opening a session uses the same complete-prefix rule; `SessionManager.getQuarantineReport()` reports any startup quarantine.
 
-Each real agent run writes fsynced `run_started` and `run_finished` records to `<session>.runjournal`. An unclosed valid run is recorded as an inferred `process_crash` on the next startup. JSON/RPC emit `session_termination`; text and TUI errors include kind, provider/model, retryability, cause, run ID, and next action.
+Each agent attempt writes fsynced `run_started` and `run_finished` records to `<session>.runjournal`. An unclosed valid run is recorded as an inferred `process_crash` on the next startup. JSON/RPC emit `session_termination`; text and TUI errors include kind, provider/model, retryability, cause, run ID, and next action. Recovered retries therefore record the failed attempt and a later `completed` attempt.
 
 ## Context Files
 
@@ -279,6 +311,8 @@ 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.
+
 ### Resource Options
 
 | Option | Description |
@@ -346,7 +380,7 @@ omk --model sonnet:high "Solve this complex problem"
 # Limit model cycling
 omk --models "claude-*,gpt-4o"
 
-# Read-only mode
+# Inspection-only tool allowlist; legacy read mode may create a spill sidecar
 omk --tools read,grep,find,ls -p "Review the code"
 
 # Disable one extension or built-in tool while keeping the rest available
@@ -355,22 +389,10 @@ omk --exclude-tools ask_question
 
 ### Environment Variables
 
-| Variable | Description |
-| ---------- | ------------- |
-| `OMK_CODING_AGENT_DIR` | Override config directory; default is `~/.omk/agent` |
-| `OMK_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
-| `OMK_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
-| `OMK_TOOL_SCHEDULER` | Override the tool scheduler with `dag-v2` or use `waves-v1` for process-local rollback |
-| `OMK_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
-| `OMK_SKIP_VERSION_CHECK` | Skip the OMK version update check at startup. This prevents the `the OMK repository` latest-version request |
-| `OMK_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
-| `OMK_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
-| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
+See [Environment Variables](environment-variables.md) for the authoritative variable list and exact startup semantics.
 
 ## Design Principles
 
-OMK keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
-
-It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+OMK keeps the core small while shipping a first-party MCP client and a small default harness layer for loop detection, context repair, model guidance, and durable goals. Broader subagent runtimes, permission UIs, plan mode, and background bash remain extension or package concerns.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-omk-coding-agent/).

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

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.95.2",
+  "version": "0.96.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.95.2",
+      "version": "0.96.1",
       "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.95.2",
+	"version": "0.96.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -244,7 +244,12 @@ async function loginGitLab(callbacks: OAuthLoginCallbacks): Promise<OAuthCredent
 
 	callbacks.onAuth({ url: `${GITLAB_COM_URL}/oauth/authorize?${authParams.toString()}` });
 	const callbackUrl = await callbacks.onPrompt({ message: "Paste the callback URL:" });
-	const code = new URL(callbackUrl).searchParams.get("code");
+	let code: string | null = null;
+	try {
+		code = new URL(callbackUrl).searchParams.get("code");
+	} catch {
+		throw new Error("Invalid callback URL — paste the full redirect URL from the browser");
+	}
 	if (!code) throw new Error("No authorization code found in callback URL");
 
 	const tokenResponse = await fetch(`${GITLAB_COM_URL}/oauth/token`, {

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

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.95.2",
+	"version": "0.96.1",
 	"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.95.2",
+	"version": "0.96.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.95.2",
+			"version": "0.96.1",
 			"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.95.2",
+	"version": "0.96.1",
 	"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.95.2",
+	"version": "0.96.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.95.2",
+			"version": "0.96.1",
 			"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.95.2",
+	"version": "0.96.1",
 	"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.95.2",
+  "version": "0.96.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-with-deps",
-      "version": "0.95.2",
+      "version": "0.96.1",
       "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.95.2",
+	"version": "0.96.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/npm-shrinkwrap.json

@@ -1,18 +1,19 @@
 {
 	"name": "open-multi-agent-kit",
-	"version": "0.95.2",
+	"version": "0.96.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "open-multi-agent-kit",
-			"version": "0.95.2",
+			"version": "0.96.1",
 			"license": "MIT",
 			"dependencies": {
-				"omk-agent-core": "^0.95.2",
-				"omk-ai": "^0.95.2",
-				"omk-tui": "^0.95.2",
+				"omk-agent-core": "^0.96.1",
+				"omk-ai": "^0.96.1",
+				"omk-tui": "^0.96.1",
 				"@silvia-odwyer/photon-node": "0.3.4",
+				"canonicalize": "4.0.0",
 				"chalk": "5.6.2",
 				"cross-spawn": "7.0.6",
 				"diff": "8.0.4",
@@ -26,7 +27,8 @@
 				"typebox": "1.3.11",
 				"undici": "8.10.0",
 				"yaml": "2.9.0",
-				"omk-adaptorch-wpl": "^0.95.2"
+				"omk-adaptorch-wpl": "^0.96.1",
+				"omk-protocol": "^0.96.1"
 			},
 			"optionalDependencies": {
 				"@mariozechner/clipboard": "0.3.9"
@@ -861,6 +863,18 @@
 			"integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==",
 			"license": "BSD-3-Clause"
 		},
+		"node_modules/canonicalize": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/canonicalize/-/canonicalize-4.0.0.tgz",
+			"integrity": "sha512-FEdXzwWs+N3rZqEqpqleiY9M1A6IAf9oo1zHFABnLW9FcJ/jzsu+G/Ks3Hq3FglmPKe80GeGBw8ZXLEnwPB0vQ==",
+			"license": "Apache-2.0",
+			"bin": {
+				"canonicalize": "bin/canonicalize.js"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
 		"node_modules/chalk": {
 			"version": "5.6.2",
 			"resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz",
@@ -1271,19 +1285,19 @@
 			}
 		},
 		"node_modules/omk-adaptorch-wpl": {
-			"version": "0.95.2",
-			"resolved": "https://registry.npmjs.org/omk-adaptorch-wpl/-/omk-adaptorch-wpl-0.95.2.tgz",
+			"version": "0.96.1",
+			"resolved": "https://registry.npmjs.org/omk-adaptorch-wpl/-/omk-adaptorch-wpl-0.96.1.tgz",
 			"license": "MIT",
 			"engines": {
 				"node": ">=22.19.0"
 			}
 		},
 		"node_modules/omk-agent-core": {
-			"version": "0.95.2",
-			"resolved": "https://registry.npmjs.org/omk-agent-core/-/omk-agent-core-0.95.2.tgz",
+			"version": "0.96.1",
+			"resolved": "https://registry.npmjs.org/omk-agent-core/-/omk-agent-core-0.96.1.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"omk-ai": "^0.95.2",
+				"omk-ai": "^0.96.1",
 				"ignore": "7.0.6",
 				"typebox": "1.3.11",
 				"yaml": "2.9.0"
@@ -1293,8 +1307,8 @@
 			}
 		},
 		"node_modules/omk-ai": {
-			"version": "0.95.2",
-			"resolved": "https://registry.npmjs.org/omk-ai/-/omk-ai-0.95.2.tgz",
+			"version": "0.96.1",
+			"resolved": "https://registry.npmjs.org/omk-ai/-/omk-ai-0.96.1.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -1315,9 +1329,17 @@
 				"node": ">=22.19.0"
 			}
 		},
+		"node_modules/omk-protocol": {
+			"version": "0.96.1",
+			"resolved": "https://registry.npmjs.org/omk-protocol/-/omk-protocol-0.96.1.tgz",
+			"license": "MIT",
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
 		"node_modules/omk-tui": {
-			"version": "0.95.2",
-			"resolved": "https://registry.npmjs.org/omk-tui/-/omk-tui-0.95.2.tgz",
+			"version": "0.96.1",
+			"resolved": "https://registry.npmjs.org/omk-tui/-/omk-tui-0.96.1.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.95.2",
+	"version": "0.96.1",
 	"description": "OMK (Open Multi-Agent Kit) coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"omkConfig": {
@@ -44,10 +44,11 @@
 		"postinstall": "node ./scripts/link-workspace-deps.mjs"
 	},
 	"dependencies": {
-		"omk-agent-core": "^0.95.2",
-		"omk-ai": "^0.95.2",
-		"omk-tui": "^0.95.2",
+		"omk-agent-core": "^0.96.1",
+		"omk-ai": "^0.96.1",
+		"omk-tui": "^0.96.1",
 		"@silvia-odwyer/photon-node": "0.3.4",
+		"canonicalize": "4.0.0",
 		"chalk": "5.6.2",
 		"cross-spawn": "7.0.6",
 		"diff": "8.0.4",
@@ -61,7 +62,8 @@
 		"typebox": "1.3.11",
 		"undici": "8.10.0",
 		"yaml": "2.9.0",
-		"omk-adaptorch-wpl": "^0.95.2"
+		"omk-adaptorch-wpl": "^0.96.1",
+		"omk-protocol": "^0.96.1"
 	},
 	"overrides": {
 		"rimraf": "6.1.2",
@@ -79,6 +81,7 @@
 		"@types/ms": "2.1.0",
 		"@types/node": "24.12.4",
 		"@types/proper-lockfile": "4.1.4",
+		"fast-check": "4.9.0",
 		"shx": "0.4.0",
 		"typescript": "5.9.3",
 		"vitest": "3.2.6"

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

@@ -1,50 +0,0 @@
-import { type TokenCounterAdapter, type TokenCountResult } from "./context-budget-token-counter.ts";
-export type ContextBudgetCompressorMode = "off" | "auto" | "headroom" | "llmlingua";
-export type ContextBudgetCompressionMethod = "compressed" | "none";
-export interface ContextCompressionRequest {
-    readonly text: string;
-    readonly targetTokens: number;
-    readonly modelId: string;
-    readonly timeoutMs?: number;
-    readonly maxOutputChars?: number;
-}
-export interface ContextCompressionResult {
-    readonly text: string;
-    readonly method: ContextBudgetCompressionMethod;
-    readonly adapterId: string;
-    readonly input: TokenCountResult;
-    readonly output: TokenCountResult;
-    readonly notes: readonly string[];
-}
-export interface ContextCompressorAdapter {
-    readonly id: string;
-    readonly priority: number;
-    isAvailable(): Promise<boolean>;
-    compress(request: ContextCompressionRequest): Promise<ContextCompressionResult>;
-}
-export interface CommandRunRequest {
-    readonly command: string;
-    readonly args: readonly string[];
-    readonly input: string;
-    readonly timeoutMs: number;
-}
-export interface CommandRunResult {
-    readonly exitCode: number | null;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly timedOut: boolean;
-}
-export interface CommandRunner {
-    run(request: CommandRunRequest): Promise<CommandRunResult>;
-}
-export interface CliCompressorOptions {
-    readonly command?: string;
-    readonly runner?: CommandRunner;
-    readonly tokenCounter?: TokenCounterAdapter;
-}
-export declare function createNodeCommandRunner(): CommandRunner;
-export declare function createHeadroomCliCompressor(options?: CliCompressorOptions): ContextCompressorAdapter;
-export declare function createLlmlinguaCliCompressor(options?: CliCompressorOptions): ContextCompressorAdapter;
-export declare function createContextCompressorForMode(mode: ContextBudgetCompressorMode, options?: CliCompressorOptions): ContextCompressorAdapter | undefined;
-export declare function createCompressorRegistry(adapters: readonly ContextCompressorAdapter[]): ContextCompressorAdapter;
-//# sourceMappingURL=context-budget-compressors.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"context-budget-compressors.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-compressors.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,2BAA2B,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,CAAC;AACpF,MAAM,MAAM,8BAA8B,GAAG,YAAY,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;CAC5C;AAKD,wBAAgB,uBAAuB,IAAI,aAAa,CAqCvD;AAED,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,wBAAwB,CASxG;AAED,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,oBAAyB,GAAG,wBAAwB,CASzG;AAED,wBAAgB,8BAA8B,CAC7C,IAAI,EAAE,2BAA2B,EACjC,OAAO,GAAE,oBAAyB,GAChC,wBAAwB,GAAG,SAAS,CAWtC;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,GAAG,wBAAwB,CAwBhH","sourcesContent":["import { spawn } from \"node:child_process\";\nimport {\n\tcreateFallbackTokenCounter,\n\ttype TokenCounterAdapter,\n\ttype TokenCountResult,\n} from \"./context-budget-token-counter.ts\";\n\nexport type ContextBudgetCompressorMode = \"off\" | \"auto\" | \"headroom\" | \"llmlingua\";\nexport type ContextBudgetCompressionMethod = \"compressed\" | \"none\";\n\nexport interface ContextCompressionRequest {\n\treadonly text: string;\n\treadonly targetTokens: number;\n\treadonly modelId: string;\n\treadonly timeoutMs?: number;\n\treadonly maxOutputChars?: number;\n}\n\nexport interface ContextCompressionResult {\n\treadonly text: string;\n\treadonly method: ContextBudgetCompressionMethod;\n\treadonly adapterId: string;\n\treadonly input: TokenCountResult;\n\treadonly output: TokenCountResult;\n\treadonly notes: readonly string[];\n}\n\nexport interface ContextCompressorAdapter {\n\treadonly id: string;\n\treadonly priority: number;\n\tisAvailable(): Promise<boolean>;\n\tcompress(request: ContextCompressionRequest): Promise<ContextCompressionResult>;\n}\n\nexport interface CommandRunRequest {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly input: string;\n\treadonly timeoutMs: number;\n}\n\nexport interface CommandRunResult {\n\treadonly exitCode: number | null;\n\treadonly stdout: string;\n\treadonly stderr: string;\n\treadonly timedOut: boolean;\n}\n\nexport interface CommandRunner {\n\trun(request: CommandRunRequest): Promise<CommandRunResult>;\n}\n\nexport interface CliCompressorOptions {\n\treadonly command?: string;\n\treadonly runner?: CommandRunner;\n\treadonly tokenCounter?: TokenCounterAdapter;\n}\n\nconst DEFAULT_TIMEOUT_MS = 15_000;\nconst DEFAULT_MAX_OUTPUT_CHARS = 400_000;\n\nexport function createNodeCommandRunner(): CommandRunner {\n\treturn {\n\t\trun(request) {\n\t\t\treturn new Promise((resolve) => {\n\t\t\t\tconst child = spawn(request.command, [...request.args], { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n\t\t\t\tlet stdout = \"\";\n\t\t\t\tlet stderr = \"\";\n\t\t\t\tlet settled = false;\n\t\t\t\tconst timeout = setTimeout(() => {\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tchild.kill(\"SIGTERM\");\n\t\t\t\t\tresolve({ exitCode: null, stdout, stderr, timedOut: true });\n\t\t\t\t}, request.timeoutMs);\n\t\t\t\tchild.stdout.setEncoding(\"utf8\");\n\t\t\t\tchild.stderr.setEncoding(\"utf8\");\n\t\t\t\tchild.stdout.on(\"data\", (chunk: string) => {\n\t\t\t\t\tstdout += chunk;\n\t\t\t\t});\n\t\t\t\tchild.stderr.on(\"data\", (chunk: string) => {\n\t\t\t\t\tstderr += chunk;\n\t\t\t\t});\n\t\t\t\tchild.on(\"error\", (error) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tclearTimeout(timeout);\n\t\t\t\t\tresolve({ exitCode: null, stdout, stderr: error.message, timedOut: false });\n\t\t\t\t});\n\t\t\t\tchild.on(\"close\", (exitCode) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tclearTimeout(timeout);\n\t\t\t\t\tresolve({ exitCode, stdout, stderr, timedOut: false });\n\t\t\t\t});\n\t\t\t\tchild.stdin.end(request.input, \"utf8\");\n\t\t\t});\n\t\t},\n\t};\n}\n\nexport function createHeadroomCliCompressor(options: CliCompressorOptions = {}): ContextCompressorAdapter {\n\treturn createCliCompressor({\n\t\tid: \"headroom-cli\",\n\t\tpriority: 80,\n\t\tcommand: options.command ?? \"headroom\",\n\t\targs: (request) => [\"compress\", \"--target-tokens\", String(request.targetTokens), \"--model\", request.modelId],\n\t\trunner: options.runner,\n\t\ttokenCounter: options.tokenCounter,\n\t});\n}\n\nexport function createLlmlinguaCliCompressor(options: CliCompressorOptions = {}): ContextCompressorAdapter {\n\treturn createCliCompressor({\n\t\tid: \"llmlingua-cli\",\n\t\tpriority: 60,\n\t\tcommand: options.command ?? \"llmlingua\",\n\t\targs: (request) => [\"compress\", \"--target-tokens\", String(request.targetTokens), \"--model\", request.modelId],\n\t\trunner: options.runner,\n\t\ttokenCounter: options.tokenCounter,\n\t});\n}\n\nexport function createContextCompressorForMode(\n\tmode: ContextBudgetCompressorMode,\n\toptions: CliCompressorOptions = {},\n): ContextCompressorAdapter | undefined {\n\tif (mode === \"off\") {\n\t\treturn undefined;\n\t}\n\tif (mode === \"headroom\") {\n\t\treturn createHeadroomCliCompressor(options);\n\t}\n\tif (mode === \"llmlingua\") {\n\t\treturn createLlmlinguaCliCompressor(options);\n\t}\n\treturn createCompressorRegistry([createHeadroomCliCompressor(options), createLlmlinguaCliCompressor(options)]);\n}\n\nexport function createCompressorRegistry(adapters: readonly ContextCompressorAdapter[]): ContextCompressorAdapter {\n\tconst ordered = [...adapters].sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));\n\treturn {\n\t\tid: \"context-compressor-registry\",\n\t\tpriority: 100,\n\t\tisAvailable: async () => true,\n\t\tasync compress(request) {\n\t\t\tconst notes: string[] = [];\n\t\t\tfor (const adapter of ordered) {\n\t\t\t\ttry {\n\t\t\t\t\tif (!(await adapter.isAvailable())) {\n\t\t\t\t\t\tnotes.push(`${adapter.id}:unavailable`);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await adapter.compress(request);\n\t\t\t\t\treturn { ...result, notes: [...notes, ...result.notes] };\n\t\t\t\t} catch (error) {\n\t\t\t\t\tconst message = error instanceof Error ? error.message : \"unknown compressor failure\";\n\t\t\t\t\tnotes.push(`${adapter.id}:failed:${message}`);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn createNoCompressionResult(request, createFallbackTokenCounter(), notes);\n\t\t},\n\t};\n}\n\ninterface CliCompressorInternalOptions {\n\treadonly id: string;\n\treadonly priority: number;\n\treadonly command: string;\n\treadonly args: (request: ContextCompressionRequest) => readonly string[];\n\treadonly runner?: CommandRunner;\n\treadonly tokenCounter?: TokenCounterAdapter;\n}\n\nfunction createCliCompressor(options: CliCompressorInternalOptions): ContextCompressorAdapter {\n\tconst runner = options.runner ?? createNodeCommandRunner();\n\tconst tokenCounter = options.tokenCounter ?? createFallbackTokenCounter();\n\treturn {\n\t\tid: options.id,\n\t\tpriority: options.priority,\n\t\tasync isAvailable() {\n\t\t\tconst result = await runner.run({\n\t\t\t\tcommand: options.command,\n\t\t\t\targs: [\"--version\"],\n\t\t\t\tinput: \"\",\n\t\t\t\ttimeoutMs: 3_000,\n\t\t\t});\n\t\t\treturn result.exitCode === 0 && !result.timedOut;\n\t\t},\n\t\tasync compress(request) {\n\t\t\tconst input = tokenCounter.countText(request.text, request.modelId);\n\t\t\tif (input.tokens <= request.targetTokens) {\n\t\t\t\treturn createNoCompressionResult(request, tokenCounter, [`${options.id}:already-within-budget`]);\n\t\t\t}\n\t\t\tconst timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\t\t\tconst result = await runner.run({\n\t\t\t\tcommand: options.command,\n\t\t\t\targs: options.args(request),\n\t\t\t\tinput: request.text,\n\t\t\t\ttimeoutMs,\n\t\t\t});\n\t\t\tif (result.timedOut) {\n\t\t\t\treturn createNoCompressionResult(request, tokenCounter, [`${options.id}:timeout`]);\n\t\t\t}\n\t\t\tif (result.exitCode !== 0) {\n\t\t\t\treturn createNoCompressionResult(request, tokenCounter, [\n\t\t\t\t\t`${options.id}:exit:${result.exitCode ?? \"null\"}`,\n\t\t\t\t]);\n\t\t\t}\n\t\t\tconst maxOutputChars = request.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;\n\t\t\tconst outputText = result.stdout.slice(0, maxOutputChars);\n\t\t\tif (outputText.trim().length === 0) {\n\t\t\t\treturn createNoCompressionResult(request, tokenCounter, [`${options.id}:empty-output`]);\n\t\t\t}\n\t\t\tconst output = tokenCounter.countText(outputText, request.modelId);\n\t\t\treturn {\n\t\t\t\ttext: outputText,\n\t\t\t\tmethod: \"compressed\",\n\t\t\t\tadapterId: options.id,\n\t\t\t\tinput,\n\t\t\t\toutput,\n\t\t\t\tnotes: outputText.length < result.stdout.length ? [`${options.id}:output-truncated`] : [`${options.id}:ok`],\n\t\t\t};\n\t\t},\n\t};\n}\n\nfunction createNoCompressionResult(\n\trequest: ContextCompressionRequest,\n\ttokenCounter: TokenCounterAdapter,\n\tnotes: readonly string[],\n): ContextCompressionResult {\n\tconst input = tokenCounter.countText(request.text, request.modelId);\n\treturn {\n\t\ttext: request.text,\n\t\tmethod: \"none\",\n\t\tadapterId: \"none\",\n\t\tinput,\n\t\toutput: input,\n\t\tnotes,\n\t};\n}\n"]}