@ashlr/hub 3.8.0 → 3.9.0

package/dist/core/verse/session-engine.d.ts

@@ -11,6 +11,19 @@
  * whole group, escalating SIGINT → SIGKILL after a grace period, with a bounded
  * drain so a descendant holding our pipes cannot keep a turn "running" forever.
  *
+ * CONTEXT (V3.9, docs/VERSE-CONTEXT.md). The engine is the one place a
+ * session's context budget is decided and kept current:
+ *   - at creation, from the seat's model option and the session's mode
+ *     (`budgetFor`), recorded on `usage` with where the window came from;
+ *   - on every reading, a window the CLI reports at runtime WINS over the
+ *     catalog (a 1M Claude model the CLI clamps to 200k is a 200k session),
+ *     and the compaction point is recomputed for it (`reconcileAutoCompactAt`);
+ *   - `context` / `compaction` events replace occupancy and count compactions;
+ *   - adapters that can only see exact occupancy in the CLI's own files
+ *     (codex rollouts) get bounded telemetry hooks: polled while the turn
+ *     runs, and called once after the parser has flushed.
+ * None of this spends: it reads what the CLI already reported or wrote.
+ *
  * LOCAL-ONLY. Because the spawn is raw rather than routed through
  * `run/engines.spawnEngine`, this module is a SECOND subprocess funnel and none
  * of the daemon's gates cover it. It therefore carries its own call to the one
@@ -20,7 +33,8 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { type LocalOnlyVerdict } from '../policy/local-only.js';
 import type { AshlrConfig } from '../types.js';
-import { type VerseCreateSessionRequest, type VerseEngine, type VerseEvent, type VerseSeat, type VerseSession } from './types.js';
+import { type VerseAdapter } from './adapters/index.js';
+import { type VerseContextMode, type VerseCreateSessionRequest, type VerseEngine, type VerseEvent, type VerseModelOption, type VerseSeat, type VerseSession } from './types.js';
 export type VerseErrorCode = 'VERSE_SESSION_NOT_FOUND' | 'VERSE_SESSION_BUSY' | 'VERSE_INVALID' | 'VERSE_TOO_LARGE';
 export declare class VerseError extends Error {
     readonly code: VerseErrorCode;
@@ -46,16 +60,72 @@ export interface VerseSeatLaunch {
      * means "the Ollama lane", which is what those sessions were created on.
      */
     anthropicBaseUrl?: string;
+    /**
+     * V3.9 ADDITIVE. Shared project memory offered to this session, SNAPSHOTTED
+     * at creation: `dir` is the private memory directory, `block` the exact text
+     * appended to the CLI's system prompt on EVERY turn. Pinned rather than
+     * re-rendered per turn so the prompt prefix stays byte-identical and the
+     * provider's prompt cache survives; agents read the live file from `dir`.
+     * Absent = memory off for this session (and on every older record).
+     */
+    memory?: {
+        dir: string;
+        block: string;
+        writable: boolean;
+    };
+}
+/** V3.9 — creation-time extras the API resolves (preferences, provenance); never read off a request body. */
+export interface VerseCreateOptions {
+    memory?: {
+        dir: string;
+        block: string;
+        writable: boolean;
+    } | null;
+    handoffFrom?: {
+        sessionId: string;
+        title: string;
+    } | null;
 }
 export interface VerseEngineHandle {
     listSessions(): VerseSession[];
     getSession(id: string): VerseSession | null;
     getEvents(id: string, fromSeq?: number): VerseEvent[];
-    createSession(req: VerseCreateSessionRequest, launch: VerseSeatLaunch): VerseSession;
+    /**
+     * `opts` carries what the API resolved server-side (memory snapshot, handoff
+     * provenance). Omitted by every pre-3.9 caller, whose records then carry no
+     * memory or handoff keys at all.
+     */
+    createSession(req: VerseCreateSessionRequest, launch: VerseSeatLaunch, opts?: VerseCreateOptions): VerseSession;
     sendTurn(id: string, text: string): {
         turnId: string;
         session: VerseSession;
     };
+    /**
+     * V3.9. Switch the session's context budget. Takes effect from the NEXT turn
+     * (it only changes CLI flags, never prompt content, so the cache survives).
+     * Refused while a turn runs — that turn was launched with the old flags and
+     * its readings must be measured against them — and for a mode the model has
+     * no budget for.
+     */
+    setContextMode(id: string, mode: VerseContextMode): VerseSession;
+    /**
+     * V3.9. Re-read a LOCAL session's window from the seat's LIVE option (the
+     * API calls this before each turn with the option discovery resolves now).
+     *
+     * Local windows are the runtime's allocation — the dispatch lane, the pinned
+     * `num_ctx`, what `/api/ps` has resident — and change after a chat is
+     * created; a pre-3.9 record may even hold a window the old discovery got
+     * wrong (262,144 stored for a `-ctx64k` tag that serves 65,536). The CLI is
+     * told `usage.contextWindow` (`CLAUDE_CODE_MAX_CONTEXT_TOKENS`) and the meter
+     * draws the same field, so correcting it HERE, before the launch, keeps what
+     * the CLI compacts against and what the operator sees one number.
+     *
+     * Writes (and emits one `context` event) only when window, compaction point
+     * or source actually changed. A no-op for any other engine, and for an
+     * option with no window. Refused while a turn runs (its CLI was launched
+     * with the old window) and for an option naming a different model.
+     */
+    refreshLocalWindow(id: string, option: VerseModelOption): VerseSession;
     cancelTurn(id: string): boolean;
     deleteSession(id: string): void;
     renameSession(id: string, title: string): VerseSession;
@@ -86,6 +156,10 @@ export interface VerseEngineOptions {
      * file. The config is the user's; this module only ever reads it.
      */
     loadConfig?: () => AshlrConfig | undefined;
+    /** Adapter resolver. Default: `adapters/index.adapterFor`. A test seam, like `spawn`. */
+    adapterFor?: (engine: VerseEngine) => VerseAdapter;
+    /** Telemetry poll interval for adapters with `pollTelemetry`. Default VERSE_TELEMETRY_POLL_MS. */
+    telemetryPollMs?: number;
 }
 /**
  * Is this SEAT permitted to run a turn right now?