open-multi-agent-kit 1.0.0 → 1.2.2

package/dist/core/compaction/control-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-state.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/control-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAWD,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,GAAG,sBAAsB,GAAG,IAAI,CAcxG;AAED;;;;GAIG;AACH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO5D;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,GAAG;IAC7E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAOA;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAYtF","sourcesContent":["/**\n * Host control snapshot bound into a compaction envelope's preserved provenance.\n *\n * A natural-language summary cannot restore the obligation set: if the only\n * record of \"what is still open\" is prose the summarizer wrote, a dropped line\n * silently closes real work. The host supplies this structured snapshot\n * instead, and the compaction commit compares its digest so a summary generated\n * under different control state is discarded rather than committed.\n *\n * Producer output is untrusted input here: malformed shapes fail closed instead\n * of degrading into an empty-but-valid checkpoint, which would look like\n * \"nothing was open\" to every later reader.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { sanitizeBinaryOutput } from \"../../utils/shell.ts\";\nimport { redactSensitiveTextForced } from \"../redaction.ts\";\nimport { redactCredentialShapedContent } from \"./transaction.ts\";\n\n/** Envelope validators reject credential shapes and control characters outright. */\nconst MAX_PROVENANCE_TEXT = 4096;\n\nexport interface CompactionControlState {\n\treadonly openTasks: readonly string[];\n\treadonly blockerReasons: readonly string[];\n\treadonly branch: string | null;\n}\n\nconst MAX_CONTROL_STATE_ITEMS = 1024;\nconst MAX_CONTROL_STATE_TEXT = 16_384;\n\nfunction assertControlStateText(value: unknown, field: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.length > MAX_CONTROL_STATE_TEXT) {\n\t\tthrow new TypeError(`control state ${field} must be a bounded string`);\n\t}\n}\n\n/** Validate producer output; malformed input fails closed, never degrades to an empty checkpoint. */\nexport function validateControlState(value: CompactionControlState | null): CompactionControlState | null {\n\tif (value === null) return null;\n\tif (typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new TypeError(\"control state must be an object or null\");\n\t}\n\tfor (const field of [\"openTasks\", \"blockerReasons\"] as const) {\n\t\tconst list = value[field];\n\t\tif (!Array.isArray(list) || list.length > MAX_CONTROL_STATE_ITEMS) {\n\t\t\tthrow new TypeError(`control state ${field} must be a bounded array`);\n\t\t}\n\t\tfor (const item of list) assertControlStateText(item, `${field} item`);\n\t}\n\tif (value.branch !== null) assertControlStateText(value.branch, \"branch\");\n\treturn value;\n}\n\n/**\n * Digest the snapshot deterministically. Null stays null so \"no control\n * authority attached\" stays distinguishable from \"authority reporting nothing\n * open\" — the transition between them is itself a change worth discarding on.\n */\n/**\n * Make one control-state string safe for the envelope validators.\n *\n * Returns `[REDACTED]` rather than an empty string when sanitization consumes\n * everything: the validators reject empty entries, and dropping the entry would\n * quietly reduce the open-task count instead of preserving that work exists.\n */\nexport function sanitizeProvenanceText(value: string): string {\n\tconst sanitized = redactCredentialShapedContent(\n\t\tsanitizeBinaryOutput(redactSensitiveTextForced(value.trim()))\n\t\t\t.replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]/gu, \"\")\n\t\t\t.slice(0, MAX_PROVENANCE_TEXT),\n\t);\n\treturn sanitized.length > 0 ? sanitized : \"[REDACTED]\";\n}\n\n/** Project a control snapshot onto the envelope's preserved-provenance fields. */\nexport function controlStateProvenance(state: CompactionControlState | null): {\n\treadonly openTasks: readonly string[];\n\treadonly blockerReasons: readonly string[];\n\treadonly branch: string | null;\n} {\n\tif (state === null) return { openTasks: [], blockerReasons: [], branch: null };\n\treturn {\n\t\topenTasks: state.openTasks.map(sanitizeProvenanceText),\n\t\tblockerReasons: state.blockerReasons.map(sanitizeProvenanceText),\n\t\tbranch: state.branch == null ? null : sanitizeProvenanceText(state.branch),\n\t};\n}\n\nexport function controlStateDigest(state: CompactionControlState | null): string | null {\n\tif (state === null) return null;\n\treturn createHash(\"sha256\")\n\t\t.update(\n\t\t\tJSON.stringify({\n\t\t\t\topenTasks: [...state.openTasks],\n\t\t\t\tblockerReasons: [...state.blockerReasons],\n\t\t\t\tbranch: state.branch,\n\t\t\t}),\n\t\t\t\"utf8\",\n\t\t)\n\t\t.digest(\"hex\");\n}\n"]}

package/dist/core/compaction/control-state.js

@@ -0,0 +1,85 @@
+/**
+ * Host control snapshot bound into a compaction envelope's preserved provenance.
+ *
+ * A natural-language summary cannot restore the obligation set: if the only
+ * record of "what is still open" is prose the summarizer wrote, a dropped line
+ * silently closes real work. The host supplies this structured snapshot
+ * instead, and the compaction commit compares its digest so a summary generated
+ * under different control state is discarded rather than committed.
+ *
+ * Producer output is untrusted input here: malformed shapes fail closed instead
+ * of degrading into an empty-but-valid checkpoint, which would look like
+ * "nothing was open" to every later reader.
+ */
+import { createHash } from "node:crypto";
+import { sanitizeBinaryOutput } from "../../utils/shell.js";
+import { redactSensitiveTextForced } from "../redaction.js";
+import { redactCredentialShapedContent } from "./transaction.js";
+/** Envelope validators reject credential shapes and control characters outright. */
+const MAX_PROVENANCE_TEXT = 4096;
+const MAX_CONTROL_STATE_ITEMS = 1024;
+const MAX_CONTROL_STATE_TEXT = 16_384;
+function assertControlStateText(value, field) {
+    if (typeof value !== "string" || value.length > MAX_CONTROL_STATE_TEXT) {
+        throw new TypeError(`control state ${field} must be a bounded string`);
+    }
+}
+/** Validate producer output; malformed input fails closed, never degrades to an empty checkpoint. */
+export function validateControlState(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("control state must be an object or null");
+    }
+    for (const field of ["openTasks", "blockerReasons"]) {
+        const list = value[field];
+        if (!Array.isArray(list) || list.length > MAX_CONTROL_STATE_ITEMS) {
+            throw new TypeError(`control state ${field} must be a bounded array`);
+        }
+        for (const item of list)
+            assertControlStateText(item, `${field} item`);
+    }
+    if (value.branch !== null)
+        assertControlStateText(value.branch, "branch");
+    return value;
+}
+/**
+ * Digest the snapshot deterministically. Null stays null so "no control
+ * authority attached" stays distinguishable from "authority reporting nothing
+ * open" — the transition between them is itself a change worth discarding on.
+ */
+/**
+ * Make one control-state string safe for the envelope validators.
+ *
+ * Returns `[REDACTED]` rather than an empty string when sanitization consumes
+ * everything: the validators reject empty entries, and dropping the entry would
+ * quietly reduce the open-task count instead of preserving that work exists.
+ */
+export function sanitizeProvenanceText(value) {
+    const sanitized = redactCredentialShapedContent(sanitizeBinaryOutput(redactSensitiveTextForced(value.trim()))
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "")
+        .slice(0, MAX_PROVENANCE_TEXT));
+    return sanitized.length > 0 ? sanitized : "[REDACTED]";
+}
+/** Project a control snapshot onto the envelope's preserved-provenance fields. */
+export function controlStateProvenance(state) {
+    if (state === null)
+        return { openTasks: [], blockerReasons: [], branch: null };
+    return {
+        openTasks: state.openTasks.map(sanitizeProvenanceText),
+        blockerReasons: state.blockerReasons.map(sanitizeProvenanceText),
+        branch: state.branch == null ? null : sanitizeProvenanceText(state.branch),
+    };
+}
+export function controlStateDigest(state) {
+    if (state === null)
+        return null;
+    return createHash("sha256")
+        .update(JSON.stringify({
+        openTasks: [...state.openTasks],
+        blockerReasons: [...state.blockerReasons],
+        branch: state.branch,
+    }), "utf8")
+        .digest("hex");
+}
+//# sourceMappingURL=control-state.js.map

