@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/client/theokit-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TheoKitClient — browser-safe client for consuming server adapter endpoints
+ * (T20.2, ADR D454).
+ *
+ * Zero Node dependencies. Uses native fetch + manual SSE parsing.
+ * Consumes the same HTTP contract as server adapters (POST /send, GET /stream).
+ *
+ * @public
+ * @deprecated since 2.x — consumes a legacy server-adapter HTTP contract
+ * (`POST /agent/send`, `GET /agent/stream`) that the ecosystem no longer
+ * produces. For in-process agent runs use the `Agent` façade (`@theokit/sdk`);
+ * for HTTP, the framework (`theokit`) exposes agents at `POST /api/agents/<name>`
+ * over a `UIMessageStream` with its own typed client. The `@theokit/sdk/client`
+ * sub-path will be removed in the next major.
+ */
+import type { ClientOptions, SendResponse, StreamEvent } from "./types.js";
+/**
+ * Browser-safe client for the legacy agent HTTP contract: `POST <basePath>/send`
+ * and `GET <basePath>/stream`. Uses only `fetch` and `TextDecoder`, so it runs in
+ * a browser, a worker, or Node with no Node-only dependency.
+ *
+ *   const client = new TheoKitClient({ baseUrl: "https://api.example.com" });
+ *   const res = await client.send("hello");
+ *   for await (const ev of client.stream("hello")) console.log(ev.type);
+ *
+ * Deprecated together with the `@theokit/sdk/client` sub-path — the module note
+ * above names the replacements.
+ *
+ * Needs a reachable `baseUrl` (a trailing `/` is stripped) and a server exposing
+ * BOTH routes under `basePath` (default `/agent`). `opts.headers` is merged into
+ * every request and is the only auth affordance; there is no retry, no timeout and
+ * no way to pass an `AbortSignal` — neither method accepts one.
+ *
+ * How it fails: both methods throw a plain `Error` on any non-2xx
+ * (`TheoKitClient: send failed with status <n>` /
+ * `TheoKitClient: stream failed with status <n>`), so the server's error body is
+ * discarded. `stream` additionally throws
+ * `TheoKitClient: response body is not readable` when the response carries no
+ * body. There is no typed error class and no status field to branch on.
+ *
+ * Traps:
+ *  - `stream` ends on a `data: [DONE]` sentinel. NOTHING in this package emits SSE
+ *    framing: `createAgentHandler` returns a raw `AsyncIterable` and leaves
+ *    `data: ` / `[DONE]` to the host. Pointed at this SDK's own adapter as-is, the
+ *    generator yields no events and ends only when the socket closes.
+ *  - A `data:` line whose payload is not JSON is skipped SILENTLY, so malformed
+ *    output looks like a quiet stream rather than an error.
+ *  - Leaving the loop early (`break`) releases the reader lock but does NOT abort
+ *    the request; the connection stays open until the server closes it.
+ *  - `stream` puts the whole input in the query string, so a long prompt can
+ *    exceed a proxy's URL length limit while the same input works via `send`.
+ */
+export declare class TheoKitClient {
+    private readonly _baseUrl;
+    private readonly _basePath;
+    private readonly _headers;
+    constructor(opts: ClientOptions);
+    send(input: string): Promise<SendResponse>;
+    stream(input: string): AsyncGenerator<StreamEvent, void, void>;
+}

package/dist/client/types.d.cts

