@aexol/spectral 0.8.2 → 0.8.5

package/dist/server/handlers/queue.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure REST handlers for `/api/sessions/:sessionId/queue/*`.
+ *
+ * Same contract as sessions/projects handlers — pure functions that take
+ * `store` + `manager` dependencies, throw `BadRequestError`/`NotFoundError`
+ * on invalid input, and return typed responses.
+ *
+ * After mutating the queue, each handler calls `manager.pushQueueState()`
+ * to broadcast the updated queue to all subscribers via `queue_changed`.
+ */
+import type { SessionStreamManager } from "../session-stream.js";
+import type { SessionStore } from "../storage.js";
+export interface EnqueuePromptInputRaw {
+    content?: unknown;
+}
+/** Wire shape for a single queue item returned to the frontend. */
+export interface WireQueueItem {
+    id: string;
+    content: string;
+    position: number;
+    createdAt: string;
+}
+export declare function handleEnqueuePrompt(store: SessionStore, manager: SessionStreamManager, sessionId: string, body: EnqueuePromptInputRaw): WireQueueItem;
+export declare function handleGetPromptQueue(store: SessionStore, sessionId: string): WireQueueItem[];
+export declare function handleRemovePrompt(store: SessionStore, manager: SessionStreamManager, sessionId: string, itemId: string): void;
+export declare function handleClearPromptQueue(store: SessionStore, manager: SessionStreamManager, sessionId: string): void;
+//# sourceMappingURL=queue.d.ts.map

package/dist/server/handlers/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,qBAAqB,GAC1B,aAAa,CAgBf;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,GAChB,aAAa,EAAE,CAUjB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,IAAI,CAMN;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN"}

package/dist/server/handlers/sessions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure REST handlers for `/api/sessions/*`.
+ *
+ * Same shape as projects handlers — see that file's header for the contract.
+ *
+ * Note: session deletion does not tear down the in-flight pi stream itself.
+ * The Batch 3 dispatcher must call `manager.disposeSessionStream(id)` BEFORE
+ * invoking `handleDeleteSession` so the FK cascade doesn't leave a zombie
+ * bridge driving events at a row that no longer exists. This matches the
+ * ordering the old Hono route used.
+ */
+import type { SessionStreamManager } from "../session-stream.js";
+import type { SessionStore } from "../storage.js";
+import type { WireSessionDetail, WireSessionMemoryDetails, WireSessionMemoryStatus, WireSessionSummary } from "../wire.js";
+export interface CreateSessionInputRaw {
+    projectId?: unknown;
+    title?: unknown;
+}
+export interface UpdateSessionInputRaw {
+    title?: unknown;
+}
+export declare function handleCreateSession(store: SessionStore, body: CreateSessionInputRaw): WireSessionSummary;
+export declare function handleGetSessionDetail(store: SessionStore, id: string): WireSessionDetail;
+export declare function handleUpdateSession(store: SessionStore, id: string, body: UpdateSessionInputRaw): WireSessionSummary;
+export declare function handleDeleteSession(store: SessionStore, id: string): void;
+export declare function handleGetSessionMemoryStatus(store: SessionStore, manager: SessionStreamManager, id: string): WireSessionMemoryStatus;
+export declare function handleGetSessionMemoryDetails(store: SessionStore, manager: SessionStreamManager, id: string): WireSessionMemoryDetails;
+export declare function handleCompactSession(store: SessionStore, manager: SessionStreamManager, id: string): Promise<{
+    ok: true;
+}>;
+/**
+ * Remember & delete: compact the session (which persists observations as
+ * project memory via the compaction hook), then delete the session.
+ *
+ * This gives the user a way to keep a session's reflections as durable
+ * cross-session memory even for short sessions that never hit the compaction
+ * threshold naturally.
+ */
+export declare function handleRememberAndDeleteSession(store: SessionStore, manager: SessionStreamManager, id: string): Promise<{
+    ok: true;
+}>;
+/**
+ * Fork a session: create a new session copying all messages from the
+ * source, with the `fork_compact_source_id` flag set so the
+ * SessionStreamManager compacts after the first assistant turn.
+ */
+export declare function handleForkSession(store: SessionStore, id: string, body: {
+    title?: unknown;
+}): WireSessionSummary;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/server/handlers/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAG3H,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,qBAAqB,GAC1B,kBAAkB,CAQpB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACT,iBAAiB,CAInB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,qBAAqB,GAC1B,kBAAkB,CAOpB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAGzE;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,GACT,uBAAuB,CAIzB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,GACT,wBAAwB,CAI1B;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAUvB;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAUvB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACxB,kBAAkB,CAKpB"}