package/dist/core/compaction/control-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-state.js","sourceRoot":"","sources":["../../../src/core/compaction/control-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAEjE,oFAAoF;AACpF,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAQjC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC,SAAS,sBAAsB,CAAC,KAAc,EAAE,KAAa,EAA2B;IACvF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;QACxE,MAAM,IAAI,SAAS,CAAC,iBAAiB,KAAK,2BAA2B,CAAC,CAAC;IACxE,CAAC;AAAA,CACD;AAED,qGAAqG;AACrG,MAAM,UAAU,oBAAoB,CAAC,KAAoC,EAAiC;IACzG,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IAChE,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAU,EAAE,CAAC;QAC9D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;YACnE,MAAM,IAAI,SAAS,CAAC,iBAAiB,KAAK,0BAA0B,CAAC,CAAC;QACvE,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;QAAE,sBAAsB,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1E,OAAO,KAAK,CAAC;AAAA,CACb;AAED;;;;GAIG;AACH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa,EAAU;IAC7D,MAAM,SAAS,GAAG,6BAA6B,CAC9C,oBAAoB,CAAC,yBAAyB,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;SAC3D,OAAO,CAAC,kDAAkD,EAAE,EAAE,CAAC;SAC/D,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAC/B,CAAC;IACF,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC;AAAA,CACvD;AAED,kFAAkF;AAClF,MAAM,UAAU,sBAAsB,CAAC,KAAoC,EAIzE;IACD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC/E,OAAO;QACN,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,CAAC;QACtD,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,sBAAsB,CAAC;QAChE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,CAAC,MAAM,CAAC;KAC1E,CAAC;AAAA,CACF;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAoC,EAAiB;IACvF,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACzB,MAAM,CACN,IAAI,CAAC,SAAS,CAAC;QACd,SAAS,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;QAC/B,cAAc,EAAE,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC;QACzC,MAAM,EAAE,KAAK,CAAC,MAAM;KACpB,CAAC,EACF,MAAM,CACN;SACA,MAAM,CAAC,KAAK,CAAC,CAAC;AAAA,CAChB","sourcesContent":["/**\n * Host control snapshot bound into a compaction envelope's preserved provenance.\n *\n * A natural-language summary cannot restore the obligation set: if the only\n * record of \"what is still open\" is prose the summarizer wrote, a dropped line\n * silently closes real work. The host supplies this structured snapshot\n * instead, and the compaction commit compares its digest so a summary generated\n * under different control state is discarded rather than committed.\n *\n * Producer output is untrusted input here: malformed shapes fail closed instead\n * of degrading into an empty-but-valid checkpoint, which would look like\n * \"nothing was open\" to every later reader.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { sanitizeBinaryOutput } from \"../../utils/shell.ts\";\nimport { redactSensitiveTextForced } from \"../redaction.ts\";\nimport { redactCredentialShapedContent } from \"./transaction.ts\";\n\n/** Envelope validators reject credential shapes and control characters outright. */\nconst MAX_PROVENANCE_TEXT = 4096;\n\nexport interface CompactionControlState {\n\treadonly openTasks: readonly string[];\n\treadonly blockerReasons: readonly string[];\n\treadonly branch: string | null;\n}\n\nconst MAX_CONTROL_STATE_ITEMS = 1024;\nconst MAX_CONTROL_STATE_TEXT = 16_384;\n\nfunction assertControlStateText(value: unknown, field: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.length > MAX_CONTROL_STATE_TEXT) {\n\t\tthrow new TypeError(`control state ${field} must be a bounded string`);\n\t}\n}\n\n/** Validate producer output; malformed input fails closed, never degrades to an empty checkpoint. */\nexport function validateControlState(value: CompactionControlState | null): CompactionControlState | null {\n\tif (value === null) return null;\n\tif (typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new TypeError(\"control state must be an object or null\");\n\t}\n\tfor (const field of [\"openTasks\", \"blockerReasons\"] as const) {\n\t\tconst list = value[field];\n\t\tif (!Array.isArray(list) || list.length > MAX_CONTROL_STATE_ITEMS) {\n\t\t\tthrow new TypeError(`control state ${field} must be a bounded array`);\n\t\t}\n\t\tfor (const item of list) assertControlStateText(item, `${field} item`);\n\t}\n\tif (value.branch !== null) assertControlStateText(value.branch, \"branch\");\n\treturn value;\n}\n\n/**\n * Digest the snapshot deterministically. Null stays null so \"no control\n * authority attached\" stays distinguishable from \"authority reporting nothing\n * open\" — the transition between them is itself a change worth discarding on.\n */\n/**\n * Make one control-state string safe for the envelope validators.\n *\n * Returns `[REDACTED]` rather than an empty string when sanitization consumes\n * everything: the validators reject empty entries, and dropping the entry would\n * quietly reduce the open-task count instead of preserving that work exists.\n */\nexport function sanitizeProvenanceText(value: string): string {\n\tconst sanitized = redactCredentialShapedContent(\n\t\tsanitizeBinaryOutput(redactSensitiveTextForced(value.trim()))\n\t\t\t.replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]/gu, \"\")\n\t\t\t.slice(0, MAX_PROVENANCE_TEXT),\n\t);\n\treturn sanitized.length > 0 ? sanitized : \"[REDACTED]\";\n}\n\n/** Project a control snapshot onto the envelope's preserved-provenance fields. */\nexport function controlStateProvenance(state: CompactionControlState | null): {\n\treadonly openTasks: readonly string[];\n\treadonly blockerReasons: readonly string[];\n\treadonly branch: string | null;\n} {\n\tif (state === null) return { openTasks: [], blockerReasons: [], branch: null };\n\treturn {\n\t\topenTasks: state.openTasks.map(sanitizeProvenanceText),\n\t\tblockerReasons: state.blockerReasons.map(sanitizeProvenanceText),\n\t\tbranch: state.branch == null ? null : sanitizeProvenanceText(state.branch),\n\t};\n}\n\nexport function controlStateDigest(state: CompactionControlState | null): string | null {\n\tif (state === null) return null;\n\treturn createHash(\"sha256\")\n\t\t.update(\n\t\t\tJSON.stringify({\n\t\t\t\topenTasks: [...state.openTasks],\n\t\t\t\tblockerReasons: [...state.blockerReasons],\n\t\t\t\tbranch: state.branch,\n\t\t\t}),\n\t\t\t\"utf8\",\n\t\t)\n\t\t.digest(\"hex\");\n}\n"]}

package/dist/core/compaction/fallback.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What to do when compaction summarization cannot run.
+ *
+ * The resilience ladder, in order:
+ *   1. the resolved compaction model (caller's `summarize`),
+ *   2. the live session model — a pinned `compaction.model` can be quota-dead
+ *      while the model the user is actively talking to still serves traffic,
+ *   3. a deterministic trim that needs no model at all.
+ *
+ * Step 3 exists because the alternative is stranding the run: once context is
+ * over the window, a failed compaction means no later turn can succeed until
+ * the billing cycle resets.
+ *
+ * Kept out of `compaction.ts` so the ladder is unit-testable without an
+ * AgentSession, and so neither module carries the other's growth.
+ */
+import type { Model } from "omk-ai";
+import type { CompactionDetails, CompactionPreparation, CompactionResult } from "./compaction.ts";
+/**
+ * Detail shape unique to the no-model path. Kept here rather than on
+ * `CompactionDetails` so a reader of a normal entry never has to wonder why a
+ * `deterministicEmergency` flag exists on it.
+ */
+export interface DeterministicCompactionDetails extends CompactionDetails {
+    readonly deterministicEmergency: true;
+    /** Sanitized, bounded reason the model path was unavailable. */
+    readonly deterministicReason: string;
+}
+/**
+ * Compact without a model.
+ *
+ * Keeps exactly what `prepareCompaction()` already derived deterministically —
+ * the prior summary, source-bound user rules, and file operations — plus the
+ * recent window the cut point preserved. It never claims to be a model summary:
+ * the heading and `details.deterministicEmergency` mark it as a trim, because
+ * the dropped turns were discarded without semantic summarization.
+ *
+ * Takes no model, key, or stream function: the signature itself proves no
+ * provider call can occur on this path.
+ */
+export declare function compactDeterministic(preparation: CompactionPreparation, reason: string): CompactionResult;
+export interface SummarizationFallbackInput {
+    readonly preparation: CompactionPreparation;
+    readonly primaryModel: Model<any>;
+    /** The model the session is actually running, when known. */
+    readonly sessionModel: Model<any> | undefined;
+    /**
+     * Summarize on one model, resolving that model's own credentials. A
+     * cross-provider rescue must not inherit the failed model's key or headers.
+     */
+    readonly summarize: (model: Model<any>) => Promise<CompactionResult>;
+    readonly isAborted: () => boolean;
+    /**
+     * Rescue on every summarization failure, not only quota exhaustion.
+     * Overflow recovery is the session's last chance before the provider
+     * 400 strands it, so a non-quota failure (e.g. a failover candidate's
+     * entitlement 403 surfaced mid-chain) must also reach the trim — a
+     * persistent per-provider permission failure will not heal on retry.
+     * Manual/threshold compaction keeps the quota-only gate: a transient
+     * primary failure there must propagate as an error, not silently
+     * degrade the summary.
+     */
+    readonly alwaysRescue?: boolean;
+}
+/**
+ * Run the summarization ladder. Aborts and (without `alwaysRescue`)
+ * non-quota failures propagate unchanged — a transient 503 must retry its
+ * model, not silently degrade.
+ */
+export declare function summarizeWithFallback(input: SummarizationFallbackInput): Promise<CompactionResult>;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/core/compaction/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAYlG;;;;GAIG;AACH,MAAM,WAAW,8BAA+B,SAAQ,iBAAiB;IACxE,QAAQ,CAAC,sBAAsB,EAAE,IAAI,CAAC;IACtC,gEAAgE;IAChE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACrC;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAwDzG;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CAChC;AAMD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmBxG","sourcesContent":["/**\n * What to do when compaction summarization cannot run.\n *\n * The resilience ladder, in order:\n *   1. the resolved compaction model (caller's `summarize`),\n *   2. the live session model — a pinned `compaction.model` can be quota-dead\n *      while the model the user is actively talking to still serves traffic,\n *   3. a deterministic trim that needs no model at all.\n *\n * Step 3 exists because the alternative is stranding the run: once context is\n * over the window, a failed compaction means no later turn can succeed until\n * the billing cycle resets.\n *\n * Kept out of `compaction.ts` so the ladder is unit-testable without an\n * AgentSession, and so neither module carries the other's growth.\n */\n\nimport type { Model } from \"omk-ai\";\nimport { isQuotaExhaustionMessage } from \"../provider-resilience.ts\";\nimport { redactSensitiveTextForced } from \"../redaction.ts\";\nimport type { CompactionDetails, CompactionPreparation, CompactionResult } from \"./compaction.ts\";\nimport { applyCompactionKnowledgeTriage } from \"./knowledge-triage.ts\";\nimport { redactCredentialShapedContent } from \"./transaction.ts\";\nimport { computeFileLists, formatFileOperations } from \"./utils.ts\";\n\n/** Upper bound on the reason text persisted into the compaction entry. */\nconst DETERMINISTIC_REASON_MAX_CHARS = 512;\n/** Upper bound on the prior summary carried forward verbatim. */\nconst CARRIED_SUMMARY_MAX_CHARS = 16_384;\n\nconst DETERMINISTIC_EMERGENCY_HEADING = \"## Deterministic emergency compaction\";\n\n/**\n * Detail shape unique to the no-model path. Kept here rather than on\n * `CompactionDetails` so a reader of a normal entry never has to wonder why a\n * `deterministicEmergency` flag exists on it.\n */\nexport interface DeterministicCompactionDetails extends CompactionDetails {\n\treadonly deterministicEmergency: true;\n\t/** Sanitized, bounded reason the model path was unavailable. */\n\treadonly deterministicReason: string;\n}\n\nfunction boundedSanitizedText(value: string, maxChars: number): string {\n\tconst sanitized = redactCredentialShapedContent(redactSensitiveTextForced(value))\n\t\t.replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]/gu, \"\")\n\t\t.trim();\n\treturn sanitized.length <= maxChars ? sanitized : `${sanitized.slice(0, maxChars - 1)}\\u2026`;\n}\n\n/**\n * Compact without a model.\n *\n * Keeps exactly what `prepareCompaction()` already derived deterministically —\n * the prior summary, source-bound user rules, and file operations — plus the\n * recent window the cut point preserved. It never claims to be a model summary:\n * the heading and `details.deterministicEmergency` mark it as a trim, because\n * the dropped turns were discarded without semantic summarization.\n *\n * Takes no model, key, or stream function: the signature itself proves no\n * provider call can occur on this path.\n */\nexport function compactDeterministic(preparation: CompactionPreparation, reason: string): CompactionResult {\n\tconst {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tpreviousRuleHistory,\n\t\tcurrentRuleEntries,\n\t\tfileOps,\n\t} = preparation;\n\n\tif (!firstKeptEntryId) {\n\t\tthrow new Error(\"First kept entry has no UUID - session may need migration\");\n\t}\n\n\tconst safeReason = boundedSanitizedText(reason, DETERMINISTIC_REASON_MAX_CHARS);\n\tconst carried =\n\t\tpreviousSummary === undefined ? \"\" : boundedSanitizedText(previousSummary, CARRIED_SUMMARY_MAX_CHARS);\n\n\tconst sections = [\n\t\tDETERMINISTIC_EMERGENCY_HEADING,\n\t\t\"Model summarization was unavailable, so the context was trimmed deterministically \" +\n\t\t\t\"rather than leaving the session unable to continue. This is not a model-generated \" +\n\t\t\t\"summary: older turns were dropped without semantic summarization, and only the \" +\n\t\t\t\"structured state below plus the retained recent window survive.\",\n\t\t`Cause: ${safeReason.length > 0 ? safeReason : \"unspecified summarization failure\"}`,\n\t];\n\tif (carried.length > 0) {\n\t\tsections.push(`### Carried forward from the previous compaction\\n\\n${carried}`);\n\t}\n\n\tconst triage = applyCompactionKnowledgeTriage({\n\t\tgeneratedSummary: sections.join(\"\\n\\n\"),\n\t\tcurrentMessages: [...messagesToSummarize, ...turnPrefixMessages],\n\t\tcurrentEntries: currentRuleEntries,\n\t\tpreviousRules: previousRuleHistory?.rules,\n\t\tpreviousSummary,\n\t\tpreviousEntries: previousRuleHistory?.entries,\n\t});\n\n\tconst { readFiles, modifiedFiles } = computeFileLists(fileOps);\n\tconst summary = triage.summary + formatFileOperations(readFiles, modifiedFiles);\n\n\treturn {\n\t\tsummary,\n\t\tfirstKeptEntryId,\n\t\ttokensBefore,\n\t\tdetails: {\n\t\t\treadFiles,\n\t\t\tmodifiedFiles,\n\t\t\tpreservedRules: [...triage.preservedRules],\n\t\t\tdeterministicEmergency: true,\n\t\t\tdeterministicReason: safeReason,\n\t\t} satisfies DeterministicCompactionDetails,\n\t};\n}\n\nexport interface SummarizationFallbackInput {\n\treadonly preparation: CompactionPreparation;\n\treadonly primaryModel: Model<any>;\n\t/** The model the session is actually running, when known. */\n\treadonly sessionModel: Model<any> | undefined;\n\t/**\n\t * Summarize on one model, resolving that model's own credentials. A\n\t * cross-provider rescue must not inherit the failed model's key or headers.\n\t */\n\treadonly summarize: (model: Model<any>) => Promise<CompactionResult>;\n\treadonly isAborted: () => boolean;\n\t/**\n\t * Rescue on every summarization failure, not only quota exhaustion.\n\t * Overflow recovery is the session's last chance before the provider\n\t * 400 strands it, so a non-quota failure (e.g. a failover candidate's\n\t * entitlement 403 surfaced mid-chain) must also reach the trim — a\n\t * persistent per-provider permission failure will not heal on retry.\n\t * Manual/threshold compaction keeps the quota-only gate: a transient\n\t * primary failure there must propagate as an error, not silently\n\t * degrade the summary.\n\t */\n\treadonly alwaysRescue?: boolean;\n}\n\nfunction sameModel(a: Model<any>, b: Model<any>): boolean {\n\treturn a.provider === b.provider && a.id === b.id;\n}\n\n/**\n * Run the summarization ladder. Aborts and (without `alwaysRescue`)\n * non-quota failures propagate unchanged — a transient 503 must retry its\n * model, not silently degrade.\n */\nexport async function summarizeWithFallback(input: SummarizationFallbackInput): Promise<CompactionResult> {\n\ttry {\n\t\treturn await input.summarize(input.primaryModel);\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tif (input.isAborted()) throw error;\n\t\tif (!input.alwaysRescue && !isQuotaExhaustionMessage(message)) throw error;\n\n\t\tconst session = input.sessionModel;\n\t\tif (session !== undefined && !sameModel(session, input.primaryModel)) {\n\t\t\ttry {\n\t\t\t\treturn await input.summarize(session);\n\t\t\t} catch (rescueError) {\n\t\t\t\tif (input.isAborted()) throw rescueError;\n\t\t\t\t// Session model could not help either; fall through to the trim.\n\t\t\t}\n\t\t}\n\t\treturn compactDeterministic(input.preparation, message);\n\t}\n}\n"]}

