hammoc 1.8.4 → 1.9.0

package/packages/server/dist/services/chatService.d.ts

@@ -1,6 +1,7 @@
 import { type SDKMessage, type CanUseTool, type RewindFilesResult } from '@anthropic-ai/claude-agent-sdk';
 import type { ChatServiceConfig, ChatOptions, ChatResponse, PermissionMode, StreamCallbacks } from '@hammoc/shared';
 import type { ChatEngine } from './chatEngine.js';
+import { HookEventBridge } from '../handlers/hookBridge.js';
 /**
  * ChatService - Wrapper for Claude Agent SDK
  * Handles communication with Claude Code through the official SDK
@@ -12,9 +13,43 @@ export declare class ChatService implements ChatEngine {
     private disallowedTools;
     /** Auto-compaction master switch (both engines). Mirrors the autoCompactEnabled preference; default true. */
     private autoCompactEnabled;
+    /**
+     * The persistent SDK query. Epic 38: created ONCE (lazily on the first send)
+     * and kept alive for the session — NOT recreated per turn — so the control
+     * channel stays open for post-result hooks. `null` before the first send and
+     * after `close()`; `interrupt()`/`setPermissionMode()` reach it between turns.
+     */
     private currentQuery;
+    /** Single iterator over the persistent query — each turn consumes one slice of it. */
+    private sessionIterator;
+    /** Manually-driven prompt input; each turn pushes its user message here. */
+    private promptQueue;
+    /** SDK hook → internal-event bridge (observe-only in 38.1; 38.2 consumes the ledger). */
+    private hookBridge;
+    /**
+     * Story 38.5 (Task 2) — process-residency flag. When `true`, the callback path
+     * does NOT close the persistent stream at turn end: the engine is retained across
+     * turns and its lifecycle (idle timeout / LRU eviction / crash cleanup) is owned
+     * by the higher-level residency registry, not by the turn. Default `false` keeps
+     * the Story 38.1 behavior (one turn per instance, close at turn end) for any
+     * caller that has not opted into residency. SDK-engine-only concept.
+     */
+    private resident;
+    /**
+     * The CURRENT turn's permission callback. The SDK's `canUseTool` is a query-
+     * CREATION option (fixed for the persistent query's lifetime), but each turn's
+     * handler is bound to that turn's live stream (its event buffer, pending-
+     * permission map, sockets). A resident engine is reused across turns, so the
+     * query registers a stable delegator that reads this field — refreshed on every
+     * send — instead of capturing the first turn's handler. Without this, an
+     * AskUserQuestion/permission prompt on a reuse turn lands on the dead
+     * creation-turn stream: invisible after refresh and unanswerable.
+     */
+    private activeCanUseTool;
     /** Warning message from rewindFiles failure (non-fatal, streaming continues) */
     rewindWarning: string | null;
+    /** Last turn ended via tracker-hold grace expiry → residency must evict (see ChatEngine docs). */
+    lastTurnTrackerHoldExpired: boolean;
     constructor(config?: ChatServiceConfig);
     /**
      * Initialize a new session with a project directory
@@ -37,11 +72,61 @@ export declare class ChatService implements ChatEngine {
      */
     getWorkingDirectory(): string | undefined;
     /**
-     * Send a message and receive responses through an async generator
+     * Send a message and receive responses through an async generator.
+     *
+     * Epic 38 (Story 38.1): the underlying `query()` is a PERSISTENT stream —
+     * created lazily on the first send and reused for every subsequent turn (no
+     * per-turn process re-spawn, control channel stays open for post-result hooks).
+     * Each call pushes its user message onto the shared prompt queue and consumes
+     * the stream up to THIS turn's `result`, WITHOUT draining the generator: the
+     * stream never ends on its own (the prompt queue keeps it open), so the turn
+     * boundary is the `result` message and the consumer (processStream) decides
+     * when to stop. Teardown is `close()`, not turn end.
+     *
+     * In production the callback path (`sendMessageWithCallbacks`) still closes the
+     * stream at turn end (one turn per engine instance today — websocket recreates
+     * the engine per send), so behavior is unchanged. The multi-turn capability is
+     * exercised by calling this generator repeatedly on one instance; cross-turn
+     * process residency wiring is Story 38.5.
      */
     sendMessage(content: string, options?: ChatOptions, canUseTool?: CanUseTool): AsyncGenerator<SDKMessage, ChatResponse, void>;
     /**
-     * Send a message and collect all responses (non-streaming)
+     * Build the queryOptions and create the persistent `query()` with the manually
+     * driven prompt queue + SDK hooks. Called once per session (first send).
+     */
+    private createPersistentQuery;
+    /** Inline rewind-before-send (Story 25.7): rewind project files to `messageUuid`. */
+    private applyInlineRewind;
+    /**
+     * Tear down the persistent stream (session end / abort). Ends the prompt queue
+     * so a parked `next()` unblocks, closes the query, and clears references.
+     * Idempotent. Story 38.3/38.5 own the higher-level abort/lifecycle wiring.
+     */
+    close(): Promise<void>;
+    /** The hook→event bridge for the active persistent query (Story 38.2 consumes its ledger). */
+    getHookBridge(): HookEventBridge | null;
+    /**
+     * Story 38.5 (Task 2) — opt this engine into cross-turn residency. Set by the
+     * residency registry when it takes ownership of the engine's lifecycle: while
+     * resident, the callback path skips the turn-end `close()` so the persistent
+     * query survives into the next turn (no ~3s re-spawn — probe-confirmed). The
+     * registry then closes it on idle timeout / LRU eviction / crash. Idempotent.
+     */
+    setResident(resident: boolean): void;
+    /** Whether a persistent query is currently live (used by the registry to detect a torn-down engine). */
+    isLive(): boolean;
+    /**
+     * Send a message and collect the final response (non-streaming).
+     *
+     * Story 38.5 (Task 6d) — latent-hang guard. The persistent `sendMessage`
+     * generator does NOT return after a turn's `result`: it loops back to a parked
+     * `sessionIterator.next()` awaiting the NEXT prompt (or `close()`), so a naive
+     * "pull until done" would block forever the moment the first result is yielded —
+     * a latent infinite wait that only the streaming/callback path (which stops
+     * pulling at the result) avoided. This helper therefore STOPS consuming at this
+     * turn's result and builds the response from it. It handles one turn (the first
+     * result); background-task follow-ups are the streaming path's concern, not this
+     * sync helper's. Not on the production path — kept for tests/manual verification.
      */
     sendMessageSync(content: string, options?: ChatOptions): Promise<ChatResponse>;
     /**
@@ -56,6 +141,18 @@ export declare class ChatService implements ChatEngine {
      * Set the permission mode for the current session
      */
     setPermissionMode(mode: PermissionMode): Promise<void>;