@@ -0,0 +1,51 @@
+/**
+ * Client SDK types (T20.2, ADR D454).
+ * @public
+ * @deprecated since 2.x — types for the deprecated `@theokit/sdk/client`
+ * (`TheoKitClient`) sub-path; removed with it in the next major.
+ */
+export interface ClientOptions {
+    baseUrl: string;
+    basePath?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Body of `POST <basePath>/send` as {@link TheoKitClient.send} resolves it.
+ *
+ * Deprecated with the sub-path, and worth reading as a loose envelope rather than
+ * a contract: it does NOT describe what this package's own server adapters
+ * produce. `createAgentHandler` answers with a `RunResult`
+ * (`{ id, status, result?, model?, durationMs?, ... }`), so against that server
+ * `output` and `error` are always `undefined` and the agent's text arrives under
+ * a `result` key this interface does not declare.
+ *
+ * `status` is a bare `string` here; `RunResult.status` is the narrower
+ * `"finished" | "error" | "cancelled"`.
+ *
+ * A non-2xx response never reaches this type — `send` throws instead, so `error`
+ * is not where a transport failure shows up.
+ */
+export interface SendResponse {
+    status: string;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * One decoded SSE frame from {@link TheoKitClient.stream}: the JSON body of a
+ * `data:` line, with `type` promoted and every other key left open.
+ *
+ * Deprecated with the sub-path. `type`/`text` mirror the legacy server contract;
+ * the events this SDK's own `Run.stream()` emits are `SDKMessage`s carrying their
+ * own fields, which is why everything else is `unknown` and must be narrowed
+ * before use.
+ *
+ * Trap: nothing validates the frame. A `data:` line that is not JSON is skipped
+ * silently, and one that parses to any JSON value at all is cast to this type
+ * unchecked — `event.type` can be `undefined` at runtime despite being declared
+ * required.
+ */
+export interface StreamEvent {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}

package/dist/client/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Client SDK types (T20.2, ADR D454).
+ * @public
+ * @deprecated since 2.x — types for the deprecated `@theokit/sdk/client`
+ * (`TheoKitClient`) sub-path; removed with it in the next major.
+ */
+export interface ClientOptions {
+    baseUrl: string;
+    basePath?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Body of `POST <basePath>/send` as {@link TheoKitClient.send} resolves it.
+ *
+ * Deprecated with the sub-path, and worth reading as a loose envelope rather than
+ * a contract: it does NOT describe what this package's own server adapters
+ * produce. `createAgentHandler` answers with a `RunResult`
+ * (`{ id, status, result?, model?, durationMs?, ... }`), so against that server
+ * `output` and `error` are always `undefined` and the agent's text arrives under
+ * a `result` key this interface does not declare.
+ *
+ * `status` is a bare `string` here; `RunResult.status` is the narrower
+ * `"finished" | "error" | "cancelled"`.
+ *
+ * A non-2xx response never reaches this type — `send` throws instead, so `error`
+ * is not where a transport failure shows up.
+ */
+export interface SendResponse {
+    status: string;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * One decoded SSE frame from {@link TheoKitClient.stream}: the JSON body of a
+ * `data:` line, with `type` promoted and every other key left open.
+ *
+ * Deprecated with the sub-path. `type`/`text` mirror the legacy server contract;
+ * the events this SDK's own `Run.stream()` emits are `SDKMessage`s carrying their
+ * own fields, which is why everything else is `unknown` and must be narrowed
+ * before use.
+ *
+ * Trap: nothing validates the frame. A `data:` line that is not JSON is skipped
+ * silently, and one that parses to any JSON value at all is cast to this type
+ * unchecked — `event.type` can be `undefined` at runtime despite being declared
+ * required.
+ */
+export interface StreamEvent {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}

package/dist/compact-session-BHTPCIHA.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+var chunk2HPNT6HH_cjs = require('./chunk-2HPNT6HH.cjs');
+require('./chunk-FUSDYC2B.cjs');
+require('./chunk-YJNYDJ2T.cjs');
+require('./chunk-24SYBZPL.cjs');
+require('./chunk-QOGNZMHD.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-YSTXFWQE.cjs');
+require('./chunk-FRITRLZQ.cjs');
+require('./chunk-7A6535RA.cjs');
+require('./chunk-SA6K24NB.cjs');
+require('./chunk-GZV6AVRL.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-ATT276RD.cjs');
+require('./chunk-3EE6LVWT.cjs');
+require('./chunk-QC55H6RJ.cjs');
+require('./chunk-NVXXWAU7.cjs');
+require('./chunk-4NLCWGH7.cjs');
+require('./chunk-EXTRW7GW.cjs');
+require('./chunk-HUFSABUZ.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "COMPACT_SUMMARY_MARKER", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.COMPACT_SUMMARY_MARKER; }
+});
+Object.defineProperty(exports, "COMPACT_USER_MESSAGE_MAX_TOKENS", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.COMPACT_USER_MESSAGE_MAX_TOKENS; }
+});
+Object.defineProperty(exports, "autoCompactIfNeeded", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.autoCompactIfNeeded; }
+});
+Object.defineProperty(exports, "buildDefaultSummarizer", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.buildDefaultSummarizer; }
+});
+Object.defineProperty(exports, "compactSessionTranscript", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.compactSessionTranscript; }
+});
+Object.defineProperty(exports, "isCompactSummary", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.isCompactSummary; }
+});
+Object.defineProperty(exports, "resolveSummarizerRoute", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.resolveSummarizerRoute; }
+});
+Object.defineProperty(exports, "shouldAutoCompact", {
+  enumerable: true,
+  get: function () { return chunk2HPNT6HH_cjs.shouldAutoCompact; }
+});
+//# sourceMappingURL=compact-session-BHTPCIHA.cjs.map
+//# sourceMappingURL=compact-session-BHTPCIHA.cjs.map