package/dist/core/compaction/fallback.js

@@ -0,0 +1,118 @@
+/**
+ * What to do when compaction summarization cannot run.
+ *
+ * The resilience ladder, in order:
+ *   1. the resolved compaction model (caller's `summarize`),
+ *   2. the live session model — a pinned `compaction.model` can be quota-dead
+ *      while the model the user is actively talking to still serves traffic,
+ *   3. a deterministic trim that needs no model at all.
+ *
+ * Step 3 exists because the alternative is stranding the run: once context is
+ * over the window, a failed compaction means no later turn can succeed until
+ * the billing cycle resets.
+ *
+ * Kept out of `compaction.ts` so the ladder is unit-testable without an
+ * AgentSession, and so neither module carries the other's growth.
+ */
+import { isQuotaExhaustionMessage } from "../provider-resilience.js";
+import { redactSensitiveTextForced } from "../redaction.js";
+import { applyCompactionKnowledgeTriage } from "./knowledge-triage.js";
+import { redactCredentialShapedContent } from "./transaction.js";
+import { computeFileLists, formatFileOperations } from "./utils.js";
+/** Upper bound on the reason text persisted into the compaction entry. */
+const DETERMINISTIC_REASON_MAX_CHARS = 512;
+/** Upper bound on the prior summary carried forward verbatim. */
+const CARRIED_SUMMARY_MAX_CHARS = 16_384;
+const DETERMINISTIC_EMERGENCY_HEADING = "## Deterministic emergency compaction";
+function boundedSanitizedText(value, maxChars) {
+    const sanitized = redactCredentialShapedContent(redactSensitiveTextForced(value))
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "")
+        .trim();
+    return sanitized.length <= maxChars ? sanitized : `${sanitized.slice(0, maxChars - 1)}\u2026`;
+}
+/**
+ * Compact without a model.
+ *
+ * Keeps exactly what `prepareCompaction()` already derived deterministically —
+ * the prior summary, source-bound user rules, and file operations — plus the
+ * recent window the cut point preserved. It never claims to be a model summary:
+ * the heading and `details.deterministicEmergency` mark it as a trim, because
+ * the dropped turns were discarded without semantic summarization.
+ *
+ * Takes no model, key, or stream function: the signature itself proves no
+ * provider call can occur on this path.
+ */
+export function compactDeterministic(preparation, reason) {
+    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, tokensBefore, previousSummary, previousRuleHistory, currentRuleEntries, fileOps, } = preparation;
+    if (!firstKeptEntryId) {
+        throw new Error("First kept entry has no UUID - session may need migration");
+    }
+    const safeReason = boundedSanitizedText(reason, DETERMINISTIC_REASON_MAX_CHARS);
+    const carried = previousSummary === undefined ? "" : boundedSanitizedText(previousSummary, CARRIED_SUMMARY_MAX_CHARS);
+    const sections = [
+        DETERMINISTIC_EMERGENCY_HEADING,
+        "Model summarization was unavailable, so the context was trimmed deterministically " +
+            "rather than leaving the session unable to continue. This is not a model-generated " +
+            "summary: older turns were dropped without semantic summarization, and only the " +
+            "structured state below plus the retained recent window survive.",
+        `Cause: ${safeReason.length > 0 ? safeReason : "unspecified summarization failure"}`,
+    ];
+    if (carried.length > 0) {
+        sections.push(`### Carried forward from the previous compaction\n\n${carried}`);
+    }
+    const triage = applyCompactionKnowledgeTriage({
+        generatedSummary: sections.join("\n\n"),
+        currentMessages: [...messagesToSummarize, ...turnPrefixMessages],
+        currentEntries: currentRuleEntries,
+        previousRules: previousRuleHistory?.rules,
+        previousSummary,
+        previousEntries: previousRuleHistory?.entries,
+    });
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    const summary = triage.summary + formatFileOperations(readFiles, modifiedFiles);
+    return {
+        summary,
+        firstKeptEntryId,
+        tokensBefore,
+        details: {
+            readFiles,
+            modifiedFiles,
+            preservedRules: [...triage.preservedRules],
+            deterministicEmergency: true,
+            deterministicReason: safeReason,
+        },
+    };
+}
+function sameModel(a, b) {
+    return a.provider === b.provider && a.id === b.id;
+}
+/**
+ * Run the summarization ladder. Aborts and (without `alwaysRescue`)
+ * non-quota failures propagate unchanged — a transient 503 must retry its
+ * model, not silently degrade.
+ */
+export async function summarizeWithFallback(input) {
+    try {
+        return await input.summarize(input.primaryModel);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (input.isAborted())
+            throw error;
+        if (!input.alwaysRescue && !isQuotaExhaustionMessage(message))
+            throw error;
+        const session = input.sessionModel;
+        if (session !== undefined && !sameModel(session, input.primaryModel)) {
+            try {
+                return await input.summarize(session);
+            }
+            catch (rescueError) {
+                if (input.isAborted())
+                    throw rescueError;
+                // Session model could not help either; fall through to the trim.
+            }
+        }
+        return compactDeterministic(input.preparation, message);
+    }
+}
+//# sourceMappingURL=fallback.js.map

