@theokit/sdk 4.23.0 → 4.25.0

package/dist/chunk-EVADEGM7.cjs

@@ -0,0 +1,168 @@
+'use strict';
+
+var chunkA44COQJJ_cjs = require('./chunk-A44COQJJ.cjs');
+var chunkBEURCLDV_cjs = require('./chunk-BEURCLDV.cjs');
+
+// src/internal/runtime/compression/compression-helpers.ts
+function selectCompressionWindow(messages, preserveLast = 6) {
+  if (messages.length <= preserveLast) {
+    return { toCompress: [], toPreserve: [...messages] };
+  }
+  return {
+    toCompress: messages.slice(0, -preserveLast),
+    toPreserve: messages.slice(-preserveLast)
+  };
+}
+
+// src/compaction.ts
+var CHECKPOINT_MARKER = "[[theokit:checkpoint]] ";
+var SUMMARY_TEMPLATE = `Summarize the conversation so far into these sections (keep every header even if empty):
+
+## Goal
+What the user is ultimately trying to achieve.
+
+## Constraints
+Hard requirements, conventions, and rules stated.
+
+## Progress
+What has been done so far.
+
+## Decisions
+Choices made and their rationale.
+
+## Next
+The immediate next steps.
+
+## Critical
+Anything that MUST NOT be forgotten (preserve verbatim: error messages, exact values).
+
+## Files
+File paths touched or referenced (verbatim).`;
+function assertMarker(marker) {
+  if (marker === "") {
+    throw new chunkA44COQJJ_cjs.TheokitAgentError("compaction marker must be non-empty", {
+      code: "invalid_argument"
+    });
+  }
+}
+function isSystemPrompt(message, marker) {
+  return message.role === "system" && !message.content.startsWith(marker);
+}
+function selectByTokenBudget(messages, keepTokens) {
+  let acc = 0;
+  let splitIndex = messages.length;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    acc += estimateTokens(messages[i]?.content ?? "");
+    if (acc > keepTokens && i < messages.length - 1) {
+      splitIndex = i + 1;
+      break;
+    }
+    splitIndex = i;
+  }
+  return { head: messages.slice(0, splitIndex), recent: messages.slice(splitIndex) };
+}
+function splitByRecent(messages, keepRecent, marker) {
+  const systemPrompts = messages.filter((m) => isSystemPrompt(m, marker));
+  const rest = messages.filter((m) => !isSystemPrompt(m, marker));
+  const { toCompress, toPreserve } = selectCompressionWindow(rest, keepRecent);
+  return { systemPrompts, head: toCompress, recent: toPreserve };
+}
+var FAILSAFE_ABORT = /* @__PURE__ */ Symbol("failsafe-abort");
+async function runSummarize(summarize, head, template, failSafe) {
+  try {
+    return await summarize(head, template);
+  } catch (err) {
+    if (!failSafe) throw err;
+    console.warn(
+      `[compaction] summarizer failed \u2014 proceeding uncompacted: ${chunkBEURCLDV_cjs.redactSecrets(err instanceof Error ? err.message : String(err))}`
+    );
+    return FAILSAFE_ABORT;
+  }
+}
+async function compactTranscript(messages, options = {}) {
+  const marker = options.marker ?? CHECKPOINT_MARKER;
+  assertMarker(marker);
+  const split = options.keepTokens != null ? { systemPrompts: [], ...selectByTokenBudget(messages, options.keepTokens) } : splitByRecent(messages, options.keepRecent ?? 6, marker);
+  if (split.head.length === 0) {
+    return [...messages];
+  }
+  if (!options.summarize) {
+    return [...split.systemPrompts, ...split.recent];
+  }
+  const template = options.summaryTemplate ?? SUMMARY_TEMPLATE;
+  const summary = await runSummarize(
+    options.summarize,
+    split.head,
+    template,
+    options.failSafe ?? false
+  );
+  if (summary === FAILSAFE_ABORT) {
+    return [...messages];
+  }
+  return [...split.systemPrompts, summary, ...split.recent];
+}
+function buildCheckpoint(label, marker = CHECKPOINT_MARKER) {
+  assertMarker(marker);
+  return { role: "system", content: marker + (label ?? "") };
+}
+function filterFromLatestCheckpoint(messages, options = {}) {
+  const marker = options.marker ?? CHECKPOINT_MARKER;
+  const offset = options.include === "from" ? 0 : 1;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i]?.content.startsWith(marker)) {
+      return messages.slice(i + offset);
+    }
+  }
+  return [...messages];
+}
+function isContextOverflowError(err) {
+  return err instanceof chunkA44COQJJ_cjs.TheokitAgentError && (err.code === "context_too_long" || err.metadata?.code === "context_too_long");
+}
+var ContextWindowMarginError = class extends chunkA44COQJJ_cjs.TheokitAgentError {
+  constructor(margin) {
+    super(
+      `context-window margin must be in (0, 1], got ${String(margin)}. A margin above 1 grows the assumed window and delays compaction past the real limit.`,
+      { code: "invalid_context_window_margin" }
+    );
+    this.margin = margin;
+  }
+  margin;
+};
+var CONTEXT_WINDOW_MARGIN = 0.95;
+var CONTEXT_WINDOW_FLOOR = 128e3;
+function resolveEffectiveContextWindow(input) {
+  if (!(input.margin > 0) || input.margin > 1) {
+    throw new ContextWindowMarginError(input.margin);
+  }
+  const withMargin = (raw) => Math.floor(raw * input.margin);
+  if (input.override !== void 0) {
+    const clamped = input.catalog !== void 0 && input.override > input.catalog;
+    const raw = clamped ? input.catalog : input.override;
+    return { window: withMargin(raw), source: "override", clamped };
+  }
+  if (input.catalog !== void 0) {
+    return { window: withMargin(input.catalog), source: "catalog", clamped: false };
+  }
+  return { window: withMargin(input.floor ?? 0), source: "fallback", clamped: false };
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function shouldCompact(input) {
+  return input.estimated >= input.contextWindow - input.buffer - (input.maxOutput ?? 0);
+}
+
+exports.CHECKPOINT_MARKER = CHECKPOINT_MARKER;
+exports.CONTEXT_WINDOW_FLOOR = CONTEXT_WINDOW_FLOOR;
+exports.CONTEXT_WINDOW_MARGIN = CONTEXT_WINDOW_MARGIN;
+exports.ContextWindowMarginError = ContextWindowMarginError;
+exports.SUMMARY_TEMPLATE = SUMMARY_TEMPLATE;
+exports.buildCheckpoint = buildCheckpoint;
+exports.compactTranscript = compactTranscript;
+exports.estimateTokens = estimateTokens;
+exports.filterFromLatestCheckpoint = filterFromLatestCheckpoint;
+exports.isContextOverflowError = isContextOverflowError;
+exports.resolveEffectiveContextWindow = resolveEffectiveContextWindow;
+exports.shouldCompact = shouldCompact;
+//# sourceMappingURL=chunk-EVADEGM7.cjs.map
+//# sourceMappingURL=chunk-EVADEGM7.cjs.map

package/dist/chunk-EVADEGM7.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/compression/compression-helpers.ts","../src/compaction.ts"],"names":["TheokitAgentError","redactSecrets"],"mappings":"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","file":"chunk-EVADEGM7.cjs","sourcesContent":["/**\n * Compression helpers (T2.3, ADR D92).\n *\n * Scaffold for future compression LLM integration:\n *   - `selectCompressionWindow` — splits messages into compress/preserve halves\n *   - `assertCompressionReduced` — 10% reduction floor to detect \"compression placebo\"\n *\n * The compression LLM call itself is out of scope for this plan (requires\n * an auxiliary-model ADR). These helpers are used by `Agent.send` when a\n * future iteration adds compression.\n *\n * @internal\n */\n\nexport interface CompressionWindow<M> {\n  toCompress: M[];\n  toPreserve: M[];\n}\n\n/**\n * Split `messages` into the half to compress (older) and the half to\n * preserve verbatim (recent). When `messages.length <= preserveLast`,\n * everything is preserved.\n *\n * @internal\n */\nexport function selectCompressionWindow<M>(\n  messages: readonly M[],\n  preserveLast = 6,\n): CompressionWindow<M> {\n  if (messages.length <= preserveLast) {\n    return { toCompress: [], toPreserve: [...messages] };\n  }\n  return {\n    toCompress: messages.slice(0, -preserveLast),\n    toPreserve: messages.slice(-preserveLast),\n  };\n}\n\nexport interface CompressionCheck {\n  reduced: boolean;\n  reductionPct: number;\n  reason?: string;\n}\n\n/**\n * Check that compression actually reduced token count by at least `minPct`\n * (default 10%). Returns `{ reduced: false }` for spirals-in-formation\n * (compression LLM outputs that grow or barely shrink).\n *\n * @internal\n */\nexport function assertCompressionReduced(\n  before: number,\n  after: number,\n  minPct = 10,\n): CompressionCheck {\n  if (before <= 0) {\n    return { reduced: false, reductionPct: 0, reason: \"before count was zero\" };\n  }\n  const reductionPct = ((before - after) / before) * 100;\n  if (reductionPct >= minPct) {\n    return { reduced: true, reductionPct };\n  }\n  return {\n    reduced: false,\n    reductionPct,\n    reason: `compression reduced ${reductionPct.toFixed(1)}% (< ${minPct}% min). Spiral likely.`,\n  };\n}\n","/**\n * Public compaction / context-management helpers (M2-1, extended V3-3).\n *\n * Promotes the SDK's compaction capability to a public surface so consumers can\n * compact a transcript, mark/filter conversation checkpoints, and detect\n * context-overflow — without reaching into `internal/`.\n *\n * Two recent-window modes (V3-3):\n *  - `keepRecent` (turn-count, default) — keeps the last N turns verbatim and\n *    always preserves leading system PROMPTS; reuses the internal\n *    `selectCompressionWindow` (no second algorithm).\n *  - `keepTokens` (token-budget) — keeps the trailing turns whose accumulated\n *    `estimateTokens` fits the budget (theocode `splitTranscript` semantics). In\n *    this mode leading system prompts are NOT special-cased (D6).\n *\n * Summarization is delegated to a caller-supplied callback (which receives the\n * older window + the summary template). With `failSafe`, a thrown summarizer\n * returns the ORIGINAL transcript + a structured warn (compaction is an\n * optimization, never a cause of data loss); without it, the error propagates.\n *\n * Public from the `@theokit/sdk/compaction` sub-path.\n */\n\nimport { TheokitAgentError } from \"./errors.js\";\nimport { selectCompressionWindow } from \"./internal/runtime/compression/compression-helpers.js\";\nimport { redactSecrets } from \"./internal/security/redact.js\";\n\n/**\n * Minimal message shape for compaction/compression input. THE canonical public origin (leaf type —\n * rollup-plugin-dts cannot re-export types from internal modules into entry bundles; M42 lesson).\n *\n * @public\n */\nexport interface CompressibleMessage {\n  role: \"user\" | \"assistant\" | \"system\";\n  content: string;\n}\n\n/**\n * Sentinel prefix marking a conversation checkpoint turn. A visible, structured,\n * prose-unlikely token (no invisible/control bytes — safe to persist and to read\n * in source). Only {@link buildCheckpoint} should produce content beginning with it.\n */\nexport const CHECKPOINT_MARKER = \"[[theokit:checkpoint]] \";\n\n/**\n * The 7-section summary template handed to the `summarize` callback (theocode\n * parity shape). Every header is always present so the summarizer cannot silently\n * drop a category; the model is told to preserve file paths, commands, and error\n * text verbatim. Override per-call via {@link CompactTranscriptOptions.summaryTemplate}.\n */\nexport const SUMMARY_TEMPLATE = `Summarize the conversation so far into these sections (keep every header even if empty):\n\n## Goal\nWhat the user is ultimately trying to achieve.\n\n## Constraints\nHard requirements, conventions, and rules stated.\n\n## Progress\nWhat has been done so far.\n\n## Decisions\nChoices made and their rationale.\n\n## Next\nThe immediate next steps.\n\n## Critical\nAnything that MUST NOT be forgotten (preserve verbatim: error messages, exact values).\n\n## Files\nFile paths touched or referenced (verbatim).`;\n\n/** Reject an empty marker — it would match every turn via `startsWith(\"\")` (EC-3). */\nfunction assertMarker(marker: string): void {\n  if (marker === \"\") {\n    throw new TheokitAgentError(\"compaction marker must be non-empty\", {\n      code: \"invalid_argument\",\n    });\n  }\n}\n\n/** True for a real system prompt — a `system` turn that is NOT a checkpoint marker. */\nfunction isSystemPrompt(message: CompressibleMessage, marker: string): boolean {\n  return message.role === \"system\" && !message.content.startsWith(marker);\n}\n\n/** Carried split: leading system prompts (preserved), the older window, the verbatim tail. */\ninterface TranscriptSplit {\n  systemPrompts: CompressibleMessage[];\n  head: CompressibleMessage[];\n  recent: CompressibleMessage[];\n}\n\n/**\n * Token-budget split (theocode `splitTranscript`): walk from the END accumulating\n * `estimateTokens` until `keepTokens` is exceeded; everything older is the head.\n * Always keeps ≥ 1 recent turn. No system-prompt special-casing (D6).\n */\nfunction selectByTokenBudget(\n  messages: CompressibleMessage[],\n  keepTokens: number,\n): { head: CompressibleMessage[]; recent: CompressibleMessage[] } {\n  let acc = 0;\n  let splitIndex = messages.length;\n  for (let i = messages.length - 1; i >= 0; i -= 1) {\n    acc += estimateTokens(messages[i]?.content ?? \"\");\n    if (acc > keepTokens && i < messages.length - 1) {\n      splitIndex = i + 1;\n      break;\n    }\n    splitIndex = i;\n  }\n  return { head: messages.slice(0, splitIndex), recent: messages.slice(splitIndex) };\n}\n\n/** Turn-count split (M2): preserve leading system prompts; window the rest by `keepRecent`. */\nfunction splitByRecent(\n  messages: CompressibleMessage[],\n  keepRecent: number,\n  marker: string,\n): TranscriptSplit {\n  const systemPrompts = messages.filter((m) => isSystemPrompt(m, marker));\n  const rest = messages.filter((m) => !isSystemPrompt(m, marker));\n  const { toCompress, toPreserve } = selectCompressionWindow(rest, keepRecent);\n  return { systemPrompts, head: toCompress, recent: toPreserve };\n}\n\n/** Options for {@link compactTranscript}. */\nexport interface CompactTranscriptOptions {\n  /** Trailing turns preserved verbatim by COUNT (default 6). Ignored when `keepTokens` is set. */\n  keepRecent?: number;\n  /**\n   * Trailing turns preserved verbatim by TOKEN BUDGET (theocode mode). When set,\n   * takes precedence over `keepRecent` and disables system-prompt preservation (D6).\n   */\n  keepTokens?: number;\n  /** Checkpoint marker (default {@link CHECKPOINT_MARKER}). Must be non-empty. */\n  marker?: string;\n  /** Summary template passed to `summarize` (default {@link SUMMARY_TEMPLATE}). */\n  summaryTemplate?: string;\n  /** Summarize the older window into one turn; if omitted, the older window is dropped. */\n  summarize?: (older: CompressibleMessage[], template: string) => Promise<CompressibleMessage>;\n  /**\n   * When true, a thrown `summarize` returns the ORIGINAL transcript + a structured\n   * warn (compaction never loses data). Default false: the error propagates.\n   */\n  failSafe?: boolean;\n}\n\n/** Sentinel returned by {@link runSummarize} when fail-safe swallowed a throw. */\nconst FAILSAFE_ABORT = Symbol(\"failsafe-abort\");\n\n/** Run the summarizer; on throw, either propagate or (fail-safe) warn + signal abort. */\nasync function runSummarize(\n  summarize: NonNullable<CompactTranscriptOptions[\"summarize\"]>,\n  head: CompressibleMessage[],\n  template: string,\n  failSafe: boolean,\n): Promise<CompressibleMessage | typeof FAILSAFE_ABORT> {\n  try {\n    return await summarize(head, template);\n  } catch (err) {\n    if (!failSafe) throw err;\n    // Unbreakable Rule 8 — never fail silently. The breadcrumb points at the root\n    // cause when a summarizer fails every turn and context grows unchecked. The\n    // summarizer is caller-supplied, so its error text is routed through\n    // `redactSecrets` (ADR D68 — no unredacted output sink in src/).\n    console.warn(\n      `[compaction] summarizer failed — proceeding uncompacted: ${redactSecrets(err instanceof Error ? err.message : String(err))}`,\n    );\n    return FAILSAFE_ABORT;\n  }\n}\n\n/**\n * Compact a transcript. In `keepRecent` mode (default) the last `keepRecent` turns\n * are kept verbatim and leading system PROMPTS preserved; in `keepTokens` mode the\n * trailing turns within the token budget are kept (no system special-casing, D6).\n * The older window is summarized (via `summarize`, receiving the template) or\n * dropped. Never mutates the input.\n */\nexport async function compactTranscript(\n  messages: CompressibleMessage[],\n  options: CompactTranscriptOptions = {},\n): Promise<CompressibleMessage[]> {\n  const marker = options.marker ?? CHECKPOINT_MARKER;\n  assertMarker(marker);\n  const split =\n    options.keepTokens != null\n      ? { systemPrompts: [], ...selectByTokenBudget(messages, options.keepTokens) }\n      : splitByRecent(messages, options.keepRecent ?? 6, marker);\n  if (split.head.length === 0) {\n    return [...messages];\n  }\n  if (!options.summarize) {\n    return [...split.systemPrompts, ...split.recent];\n  }\n  const template = options.summaryTemplate ?? SUMMARY_TEMPLATE;\n  const summary = await runSummarize(\n    options.summarize,\n    split.head,\n    template,\n    options.failSafe ?? false,\n  );\n  if (summary === FAILSAFE_ABORT) {\n    return [...messages];\n  }\n  return [...split.systemPrompts, summary, ...split.recent];\n}\n\n/**\n * Build a checkpoint marker turn (a `system` turn whose content starts with\n * `marker`, default {@link CHECKPOINT_MARKER}). `marker` must be non-empty.\n */\nexport function buildCheckpoint(\n  label?: string,\n  marker: string = CHECKPOINT_MARKER,\n): CompressibleMessage {\n  assertMarker(marker);\n  return { role: \"system\", content: marker + (label ?? \"\") };\n}\n\n/** Options for {@link filterFromLatestCheckpoint}. */\nexport interface FilterCheckpointOptions {\n  /** Marker to scan for (default {@link CHECKPOINT_MARKER}). */\n  marker?: string;\n  /**\n   * `'after'` (default, M2) returns turns AFTER the latest marker (exclusive);\n   * `'from'` (theocode) returns turns FROM the latest marker (inclusive).\n   */\n  include?: \"after\" | \"from\";\n}\n\n/**\n * Return the turns relative to the most recent checkpoint marker (all turns if\n * none). `include: 'after'` (default) excludes the checkpoint; `'from'` includes\n * it (the summary stands in for the pruned head). Never mutates the input.\n */\nexport function filterFromLatestCheckpoint(\n  messages: CompressibleMessage[],\n  options: FilterCheckpointOptions = {},\n): CompressibleMessage[] {\n  const marker = options.marker ?? CHECKPOINT_MARKER;\n  const offset = options.include === \"from\" ? 0 : 1;\n  for (let i = messages.length - 1; i >= 0; i -= 1) {\n    if (messages[i]?.content.startsWith(marker)) {\n      return messages.slice(i + offset);\n    }\n  }\n  return [...messages];\n}\n\n/**\n * True iff `err` is a {@link TheokitAgentError} (or subclass) reporting a\n * context-window-exceeded condition (the typed `context_too_long` code). Reads\n * both `code` (set by provider mappers) and `metadata.code` (the preferred field)\n * — never a brittle message regex.\n */\nexport function isContextOverflowError(err: unknown): boolean {\n  return (\n    err instanceof TheokitAgentError &&\n    (err.code === \"context_too_long\" || err.metadata?.code === \"context_too_long\")\n  );\n}\n\n/**\n * M77 — the margin is outside `(0, 1]`. Typed, because a margin > 1 would GROW the assumed window,\n * which is the unsafe direction: `shouldCompact` is monotonically decreasing in `contextWindow`, so\n * overestimating it makes the trigger fire too late and the context overflow.\n */\nexport class ContextWindowMarginError extends TheokitAgentError {\n  constructor(readonly margin: number) {\n    super(\n      `context-window margin must be in (0, 1], got ${String(margin)}. ` +\n        `A margin above 1 grows the assumed window and delays compaction past the real limit.`,\n      { code: \"invalid_context_window_margin\" },\n    );\n  }\n}\n\n/**\n * M77 — default safety margin on the context window.\n *\n * `0.95` is not a guess: it is the single reference's value. Codex ships\n * `effective_context_window_percent: 95` (`models-manager/src/model_info.rs:158`) and never budgets\n * against 100% of a window. Being MULTIPLICATIVE, it stays conservative at any window size, which a\n * fixed subtraction would not.\n */\nexport const CONTEXT_WINDOW_MARGIN = 0.95;\n\n/**\n * M77 — the floor used ONLY when neither the catalog nor the caller knows the window.\n *\n * Honest about its own weakness. This number has **one** source (the M77 milestone text); the search\n * for a second one failed, because the reference has no fallback at all — Codex returns `Option` and\n * its callers early-return (`core/src/session/turn_context.rs:213`, `core/src/compact_remote.rs:374`).\n *\n * It is conservative only UPWARD. For a model whose real window is larger, budgeting against 128k\n * compacts early — wasteful but safe. For a model whose real window is SMALLER (an 8k or 32k model\n * absent from the catalog), it compacts too late and the context still overflows. That residual risk\n * is real and is why {@link resolveEffectiveContextWindow} never lets this floor compete with a known\n * catalog value, and why the `compaction_fallback` event exists: a surface can show that the budget is\n * a guess instead of the user finding out when the provider rejects the request.\n */\nexport const CONTEXT_WINDOW_FLOOR = 128_000;\n\n/** Where the effective window came from — carried into the M77 structured event. */\nexport type ContextWindowSource = \"override\" | \"catalog\" | \"fallback\";\n\n/** Input to {@link resolveEffectiveContextWindow}. */\nexport interface EffectiveContextWindowInput {\n  /** Caller-supplied window, in tokens. Clamped by `catalog` when both are present. */\n  readonly override?: number | undefined;\n  /** The model's window from the catalog, in tokens. Absent when the model is unknown. */\n  readonly catalog?: number | undefined;\n  /** Safety margin in `(0, 1]`. Codex uses 0.95 (`model_info.rs:158`). */\n  readonly margin: number;\n  /** Conservative floor used ONLY when neither `override` nor `catalog` is available. */\n  readonly floor?: number | undefined;\n}\n\n/** Result of {@link resolveEffectiveContextWindow}. */\nexport interface EffectiveContextWindow {\n  /** The window to budget against, after clamp and margin. */\n  readonly window: number;\n  /** Which input won — `\"fallback\"` means neither override nor catalog was available. */\n  readonly source: ContextWindowSource;\n  /** `true` when an `override` above the catalog window was clamped down to it. */\n  readonly clamped: boolean;\n}\n\n/**\n * Resolve the window to budget against — the fail-SAFE replacement for reading the catalog directly.\n *\n * Today `post-run-lifecycle.ts` reads `getCatalogModelInfo(model)?.limit?.context` and, when that is\n * `undefined`, auto-compaction simply never fires. That is fail-OPEN: the context grows until the\n * provider rejects the request. (The comment there calls it \"fail-safe\" — M77 corrects it.)\n *\n * Three techniques, two of them borrowed from the single reference:\n *\n *  1. **Override, CLAMPED by the catalog** — Codex `models-manager/src/model_info.rs:26-31` lets\n *     config override the window but limits it with `context_window.min(max_context_window)`.\n *     Without the clamp, declaring 999k on a 200k model reopens the overflow through another door.\n *  2. **Multiplicative margin** — Codex `model_info.rs:158` (`effective_context_window_percent: 95`)\n *     never budgets against 100% of the window. Being multiplicative, it is conservative for ANY\n *     window size.\n *  3. **Floor, only when nothing is known** — deliberately NOT a blanket default. A fixed floor is\n *     conservative only upward: applied to a small model it would inflate the assumed window and\n *     reproduce the very fail-open this function exists to close. Hence the floor never competes\n *     with a known catalog value.\n *\n * Pure — no catalog lookup, no I/O. The caller supplies the numbers, mirroring `shouldCompact`.\n */\nexport function resolveEffectiveContextWindow(\n  input: EffectiveContextWindowInput,\n): EffectiveContextWindow {\n  if (!(input.margin > 0) || input.margin > 1) {\n    throw new ContextWindowMarginError(input.margin);\n  }\n\n  const withMargin = (raw: number): number => Math.floor(raw * input.margin);\n\n  if (input.override !== undefined) {\n    const clamped = input.catalog !== undefined && input.override > input.catalog;\n    const raw = clamped ? (input.catalog as number) : input.override;\n    return { window: withMargin(raw), source: \"override\", clamped };\n  }\n\n  if (input.catalog !== undefined) {\n    return { window: withMargin(input.catalog), source: \"catalog\", clamped: false };\n  }\n\n  return { window: withMargin(input.floor ?? 0), source: \"fallback\", clamped: false };\n}\n\n/** Input to {@link shouldCompact}: an estimate, the model's window, and reserved headroom. */\nexport interface ShouldCompactInput {\n  /** Estimated token count of the next request (e.g. from {@link estimateTokens}). */\n  readonly estimated: number;\n  /** The model's total context window, in tokens. */\n  readonly contextWindow: number;\n  /** Tokens to reserve as headroom (output + safety margin). */\n  readonly buffer: number;\n  /**\n   * Tokens reserved for the model's response generation, SEPARATE from `buffer`.\n   * Default 0 — omitting it preserves the legacy\n   * `estimated >= contextWindow - buffer` result.\n   */\n  readonly maxOutput?: number;\n}\n\n/**\n * Tokenizer-free token estimate via the conventional ~4-chars-per-token\n * heuristic: `ceil(text.length / 4)`. `\"\"` → 0; any non-empty text → ≥ 1.\n * A cheap PRE-CALL gate for {@link shouldCompact} — NOT exact tokenization\n * (a consumer needing exactness supplies their own tokenizer). Uses UTF-16\n * `.length` (code units), so multibyte text is approximate.\n */\nexport function estimateTokens(text: string): number {\n  return Math.ceil(text.length / 4);\n}\n\n/**\n * Decide BEFORE sending whether to compact: `true` when the `estimated` token\n * count leaves less than `buffer` headroom in the `contextWindow`\n * (`estimated >= contextWindow - buffer`). A `buffer >= contextWindow`\n * (non-positive threshold) always returns `true`. Pure — the caller supplies\n * the window (e.g. from `resolveModelCapabilities`), keeping this decoupled\n * from the per-model catalog.\n */\nexport function shouldCompact(input: ShouldCompactInput): boolean {\n  return input.estimated >= input.contextWindow - input.buffer - (input.maxOutput ?? 0);\n}\n"]}