@ashlr/hub 3.8.0 → 3.9.0

package/dist/core/verse/types.d.ts

@@ -43,11 +43,90 @@ export interface VerseSeat {
      * at all — `health.state` says what it does know.
      */
     capacity?: VerseSeatCapacity;
+    /**
+     * V3.9 ADDITIVE. The version of the CLI binary this seat is PINNED to (its
+     * native-profile launcher execs one exact file). Absent when unknown and on
+     * local seats. A pinned binary never updates itself, so a model that needs a
+     * newer CLI is listed with `unavailableReason` rather than silently failing.
+     */
+    cliVersion?: string;
+    /**
+     * V3.9 ADDITIVE. Plain-language facts about this seat's context setup the UI
+     * must show rather than imply (binary skew, catalog not yet fetched, …).
+     * Absent when there is nothing to say, so ordinary seats keep their shape.
+     */
+    notes?: string[];
+}
+/**
+ * Where a context-window figure came from, so nothing on screen implies more
+ * certainty than it has (docs/VERSE-CONTEXT.md §1).
+ *
+ * - `runtime`          — the CLI reported it for THIS turn (claude/grok
+ *                        `result.modelUsage.<m>.contextWindow`, codex rollout
+ *                        `token_count.info.model_context_window`, Ollama
+ *                        `/api/ps`). Wins over everything else.
+ * - `provider-catalog` — the seat's own served catalog on disk (codex/grok
+ *                        `native-state/models_cache.json`).
+ * - `cli-catalog`      — read out of the pinned CLI binary's embedded catalog
+ *                        and recorded here with the version it was read from.
+ * - `documented`       — the provider's published model table.
+ * - `fallback`         — a named default; the UI marks it as an estimate.
+ */
+export type VerseWindowSource = 'runtime' | 'provider-catalog' | 'cli-catalog' | 'documented' | 'fallback';
+/**
+ * How much context a session is allowed to accumulate before the CLI compacts.
+ *
+ * - `standard`  — the default. Evidence-based budget per engine: Claude 1M
+ *                 models compact near 400k instead of ~967k; Codex, Grok and
+ *                 local run their native windows.
+ * - `expansive` — opt-in. Claude runs its full native window (CLI `auto`),
+ *                 Codex raises `model_context_window` to the model's catalog
+ *                 maximum (872k on GPT-6 / GPT-5.6). Costs more usage per turn,
+ *                 buys simultaneous visibility for coupled, cross-cutting work.
+ *
+ * A mode that does not exist for a model (Grok, local, 200k Claude models,
+ * GPT-5.5) is simply absent from that model's option — never faked.
+ */
+export type VerseContextMode = 'standard' | 'expansive';
+export declare const VERSE_CONTEXT_MODES: readonly VerseContextMode[];
+/** One mode's budget for a model on a seat. */
+export interface VerseContextBudget {
+    /** The window the CLI measures against in this mode (the meter's denominator). */
+    contextWindow: number;
+    /** Token count at which the CLI auto-compacts in this mode; null when unknown. */
+    autoCompactAt: number | null;
+    /**
+     * The RAW window value the CLI must be TOLD to reach this budget, when that
+     * differs from `contextWindow` — codex measures against 95% of the window it
+     * is configured with, so expansive GPT-6 is `providerWindow: 872_000`
+     * (`-c model_context_window=872000`) but `contextWindow: 828_400`.
+     */
+    providerWindow?: number | null;
 }
 export interface VerseModelOption {
     id: string;
     label: string;
+    /** Standard-mode window the CLI measures against (codex: the 95% effective window). */
     contextWindow: number | null;
+    /**
+     * V3.9 ADDITIVE — every field below is optional so records and fixtures
+     * written before it keep validating. Absent means "not known", never zero.
+     */
+    /** Standard-mode auto-compaction point. */
+    autoCompactAt?: number | null;
+    /** Present ONLY when this model on this seat has a real expansive mode. */
+    expansive?: VerseContextBudget | null;
+    /** The CLI's default max output for this model, when known. */
+    maxOutputTokens?: number | null;
+    windowSource?: VerseWindowSource;
+    /** Minimum CLI version that knows this model id (e.g. '2.1.280'); null when any. */
+    minCliVersion?: string | null;
+    /**
+     * Why this model cannot run on this seat right now, in plain language (e.g.
+     * "needs Claude Code 2.1.280; this seat runs 2.1.257"). Null/absent = runnable.
+     * Listed rather than hidden so the operator learns WHY a model is missing.
+     */
+    unavailableReason?: string | null;
 }
 export interface VerseSeatHealth {
     state: 'ready' | 'degraded' | 'unavailable' | 'unknown';
@@ -324,9 +403,23 @@ export interface VerseUsage {
     outputTokens: number;
     cacheReadTokens: number;
     cacheCreationTokens: number;
-    /** Prompt size of the most recent assistant call = live context occupancy. */
+    /**
+     * Prompt size of the most recent assistant call = live context occupancy.
+     * Stored UNCLAMPED: a reading above the window is information (the CLI is
+     * about to compact or overflow), and only the UI decides how to draw it.
+     */
     contextTokens: number;
     contextWindow: number | null;
+    /** V3.9 ADDITIVE. Where `contextWindow` came from; absent on old records. */
+    contextWindowSource?: VerseWindowSource;
+    /** V3.9 ADDITIVE. Auto-compaction point for the session's current mode. */
+    autoCompactAt?: number | null;
+    /**
+     * V3.9 ADDITIVE. False when `contextTokens` is an UPPER BOUND rather than a
+     * measurement (codex before its rollout is readable: the turn total sums
+     * every model call). Absent means exact.
+     */
+    contextTokensExact?: boolean;
 }
 export interface VerseSession {
     id: string;
@@ -365,6 +458,30 @@ export interface VerseSession {
     turnCount: number;
     usage: VerseUsage;
     lastError: string | null;
+    /**
+     * V3.9 ADDITIVE. The session's context budget. Every record written by 3.9+
+     * carries it explicitly, so ABSENT means a pre-3.9 record: the engine
+     * materializes it on first touch — `expansive` for a Claude 1M model (that
+     * is the native ~967k compaction those chats always ran with, so upgrading
+     * never forces a paid compaction), `standard` otherwise (= native).
+     * Changeable mid-session (POST /sessions/:id/context-mode): it changes CLI
+     * flags, not prompt content — but switching DOWN below the current
+     * occupancy makes the CLI compact on its next turn.
+     */
+    contextMode?: VerseContextMode;
+    /** V3.9 ADDITIVE. Native compactions observed so far (claude/grok compact_boundary, codex rollout `compacted`). */
+    compactionCount?: number;
+    /** V3.9 ADDITIVE. Set when this session was started as a handoff from another. */
+    handoffFrom?: {
+        sessionId: string;
+        title: string;
+    };
+    /**
+     * V3.9 ADDITIVE. Shared project memory was offered to this session's CLI at
+     * creation. Pinned, like the roots: a conversation must not silently gain a
+     * writable directory because a preference moved underneath it.
+     */
+    memoryEnabled?: boolean;
 }
 /** Normalized event stream. `seq` is monotonic per session and is the SSE id. */
 export type VerseEvent = {
@@ -438,6 +555,48 @@ export type VerseEvent = {
     at: string;
     type: 'cancelled';
     turnId: string;
+}
+/**
+ * V3.9. The CLI compacted its own conversation. Token counts are the CLI's
+ * own (`compact_metadata.pre_tokens/post_tokens` on claude/grok). Codex
+ * rollouts mark only THAT a compaction happened, so its counts are the last
+ * `token_count` reading before the marker and the first one after it —
+ * measured, but by Verse, not stated by the CLI; its `durationMs` is null.
+ * Any count may be null when no reading brackets the compaction.
+ */
+ | {
+    seq: number;
+    at: string;
+    type: 'compaction';
+    turnId: string | null;
+    trigger: 'auto' | 'manual';
+    preTokens: number | null;
+    postTokens: number | null;
+    durationMs: number | null;
+}
+/**
+ * V3.9. A context-occupancy READING that is not a usage delta — e.g. codex's
+ * rollout `token_count` (exact last-call prompt size and the window the CLI
+ * measured it against), polled mid-turn and read again after it. Replaces
+ * the session's `contextTokens`; never summed. The engine fills
+ * `autoCompactAt` for the window in force.
+ */
+ | {
+    seq: number;
+    at: string;
+    type: 'context';
+    turnId: string | null;
+    contextTokens: number;
+    contextWindow: number | null;
+    exact: boolean;
+    autoCompactAt?: number | null;
+    /**
+     * Where `contextWindow` came from. A CLI reading is `runtime`; the event
+     * the engine writes after a MODE SWITCH carries the new budget's catalog
+     * source, so a client never relabels a catalog figure as a measurement.
+     * Absent on events from before this field existed (treat as `runtime`).
+     */
+    contextWindowSource?: VerseWindowSource;
 };
 export type VerseEventType = VerseEvent['type'];
 /**
@@ -529,6 +688,18 @@ export interface VerseCreateSessionRequest {
      * from.
      */
     workspaceName?: string;
+    /**
+     * V3.9 ADDITIVE. Absent → the seat's preferred mode (preferences.json), else
+     * `standard`. `expansive` on a model with no expansive budget is rejected.
+     */
+    contextMode?: VerseContextMode;
+    /**
+     * V3.9 ADDITIVE. Start this session as a handoff from an existing one. The
+     * server resolves the source's title itself (never from the body) and pins
+     * `handoffFrom`; the handoff TEXT is sent by the client as turn 1, after the
+     * operator has read it — nothing is spent on their behalf.
+     */
+    handoffFromSessionId?: string;
 }
 /** POST /api/verse/sessions/:id/turns */
 export interface VerseTurnRequest {
@@ -555,4 +726,165 @@ export interface VerseTurnLaunch {
 export declare const VERSE_MAX_TURN_TEXT_BYTES: number;
 export declare const VERSE_MAX_EVENTS_PER_SESSION = 20000;
 export declare const VERSE_TURN_TIMEOUT_MS: number;
+/**
+ * LAST-RESORT fallbacks, used only when neither the runtime, the seat's own
+ * catalog, nor the verified per-model table (core/verse/model-windows.ts) knows
+ * the model. Each mirrors what the CLI ITSELF assumes for an unknown id, so the
+ * meter never claims more than the CLI will allow:
+ *
+ * - claude 200_000 — Claude Code's `Mg()` default for an unrecognized model.
+ *   Every KNOWN Claude id carries its real window (1M for the 5.x family,
+ *   Opus 4.8 and Sonnet 5) in the per-model table instead.
+ * - codex 258_400  — 272_000 × the 95% `effective_context_window_percent`
+ *   every codex catalog entry carries; the figure codex's own rollouts report
+ *   as `model_context_window` (65,440 of 65,440 observed events).
+ * - grok 500_000   — `context_window` for every grok-4.x id in the seat catalog.
+ * - local 65_536   — the num_ctx the default local tag pins.
+ */
 export declare const VERSE_DEFAULT_CONTEXT_WINDOWS: Record<string, number>;
+/** GET /api/verse/preferences — the operator's standing context choices. */
+export interface VersePreferences {
+    version: 1;
+    /** Per-seat default context mode for NEW sessions. Absent = `standard`. */
+    seats: Record<string, {
+        contextMode?: VerseContextMode;
+    }>;
+    /** Shared project memory. On by default; listed canonical paths opt out. */
+    memory: {
+        enabled: boolean;
+        disabledProjects: string[];
+    };
+}
+/**
+ * POST /api/verse/preferences — exactly ONE of the three forms per request, so
+ * a body can never change more than the operator clicked.
+ */
+export type VersePreferencesUpdate = {
+    seatId: string;
+    contextMode: VerseContextMode;
+} | {
+    memoryEnabled: boolean;
+} | {
+    projectPath: string;
+    memoryEnabled: boolean;
+};
+/** POST /api/verse/sessions/:id/context-mode */
+export interface VerseContextModeRequest {
+    mode: VerseContextMode;
+}
+/** POST /api/verse/sessions/:id/handoff-preview */
+export interface VerseHandoffPreviewRequest {
+    /**
+     * Include the latest assistant message verbatim (capped) as the agent's own
+     * summary — used after "Ask this seat to summarize" produced one.
+     */
+    includeLastAssistant?: boolean;
+    /** Optional operator focus line, e.g. "finish the migration of X". ≤ 500 chars. */
+    focus?: string;
+}
+/** Deterministic, zero-spend handoff note built from the session's event log. */
+export interface VerseHandoffPreview {
+    sourceSessionId: string;
+    sourceTitle: string;
+    /** The exact text to send as turn 1 of the new session. ≤ VERSE_HANDOFF_MAX_CHARS. */
+    text: string;
+    stats: {
+        chars: number;
+        /** chars / 4, rounded up — the same estimator the fit badges use. */
+        estTokens: number;
+        turnsCovered: number;
+        filesTouched: number;
+        /** Sections dropped to respect the cap, by name; empty when nothing was cut. */
+        truncated: string[];
+    };
+}
+export declare const VERSE_HANDOFF_MAX_CHARS = 12000;
+/**
+ * The canned turn behind "Ask this seat to summarize first". Shared by the UI
+ * (which sends it as an ordinary turn through the normal spend chokepoint) and
+ * the handoff builder (which must NOT carry it into the new session as the
+ * operator's "latest ask" — the new chat would otherwise be told to write a
+ * handoff note instead of continuing the work).
+ *
+ * Written so the reply is useful as turn 1 of a session that has NONE of this
+ * context. It asks for no tool use on purpose: a summary that starts editing
+ * files is not a summary, and a read-only turn is also the cheapest one.
+ */
+export declare const VERSE_HANDOFF_SUMMARY_REQUEST: string;
+/** GET /api/verse/context-fit — how big the reachable code is, in tokens. */
+export interface VerseContextFitRoot {
+    path: string;
+    /** Tracked text files counted (git ls-files, binaries and >1 MB files skipped). */
+    files: number;
+    bytes: number;
+    estTokens: number;
+    /** True when the scan hit its file or time cap; estTokens is then a floor. */
+    truncated: boolean;
+}
+export interface VerseContextFit {
+    roots: VerseContextFitRoot[];
+    totalEstTokens: number;
+    /** Always 'bytes/4' today; named so a better estimator can be introduced honestly. */
+    estimator: 'bytes/4';
+    sampledAt: string;
+}
+/**
+ * Per-model verdict for a working set (see context-math.ts `fitVerdict`):
+ * fits in standard, tight in standard, fits only in expansive, or too big for
+ * any single context (split the work).
+ */
+export type VerseFitVerdict = 'fits' | 'tight' | 'expansive' | 'split';
+/** GET /api/verse/search?q=&limit= — keyword search over past sessions. Zero spend. */
+export interface VerseSearchHit {
+    sessionId: string;
+    title: string;
+    projectPath: string;
+    engine: VerseEngine;
+    seq: number;
+    at: string;
+    kind: 'user' | 'assistant';
+    /** ≤ 240 chars around the first match, whitespace-collapsed. */
+    snippet: string;
+    score: number;
+}
+export interface VerseSearchResponse {
+    query: string;
+    hits: VerseSearchHit[];
+    /** Sessions actually scanned (the scan is bounded; see session-search.ts). */
+    scannedSessions: number;
+    truncated: boolean;
+}
+/** GET/POST /api/verse/memory — shared project memory for one project. */
+export interface VerseProjectMemory {
+    projectPath: string;
+    enabled: boolean;
+    /** Contents of MEMORY.md ('' when absent). */
+    content: string;
+    bytes: number;
+    updatedAt: string | null;
+    /** Other files the agents created in the memory directory (names only). */
+    files: string[];
+    /**
+     * Present (true) only when `content` as SENT differs from the bytes on disk:
+     * the public-JSON sanitizer rewrote the home path to `~` or replaced a
+     * secret-looking value with `[REDACTED]`. The file itself is untouched; a
+     * save that would write placeholders over real values is refused (409
+     * VERSE_MEMORY_REDACTED), so the editor must say so before the operator types.
+     */
+    contentSanitized?: boolean;
+}
+/** POST /api/verse/memory */
+export interface VerseProjectMemoryWrite {
+    projectPath: string;
+    content: string;
+}
+export declare const VERSE_MEMORY_MAX_BYTES: number;
+/**
+ * POST /api/verse/memory's own JSON body cap: JSON escaping can double the
+ * content (every newline becomes `\\n`), plus room for the other fields. Every
+ * other route keeps the 64 KiB default. Shared so the browser's pre-check can
+ * never refuse a save the server would accept.
+ */
+export declare const VERSE_MEMORY_BODY_MAX_BYTES: number;
+/** Cap on the memory block appended to each session's system prompt. */
+export declare const VERSE_MEMORY_BLOCK_MAX_BYTES: number;

package/dist/core/verse/types.js

@@ -15,6 +15,7 @@
  * Nothing in this module reads secrets. Account identity is pinned by the
  * launcher command recorded in ~/.ashlr/account-connections/connections.json.
  */
+export const VERSE_CONTEXT_MODES = ['standard', 'expansive'];
 export const VERSE_ROOT_PRIORITIES = ['critical', 'high', 'normal', 'low'];
 export const VERSE_DEFAULT_ROOT_PRIORITY = 'normal';
 /** Sort weight; lower sorts first. Never a budget, never a multiplier. */
@@ -44,10 +45,61 @@ export function verseSessionRoots(session) {
 export const VERSE_MAX_TURN_TEXT_BYTES = 64 * 1024;
 export const VERSE_MAX_EVENTS_PER_SESSION = 20_000;
 export const VERSE_TURN_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * LAST-RESORT fallbacks, used only when neither the runtime, the seat's own
+ * catalog, nor the verified per-model table (core/verse/model-windows.ts) knows
+ * the model. Each mirrors what the CLI ITSELF assumes for an unknown id, so the
+ * meter never claims more than the CLI will allow:
+ *
+ * - claude 200_000 — Claude Code's `Mg()` default for an unrecognized model.
+ *   Every KNOWN Claude id carries its real window (1M for the 5.x family,
+ *   Opus 4.8 and Sonnet 5) in the per-model table instead.
+ * - codex 258_400  — 272_000 × the 95% `effective_context_window_percent`
+ *   every codex catalog entry carries; the figure codex's own rollouts report
+ *   as `model_context_window` (65,440 of 65,440 observed events).
+ * - grok 500_000   — `context_window` for every grok-4.x id in the seat catalog.
+ * - local 65_536   — the num_ctx the default local tag pins.
+ */
 export const VERSE_DEFAULT_CONTEXT_WINDOWS = {
     claude: 200_000,
-    codex: 272_000,
-    grok: 256_000,
+    codex: 258_400,
+    grok: 500_000,
     local: 65_536,
 };
+export const VERSE_HANDOFF_MAX_CHARS = 12_000;
+/**
+ * The canned turn behind "Ask this seat to summarize first". Shared by the UI
+ * (which sends it as an ordinary turn through the normal spend chokepoint) and
+ * the handoff builder (which must NOT carry it into the new session as the
+ * operator's "latest ask" — the new chat would otherwise be told to write a
+ * handoff note instead of continuing the work).
+ *
+ * Written so the reply is useful as turn 1 of a session that has NONE of this
+ * context. It asks for no tool use on purpose: a summary that starts editing
+ * files is not a summary, and a read-only turn is also the cheapest one.
+ */
+export const VERSE_HANDOFF_SUMMARY_REQUEST = [
+    'This conversation is about to continue in a fresh session that has none of its context.',
+    'Write the handoff note that new session should start from. Do not edit files or run commands for this — only write the note.',
+    '',
+    'Cover, concretely:',
+    '- The goal, and what "done" looks like.',
+    '- Decisions made so far, each with the reason it was made.',
+    '- Current state: what is finished, what is half-done, what is untested.',
+    '- Files changed and anything not yet committed.',
+    '- How to verify the work (exact commands).',
+    '- Open questions, risks, and approaches already tried that did not work.',
+    '',
+    'Keep it under 600 words. Prefer file paths and commands over prose.',
+].join('\n');
+export const VERSE_MEMORY_MAX_BYTES = 64 * 1024;
+/**
+ * POST /api/verse/memory's own JSON body cap: JSON escaping can double the
+ * content (every newline becomes `\\n`), plus room for the other fields. Every
+ * other route keeps the 64 KiB default. Shared so the browser's pre-check can
+ * never refuse a save the server would accept.
+ */
+export const VERSE_MEMORY_BODY_MAX_BYTES = 2 * VERSE_MEMORY_MAX_BYTES + 8 * 1024;
+/** Cap on the memory block appended to each session's system prompt. */
+export const VERSE_MEMORY_BLOCK_MAX_BYTES = 6 * 1024;
 //# sourceMappingURL=types.js.map

package/dist/core/verse/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/verse/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyNH,MAAM,CAAC,MAAM,qBAAqB,GAChC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAExC,MAAM,CAAC,MAAM,2BAA2B,GAAsB,QAAQ,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAsC;IACzE,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;CACP,CAAC;AA2HF,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAyD;IAEzD,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAoLD,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AACnD,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AACnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACpD,MAAM,CAAC,MAAM,6BAA6B,GAA2B;IACnE,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,MAAM;CACd,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/verse/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgFH,MAAM,CAAC,MAAM,mBAAmB,GAAgC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AA4N1F,MAAM,CAAC,MAAM,qBAAqB,GAChC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAExC,MAAM,CAAC,MAAM,2BAA2B,GAAsB,QAAQ,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAsC;IACzE,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;CACP,CAAC;AA2HF,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAyD;IAEzD,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AA6QD,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AACnD,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AACnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA2B;IACnE,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,MAAM;CACd,CAAC;AAyDF,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,yFAAyF;IACzF,8HAA8H;IAC9H,EAAE;IACF,oBAAoB;IACpB,yCAAyC;IACzC,4DAA4D;IAC5D,yEAAyE;IACzE,iDAAiD;IACjD,4CAA4C;IAC5C,0EAA0E;IAC1E,EAAE;IACF,qEAAqE;CACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AA4Eb,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,sBAAsB,GAAG,CAAC,GAAG,IAAI,CAAC;AAEjF,wEAAwE;AACxE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,GAAG,IAAI,CAAC"}

package/dist/core/verse/verse-api.d.ts

@@ -6,10 +6,10 @@
  *   - GETs sit behind the read-session boundary in server.ts.
  *   - POSTs are 404 unless ctx.allowDispatch, then passesMutationGate()
  *     (constant-time x-ashlr-token + JSON Content-Type), then readBody()
- *     (64 KB cap).
+ *     (64 KB cap; POST /memory alone gets VERSE_MEMORY_BODY_MAX_BYTES).
  *   - Every response goes through sendJson() → sanitizePublicJson().
  *
- * Routes (see docs/VERSE-CONTRACT-V1.md):
+ * Routes (see docs/VERSE-CONTRACT-V1.md, docs/VERSE-CONTEXT.md for V3.9):
  *   GET  /api/verse/bootstrap                → VerseBootstrap
  *   GET  /api/verse/seats                    → VerseSeatsResponse (pollable)
  *   GET  /api/verse/sessions                 → VerseSession[]
@@ -20,26 +20,48 @@
  *   POST /api/verse/sessions/:id/delete      → { ok: true }
  *   POST /api/verse/sessions/:id/rename      → VerseSession
  *   GET  /api/verse/sessions/:id/events      → SSE (verse-stream.ts)
+ *  V3.9 context orchestration — every one of these is ZERO SPEND: none starts
+ *  a model call; the only way a token is spent is still POST .../turns.
+ *   POST /api/verse/sessions/:id/context-mode    → VerseSession
+ *   POST /api/verse/sessions/:id/handoff-preview → VerseHandoffPreview
+ *   GET  /api/verse/preferences              → VersePreferences
+ *   POST /api/verse/preferences              → VersePreferences
+ *   GET  /api/verse/context-fit              → VerseContextFit
+ *   GET  /api/verse/search                   → VerseSearchResponse
+ *   GET  /api/verse/memory                   → VerseProjectMemory (+ contentSanitized?)
+ *   POST /api/verse/memory                   → VerseProjectMemory (+ contentSanitized?)
  *
  * Errors: { error, code? } with VERSE_SESSION_NOT_FOUND 404,
- * VERSE_SESSION_BUSY 409, VERSE_INVALID 400, VERSE_TOO_LARGE 413.
+ * VERSE_SESSION_BUSY 409, VERSE_INVALID 400, VERSE_TOO_LARGE 413, and two
+ * route-local 409s: VERSE_MODEL_UNAVAILABLE (turns: the session's model is
+ * listed but unrunnable on its seat) and VERSE_MEMORY_REDACTED (memory: the
+ * content would write redaction placeholders over real values).
+ *
+ * STRICT BODIES AND QUERIES (V3.9 routes and POST /sessions): an unknown body
+ * key or query parameter is a 400, never silently ignored — a misspelt
+ * `contextMode` would otherwise create a session in a mode nobody asked for.
  *
  * ENGINE LIFETIME: one engine handle per server process — a module-level
  * lazy singleton (`getVerseEngine()`), with `resetVerseEngine()` for tests to
  * inject a fake or force re-creation under a relocated HOME. The engine
  * module is loaded lazily (dynamic import) so this file has no load-time
- * dependency on it; tests that inject a fake never touch it.
+ * dependency on it; tests that inject a fake never touch it. The V3.9 service
+ * modules keep that property: they report bad input with their own
+ * `VerseServiceError` (same `code` vocabulary, mapped by duck type below)
+ * rather than importing the engine's `VerseError`.
  *
  * PRIVACY: seat launchers (the native-profile commands) come from seats.ts's
  * private `launches` map and go straight to engine.createSession(). They are
  * never part of any response, log line, or session record this file writes.
+ * The same holds for the shared-memory snapshot (`VerseCreateOptions.memory`):
+ * its directory and prompt block go into the private launch record only.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { AshlrConfig } from '../types.js';
 import { expandHomePrefix } from './path-guard.js';
 import { type VerseWorkspaceStore } from './workspaces.js';
 import type { VerseEngineHandle } from './session-engine.js';
-import { type VerseSession } from './types.js';
+import { type VerseSession, VERSE_MEMORY_BODY_MAX_BYTES } from './types.js';
 export declare const VERSE_API_PREFIX = "/api/verse";
 export declare function isVerseApiPath(path: string): boolean;
 export interface VerseApiContext {
@@ -92,6 +114,19 @@ export declare function verseSessionsSnapshot(): VerseSession[];
  * caller and test already uses.
  */
 export { expandHomePrefix };
+/**
+ * The body cap for POST /api/verse/memory ONLY.
+ *
+ * The memory file may be VERSE_MEMORY_MAX_BYTES of content, and JSON escaping
+ * can roughly double that (every `"`, `\` and newline becomes two bytes; a
+ * control character becomes six, but a memory file is prose). Under the shared
+ * 65,536-byte cap a file anywhere near the documented limit could never be
+ * saved: 64 KiB of content made a 65,711-byte body. 2× plus 8 KiB for the
+ * envelope (`projectPath`, keys) admits any realistic file at the limit while
+ * staying a bounded, small read. The CONTENT itself is still held to
+ * VERSE_MEMORY_MAX_BYTES (413) after parsing.
+ */
+export { VERSE_MEMORY_BODY_MAX_BYTES };
 /**
  * Handle one /api/verse/* request. Returns true when a response was written
  * (including error responses); false when `path` is not a verse route so