package/dist/core/compaction/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../../src/core/compaction/fallback.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What to do when compaction summarization cannot run.\n *\n * The resilience ladder, in order:\n *   1. the resolved compaction model (caller's `summarize`),\n *   2. the live session model — a pinned `compaction.model` can be quota-dead\n *      while the model the user is actively talking to still serves traffic,\n *   3. a deterministic trim that needs no model at all.\n *\n * Step 3 exists because the alternative is stranding the run: once context is\n * over the window, a failed compaction means no later turn can succeed until\n * the billing cycle resets.\n *\n * Kept out of `compaction.ts` so the ladder is unit-testable without an\n * AgentSession, and so neither module carries the other's growth.\n */\n\nimport type { Model } from \"omk-ai\";\nimport { isQuotaExhaustionMessage } from \"../provider-resilience.ts\";\nimport { redactSensitiveTextForced } from \"../redaction.ts\";\nimport type { CompactionDetails, CompactionPreparation, CompactionResult } from \"./compaction.ts\";\nimport { applyCompactionKnowledgeTriage } from \"./knowledge-triage.ts\";\nimport { redactCredentialShapedContent } from \"./transaction.ts\";\nimport { computeFileLists, formatFileOperations } from \"./utils.ts\";\n\n/** Upper bound on the reason text persisted into the compaction entry. */\nconst DETERMINISTIC_REASON_MAX_CHARS = 512;\n/** Upper bound on the prior summary carried forward verbatim. */\nconst CARRIED_SUMMARY_MAX_CHARS = 16_384;\n\nconst DETERMINISTIC_EMERGENCY_HEADING = \"## Deterministic emergency compaction\";\n\n/**\n * Detail shape unique to the no-model path. Kept here rather than on\n * `CompactionDetails` so a reader of a normal entry never has to wonder why a\n * `deterministicEmergency` flag exists on it.\n */\nexport interface DeterministicCompactionDetails extends CompactionDetails {\n\treadonly deterministicEmergency: true;\n\t/** Sanitized, bounded reason the model path was unavailable. */\n\treadonly deterministicReason: string;\n}\n\nfunction boundedSanitizedText(value: string, maxChars: number): string {\n\tconst sanitized = redactCredentialShapedContent(redactSensitiveTextForced(value))\n\t\t.replace(/[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]/gu, \"\")\n\t\t.trim();\n\treturn sanitized.length <= maxChars ? sanitized : `${sanitized.slice(0, maxChars - 1)}\\u2026`;\n}\n\n/**\n * Compact without a model.\n *\n * Keeps exactly what `prepareCompaction()` already derived deterministically —\n * the prior summary, source-bound user rules, and file operations — plus the\n * recent window the cut point preserved. It never claims to be a model summary:\n * the heading and `details.deterministicEmergency` mark it as a trim, because\n * the dropped turns were discarded without semantic summarization.\n *\n * Takes no model, key, or stream function: the signature itself proves no\n * provider call can occur on this path.\n */\nexport function compactDeterministic(preparation: CompactionPreparation, reason: string): CompactionResult {\n\tconst {\n\t\tfirstKeptEntryId,\n\t\tmessagesToSummarize,\n\t\tturnPrefixMessages,\n\t\ttokensBefore,\n\t\tpreviousSummary,\n\t\tpreviousRuleHistory,\n\t\tcurrentRuleEntries,\n\t\tfileOps,\n\t} = preparation;\n\n\tif (!firstKeptEntryId) {\n\t\tthrow new Error(\"First kept entry has no UUID - session may need migration\");\n\t}\n\n\tconst safeReason = boundedSanitizedText(reason, DETERMINISTIC_REASON_MAX_CHARS);\n\tconst carried =\n\t\tpreviousSummary === undefined ? \"\" : boundedSanitizedText(previousSummary, CARRIED_SUMMARY_MAX_CHARS);\n\n\tconst sections = [\n\t\tDETERMINISTIC_EMERGENCY_HEADING,\n\t\t\"Model summarization was unavailable, so the context was trimmed deterministically \" +\n\t\t\t\"rather than leaving the session unable to continue. This is not a model-generated \" +\n\t\t\t\"summary: older turns were dropped without semantic summarization, and only the \" +\n\t\t\t\"structured state below plus the retained recent window survive.\",\n\t\t`Cause: ${safeReason.length > 0 ? safeReason : \"unspecified summarization failure\"}`,\n\t];\n\tif (carried.length > 0) {\n\t\tsections.push(`### Carried forward from the previous compaction\\n\\n${carried}`);\n\t}\n\n\tconst triage = applyCompactionKnowledgeTriage({\n\t\tgeneratedSummary: sections.join(\"\\n\\n\"),\n\t\tcurrentMessages: [...messagesToSummarize, ...turnPrefixMessages],\n\t\tcurrentEntries: currentRuleEntries,\n\t\tpreviousRules: previousRuleHistory?.rules,\n\t\tpreviousSummary,\n\t\tpreviousEntries: previousRuleHistory?.entries,\n\t});\n\n\tconst { readFiles, modifiedFiles } = computeFileLists(fileOps);\n\tconst summary = triage.summary + formatFileOperations(readFiles, modifiedFiles);\n\n\treturn {\n\t\tsummary,\n\t\tfirstKeptEntryId,\n\t\ttokensBefore,\n\t\tdetails: {\n\t\t\treadFiles,\n\t\t\tmodifiedFiles,\n\t\t\tpreservedRules: [...triage.preservedRules],\n\t\t\tdeterministicEmergency: true,\n\t\t\tdeterministicReason: safeReason,\n\t\t} satisfies DeterministicCompactionDetails,\n\t};\n}\n\nexport interface SummarizationFallbackInput {\n\treadonly preparation: CompactionPreparation;\n\treadonly primaryModel: Model<any>;\n\t/** The model the session is actually running, when known. */\n\treadonly sessionModel: Model<any> | undefined;\n\t/**\n\t * Summarize on one model, resolving that model's own credentials. A\n\t * cross-provider rescue must not inherit the failed model's key or headers.\n\t */\n\treadonly summarize: (model: Model<any>) => Promise<CompactionResult>;\n\treadonly isAborted: () => boolean;\n\t/**\n\t * Rescue on every summarization failure, not only quota exhaustion.\n\t * Overflow recovery is the session's last chance before the provider\n\t * 400 strands it, so a non-quota failure (e.g. a failover candidate's\n\t * entitlement 403 surfaced mid-chain) must also reach the trim — a\n\t * persistent per-provider permission failure will not heal on retry.\n\t * Manual/threshold compaction keeps the quota-only gate: a transient\n\t * primary failure there must propagate as an error, not silently\n\t * degrade the summary.\n\t */\n\treadonly alwaysRescue?: boolean;\n}\n\nfunction sameModel(a: Model<any>, b: Model<any>): boolean {\n\treturn a.provider === b.provider && a.id === b.id;\n}\n\n/**\n * Run the summarization ladder. Aborts and (without `alwaysRescue`)\n * non-quota failures propagate unchanged — a transient 503 must retry its\n * model, not silently degrade.\n */\nexport async function summarizeWithFallback(input: SummarizationFallbackInput): Promise<CompactionResult> {\n\ttry {\n\t\treturn await input.summarize(input.primaryModel);\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tif (input.isAborted()) throw error;\n\t\tif (!input.alwaysRescue && !isQuotaExhaustionMessage(message)) throw error;\n\n\t\tconst session = input.sessionModel;\n\t\tif (session !== undefined && !sameModel(session, input.primaryModel)) {\n\t\t\ttry {\n\t\t\t\treturn await input.summarize(session);\n\t\t\t} catch (rescueError) {\n\t\t\t\tif (input.isAborted()) throw rescueError;\n\t\t\t\t// Session model could not help either; fall through to the trim.\n\t\t\t}\n\t\t}\n\t\treturn compactDeterministic(input.preparation, message);\n\t}\n}\n"]}

