@ashlr/hub 3.7.0 → 3.9.0

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

@@ -10,9 +10,31 @@
  * its own process-group leader (`detached: true`) so cancellation signals the
  * 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
+ * shared predicate (`policy/local-only.decidePermission`, reached through its
+ * published wrappers) at the top of `startTurn` — see `verseSeatPermitted`.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
-import { type VerseCreateSessionRequest, type VerseEvent, type VerseSeat, type VerseSession } from './types.js';
+import { type LocalOnlyVerdict } from '../policy/local-only.js';
+import type { AshlrConfig } 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;
@@ -38,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;
@@ -65,6 +143,43 @@ export interface VerseEngineOptions {
     turnTimeoutMs?: number;
     /** SIGINT → SIGKILL escalation delay. Default 10s. */
     killGraceMs?: number;
+    /**
+     * Read the operator config that the local-only gate consults.
+     *
+     * Called ONCE PER TURN rather than once at construction, deliberately: the
+     * cockpit's Local-only switch writes `~/.ashlr/config.json` while this engine
+     * is already live, and a mode read at startup would leave the switch looking
+     * like it did nothing until a restart. `undefined` means "no config in hand",
+     * which the policy answers from env + its process latch — i.e. toward refusal.
+     *
+     * Default: `loadConfigReadOnly()`, which never creates, seeds or writes the
+     * 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?
+ *
+ * NOT a second policy predicate — that is the point. Both branches delegate to
+ * `decidePermission()` through its published wrappers, so "local" means here
+ * exactly what it means at the daemon's chokepoints. This function contributes
+ * only the mapping from a Verse seat to a subject the predicate understands:
+ *
+ *   claude / codex / grok — a Verse engine id IS the registry engine id, so
+ *     `enginePermitted` classifies it directly (cli-agent → cloud for claude and
+ *     codex, api-model at api.x.ai → cloud for grok).
+ *
+ *   local — a local seat is discovered from a serving runtime and has no
+ *     registry engine to name, so the ENDPOINT it dispatches to is the truth
+ *     and `endpointPermitted` classifies that. A loopback runtime (the default,
+ *     and every local seat today) is permitted exactly as before. One repointed
+ *     at a remote inference host is refused, because that one would spend — the
+ *     same rule the raw-transport sites apply to `cfg.foundry.ollamaBaseUrl`.
+ */
+export declare function verseSeatPermitted(engine: VerseEngine, launch: VerseSeatLaunch, cfg: AshlrConfig | undefined): LocalOnlyVerdict;
 export declare function buildTurnEnv(extra: Record<string, string>, base?: NodeJS.ProcessEnv): Record<string, string>;
 export declare function createVerseEngine(opts?: VerseEngineOptions): VerseEngineHandle;