package/dist/compact-session-BHTPCIHA.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-BHTPCIHA.cjs"}

package/dist/compact-session-W4WLJTHA.js

@@ -0,0 +1,24 @@
+export { COMPACT_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, autoCompactIfNeeded, buildDefaultSummarizer, compactSessionTranscript, isCompactSummary, resolveSummarizerRoute, shouldAutoCompact } from './chunk-K3NH62DG.js';
+import './chunk-UBR5PWD7.js';
+import './chunk-2XC6KDJM.js';
+import './chunk-XB4GI5RZ.js';
+import './chunk-24MGQDK3.js';
+import './chunk-FD2UT76F.js';
+import './chunk-FJWQP6EE.js';
+import './chunk-NAF4L3T6.js';
+import './chunk-EH6XD3FY.js';
+import './chunk-UKMBRMGT.js';
+import './chunk-JOFVLOFY.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-6M2OIS4Y.js';
+import './chunk-R7WIIPUR.js';
+import './chunk-VWUXIVEI.js';
+import './chunk-AGACYRJ2.js';
+import './chunk-JMDDYA22.js';
+import './chunk-V22DZIXO.js';
+import './chunk-NJWYQWDL.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=compact-session-W4WLJTHA.js.map
+//# sourceMappingURL=compact-session-W4WLJTHA.js.map

package/dist/compact-session-W4WLJTHA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compact-session-W4WLJTHA.js"}

package/dist/compaction.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+var chunkATT276RD_cjs = require('./chunk-ATT276RD.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "ABSOLUTE_CONTEXT_WINDOW_CAP", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.ABSOLUTE_CONTEXT_WINDOW_CAP; }
+});
+Object.defineProperty(exports, "CHARS_PER_TOKEN", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.CHARS_PER_TOKEN; }
+});
+Object.defineProperty(exports, "CHECKPOINT_MARKER", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.CHECKPOINT_MARKER; }
+});
+Object.defineProperty(exports, "CONTEXT_WINDOW_FLOOR", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.CONTEXT_WINDOW_FLOOR; }
+});
+Object.defineProperty(exports, "CONTEXT_WINDOW_MARGIN", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.CONTEXT_WINDOW_MARGIN; }
+});
+Object.defineProperty(exports, "ContextWindowMarginError", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.ContextWindowMarginError; }
+});
+Object.defineProperty(exports, "SUMMARY_TEMPLATE", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.SUMMARY_TEMPLATE; }
+});
+Object.defineProperty(exports, "buildCheckpoint", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.buildCheckpoint; }
+});
+Object.defineProperty(exports, "compactTranscript", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.compactTranscript; }
+});
+Object.defineProperty(exports, "estimateTokens", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.estimateTokens; }
+});
+Object.defineProperty(exports, "filterFromLatestCheckpoint", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.filterFromLatestCheckpoint; }
+});
+Object.defineProperty(exports, "isContextOverflowError", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.isContextOverflowError; }
+});
+Object.defineProperty(exports, "resolveEffectiveContextWindow", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.resolveEffectiveContextWindow; }
+});
+Object.defineProperty(exports, "shouldCompact", {
+  enumerable: true,
+  get: function () { return chunkATT276RD_cjs.shouldCompact; }
+});
+//# sourceMappingURL=compaction.cjs.map
+//# sourceMappingURL=compaction.cjs.map

package/dist/compaction.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compaction.cjs"}

package/dist/compaction.d.cts