package/dist/core/compaction/index.d.ts

@@ -3,6 +3,8 @@
  */
 export * from "./branch-summarization.ts";
 export * from "./compaction.ts";
+export * from "./control-state.ts";
+export * from "./fallback.ts";
 export * from "./hysteresis.ts";
 export * from "./knowledge-triage.ts";
 export * from "./model-policy.ts";

package/dist/core/compaction/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction and summarization utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./hysteresis.ts\";\nexport * from \"./knowledge-triage.ts\";\nexport * from \"./model-policy.ts\";\nexport * from \"./resume-policy.ts\";\nexport * from \"./transaction.ts\";\nexport * from \"./utils.ts\";\n"]}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction and summarization utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./control-state.ts\";\nexport * from \"./fallback.ts\";\nexport * from \"./hysteresis.ts\";\nexport * from \"./knowledge-triage.ts\";\nexport * from \"./model-policy.ts\";\nexport * from \"./resume-policy.ts\";\nexport * from \"./transaction.ts\";\nexport * from \"./utils.ts\";\n"]}

package/dist/core/compaction/index.js

@@ -3,6 +3,8 @@
  */
 export * from "./branch-summarization.js";
 export * from "./compaction.js";
+export * from "./control-state.js";
+export * from "./fallback.js";
 export * from "./hysteresis.js";
 export * from "./knowledge-triage.js";
 export * from "./model-policy.js";

package/dist/core/compaction/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction and summarization utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./hysteresis.ts\";\nexport * from \"./knowledge-triage.ts\";\nexport * from \"./model-policy.ts\";\nexport * from \"./resume-policy.ts\";\nexport * from \"./transaction.ts\";\nexport * from \"./utils.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction and summarization utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./control-state.ts\";\nexport * from \"./fallback.ts\";\nexport * from \"./hysteresis.ts\";\nexport * from \"./knowledge-triage.ts\";\nexport * from \"./model-policy.ts\";\nexport * from \"./resume-policy.ts\";\nexport * from \"./transaction.ts\";\nexport * from \"./utils.ts\";\n"]}

package/dist/core/compaction/model-failover.d.ts

@@ -0,0 +1,21 @@
+import type { Api, Model } from "omk-ai";
+export interface CompactionRequestAuth {
+    readonly apiKey?: string;
+    readonly headers?: Record<string, string>;
+}
+export interface CompactFailoverOptions {
+    /** Cross-provider candidates need their own credential; never replay the primary key. */
+    readonly resolveCandidateAuth?: (candidate: Model<Api>) => Promise<CompactionRequestAuth>;
+}
+interface ModelFailoverInput<T> {
+    readonly model: Model<Api>;
+    readonly auth: CompactionRequestAuth;
+    readonly signal?: AbortSignal;
+    readonly candidates?: readonly Model<Api>[];
+    readonly options?: CompactFailoverOptions;
+    readonly run: (model: Model<Api>, auth: CompactionRequestAuth) => Promise<T>;
+}
+/** Preserve the primary quota failure when no authenticated candidate can serve. */
+export declare function withCompactionModelFailover<T>(input: ModelFailoverInput<T>): Promise<T>;
+export {};
+//# sourceMappingURL=model-failover.d.ts.map

package/dist/core/compaction/model-failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-failover.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/model-failover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGzC,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,sBAAsB;IACtC,yFAAyF;IACzF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC1F;AAED,UAAU,kBAAkB,CAAC,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7E;AAED,oFAAoF;AACpF,wBAAsB,2BAA2B,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiC7F","sourcesContent":["import type { Api, Model } from \"omk-ai\";\nimport { isQuotaExhaustionMessage, isTerminalProviderErrorMessage } from \"../provider-resilience.ts\";\n\nexport interface CompactionRequestAuth {\n\treadonly apiKey?: string;\n\treadonly headers?: Record<string, string>;\n}\n\nexport interface CompactFailoverOptions {\n\t/** Cross-provider candidates need their own credential; never replay the primary key. */\n\treadonly resolveCandidateAuth?: (candidate: Model<Api>) => Promise<CompactionRequestAuth>;\n}\n\ninterface ModelFailoverInput<T> {\n\treadonly model: Model<Api>;\n\treadonly auth: CompactionRequestAuth;\n\treadonly signal?: AbortSignal;\n\treadonly candidates?: readonly Model<Api>[];\n\treadonly options?: CompactFailoverOptions;\n\treadonly run: (model: Model<Api>, auth: CompactionRequestAuth) => Promise<T>;\n}\n\n/** Preserve the primary quota failure when no authenticated candidate can serve. */\nexport async function withCompactionModelFailover<T>(input: ModelFailoverInput<T>): Promise<T> {\n\ttry {\n\t\treturn await input.run(input.model, input.auth);\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tif (!isQuotaExhaustionMessage(message) || !input.candidates?.length) throw error;\n\t\tfor (const candidate of input.candidates) {\n\t\t\tif (candidate.provider === input.model.provider && candidate.id === input.model.id) continue;\n\t\t\tif (input.signal?.aborted) throw error;\n\t\t\tlet auth: CompactionRequestAuth;\n\t\t\tif (candidate.provider === input.model.provider && !input.options?.resolveCandidateAuth) {\n\t\t\t\tauth = input.auth;\n\t\t\t} else {\n\t\t\t\ttry {\n\t\t\t\t\tauth = (await input.options?.resolveCandidateAuth?.(candidate)) ?? {};\n\t\t\t\t} catch {\n\t\t\t\t\t// An unavailable credential excludes this candidate, not the remaining chain.\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (!auth.apiKey) continue;\n\t\t\t}\n\t\t\tif (input.signal?.aborted) throw error;\n\t\t\ttry {\n\t\t\t\treturn await input.run(candidate, auth);\n\t\t\t} catch (candidateError) {\n\t\t\t\tconst candidateMessage = candidateError instanceof Error ? candidateError.message : String(candidateError);\n\t\t\t\tif (!isTerminalProviderErrorMessage(candidateMessage)) {\n\t\t\t\t\tthrow new Error(`Failover candidate ${candidate.provider}/${candidate.id} failed: ${candidateMessage}`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tthrow error;\n\t}\n}\n"]}