package/dist/server/paths.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Filesystem path helpers for project management.
+ *
+ * Projects in `spectral serve` are user-owned directories on disk. We accept
+ * paths typed by the user from the browser, so two small concerns:
+ *
+ *  - Tilde expansion: `~/foo/bar` is the natural way to refer to a path
+ *    inside `$HOME`. Node's `path` module does not expand tildes; we do it
+ *    ourselves with a leading-segment check (NOT a global string replace —
+ *    `~user/...` and embedded `~` are intentionally left alone).
+ *  - Validation: the path must exist, must be a directory, and must be
+ *    readable. We do NOT attempt to verify writability — pi may want to
+ *    create files inside it, but failure modes there surface naturally
+ *    through pi's tools, and a write probe here would create stray files.
+ *
+ * Both helpers are synchronous because they're called on hot HTTP paths
+ * (POST /api/projects) where blocking is acceptable: the operation is rare
+ * and the user is waiting on the response anyway. `node:fs` sync calls in
+ * this regime are simpler than juggling promises through validation.
+ */
+/**
+ * Expand a leading `~` or `~/` to the user's home directory and return an
+ * absolute, normalized path.
+ *
+ * Behavior:
+ *   - `~`           → `$HOME`
+ *   - `~/foo`       → `$HOME/foo`
+ *   - `/abs/path`   → `/abs/path` (unchanged, normalized)
+ *   - `relative`    → resolved against `$HOME` (NOT process.cwd, since the
+ *     server runs from `$HOME` and "relative to home" matches the user's
+ *     mental model when typing into a form)
+ *   - `~user/...`   → returned as-is and resolved against `$HOME`. We do NOT
+ *     attempt to look up other users' home directories — out of scope.
+ */
+export declare function expandPath(input: string): string;
+export interface ProjectPathValidation {
+    ok: boolean;
+    /** Absolute, normalized path (set when ok=true and also for some errors). */
+    path: string;
+    /** Human-friendly error message (set when ok=false). */
+    error?: string;
+}
+/**
+ * Validate a user-supplied project path.
+ *
+ * Returns `{ok:true, path}` for a real, accessible directory. On failure,
+ * `error` carries a message suitable for surfacing to the user. The expanded
+ * path is included in both cases so callers can echo it back in errors.
+ */
+export declare function validateProjectPath(input: string): ProjectPathValidation;
+//# sourceMappingURL=paths.d.ts.map

package/dist/server/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/server/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAehD;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAmBxE"}

