@ashlr/hub 3.8.0 → 3.9.0

package/dist/core/verse/model-windows.d.ts

@@ -0,0 +1,217 @@
+/**
+ * core/verse/model-windows.ts — the per-model context budgets every seat is
+ * built from (Verse 3.9, owner U4). docs/VERSE-CONTEXT.md §1 is the prose
+ * authority; every number below was read from a CLI or a seat's own catalog on
+ * 2026-09-23, never recalled.
+ *
+ * WHY THIS MODULE EXISTS. Until 3.9 every model option carried one number, and
+ * for six of the eight Claude models it was wrong: they all inherited the
+ * CLI's 200k "unknown model" fallback while the CLI itself ran them at 1M.
+ * Codex showed its RAW 272k window while the CLI measures against 95% of it,
+ * and Grok showed 256k against a 500k window. So the meter under- or
+ * over-read on every native engine. This module is the single place a seat's
+ * model list — windows, compaction points, expansive budgets and the binary
+ * each model needs — is assembled, and it does the arithmetic ONLY through
+ * `context-math.ts`, so "compacts at 367k" can never mean two numbers.
+ *
+ * SOURCES, in the order a seat prefers them:
+ *
+ *  Claude — the CLI's EMBEDDED catalog (`windowSource: 'cli-catalog'`). There
+ *    is no per-seat file to read: the served catalog cache carries no windows
+ *    (`max_input_tokens` absent on every row), so the binary is the authority.
+ *    The table below is transcribed from the 2.1.257 and 2.1.280 binaries.
+ *  Codex  — the seat's OWN `native-state/models_cache.json`
+ *    (`provider-catalog`). Catalogs differ per ACCOUNT (codex-b lacks the
+ *    daybreak slug the global cache has) and per BINARY, so the unpinned
+ *    `~/.codex` cache is never consulted. No catalog yet → a documented list.
+ *  Grok   — the seat's OWN `native-state/models_cache.json`, whose `.models`
+ *    is a dict of `{info, api_key, env_key, api_base_url}`. ONLY `.info` is
+ *    ever read: `api_key` is a credential slot and must not be touched, copied
+ *    or returned, even though it is null today.
+ *
+ * Runtime readings (claude/grok `result.modelUsage`, codex rollouts) override
+ * all of this per turn — see the session engine. These are the STARTING
+ * budgets and the picker's promises, not the last word.
+ *
+ * Nothing here throws, spends, or reaches the network. File reads are
+ * size-capped, symlink-refusing and cached by path + mtime + size.
+ */
+import { type VerseEngine, type VerseModelOption, type VerseWindowSource } from './types.js';
+/**
+ * Every Claude model a seat offers, in picker order (first runnable = default).
+ *
+ * Transcribed from the embedded catalog of Claude Code 2.1.257 and 2.1.280
+ * (`context.window`, `context.native_1m`, `max_output_tokens.default`):
+ *
+ *  - `native1m` is the catalog's own `native_1m` flag: the CLI runs these at
+ *    1M with no `[1m]` suffix on a first-party seat. Never append `[1m]` to a
+ *    200k model — the CLI would then CLAIM 1M for a model that has 200k.
+ *  - `maxOutputTokens` is the catalog DEFAULT, not the upper bound: it is the
+ *    number Claude Code reserves from (capped at 20k) when it computes the
+ *    compaction point, which is all Verse uses it for.
+ *  - `minCliVersion` is set only where a binary genuinely lacks the id.
+ *    `claude-opus-5-5` is absent from 2.1.257 (0 occurrences) and present in
+ *    2.1.280, and the served catalog cache says `min_claude_code_version:
+ *    "2.1.280"`. An older binary does not reject it — its id normaliser falls
+ *    back to `includes('claude-opus-5')` and silently runs Opus 5 — which is
+ *    why a too-old seat lists it as UNAVAILABLE instead of offering it.
+ *
+ * The dotted `claude-opus-5.5` Verse once shipped is an ALIAS (context-math
+ * `VERSE_MODEL_ID_ALIASES`): on every binary it resolves to Opus 5. It is
+ * never offered; old records keep it and adapters send the canonical id.
+ *
+ * `claude-mythos-5` / `-5-1` are in the catalog too but are deliberately not
+ * offered: whether a subscription seat may use them is unverified, and a
+ * picker entry is a promise.
+ */
+export declare const VERSE_CLAUDE_MODEL_SPECS: readonly {
+    id: string;
+    label: string;
+    contextWindow: number;
+    maxOutputTokens: number | null;
+    minCliVersion: string | null;
+    native1m: boolean;
+}[];
+type ClaudeModelSpec = (typeof VERSE_CLAUDE_MODEL_SPECS)[number];
+/**
+ * The spec for a model id, after alias canonicalisation — so an old session
+ * stored as `claude-opus-5.5` finds Opus 5.5's budget. A trailing `[1m]`
+ * (which the CLI strips from native-1M ids anyway) is tolerated. Null for an
+ * id this table does not know: the caller falls back to the seat, then to
+ * `VERSE_DEFAULT_CONTEXT_WINDOWS.claude` — never to a guess.
+ */
+export declare function claudeSpecFor(modelId: string): ClaudeModelSpec | null;
+/**
+ * The Claude model list for a seat pinned to `cliVersion`.
+ *
+ * `cliVersion === null` means UNKNOWN, and unknown is not "too old": no model
+ * is marked unavailable on a guess (the seat carries a note instead). Order is
+ * the table's; callers put runnable models first.
+ */
+export declare function claudeModelOptions(cliVersion: string | null): VerseModelOption[];
+/** Specs a binary of `cliVersion` is too old for (empty when the version is unknown). */
+export declare function claudeModelsNeedingNewerCli(cliVersion: string | null): ClaudeModelSpec[];
+/** Labels for a note: "Opus 5.5", "Opus 5.5 and Fable 6", "A, B and C". */
+export declare function joinClaudeLabels(specs: readonly ClaudeModelSpec[]): string;
+/**
+ * Compare two CLI versions: negative when `a` is older, 0 when equal, positive
+ * when newer. Numeric per segment (2.1.280 > 2.1.257 > 2.1.99), and a
+ * pre-release sorts before its release (0.155.0-alpha.9 < 0.155.0). Strings
+ * with no `x.y.z` in them compare equal to each other and older than any real
+ * version — an unparseable version is never allowed to unlock a model.
+ */
+export declare function compareCliVersions(a: string, b: string): number;
+/**
+ * The version of the CLI a native profile is pinned to, from the executable
+ * path its launcher execs. Never runs the binary (that would be a process
+ * spawn on the discovery path, and some CLIs phone home on `--version`).
+ *
+ *  - Claude Code installs each version as a file NAMED by it:
+ *    `~/.local/share/claude/versions/2.1.257` → `2.1.257`.
+ *  - Grok's downloads embed it: `grok-0.2.118-macos-aarch64` → `0.2.118`.
+ *  - The npm codex wrapper is `…/@openai/codex/bin/codex.js`; its version is
+ *    the package's own `package.json`, read with a size cap.
+ *
+ * Anything else (e.g. the codex binary inside ChatGPT.app) is null: unknown,
+ * which is reported as unknown rather than guessed from a neighbour.
+ */
+export declare function cliVersionFromExecutable(executablePath: string): string | null;
+/** Where Claude Code's installer keeps one file per installed version. */
+export declare function defaultClaudeVersionsRoot(home?: string): string;
+/**
+ * The newest Claude Code version installed on this machine, or null. Only
+ * regular files named exactly `x.y.z` count — the installer's lock and
+ * partial-download files are skipped.
+ */
+export declare function newestInstalledClaudeVersion(root?: string): string | null;
+/** Every catalog read is capped here — codex's is ~350 KB today. */
+export declare const VERSE_CATALOG_MAX_BYTES: number;
+/** Test seam: forget every cached catalog read. */
+export declare function resetModelWindowCaches(): void;
+/** One row of a codex `models_cache.json`, reduced to what budgets need. */
+export interface CodexCatalogEntry {
+    slug: string;
+    displayName: string | null;
+    /** `list`, `hide`, … — `hide` rows are never offered. */
+    visibility: string | null;
+    /** RAW window the model is configured with by default (272_000). */
+    contextWindow: number;
+    /** Largest window `model_context_window` may be raised to (872_000); null when absent. */
+    maxContextWindow: number | null;
+    /** Share of the raw window the CLI measures against (95); null → the documented default. */
+    effectiveContextWindowPercent: number | null;
+    /** Explicit auto-compaction limit from the catalog; null → 90% of the raw window. */
+    autoCompactTokenLimit: number | null;
+    priority: number | null;
+}
+/**
+ * The seat's own codex catalog, or null when it has none yet (a seat that has
+ * never run a turn has not fetched one) or it is unreadable. `nativeStatePath`
+ * is the seat profile's `CODEX_HOME` — NEVER the unpinned `~/.codex`, whose
+ * catalog belongs to a different account and binary.
+ */
+export declare function readCodexCatalog(nativeStatePath: string): CodexCatalogEntry[] | null;
+/**
+ * A codex seat's model list: every VISIBLE slug in its own catalog, in the
+ * provider's priority order, or the documented list (`windowSource:
+ * 'documented'`) when the seat has not fetched a catalog yet.
+ */
+export declare function codexModelOptions(catalog: CodexCatalogEntry[] | null): VerseModelOption[];
+/** One grok catalog row, lifted out of `.models[id].info` and nothing else. */
+export interface GrokCatalogEntry {
+    id: string;
+    name: string | null;
+    contextWindow: number | null;
+    autoCompactThresholdPercent: number | null;
+    maxCompletionTokens: number | null;
+    hidden: boolean;
+    supportedInApi: boolean;
+}
+/**
+ * The seat's own grok catalog (`<GROK_HOME>/models_cache.json`), or null. The
+ * unpinned `~/.grok` cache is stale on this machine (fetched weeks earlier,
+ * two models) and is never consulted.
+ */
+export declare function readGrokCatalog(nativeStatePath: string): GrokCatalogEntry[] | null;
+/**
+ * A grok seat's model list: every entry that is not hidden and not flagged
+ * unsupported, in the catalog's own order (JSON object order is preserved and
+ * is the CLI's), or the documented list when the seat has no catalog. Grok has
+ * no expansive mode: its CLI cannot be told a larger budget per invocation.
+ */
+export declare function grokModelOptions(catalog: GrokCatalogEntry[] | null): VerseModelOption[];
+/**
+ * A local (Ollama / llama-server) model option. Local turns run the Claude
+ * Code binary with `CLAUDE_CODE_MAX_CONTEXT_TOKENS=<window>`, so they compact
+ * by the Claude formula over the window Verse resolved; max output is unknown
+ * for a non-Claude id, which the formula treats as the 20k reserve cap. No
+ * expansive mode: the window IS the runtime's allocation.
+ */
+export declare function localModelOption(tag: string, label: string, window: number, source: VerseWindowSource): VerseModelOption;
+/**
+ * The option whose budgets govern a session, given the option its PINNED
+ * launch snapshot lists (`snapshot`, null when the snapshot no longer lists
+ * the model).
+ *
+ * Normally the snapshot's own option. The exception is a snapshot written
+ * before 3.9: its options carry one flat window and no budgets (claude: the
+ * CLI's 200k fallback for every model; codex: the RAW 272k window, which the
+ * CLI measures against 95% of; grok: the 500k default), so it can state
+ * neither a compaction point nor an expansive budget. For those, the model's
+ * DOCUMENTED option from this module supplies the budgets — the same builders
+ * the live seat lists are made from, so the web UI (which reads the live seat)
+ * and the engine and adapters (which read the snapshot) can never disagree
+ * about whether a mode exists or what it costs. The snapshot keeps its identity
+ * (id, label); only budgets are borrowed.
+ *
+ * ONE helper, used by the engine (`effectiveModelOption`) and by every adapter
+ * that turns a budget into CLI flags (claude `--autocompact`, codex
+ * `-c model_context_window`), because two copies of this rule would drift and
+ * the flag the CLI is given must be the budget the meter shows.
+ *
+ * A model this module does not know keeps its snapshot option (and, lacking an
+ * expansive budget, gets no expansive mode — absent, never faked). Local is
+ * never substituted.
+ */
+export declare function legacyModelOptionFallback(engine: VerseEngine, model: string, snapshot: VerseModelOption | null): VerseModelOption | null;
+export {};