package/dist/core/compaction/model-failover.js

@@ -0,0 +1,46 @@
+import { isQuotaExhaustionMessage, isTerminalProviderErrorMessage } from "../provider-resilience.js";
+/** Preserve the primary quota failure when no authenticated candidate can serve. */
+export async function withCompactionModelFailover(input) {
+    try {
+        return await input.run(input.model, input.auth);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!isQuotaExhaustionMessage(message) || !input.candidates?.length)
+            throw error;
+        for (const candidate of input.candidates) {
+            if (candidate.provider === input.model.provider && candidate.id === input.model.id)
+                continue;
+            if (input.signal?.aborted)
+                throw error;
+            let auth;
+            if (candidate.provider === input.model.provider && !input.options?.resolveCandidateAuth) {
+                auth = input.auth;
+            }
+            else {
+                try {
+                    auth = (await input.options?.resolveCandidateAuth?.(candidate)) ?? {};
+                }
+                catch {
+                    // An unavailable credential excludes this candidate, not the remaining chain.
+                    continue;
+                }
+                if (!auth.apiKey)
+                    continue;
+            }
+            if (input.signal?.aborted)
+                throw error;
+            try {
+                return await input.run(candidate, auth);
+            }
+            catch (candidateError) {
+                const candidateMessage = candidateError instanceof Error ? candidateError.message : String(candidateError);
+                if (!isTerminalProviderErrorMessage(candidateMessage)) {
+                    throw new Error(`Failover candidate ${candidate.provider}/${candidate.id} failed: ${candidateMessage}`);
+                }
+            }
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=model-failover.js.map

package/dist/core/compaction/model-failover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-failover.js","sourceRoot":"","sources":["../../../src/core/compaction/model-failover.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAqBrG,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAI,KAA4B,EAAc;IAC9F,IAAI,CAAC;QACJ,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM;YAAE,MAAM,KAAK,CAAC;QACjF,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,SAAS,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,SAAS,CAAC,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,EAAE;gBAAE,SAAS;YAC7F,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,KAAK,CAAC;YACvC,IAAI,IAA2B,CAAC;YAChC,IAAI,SAAS,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,CAAC;gBACzF,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC;oBACJ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;gBACvE,CAAC;gBAAC,MAAM,CAAC;oBACR,8EAA8E;oBAC9E,SAAS;gBACV,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,MAAM;oBAAE,SAAS;YAC5B,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,KAAK,CAAC;YACvC,IAAI,CAAC;gBACJ,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,cAAc,EAAE,CAAC;gBACzB,MAAM,gBAAgB,GAAG,cAAc,YAAY,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;gBAC3G,IAAI,CAAC,8BAA8B,CAAC,gBAAgB,CAAC,EAAE,CAAC;oBACvD,MAAM,IAAI,KAAK,CAAC,sBAAsB,SAAS,CAAC,QAAQ,IAAI,SAAS,CAAC,EAAE,YAAY,gBAAgB,EAAE,CAAC,CAAC;gBACzG,CAAC;YACF,CAAC;QACF,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AAAA,CACD","sourcesContent":["import type { Api, Model } from \"omk-ai\";\nimport { isQuotaExhaustionMessage, isTerminalProviderErrorMessage } from \"../provider-resilience.ts\";\n\nexport interface CompactionRequestAuth {\n\treadonly apiKey?: string;\n\treadonly headers?: Record<string, string>;\n}\n\nexport interface CompactFailoverOptions {\n\t/** Cross-provider candidates need their own credential; never replay the primary key. */\n\treadonly resolveCandidateAuth?: (candidate: Model<Api>) => Promise<CompactionRequestAuth>;\n}\n\ninterface ModelFailoverInput<T> {\n\treadonly model: Model<Api>;\n\treadonly auth: CompactionRequestAuth;\n\treadonly signal?: AbortSignal;\n\treadonly candidates?: readonly Model<Api>[];\n\treadonly options?: CompactFailoverOptions;\n\treadonly run: (model: Model<Api>, auth: CompactionRequestAuth) => Promise<T>;\n}\n\n/** Preserve the primary quota failure when no authenticated candidate can serve. */\nexport async function withCompactionModelFailover<T>(input: ModelFailoverInput<T>): Promise<T> {\n\ttry {\n\t\treturn await input.run(input.model, input.auth);\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tif (!isQuotaExhaustionMessage(message) || !input.candidates?.length) throw error;\n\t\tfor (const candidate of input.candidates) {\n\t\t\tif (candidate.provider === input.model.provider && candidate.id === input.model.id) continue;\n\t\t\tif (input.signal?.aborted) throw error;\n\t\t\tlet auth: CompactionRequestAuth;\n\t\t\tif (candidate.provider === input.model.provider && !input.options?.resolveCandidateAuth) {\n\t\t\t\tauth = input.auth;\n\t\t\t} else {\n\t\t\t\ttry {\n\t\t\t\t\tauth = (await input.options?.resolveCandidateAuth?.(candidate)) ?? {};\n\t\t\t\t} catch {\n\t\t\t\t\t// An unavailable credential excludes this candidate, not the remaining chain.\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (!auth.apiKey) continue;\n\t\t\t}\n\t\t\tif (input.signal?.aborted) throw error;\n\t\t\ttry {\n\t\t\t\treturn await input.run(candidate, auth);\n\t\t\t} catch (candidateError) {\n\t\t\t\tconst candidateMessage = candidateError instanceof Error ? candidateError.message : String(candidateError);\n\t\t\t\tif (!isTerminalProviderErrorMessage(candidateMessage)) {\n\t\t\t\t\tthrow new Error(`Failover candidate ${candidate.provider}/${candidate.id} failed: ${candidateMessage}`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tthrow error;\n\t}\n}\n"]}

package/dist/core/compaction/session-summary.d.ts

@@ -0,0 +1,21 @@
+import type { Api, Model } from "omk-ai";
+import type { CompactionPreparation, CompactionResult } from "./compaction.ts";
+import type { CompactionRequestAuth } from "./model-failover.ts";
+export interface CompactionSummaryInput {
+    readonly preparation: CompactionPreparation;
+    readonly model: Model<Api>;
+    readonly apiKey: string | undefined;
+    readonly headers: Record<string, string> | undefined;
+    readonly customInstructions?: string;
+    readonly signal: AbortSignal;
+    readonly reason: "manual" | "overflow" | "threshold";
+}
+interface SessionSummaryInput extends CompactionSummaryInput {
+    readonly sessionModel: Model<Api> | undefined;
+    readonly resolveAuth: (model: Model<Api>) => Promise<CompactionRequestAuth>;
+    readonly summarize: (input: CompactionSummaryInput) => Promise<CompactionResult>;
+}
+/** Manual and automatic compaction share one credential-bound rescue ladder. */
+export declare function summarizeSessionCompaction(input: SessionSummaryInput): Promise<CompactionResult>;
+export {};
+//# sourceMappingURL=session-summary.d.ts.map

package/dist/core/compaction/session-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/session-summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;CACrD;AAED,UAAU,mBAAoB,SAAQ,sBAAsB;IAC3D,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5E,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjF;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwBhG","sourcesContent":["import type { Api, Model } from \"omk-ai\";\nimport type { CompactionPreparation, CompactionResult } from \"./compaction.ts\";\nimport { summarizeWithFallback } from \"./fallback.ts\";\nimport type { CompactionRequestAuth } from \"./model-failover.ts\";\n\nexport interface CompactionSummaryInput {\n\treadonly preparation: CompactionPreparation;\n\treadonly model: Model<Api>;\n\treadonly apiKey: string | undefined;\n\treadonly headers: Record<string, string> | undefined;\n\treadonly customInstructions?: string;\n\treadonly signal: AbortSignal;\n\treadonly reason: \"manual\" | \"overflow\" | \"threshold\";\n}\n\ninterface SessionSummaryInput extends CompactionSummaryInput {\n\treadonly sessionModel: Model<Api> | undefined;\n\treadonly resolveAuth: (model: Model<Api>) => Promise<CompactionRequestAuth>;\n\treadonly summarize: (input: CompactionSummaryInput) => Promise<CompactionResult>;\n}\n\n/** Manual and automatic compaction share one credential-bound rescue ladder. */\nexport function summarizeSessionCompaction(input: SessionSummaryInput): Promise<CompactionResult> {\n\treturn summarizeWithFallback({\n\t\tpreparation: input.preparation,\n\t\tprimaryModel: input.model,\n\t\tsessionModel: input.sessionModel,\n\t\tisAborted: () => input.signal.aborted,\n\t\talwaysRescue: input.reason === \"overflow\",\n\t\tsummarize: async (model) => {\n\t\t\tconst auth =\n\t\t\t\tmodel.provider === input.model.provider && model.id === input.model.id\n\t\t\t\t\t? { apiKey: input.apiKey, headers: input.headers }\n\t\t\t\t\t: await input.resolveAuth(model);\n\t\t\tinput.signal.throwIfAborted();\n\t\t\treturn input.summarize({\n\t\t\t\tpreparation: input.preparation,\n\t\t\t\tmodel,\n\t\t\t\tapiKey: auth.apiKey,\n\t\t\t\theaders: auth.headers,\n\t\t\t\tcustomInstructions: input.customInstructions,\n\t\t\t\tsignal: input.signal,\n\t\t\t\treason: input.reason,\n\t\t\t});\n\t\t},\n\t});\n}\n"]}