package/dist/server/session-stream.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Session-scoped streaming layer for `spectral serve`.
+ *
+ * Background: prior to this module each WebSocket owned its own `AgentBridge`
+ * instance and the routes layer enforced single-writer-wins (4001 eviction)
+ * to keep that bridge unique per session. That model lost data on browser
+ * refresh — the WS close torn down the pi process mid-stream, and a re-open
+ * couldn't recover what hadn't yet hit `agent_end` (and thus SQLite).
+ *
+ * New model:
+ *   - Pi lifecycle is per **Spectral session**, not per WS.
+ *   - 0..N WebSockets may attach to the same session simultaneously. Each
+ *     gets the same broadcast stream of events.
+ *   - When a WS detaches (close, error, refresh), the pi process keeps
+ *     running. Closing every tab does NOT cancel the in-flight turn —
+ *     it runs to completion and persists on `agent_end` as before.
+ *   - On `attach`, the manager hands back a replay payload: full DB history
+ *     plus a snapshot of the currently in-flight turn (if any). The client
+ *     replays the snapshot through the same reducer it uses for live events
+ *     and continues streaming naturally.
+ *   - Persistence shape is unchanged: only the final assistant message is
+ *     written to SQLite on `agent_end`. In-flight events live in memory only.
+ *     A server crash mid-turn discards the in-flight state — acceptable
+ *     for MVP.
+ *
+ * Failure modes:
+ *   - Pi throws synchronously in `prompt()` → bridge surfaces as `error`
+ *     event; manager broadcasts and clears `currentTurn`.
+ *   - One subscriber's `ws.send` throws → caught, logged, removed from the
+ *     subscriber set; broadcast continues to the rest.
+ *   - `agent_end` arrives without a current turn (defensive) → broadcast
+ *     anyway so any late attachers don't get stuck.
+ *
+ * TODO (future): idle GC. A `SessionStream` with `subscribers.size === 0`
+ *   and no current turn could be disposed after some grace window (e.g. 5
+ *   minutes) to release pi resources for chronically-idle sessions. Skipped
+ *   for now — streams accumulate for the lifetime of the server process.
+ */
+import { type AgentBridgeOptions } from "./agent-bridge.js";
+import type { SessionStore } from "./storage.js";
+import type { ImageAttachment, InProgressTurnSnapshot, ServerEvent, WireMessage, WireSessionMemoryDetails } from "./wire.js";
+/**
+ * Anything we can `send` and `close` on. The `ws` library's WebSocket fits;
+ * tests can pass a stub. Kept minimal so we don't drag the `ws` types in.
+ */
+export interface Subscriber {
+    /** Send a JSON-serialized event. Implementations should be best-effort. */
+    send(event: ServerEvent): void;
+    /** True when the subscriber is no longer reachable (closed/closing). */
+    isOpen(): boolean;
+}
+/**
+ * Bridge-shaped object — `AgentBridge` is the only real impl; tests duck-type
+ * via this interface. Identical contract to `BridgeLike` in `routes.ts` but
+ * defined here too so `session-stream.ts` doesn't depend on `routes.ts`.
+ */
+export interface BridgeLike {
+    start(): Promise<void>;
+    prompt(text: string, images?: ImageAttachment[]): Promise<void>;
+    dispose(): void;
+    /**
+     * Manually compact the session context via pi's built-in compaction.
+     * Fires compaction_start / compaction_end events through the bridge's
+     * emit callback. Used by the Fork & Compact flow after the first
+     * assistant turn of a forked session completes.
+     */
+    compact?(customInstructions?: string): Promise<void>;
+    /**
+     * Optional sticky reasoning effort. Maps frontend effort strings
+     * (xhigh|high|medium|low|minimal|none) to pi ThinkingLevel.
+     */
+    setReasoningEffort?(effort: string | undefined): void;
+    /**
+     * Optional sticky model selection. Phase 3 (Available Models whitelist).
+     * Real AgentBridge implements this; test stubs may omit it (the manager
+     * skips the call when undefined, which is exactly what tests want).
+     * Returns true when the model is in effect; false when the bridge
+     * surfaced an error (the manager will then drop the prompt).
+     */
+    setModel?(modelId: string | null | undefined): Promise<boolean>;
+    /**
+     * Return the modelId of the first available model from the backend
+     * whitelist (preserving backend sortOrder). Used as defense-in-depth
+     * default when neither the envelope nor SQLite supply a modelId.
+     * Returns `undefined` when no models are available.
+     */
+    getFirstAvailableModelId?(): string | undefined;
+    /**
+     * Return current session context usage from pi's built-in estimator.
+     * Returns `undefined` when the bridge hasn't started yet or the model
+     * has no context window configured.
+     */
+    getContextUsage?(): {
+        tokens: number | null;
+        contextWindow: number;
+        percent: number | null;
+    } | undefined;
+    getSessionBranch?(): Array<{
+        type: string;
+        id: string;
+        timestamp?: string;
+        message?: unknown;
+        content?: unknown;
+        customType?: string;
+        summary?: unknown;
+        fromId?: string;
+        data?: unknown;
+        details?: unknown;
+        firstKeptEntryId?: string;
+    }>;
+    getMemoryActivity?(): {
+        phase: "idle" | "observing" | "compacting" | "reflecting" | "pruning";
+        inFlight: {
+            observer: boolean;
+            compaction: boolean;
+            reflection: boolean;
+            pruner: boolean;
+        };
+    };
+}
+/** Factory signature shared with `routes.ts`. */
+export type BridgeFactory = (args: AgentBridgeOptions) => BridgeLike;
+export interface SessionMemoryStatus {
+    mode: "active" | "passive";
+    phase: "idle" | "observing" | "compacting" | "reflecting" | "pruning";
+    inFlight: {
+        observer: boolean;
+        compaction: boolean;
+        reflection: boolean;
+        pruner: boolean;
+    };
+    reflections: {
+        count: number;
+        tokens: number;
+    };
+    observations: {
+        committedCount: number;
+        committedTokens: number;
+        pendingCount: number;
+        pendingTokens: number;
+    };
+    thresholds: {
+        observation: number;
+        compaction: number;
+        reflection: number;
+    };
+    progress: {
+        sinceObservationBoundTokens: number;
+        sinceLastCompactionTokens: number;
+        observationPoolTokens: number;
+    };
+}
+export interface AttachResult {
+    history: WireMessage[];
+    currentTurn: InProgressTurnSnapshot | null;
+    /** Resolves when the underlying pi session is ready (or rejects on start failure). */
+    ready: Promise<void>;
+    /** True when this session was created via "Fork & Compact" and has not yet
+     *  triggered its first compaction. The dispatcher includes this in
+     *  `session_ready` so the frontend can adapt the send button. */
+    forkCompactPending: boolean;
+    /** Cumulative context tokens used across the session (null initially, updated on first token_usage). */
+    contextWindowUsed: number | null;
+    /** Model's total context window in tokens (null if model metadata not yet available). */
+    contextWindowMax: number | null;
+}
+export interface SessionStreamManagerOptions {
+    store: SessionStore;
+    /**
+     * Fallback cwd used ONLY when a session has no resolvable project (which
+     * shouldn't happen in normal operation since FK enforces it). Sessions
+     * with a valid project always run pi against `project.path`.
+     */
+    cwd: string;
+    /**
+     * Backend base URL — threaded into every AgentBridge so pi proxies all
+     * inference through `${backendUrl}/v1` instead of reading
+     * `~/.spectral/agent/auth.json`. Required in production; tests that supply a
+     * `bridgeFactory` may pass any non-empty placeholder.
+     */
+    backendUrl: string;
+    /**
+     * Machine JWT — used as the Bearer credential pi sends to the backend
+     * proxy on every inference call. See `backendUrl` for context.
+     */
+    machineJwt: string;
+    bridgeFactory?: BridgeFactory;
+    agentDir?: string;
+}
+export declare class SessionStreamManager {
+    private readonly store;
+    private readonly cwd;
+    private readonly backendUrl;
+    private readonly machineJwt;
+    private readonly bridgeFactory;
+    private readonly agentDir;
+    private readonly streams;
+    private disposed;
+    constructor(opts: SessionStreamManagerOptions);
+    /**
+     * Attach a subscriber to a session. Lazily creates the underlying pi
+     * session on first attach. The caller is responsible for sending the
+     * initial `session_ready` frame using the returned replay payload (this
+     * keeps wire-protocol concerns in the routes layer).
+     *
+     * Throws if the session id is unknown in SQLite (caller should turn this
+     * into a wire-level error frame + close).
+     */
+    attach(sessionId: string, subscriber: Subscriber): AttachResult;
+    /**
+     * Detach a subscriber. Idempotent. Does NOT dispose the underlying pi
+     * session — even when subscribers reach zero, the in-flight turn must
+     * complete and persist.
+     */
+    detach(sessionId: string, subscriber: Subscriber): void;
+    /** True if the session has an in-flight turn (manager-side; not WS-side). */
+    hasActiveTurn(sessionId: string): boolean;
+    /**
+     * Return the set of session IDs that currently have an in-flight turn.
+     * Cheap O(streams) scan used by the list-project / list-sessions endpoints
+     * to enrich responses with `hasActiveTurn` markers so the frontend can
+     * render a yellow pulsating dot next to active sessions/projects.
+     */
+    getActiveTurnSessionIds(): Set<string>;
+    getSessionMemoryStatus(sessionId: string): SessionMemoryStatus;
+    getSessionMemoryDetails(sessionId: string): WireSessionMemoryDetails;
+    compactSession(sessionId: string): Promise<void>;
+    /**
+     * Persist a user message and forward it to pi. Resolves after the user
+     * message is persisted + pi is invoked (NOT after the turn completes —
+     * the turn lifetime is observed via the broadcast stream).
+     *
+     * Broadcast ordering:
+     *   1. user message persisted to SQLite
+     *   2. `user_message_appended` broadcast to all subscribers (including
+     *      the originating tab)
+     *   3. new `currentTurn` opened
+     *   4. `bridge.prompt()` invoked (events arrive asynchronously and are
+     *      buffered + broadcast as they come)
+     *
+     * Sticky model selection (Phase 3 — Available Models whitelist):
+     *   - When `modelId` is provided, we apply it via `bridge.setModel()` and
+     *     persist to SQLite for cross-restart recovery, BEFORE invoking
+     *     `bridge.prompt()`. If `setModel` fails (unknown model, registry
+     *     unavailable, pi-side error) the bridge has already emitted an
+     *     `error` wire event and we drop the prompt to avoid running it
+     *     against the wrong model.
+     *   - When `modelId` is omitted, we look up SQLite. If a previous turn
+     *     persisted a value, we reapply it on this turn (this is the
+     *     cross-restart recovery path: a fresh server process has lost pi's
+     *     in-memory model state, so we re-pin from durable storage).
+     *   - When neither envelope nor SQLite have a value, we leave model
+     *     selection to pi's own settings file (pre-Phase-3 behaviour).
+     */
+    prompt(sessionId: string, content: string, modelId?: string, images?: ImageAttachment[], reasoningEffort?: string): Promise<void>;
+    /**
+     * Tear down everything. Best-effort: disposes every bridge, drops all
+     * subscribers. After this the manager is unusable.
+     */
+    dispose(): void;
+    /** Test/inspection helper: how many streams are currently tracked. */
+    streamCount(): number;
+    /**
+     * Count of sessions with an in-flight turn (i.e. a `currentTurn` set).
+     * Used by `gracefulShutdown` to decide whether to keep waiting before
+     * tearing down — a non-zero count means at least one assistant response
+     * is mid-stream and we'd rather let it finish (within the grace window)
+     * than orphan a half-streamed message in the UI.
+     *
+     * Cheap O(streams) scan; we only call it ~50× during a 5 s graceful
+     * shutdown so the linear walk is fine.
+     */
+    activeTurnCount(): number;
+    /**
+     * Cancel the in-flight turn for a session (user pressed Stop in the UI).
+     * Disposes the pi bridge and broadcasts `agent_end` so all subscribers
+     * see the turn close. The stream itself is kept alive — the next user
+     * message (via `prompt()`) will lazily create a fresh bridge.
+     *
+     * Idempotent: if no stream exists for the session, or no turn is in
+     * flight, this is a no-op.
+     */
+    cancelTurn(sessionId: string): void;
+    /**
+     * Tear down a single session's stream — disposes the pi bridge and clears
+     * subscribers. Idempotent. Called by the routes layer right before
+     * `DELETE /api/sessions/:id` so the SQL cascade doesn't leave a zombie
+     * pi process driving events at a session that no longer exists.
+     *
+     * Does NOT remove the session from the store — that's the caller's job.
+     */
+    disposeSessionStream(sessionId: string): void;
+    /**
+     * Tear down every stream whose session belongs to the given list of ids.
+     * Used by the project-delete path: the route layer reads the project's
+     * session ids from `deleteProject()` and passes them here BEFORE the SQL
+     * cascade fires, so no pi process ever observes the FK cascade.
+     */
+    disposeProjectStreams(sessionIds: readonly string[]): void;
+    /**
+     * Set the autonomous iterative loop state for a session.
+     *
+     * When `active` is true, the manager replays `originalPrompt` after each
+     * `agent_end` event — the agent sees its own file changes from prior
+     * iterations and iteratively improves its solution (Ralph Wiggum pattern).
+     * The loop stops when the agent emits `<LOOP_DONE>` in its response or the
+     * safety iteration limit is reached.
+     */
+    setLoopActive(sessionId: string, active: boolean, originalPrompt?: string, maxIterations?: number, goal?: string): void;
+    /**
+     * Fork & Compact: trigger compaction after the first assistant turn of a
+     * forked session. Uses pi's built-in `compact()` which generates a summary
+     * of older context, retaining the most recent ~20K tokens (including the
+     * user's new message + the assistant's response).
+     *
+     * Custom instructions reference the most recent user message so the LLM
+     * summary prioritizes information relevant to the current task.
+     */
+    private triggerForkCompact;
+    /**
+     * Send the next prompt for an autonomous loop iteration, waiting for any
+     * in-flight observational-memory compaction to finish first so the LLM
+     * sees the compacted context.
+     *
+     * The compaction-trigger extension fires on agent_end (via setTimeout),
+     * so we poll stream.compacting briefly. If compaction hasn't started after
+     * a short grace period, we check whether the context window exceeds the
+     * threshold and proactively trigger compaction via the bridge (which
+     * invokes pi's full pipeline, including the session_before_compact hook
+     * where the observational memory extension provides its summary).
+     *
+     * A duplicate call from the extension's delayed compaction trigger is
+     * harmless — pi throws "Already compacted" which the extension catches.
+     */
+    /**
+     * Send the next prompt for an autonomous loop iteration, compacting first
+     * if the context window exceeds the threshold.
+     *
+     * Instead of polling for the extension's delayed compaction-trigger (which
+     * fires via setTimeout), we proactively call bridge.compact() directly.
+     * bridge.compact() → session.compact() → fires session_before_compact
+     * (where the extension's compaction-hook provides the observational-memory
+     * summary), then appends the compaction entry, reloads the compacted
+     * context into agent.state.messages, and emits compaction_start/end.
+     *
+     * The extension's trigger still fires (via setTimeout), but by the time
+     * its callback runs, bridge.compact() has already appended the compaction
+     * entry → prepareCompaction() returns undefined → "Already compacted"
+     * → the trigger's onError handler catches it harmlessly.
+     */
+    private buildLoopPrompt;
+    private sendNextLoopIteration;
+    private createStream;
+    private handleBridgeEvent;
+    /**
+     * Flush the current in-flight turn's events to SQLite for crash recovery.
+     * Only the events accumulated since the last flush are written — we append
+     * them to the already-stored JSONL via INSERT OR REPLACE. Called every
+     * `BATCH_FLUSH_INTERVAL` events from `handleBridgeEvent`.
+     *
+     * Errors are caught, logged, and swallowed: batch persistence is a
+     * best-effort hardening, never a failure path that should block the stream.
+     */
+    private flushInFlightTurn;
+    private broadcast;
+    /**
+     * Push the current prompt queue state to all subscribers of a session.
+     * Called after every queue mutation (enqueue, remove, clear, dequeue).
+     * Safe to call when no stream exists or no subscribers — silently no-ops.
+     */
+    pushQueueState(sessionId: string): void;
+    /**
+     * Auto-dequeue the next prompt from the persistent queue and start a
+     * new turn. Called from the `agent_end` handler when no loop is active.
+     * Returns true if a prompt was dequeued and a turn started.
+     */
+    private maybeAutoDequeue;
+}
+//# sourceMappingURL=session-stream.d.ts.map