+    /**
+     * Story 38.4 — runtime model switch. Change the model used for subsequent
+     * responses on the LIVE persistent query, without recreating it (no ~3s
+     * restart). `resolveEffectiveModel` resolves the `[1m]` suffix identically to
+     * the creation path (`createPersistentQuery` model option), so a runtime
+     * switch and a fresh-query model land on the exact same effective id. No-op
+     * when no query exists yet — the next `createPersistentQuery` reads the model
+     * from the send options instead. Probe-confirmed GO (setModel reflects on the
+     * next turn's response model meta); SDK-mode only (CLI omits this, callers
+     * feature-detect).
+     */
+    setModel(model: string | undefined): Promise<void>;
     /**
      * Send a message with callback-based event handling
      * Uses StreamHandler internally to process the async generator
@@ -75,7 +172,19 @@ export declare class ChatService implements ChatEngine {
         thinking?: boolean;
     }) => void, 
     /** Story 36.2: CLI phase callback — accepted for the ChatEngine interface, UNUSED in SDK mode. */
-    _onPhase?: (phase: 'launching' | 'submitting' | 'waiting' | null) => void, _onScreenFrame?: (frame: string) => void, _screenFrameThrottleMs?: number, _backgroundTracker?: import('../utils/backgroundTaskTracker.js').BackgroundTaskTracker, _onPermissionModeSync?: (mode: import('@hammoc/shared').PermissionMode) => void): Promise<ChatResponse>;
+    _onPhase?: (phase: 'launching' | 'submitting' | 'waiting' | null) => void, _onScreenFrame?: (frame: string) => void, _screenFrameThrottleMs?: number, 
+    /**
+     * Turn-boundary gate 2 (2026-07-12 fix). Story 38.2 made the engine's Stop
+     * hook (via {@link StopSnapshotSource} below) the boundary source and retired
+     * this tracker from the judgment — but the Stop ledger has a deterministic
+     * blind spot: a task that COMPLETES while a generation is still running has
+     * already left `background_tasks[]` at that generation's Stop, while its
+     * queued `<task-notification>` guarantees an auto-resume follow-up. The
+     * tracker (task_started/acks minus notifications) still holds such a task,
+     * so streamHandler now gates the turn on BOTH sources. Also remains the
+     * crash-safety-net poller's pending set (websocket owns `stream.backgroundTracker`).
+     */
+    backgroundTracker?: import('../utils/backgroundTaskTracker.js').BackgroundTaskTracker, _onPermissionModeSync?: (mode: import('@hammoc/shared').PermissionMode) => void): Promise<ChatResponse>;
     /**
      * Standalone file rewind (no message send) — backs the `session:rewind-files`
      * handler. Delegates to the shared billing-neutral `rewindSessionFiles` helper

package/packages/server/dist/services/chatService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chatService.d.ts","sourceRoot":"","sources":["../../src/services/chatService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,UAAU,EAAuB,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAChK,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EAEhB,MAAM,gBAAgB,CAAC;AASxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAYlD;;;GAGG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAW;IAC/B,OAAO,CAAC,eAAe,CAAW;IAClC,6GAA6G;IAC7G,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,YAAY,CAAsB;IAC1C,gFAAgF;IAChF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAExB,MAAM,GAAE,iBAAsB;IAQ1C;;OAEG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD;;OAEG;YACW,mBAAmB;IASjC;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAItC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIzC;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAIzC;;OAEG;IACI,WAAW,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,EACzB,UAAU,CAAC,EAAE,UAAU,GACtB,cAAc,CAAC,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC;IAwLjD;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,YAAY,CAAC;IAcxB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAMhC;;OAEG;IACH,iBAAiB,IAAI,cAAc;IAInC;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D;;;OAGG;IACG,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,WAAgB,EACzB,UAAU,CAAC,EAAE,UAAU;IACvB,uEAAuE;IACvE,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI;IAC5C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI;IAC1G,kGAAkG;IAClG,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,IAAI,KAAK,IAAI,EACzE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EACxC,sBAAsB,CAAC,EAAE,MAAM,EAC/B,kBAAkB,CAAC,EAAE,OAAO,mCAAmC,EAAE,qBAAqB,EACtF,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,gBAAgB,EAAE,cAAc,KAAK,IAAI,GAC9E,OAAO,CAAC,YAAY,CAAC;IA+BxB;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGpH"}
+{"version":3,"file":"chatService.d.ts","sourceRoot":"","sources":["../../src/services/chatService.ts"],"names":[],"mappings":"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"}