package/dist/core/compaction/session-summary.js

@@ -0,0 +1,27 @@
+import { summarizeWithFallback } from "./fallback.js";
+/** Manual and automatic compaction share one credential-bound rescue ladder. */
+export function summarizeSessionCompaction(input) {
+    return summarizeWithFallback({
+        preparation: input.preparation,
+        primaryModel: input.model,
+        sessionModel: input.sessionModel,
+        isAborted: () => input.signal.aborted,
+        alwaysRescue: input.reason === "overflow",
+        summarize: async (model) => {
+            const auth = model.provider === input.model.provider && model.id === input.model.id
+                ? { apiKey: input.apiKey, headers: input.headers }
+                : await input.resolveAuth(model);
+            input.signal.throwIfAborted();
+            return input.summarize({
+                preparation: input.preparation,
+                model,
+                apiKey: auth.apiKey,
+                headers: auth.headers,
+                customInstructions: input.customInstructions,
+                signal: input.signal,
+                reason: input.reason,
+            });
+        },
+    });
+}
+//# sourceMappingURL=session-summary.js.map

package/dist/core/compaction/session-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-summary.js","sourceRoot":"","sources":["../../../src/core/compaction/session-summary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAmBtD,gFAAgF;AAChF,MAAM,UAAU,0BAA0B,CAAC,KAA0B,EAA6B;IACjG,OAAO,qBAAqB,CAAC;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,YAAY,EAAE,KAAK,CAAC,KAAK;QACzB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO;QACrC,YAAY,EAAE,KAAK,CAAC,MAAM,KAAK,UAAU;QACzC,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3B,MAAM,IAAI,GACT,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,EAAE;gBACrE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;gBAClD,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,SAAS,CAAC;gBACtB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,KAAK;gBACL,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;gBAC5C,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,MAAM,EAAE,KAAK,CAAC,MAAM;aACpB,CAAC,CAAC;QAAA,CACH;KACD,CAAC,CAAC;AAAA,CACH","sourcesContent":["import type { Api, Model } from \"omk-ai\";\nimport type { CompactionPreparation, CompactionResult } from \"./compaction.ts\";\nimport { summarizeWithFallback } from \"./fallback.ts\";\nimport type { CompactionRequestAuth } from \"./model-failover.ts\";\n\nexport interface CompactionSummaryInput {\n\treadonly preparation: CompactionPreparation;\n\treadonly model: Model<Api>;\n\treadonly apiKey: string | undefined;\n\treadonly headers: Record<string, string> | undefined;\n\treadonly customInstructions?: string;\n\treadonly signal: AbortSignal;\n\treadonly reason: \"manual\" | \"overflow\" | \"threshold\";\n}\n\ninterface SessionSummaryInput extends CompactionSummaryInput {\n\treadonly sessionModel: Model<Api> | undefined;\n\treadonly resolveAuth: (model: Model<Api>) => Promise<CompactionRequestAuth>;\n\treadonly summarize: (input: CompactionSummaryInput) => Promise<CompactionResult>;\n}\n\n/** Manual and automatic compaction share one credential-bound rescue ladder. */\nexport function summarizeSessionCompaction(input: SessionSummaryInput): Promise<CompactionResult> {\n\treturn summarizeWithFallback({\n\t\tpreparation: input.preparation,\n\t\tprimaryModel: input.model,\n\t\tsessionModel: input.sessionModel,\n\t\tisAborted: () => input.signal.aborted,\n\t\talwaysRescue: input.reason === \"overflow\",\n\t\tsummarize: async (model) => {\n\t\t\tconst auth =\n\t\t\t\tmodel.provider === input.model.provider && model.id === input.model.id\n\t\t\t\t\t? { apiKey: input.apiKey, headers: input.headers }\n\t\t\t\t\t: await input.resolveAuth(model);\n\t\t\tinput.signal.throwIfAborted();\n\t\t\treturn input.summarize({\n\t\t\t\tpreparation: input.preparation,\n\t\t\t\tmodel,\n\t\t\t\tapiKey: auth.apiKey,\n\t\t\t\theaders: auth.headers,\n\t\t\t\tcustomInstructions: input.customInstructions,\n\t\t\t\tsignal: input.signal,\n\t\t\t\treason: input.reason,\n\t\t\t});\n\t\t},\n\t});\n}\n"]}

package/dist/core/context-budget-headroom-candidates.d.ts

@@ -1,3 +1,18 @@
 import { type ContextBudgetItemV2, type ContextRepresentationCandidateV2, type HeadroomQualityPolicyV2 } from "./context-budget-headroom-types.ts";
-export declare function deriveRepresentationCandidates(item: ContextBudgetItemV2, policy?: HeadroomQualityPolicyV2): readonly ContextRepresentationCandidateV2[];
+/** Prices one materialized representation string; must be the counter that produced the item's full-text cost. */
+export type RepresentationTokenCounter = (text: string) => number;
+/**
+ * Derive the representations the selector may choose for one item.
+ *
+ * Every non-full candidate is priced by counting the string it actually
+ * materializes with `countTokens` — the same counter that priced the full
+ * text — so the cost the selector checks against the budget is the cost of
+ * the text that would be sent. A compression ratio is never a cost: a summary
+ * that returns its source unchanged saves nothing, and a representation whose
+ * materialized text is not cheaper than the full text is not offered at all.
+ * Pass the counter that produced `item.tokenEstimate`; mixing an exact
+ * tokenizer for the full text with the heuristic for its alternatives makes
+ * the candidates incomparable.
+ */
+export declare function deriveRepresentationCandidates(item: ContextBudgetItemV2, policy?: HeadroomQualityPolicyV2, countTokens?: RepresentationTokenCounter): readonly ContextRepresentationCandidateV2[];
 //# sourceMappingURL=context-budget-headroom-candidates.d.ts.map