package/dist/server/session-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-stream.d.ts","sourceRoot":"","sources":["../../src/server/session-stream.ts"],"names":[],"mappings":"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"}

package/dist/server/shutdown.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Graceful shutdown helper for `spectral serve`.
+ *
+ * Why a separate module:
+ *  - The shutdown flag (`shutdownState.isShuttingDown`) is read by the relay
+ *    dispatcher to reject new `client_message` envelopes. Putting it on
+ *    `serve.ts` would create a circular import (dispatcher → serve → relay
+ *    client → …); pulling it out keeps the dependency graph linear.
+ *  - The orchestration is small but has enough edge cases (idempotent on a
+ *    second SIGTERM, bounded wait for in-flight streams, best-effort store
+ *    close) that it's worth one focused unit test.
+ *
+ * Behaviour summary (matches the contract in the Batch 6 brief):
+ *  1. First SIGINT/SIGTERM:
+ *     - Log "Shutting down…" to stderr.
+ *     - Flip `shutdownState.isShuttingDown = true`. From this point on the
+ *       dispatcher refuses new `client_message` frames with an error
+ *       wrapped as a `ws_event` (so the browser sees the rejection on the
+ *       same stream it was using).
+ *     - Wait up to `gracePeriodMs` (default 5_000 ms) for the in-flight
+ *       stream count reported by `inFlightCount()` to drain to 0. Polled
+ *       every 100 ms — any non-zero value indicates an active turn.
+ *     - Close the relay (code 1000, reason "shutdown") and dispose the
+ *       manager. The dispose order matters: relay first so the backend
+ *       sees a clean close before our local state goes; manager second so
+ *       any pi processes get torn down deterministically.
+ *     - Close the SQLite store (best-effort — a failure here just gets
+ *       logged; the process is exiting anyway).
+ *     - Exit with the supplied code (default 0).
+ *  2. Second SIGINT/SIGTERM during the grace period: skip the wait, force
+ *     immediate exit with code 1. We don't want a hung pi process to
+ *     prevent operators from killing the server with a second Ctrl-C.
+ *
+ * The function is intentionally framework-free — it takes plain callbacks
+ * for everything I/O-shaped so the unit test can exercise the orchestration
+ * without spawning a real relay or sqlite handle.
+ */
+/**
+ * Process-wide shutdown flag. Read by the dispatcher to gate new
+ * `client_message` envelopes; written by `gracefulShutdown` (and by tests
+ * via `resetShutdownState`).
+ *
+ * Module-level singleton because there is exactly one server process per
+ * `spectral serve` invocation; co-locating with serve.ts would require
+ * threading the flag through the dispatcher's deps (already a small
+ * object) and risks dispatcher tests carrying serve.ts state.
+ */
+export declare const shutdownState: {
+    isShuttingDown: boolean;
+};
+/**
+ * Reset the singleton flag. Tests use this in `beforeEach` so a previous
+ * test's shutdown doesn't bleed into the next. Production code must NOT
+ * call this — once the process is shutting down, it's shutting down.
+ */
+export declare function resetShutdownState(): void;
+export interface GracefulShutdownOptions {
+    /** Logger; defaults to `console`. Tests inject a noop or a recorder. */
+    logger?: Pick<Console, "log" | "warn" | "error">;
+    /**
+     * Reports in-flight stream count (e.g. `() => manager.activeTurnCount()`).
+     * Polled every 100 ms until it returns 0 or `gracePeriodMs` elapses.
+     * If omitted we skip the wait entirely (treated as "nothing in flight").
+     */
+    inFlightCount?: () => number;
+    /** Close the relay with code 1000 / reason "shutdown". */
+    closeRelay?: () => void | Promise<void>;
+    /** Dispose the SessionStreamManager (kills pi processes). */
+    disposeManager?: () => void | Promise<void>;
+    /** Close the SQLite store. Failures are logged, not rethrown. */
+    closeStore?: () => void;
+    /** Bound on how long to wait for in-flight streams. Default 5_000 ms. */
+    gracePeriodMs?: number;
+    /** Polling interval for the in-flight wait. Default 100 ms. */
+    pollIntervalMs?: number;
+    /** Exit code on a clean first-signal shutdown. Default 0. */
+    exitCode?: number;
+    /**
+     * Override `process.exit` for tests. Not called as a function reference
+     * directly so the test can assert on what was requested without actually
+     * killing vitest.
+     */
+    exitFn?: (code: number) => void;
+    /**
+     * Sleep helper. Tests inject a mock clock; production uses real
+     * `setTimeout`. Resolves after `ms` milliseconds.
+     */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Test-only: reset the entry counter alongside `shutdownState`. */
+export declare function resetShutdownEntryCount(): void;
+/**
+ * Run the graceful shutdown sequence. Idempotent on the entry-count
+ * dimension: the second concurrent call resolves immediately after
+ * triggering an immediate exit.
+ *
+ * Returns once the supplied `exitFn` has been invoked (or would have been
+ * invoked in production where `process.exit` does not return). Tests can
+ * await it to assert ordering.
+ */
+export declare function gracefulShutdown(opts?: GracefulShutdownOptions): Promise<void>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/server/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/server/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAEpD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAaD,oEAAoE;AACpE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,IAAI,CAAC,CAmGf"}