@@ -0,0 +1,240 @@
+/**
+ * Public compaction / context-management helpers (M2-1, extended V3-3).
+ *
+ * Promotes the SDK's compaction capability to a public surface so consumers can
+ * compact a transcript, mark/filter conversation checkpoints, and detect
+ * context-overflow — without reaching into `internal/`.
+ *
+ * Two recent-window modes (V3-3):
+ *  - `keepRecent` (turn-count, default) — keeps the last N turns verbatim and
+ *    always preserves leading system PROMPTS; reuses the internal
+ *    `selectCompressionWindow` (no second algorithm).
+ *  - `keepTokens` (token-budget) — keeps the trailing turns whose accumulated
+ *    `estimateTokens` fits the budget (theocode `splitTranscript` semantics). In
+ *    this mode leading system prompts are NOT special-cased (D6).
+ *
+ * Summarization is delegated to a caller-supplied callback (which receives the
+ * older window + the summary template). With `failSafe`, a thrown summarizer
+ * returns the ORIGINAL transcript + a structured warn (compaction is an
+ * optimization, never a cause of data loss); without it, the error propagates.
+ *
+ * Public from the `@theokit/sdk/compaction` sub-path.
+ */
+import { TheokitAgentError } from "./errors.js";
+/**
+ * Minimal message shape for compaction/compression input. THE canonical public origin (leaf type —
+ * rollup-plugin-dts cannot re-export types from internal modules into entry bundles; M42 lesson).
+ *
+ * @public
+ */
+export interface CompressibleMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * Sentinel prefix marking a conversation checkpoint turn. A visible, structured,
+ * prose-unlikely token (no invisible/control bytes — safe to persist and to read
+ * in source). Only {@link buildCheckpoint} should produce content beginning with it.
+ */
+export declare const CHECKPOINT_MARKER = "[[theokit:checkpoint]] ";
+/**
+ * The 7-section summary template handed to the `summarize` callback (theocode
+ * parity shape). Every header is always present so the summarizer cannot silently
+ * drop a category; the model is told to preserve file paths, commands, and error
+ * text verbatim. Override per-call via {@link CompactTranscriptOptions.summaryTemplate}.
+ */
+export declare 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).";
+/** Options for {@link compactTranscript}. */
+export interface CompactTranscriptOptions {
+    /** Trailing turns preserved verbatim by COUNT (default 6). Ignored when `keepTokens` is set. */
+    keepRecent?: number;
+    /**
+     * Trailing turns preserved verbatim by TOKEN BUDGET (theocode mode). When set,
+     * takes precedence over `keepRecent` and disables system-prompt preservation (D6).
+     */
+    keepTokens?: number;
+    /** Checkpoint marker (default {@link CHECKPOINT_MARKER}). Must be non-empty. */
+    marker?: string;
+    /** Summary template passed to `summarize` (default {@link SUMMARY_TEMPLATE}). */
+    summaryTemplate?: string;
+    /** Summarize the older window into one turn; if omitted, the older window is dropped. */
+    summarize?: (older: CompressibleMessage[], template: string) => Promise<CompressibleMessage>;
+    /**
+     * When true, a thrown `summarize` returns the ORIGINAL transcript + a structured
+     * warn (compaction never loses data). Default false: the error propagates.
+     */
+    failSafe?: boolean;
+}
+/**
+ * Compact a transcript. In `keepRecent` mode (default) the last `keepRecent` turns
+ * are kept verbatim and leading system PROMPTS preserved; in `keepTokens` mode the
+ * trailing turns within the token budget are kept (no system special-casing, D6).
+ * The older window is summarized (via `summarize`, receiving the template) or
+ * dropped. Never mutates the input.
+ */
+export declare function compactTranscript(messages: CompressibleMessage[], options?: CompactTranscriptOptions): Promise<CompressibleMessage[]>;
+/**
+ * Build a checkpoint marker turn (a `system` turn whose content starts with
+ * `marker`, default {@link CHECKPOINT_MARKER}). `marker` must be non-empty.
+ */
+export declare function buildCheckpoint(label?: string, marker?: string): CompressibleMessage;
+/** Options for {@link filterFromLatestCheckpoint}. */
+export interface FilterCheckpointOptions {
+    /** Marker to scan for (default {@link CHECKPOINT_MARKER}). */
+    marker?: string;
+    /**
+     * `'after'` (default, M2) returns turns AFTER the latest marker (exclusive);
+     * `'from'` (theocode) returns turns FROM the latest marker (inclusive).
+     */
+    include?: "after" | "from";
+}
+/**
+ * Return the turns relative to the most recent checkpoint marker (all turns if
+ * none). `include: 'after'` (default) excludes the checkpoint; `'from'` includes
+ * it (the summary stands in for the pruned head). Never mutates the input.
+ */
+export declare function filterFromLatestCheckpoint(messages: CompressibleMessage[], options?: FilterCheckpointOptions): CompressibleMessage[];
+/**
+ * True iff `err` is a {@link TheokitAgentError} (or subclass) reporting a
+ * context-window-exceeded condition (the typed `context_too_long` code). Reads
+ * both `code` (set by provider mappers) and `metadata.code` (the preferred field)
+ * — never a brittle message regex.
+ */
+export declare function isContextOverflowError(err: unknown): boolean;
+/**
+ * M77 — the margin is outside `(0, 1]`. Typed, because a margin > 1 would GROW the assumed window,
+ * which is the unsafe direction: `shouldCompact` is monotonically decreasing in `contextWindow`, so
+ * overestimating it makes the trigger fire too late and the context overflow.
+ */
+export declare class ContextWindowMarginError extends TheokitAgentError {
+    readonly margin: number;
+    constructor(margin: number);
+}
+/**
+ * M77 — default safety margin on the context window.
+ *
+ * `0.95` is not a guess: it is the single reference's value. Codex ships
+ * `effective_context_window_percent: 95` (`models-manager/src/model_info.rs:158`) and never budgets
+ * against 100% of a window. Being MULTIPLICATIVE, it stays conservative at any window size, which a
+ * fixed subtraction would not.
+ */
+export declare const CONTEXT_WINDOW_MARGIN = 0.95;
+/**
+ * M77 — the floor used ONLY when neither the catalog nor the caller knows the window.
+ *
+ * Honest about its own weakness. This number has **one** source (the M77 milestone text); the search
+ * for a second one failed, because the reference has no fallback at all — Codex returns `Option` and
+ * its callers early-return (`core/src/session/turn_context.rs:213`, `core/src/compact_remote.rs:374`).
+ *
+ * It is conservative only UPWARD. For a model whose real window is larger, budgeting against 128k
+ * compacts early — wasteful but safe. For a model whose real window is SMALLER (an 8k or 32k model
+ * absent from the catalog), it compacts too late and the context still overflows. That residual risk
+ * is real and is why {@link resolveEffectiveContextWindow} never lets this floor compete with a known
+ * catalog value, and why the `compaction_fallback` event exists: a surface can show that the budget is
+ * a guess instead of the user finding out when the provider rejects the request.
+ */
+export declare const CONTEXT_WINDOW_FLOOR = 128000;
+/** Where the effective window came from — carried into the M77 structured event. */
+export type ContextWindowSource = "override" | "catalog" | "fallback";
+/** Input to {@link resolveEffectiveContextWindow}. */
+export interface EffectiveContextWindowInput {
+    /** Caller-supplied window, in tokens. Clamped by `catalog` when both are present. */
+    readonly override?: number | undefined;
+    /** The model's window from the catalog, in tokens. Absent when the model is unknown. */
+    readonly catalog?: number | undefined;
+    /** Safety margin in `(0, 1]`. Codex uses 0.95 (`model_info.rs:158`). */
+    readonly margin: number;
+    /** Conservative floor used ONLY when neither `override` nor `catalog` is available. */
+    readonly floor?: number | undefined;
+}
+/** Result of {@link resolveEffectiveContextWindow}. */
+export interface EffectiveContextWindow {
+    /** The window to budget against, after clamp and margin. */
+    readonly window: number;
+    /** Which input won — `"fallback"` means neither override nor catalog was available. */
+    readonly source: ContextWindowSource;
+    /** `true` when an `override` above the catalog window was clamped down to it. */
+    readonly clamped: boolean;
+}
+/**
+ * Absolute cap on a declared context window, applied when no catalog entry exists to compare against.
+ *
+ * **10M**, not 2M. The first version used 2M on the rationale that it sat "comfortably above the
+ * largest published window" — adversarial review measured the opposite: Llama 4 Scout publishes
+ * **10M**, and it arrives precisely via OpenRouter, the provider **without** a catalog, which is the
+ * case this cap exists to cover. The user would have silently lost 80% of the declared window.
+ *
+ * The cap still serves what motivates it — one extra zero on 400k gives 4M, which passes; two zeros
+ * give 40M, which does not. A limit that rejects legitimate configuration is worse than no limit,
+ * because failing OPEN is visible when it happens and silently losing 80% is not.
+ */
+export declare const ABSOLUTE_CONTEXT_WINDOW_CAP = 10000000;
+/**
+ * Resolve the window to budget against — the fail-SAFE replacement for reading the catalog directly.
+ *
+ * Today `post-run-lifecycle.ts` reads `getCatalogModelInfo(model)?.limit?.context` and, when that is
+ * `undefined`, auto-compaction simply never fires. That is fail-OPEN: the context grows until the
+ * provider rejects the request. (The comment there calls it "fail-safe" — M77 corrects it.)
+ *
+ * Three techniques, two of them borrowed from the single reference:
+ *
+ *  1. **Override, CLAMPED by the catalog** — Codex `models-manager/src/model_info.rs:26-31` lets
+ *     config override the window but limits it with `context_window.min(max_context_window)`.
+ *     Without the clamp, declaring 999k on a 200k model reopens the overflow through another door.
+ *  2. **Multiplicative margin** — Codex `model_info.rs:158` (`effective_context_window_percent: 95`)
+ *     never budgets against 100% of the window. Being multiplicative, it is conservative for ANY
+ *     window size.
+ *  3. **Floor, only when nothing is known** — deliberately NOT a blanket default. A fixed floor is
+ *     conservative only upward: applied to a small model it would inflate the assumed window and
+ *     reproduce the very fail-open this function exists to close. Hence the floor never competes
+ *     with a known catalog value.
+ *
+ * Pure — no catalog lookup, no I/O. The caller supplies the numbers, mirroring `shouldCompact`.
+ */
+export declare function resolveEffectiveContextWindow(input: EffectiveContextWindowInput): EffectiveContextWindow;
+/** Input to {@link shouldCompact}: an estimate, the model's window, and reserved headroom. */
+export interface ShouldCompactInput {
+    /** Estimated token count of the next request (e.g. from {@link estimateTokens}). */
+    readonly estimated: number;
+    /** The model's total context window, in tokens. */
+    readonly contextWindow: number;
+    /** Tokens to reserve as headroom (output + safety margin). */
+    readonly buffer: number;
+    /**
+     * Tokens reserved for the model's response generation, SEPARATE from `buffer`.
+     * Default 0 — omitting it preserves the legacy
+     * `estimated >= contextWindow - buffer` result.
+     */
+    readonly maxOutput?: number;
+}
+/**
+ * Characters per token in the tokenizer-free estimate below.
+ *
+ * Exported so the ratio has ONE owner. It used to be a named constant in `built-in-processors.ts`
+ * and an inlined `4` here, with both `estimateTokens` functions `@public` from two different package
+ * entry points — so tuning the ratio, or switching to code points instead of UTF-16 units (the
+ * caveat both docblocks already carried), would have silently diverged them.
+ *
+ * @public
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/**
+ * Tokenizer-free token estimate via the conventional ~4-chars-per-token
+ * heuristic: `ceil(text.length / CHARS_PER_TOKEN)`. `""` → 0; any non-empty text → ≥ 1.
+ * A cheap PRE-CALL gate for {@link shouldCompact} — NOT exact tokenization
+ * (a consumer needing exactness supplies their own tokenizer). Uses UTF-16
+ * `.length` (code units), so multibyte text is approximate.
+ *
+ * `built-in-processors.ts` re-exports this under the same name, so both entry points keep working
+ * and there is one implementation behind them.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Decide BEFORE sending whether to compact: `true` when the `estimated` token
+ * count leaves less than `buffer` headroom in the `contextWindow`
+ * (`estimated >= contextWindow - buffer`). A `buffer >= contextWindow`
+ * (non-positive threshold) always returns `true`. Pure — the caller supplies
+ * the window (e.g. from `resolveModelCapabilities`), keeping this decoupled
+ * from the per-model catalog.
+ */
+export declare function shouldCompact(input: ShouldCompactInput): boolean;