package/dist/core/context-budget-headroom-candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-headroom-candidates.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-headroom-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EAKrC,KAAK,uBAAuB,EAE5B,MAAM,oCAAoC,CAAC;AAK5C,wBAAgB,8BAA8B,CAC7C,IAAI,EAAE,mBAAmB,EACzB,MAAM,GAAE,uBAAyD,GAC/D,SAAS,gCAAgC,EAAE,CA4D7C","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\tfnv1aHex,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\theuristicTokenCount,\n} from \"./context-budget-headroom-types.ts\";\n\nconst SUMMARY_HEAD_CHARS = 160;\nconst HEADROOM_HEAD_CHARS = 120;\n\nexport function deriveRepresentationCandidates(\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): readonly ContextRepresentationCandidateV2[] {\n\tconst full = fullTextTokens(item);\n\tconst sourceRef = item.sourceRef;\n\tconst retrievable = sourceRef?.retrievable === true;\n\tconst candidates: ContextRepresentationCandidateV2[] = [];\n\n\tcandidates.push({\n\t\tkind: \"full\",\n\t\ttext: item.text,\n\t\testimatedTokens: full,\n\t\tfidelity: item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef,\n\t});\n\n\tif (retrievable && sourceRef) {\n\t\tconst pointerText = formatPointer(sourceRef);\n\t\tcandidates.push({\n\t\t\tkind: \"pointer\",\n\t\t\ttext: pointerText,\n\t\t\testimatedTokens: heuristicTokenCount(pointerText),\n\t\t\tfidelity: \"bounded\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\tconst summaryTokens = Math.ceil(full * 0.15) + 8;\n\tif (isSummaryEligible(item, full, policy) && summaryTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"summary\",\n\t\t\ttext: summarizeText(item.text),\n\t\t\testimatedTokens: summaryTokens,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsummaryHash: fnv1aHex(item.text),\n\t\t});\n\t}\n\n\tconst headroomText = formatHeadroom(item.text, sourceRef);\n\tconst headroomTokens = Math.max(Math.ceil(full * 0.35) + 16, heuristicTokenCount(headroomText));\n\tif (full > policy.headroomThresholdTokens && retrievable && headroomTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"headroom-compressed\",\n\t\t\ttext: headroomText,\n\t\t\testimatedTokens: headroomTokens,\n\t\t\tfidelity: \"reversible\",\n\t\t\tsourceRef,\n\t\t\tcompressorId: \"headroom-shadow\",\n\t\t});\n\t}\n\n\tif (policy.allowOmit) {\n\t\tcandidates.push({\n\t\t\tkind: \"omit\",\n\t\t\ttext: \"\",\n\t\t\testimatedTokens: 0,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\treturn candidates;\n}\n\nfunction isSummaryEligible(item: ContextBudgetItemV2, fullTokens: number, policy: HeadroomQualityPolicyV2): boolean {\n\treturn (\n\t\titem.tier === \"history\" ||\n\t\titem.tier === \"evidence\" ||\n\t\titem.tier === \"scratch\" ||\n\t\t(item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns ||\n\t\tfullTokens > policy.headroomThresholdTokens\n\t);\n}\n\nfunction formatPointer(ref: ContextSourceRefV2): string {\n\tconst parts: string[] = [`uri=\"${escapeMetadataValue(ref.uri)}\"`];\n\tif (ref.symbol) parts.push(`symbol=\"${escapeMetadataValue(ref.symbol)}\"`);\n\tif (ref.range) parts.push(`lines=\"${ref.range.startLine}-${ref.range.endLine}\"`);\n\tparts.push(`hash=\"${escapeMetadataValue(ref.contentHash)}\"`);\n\treturn `<pointer ${parts.join(\" \")} />`;\n}\n\nfunction summarizeText(text: string): string {\n\tif (text.length <= SUMMARY_HEAD_CHARS) {\n\t\treturn text;\n\t}\n\treturn `${text.slice(0, SUMMARY_HEAD_CHARS)} …[summary]`;\n}\n\nfunction formatHeadroom(text: string, ref?: ContextSourceRefV2): string {\n\tconst head = text.slice(0, HEADROOM_HEAD_CHARS);\n\tconst hash = fnv1aHex(text);\n\tconst where = ref ? ` uri=\"${escapeMetadataValue(ref.uri)}\"` : \"\";\n\treturn `${head} …[headroom-compressed${where} hash=\"${hash}\"]`;\n}\n\nfunction escapeMetadataValue(value: string): string {\n\treturn value\n\t\t.replace(/&/g, \"&amp;\")\n\t\t.replace(/</g, \"&lt;\")\n\t\t.replace(/>/g, \"&gt;\")\n\t\t.replace(/\"/g, \"&quot;\")\n\t\t.replace(/'/g, \"&apos;\");\n}\n"]}
+{"version":3,"file":"context-budget-headroom-candidates.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-headroom-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EAKrC,KAAK,uBAAuB,EAE5B,MAAM,oCAAoC,CAAC;AAK5C,kHAAkH;AAClH,MAAM,MAAM,0BAA0B,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC7C,IAAI,EAAE,mBAAmB,EACzB,MAAM,GAAE,uBAAyD,EACjE,WAAW,GAAE,0BAAgD,GAC3D,SAAS,gCAAgC,EAAE,CAgE7C","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\tfnv1aHex,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\theuristicTokenCount,\n} from \"./context-budget-headroom-types.ts\";\n\nconst SUMMARY_HEAD_CHARS = 160;\nconst HEADROOM_HEAD_CHARS = 120;\n\n/** Prices one materialized representation string; must be the counter that produced the item's full-text cost. */\nexport type RepresentationTokenCounter = (text: string) => number;\n\n/**\n * Derive the representations the selector may choose for one item.\n *\n * Every non-full candidate is priced by counting the string it actually\n * materializes with `countTokens` — the same counter that priced the full\n * text — so the cost the selector checks against the budget is the cost of\n * the text that would be sent. A compression ratio is never a cost: a summary\n * that returns its source unchanged saves nothing, and a representation whose\n * materialized text is not cheaper than the full text is not offered at all.\n * Pass the counter that produced `item.tokenEstimate`; mixing an exact\n * tokenizer for the full text with the heuristic for its alternatives makes\n * the candidates incomparable.\n */\nexport function deriveRepresentationCandidates(\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n\tcountTokens: RepresentationTokenCounter = heuristicTokenCount,\n): readonly ContextRepresentationCandidateV2[] {\n\tconst full = fullTextTokens(item);\n\tconst sourceRef = item.sourceRef;\n\tconst retrievable = sourceRef?.retrievable === true;\n\tconst candidates: ContextRepresentationCandidateV2[] = [];\n\tconst offerIfCheaper = (candidate: ContextRepresentationCandidateV2): void => {\n\t\tif (candidate.text !== item.text && candidate.estimatedTokens < full) candidates.push(candidate);\n\t};\n\n\tcandidates.push({\n\t\tkind: \"full\",\n\t\ttext: item.text,\n\t\testimatedTokens: full,\n\t\tfidelity: item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef,\n\t});\n\n\tif (retrievable && sourceRef) {\n\t\tconst pointerText = formatPointer(sourceRef);\n\t\tofferIfCheaper({\n\t\t\tkind: \"pointer\",\n\t\t\ttext: pointerText,\n\t\t\testimatedTokens: countTokens(pointerText),\n\t\t\tfidelity: \"bounded\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\tif (isSummaryEligible(item, full, policy)) {\n\t\tconst summaryText = summarizeText(item.text);\n\t\tofferIfCheaper({\n\t\t\tkind: \"summary\",\n\t\t\ttext: summaryText,\n\t\t\testimatedTokens: countTokens(summaryText),\n\t\t\tfidelity: \"lossy\",\n\t\t\tsummaryHash: fnv1aHex(item.text),\n\t\t});\n\t}\n\n\tif (full > policy.headroomThresholdTokens && retrievable) {\n\t\tconst headroomText = formatHeadroom(item.text, sourceRef);\n\t\t// The shadow compressor's reversible payload is larger than the visible\n\t\t// head, so its price keeps a floor above the counted head text.\n\t\tofferIfCheaper({\n\t\t\tkind: \"headroom-compressed\",\n\t\t\ttext: headroomText,\n\t\t\testimatedTokens: Math.max(Math.ceil(full * 0.35) + 16, countTokens(headroomText)),\n\t\t\tfidelity: \"reversible\",\n\t\t\tsourceRef,\n\t\t\tcompressorId: \"headroom-shadow\",\n\t\t});\n\t}\n\n\tif (policy.allowOmit) {\n\t\tcandidates.push({\n\t\t\tkind: \"omit\",\n\t\t\ttext: \"\",\n\t\t\testimatedTokens: 0,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\treturn candidates;\n}\n\nfunction isSummaryEligible(item: ContextBudgetItemV2, fullTokens: number, policy: HeadroomQualityPolicyV2): boolean {\n\treturn (\n\t\titem.tier === \"history\" ||\n\t\titem.tier === \"evidence\" ||\n\t\titem.tier === \"scratch\" ||\n\t\t(item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns ||\n\t\tfullTokens > policy.headroomThresholdTokens\n\t);\n}\n\nfunction formatPointer(ref: ContextSourceRefV2): string {\n\tconst parts: string[] = [`uri=\"${escapeMetadataValue(ref.uri)}\"`];\n\tif (ref.symbol) parts.push(`symbol=\"${escapeMetadataValue(ref.symbol)}\"`);\n\tif (ref.range) parts.push(`lines=\"${ref.range.startLine}-${ref.range.endLine}\"`);\n\tparts.push(`hash=\"${escapeMetadataValue(ref.contentHash)}\"`);\n\treturn `<pointer ${parts.join(\" \")} />`;\n}\n\nfunction summarizeText(text: string): string {\n\tif (text.length <= SUMMARY_HEAD_CHARS) {\n\t\treturn text;\n\t}\n\treturn `${text.slice(0, SUMMARY_HEAD_CHARS)} …[summary]`;\n}\n\nfunction formatHeadroom(text: string, ref?: ContextSourceRefV2): string {\n\tconst head = text.slice(0, HEADROOM_HEAD_CHARS);\n\tconst hash = fnv1aHex(text);\n\tconst where = ref ? ` uri=\"${escapeMetadataValue(ref.uri)}\"` : \"\";\n\treturn `${head} …[headroom-compressed${where} hash=\"${hash}\"]`;\n}\n\nfunction escapeMetadataValue(value: string): string {\n\treturn value\n\t\t.replace(/&/g, \"&amp;\")\n\t\t.replace(/</g, \"&lt;\")\n\t\t.replace(/>/g, \"&gt;\")\n\t\t.replace(/\"/g, \"&quot;\")\n\t\t.replace(/'/g, \"&apos;\");\n}\n"]}