@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/claude-session-capture.ts

@@ -0,0 +1,293 @@
+import { readFile } from "node:fs/promises";
+import { errMessage } from "@humwick/sdk";
+import type { ManagedProcess, ProviderSessionEvent, ProviderSessionEventBatch, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderSessionTurnResult, ProviderUserPromptInput } from "../adapter";
+import type { SessionEvent } from "../session-insights";
+import {
+  collectClaudeSessionEvents,
+  countTranscriptEntries,
+  extractAssistantTurnForPrompt,
+  extractHookAssistantMessage,
+  extractLastAssistantTurn,
+  extractLastAssistantTurnAfterEntry,
+  extractLatestTurnSteps,
+  pendingQueuedPrompts,
+  stepDedupKeys,
+  transcriptHasToolUseAnchor,
+  transcriptLooksComplete,
+  transcriptToolUseOccurredAt,
+  turnStepEvent,
+} from "./claude-transcript";
+import { IncrementalClaudeTranscriptTail } from "./claude-transcript-tail";
+import { ClaudePromptHookLedger } from "./claude-prompt-hook";
+import { readIncrementalFileRange, statIncrementalFile } from "./incremental-file";
+
+interface ReasoningTailState {
+  timer: ReturnType<typeof setInterval>;
+  emittedNarrationKeys: Set<string>;
+  poll(): Promise<void>;
+}
+
+const REASONING_POLL_MS = 1_200;
+// Bounded the same way as control-server.ts's resolvedApprovals so a long session's dedup
+// guard (see emittedStepKeys) can't grow without limit.
+const EMITTED_STEP_KEY_LIMIT = 2048;
+// #2919 — a prompt still queued at a Stop was enqueued after the turn's last tool boundary, so it
+// sits in the transcript's last entries; a bounded tail read finds it.
+const QUEUE_SCAN_BYTES = 256 * 1024;
+const HOOKED_PROMPT_LIMIT = 8;
+
+export class ClaudeSessionCapture {
+  // #2664 — every UserPromptSubmit hook; the proof that Claude accepted a submitted prompt.
+  readonly promptHooks = new ClaudePromptHookLedger();
+  private narrativeFlushEntryCount = 0;
+  private reasoningTail?: ReasoningTailState;
+  // Step signatures already published to chat — by the deny-then-hold pre-flush harvest or a
+  // prior reasoning-tail instance — kept for the life of this capture (not reset when a new
+  // tail starts). A fresh tail is created on every new prompt (see startReasoningTail),
+  // including the runner's own injected AskUserQuestion answer; it re-reads the transcript
+  // from byte 0 and recomputes "latest turn" steps from scratch, so if that first poll lands
+  // before the injected prompt's own transcript entry has advanced the "latest turn" window,
+  // it can re-derive the exact same step signatures the earlier tail already emitted. Seeding
+  // each new tail's `seen` set from this closes that gap regardless of the exact timing.
+  private emittedStepKeys = new Set<string>();
+  // #2919 — recent UserPromptSubmit prompts. Claude hooks a prompt submitted mid-turn when it queues
+  // it and never again when it runs it. Pruned at every Stop to the ones still queued.
+  private hookedPrompts: string[] = [];
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
+  private sessionEventsCb: (events: ProviderSessionEventBatch) => void = (events) => { for (const event of events) this.sessionEventCb(event); };
+
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  onSessionEvents(cb: (events: ProviderSessionEventBatch) => void): void {
+    this.sessionEventsCb = cb;
+  }
+
+  async captureSessionTurn(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void> {
+    if (input.isPreFlush) {
+      if (!input.transcriptPath) return { reasoningSettled: true };
+      const settled = await this.settlePollForToolUse(input.transcriptPath, input.toolName, input.toolInput, ctx);
+      const jsonl = settled.jsonl;
+      if (jsonl === undefined) return { reasoningSettled: false };
+      const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
+      await this.drainReasoningTail(ctx);
+      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
+      // With reasoningCapture off the mirror dropped the tail's narration rows, so none were mirrored.
+      if (body && !(ctx.reasoningCapture !== false && this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, body))) {
+        ctx.log(`pre-flush narrative for turn ${ctx.turnId ?? "?"} (${body.length} chars)`);
+        this.emit({ type: "response", origin: "provider", body, final: false, ...(ctx.turnId ? { turnId: ctx.turnId } : {}) });
+      }
+      await ctx.flushSessionEvents(2_000).then(
+        (ok) => { if (!ok) ctx.log(`pre-flush session outbox incomplete before blocking control (${ctx.pendingSessionEventCount()} pending)`); },
+        (error) => ctx.log(`pre-flush session outbox failed before blocking control: ${errMessage(error)}`),
+      );
+      const toolUseOccurredAt = input.toolName ? transcriptToolUseOccurredAt(jsonl, input.toolName, input.toolInput) : undefined;
+      return { reasoningSettled: settled.settled, ...(toolUseOccurredAt ? { toolUseOccurredAt } : {}) };
+    }
+
+    const turnId = input.promptId ?? ctx.turnId;
+    await this.drainReasoningTail(ctx);
+    this.stopSessionTrace();
+    if (input.transcriptPath && await this.hookedPromptStillQueued(input.transcriptPath)) ctx.noteQueuedTurn?.();
+    const flushCount = this.narrativeFlushEntryCount;
+    this.narrativeFlushEntryCount = 0;
+
+    // #2840 — the reasoning tail already mirrors each narration line as its own row, so the
+    // turn-final (and the report built from it) is the closing text only.
+    const closingOnly = ctx.chatCaptureMode === "final" || ctx.reasoningCapture !== false;
+    let body = extractHookAssistantMessage(input.lastAssistantMessage);
+    if (!closingOnly && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined && transcriptLooksComplete(jsonl)) {
+        let full = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        if (!full) full = flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl);
+        if (full) body = full;
+      }
+    }
+    if (!body && closingOnly && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined) {
+        const fallback = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount, true) : "";
+        body = fallback || (flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount, true) : extractLastAssistantTurn(jsonl, true));
+      }
+    }
+    if (!body) {
+      ctx.log(`response capture: no closing text for turn ${turnId ?? "?"} (skipped)`);
+      return;
+    }
+
+    ctx.log(`response captured for turn ${turnId ?? "?"} (${body.length} chars)`);
+    this.emit({
+      type: "response",
+      origin: "provider",
+      body,
+      final: true,
+      confidence: "definitive",
+      endedBy: "completed",
+      replyToUserObligation: true,
+      ...(turnId ? { turnId } : {}),
+      ...(ctx.opener !== undefined ? { opener: ctx.opener } : {}),
+    });
+  }
+
+  async handleUserPrompt(input: ProviderUserPromptInput, ctx: ProviderSessionTurnContext): Promise<void> {
+    const prompt = input.prompt?.trim();
+    if (prompt && this.promptHooks.observe(input.prompt, input.firedAt) === "unstamped") ctx.log("UserPromptSubmit hook carried no firedAt; not submit evidence");
+    if (prompt) this.hookedPrompts = [...this.hookedPrompts, prompt].slice(-HOOKED_PROMPT_LIMIT);
+    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath, ctx);
+  }
+
+  handleHookCheck(input: { firedAt?: number }, ctx: ProviderSessionTurnContext): void {
+    this.promptHooks.hookCheckedIn(input.firedAt);
+    ctx.log(input.firedAt === undefined ? "hook check-in carried no firedAt; submits stay on composer confirmation" : "hook check-in: stamped hook path verified");
+  }
+
+  /** #2919 — whether a prompt Claude already hooked is still queued, so it runs next with no hook of its own. */
+  private async hookedPromptStillQueued(transcriptPath: string): Promise<boolean> {
+    if (!this.hookedPrompts.length) return false;
+    const queued = pendingQueuedPrompts(await readTranscriptTail(transcriptPath)).map((prompt) => prompt.trim());
+    this.hookedPrompts = this.hookedPrompts.filter((prompt) => queued.includes(prompt));
+    return this.hookedPrompts.length > 0;
+  }
+
+  async drainReasoningTail(_ctx: ProviderSessionTurnContext): Promise<void> {
+    await this.reasoningTail?.poll();
+  }
+
+  stopSessionTrace(): void {
+    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
+    this.reasoningTail = undefined;
+  }
+
+  async settlePollForToolUse(transcriptPath: string, toolName: string | undefined, toolInput: unknown, ctx: ProviderSessionTurnContext): Promise<{ settled: boolean; jsonl?: string }> {
+    const deadline = Date.now() + ctx.settlePollTimeoutMs;
+    for (;;) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (!toolName) return { settled: Boolean(jsonl), jsonl };
+      if (jsonl !== undefined && transcriptHasToolUseAnchor(jsonl, toolName, toolInput)) return { settled: true, jsonl };
+      if (Date.now() >= deadline) return { settled: false, jsonl };
+      await Bun.sleep(ctx.settlePollIntervalMs);
+    }
+  }
+
+  // #3411 — runs whatever reasoningCapture says: its tool steps carry the paths area memory matches,
+  // and the session mirror drops the steps from chat when reasoningCapture is off.
+  private startReasoningTail(transcriptPath: string, ctx: ProviderSessionTurnContext): void {
+    this.stopSessionTrace();
+    const seen = new Set<string>(this.emittedStepKeys);
+    const emittedNarrationKeys = new Set<string>();
+    const transcriptTail = new IncrementalClaudeTranscriptTail();
+    const turnIdAtStart = ctx.turnId;
+    let seeded = false;
+    let pendingPoll = Promise.resolve();
+    const pollBody = async (): Promise<void> => {
+      const result = await transcriptTail.poll(transcriptPath);
+      if (!result.available) return;
+      if (result.reset) { seen.clear(); emittedNarrationKeys.clear(); seeded = false; }
+      if (!result.changed && (seeded || (!result.steps.length && !result.transcriptLooksComplete))) return;
+      const keyed = stepDedupKeys(result.steps).map((sig, i) => ({ sig, step: result.steps[i]! }));
+      if (!seeded) {
+        seeded = true;
+        if (result.transcriptLooksComplete) {
+          for (const { sig } of keyed) seen.add(sig);
+        }
+      }
+      const turnId = ctx.turnId ?? turnIdAtStart ?? result.promptId;
+      let emitted = 0;
+      const events: ProviderSessionEvent[] = [];
+      for (const { sig, step } of keyed) {
+        if (seen.has(sig)) continue;
+        seen.add(sig);
+        this.rememberEmittedStepKey(sig);
+        emitted += 1;
+        events.push(turnStepEvent(step, turnId));
+        if (step.type === "narration") emittedNarrationKeys.add(sig);
+      }
+      if (events.length) this.emitBatch(events);
+      if (emitted) ctx.debug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
+    };
+    const poll = (): Promise<void> => {
+      const next = pendingPoll.then(pollBody, pollBody);
+      pendingPoll = next.catch(() => {});
+      return next;
+    };
+    // The serialized pendingPoll deliberately catches so later polls may continue, but poll()
+    // still returns the original rejection to its caller. Both timer-driven calls below have no
+    // caller, so catch them here rather than turning a rotating transcript into a process-fatal
+    // unhandled rejection.
+    const pollInBackground = (): void => {
+      void poll().catch((error) => {
+        try { ctx.log(`reasoning tail poll failed: ${errMessage(error)}`); } catch {}
+      });
+    };
+    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(pollInBackground, REASONING_POLL_MS) };
+    ctx.log(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
+    pollInBackground();
+  }
+
+  private rememberEmittedStepKey(sig: string): void {
+    this.emittedStepKeys.delete(sig);
+    this.emittedStepKeys.add(sig);
+    while (this.emittedStepKeys.size > EMITTED_STEP_KEY_LIMIT) {
+      const oldest = this.emittedStepKeys.values().next().value;
+      if (oldest === undefined) break;
+      this.emittedStepKeys.delete(oldest);
+    }
+  }
+
+  private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
+    const tail = this.reasoningTail;
+    if (!tail || !tail.emittedNarrationKeys.size) return false;
+    const steps = extractLatestTurnSteps(jsonl);
+    const keys = stepDedupKeys(steps);
+    const mirrored = steps
+      .map((step, index) => ({ step, key: keys[index]! }))
+      .filter(({ step, key }) => step.type === "narration" && tail.emittedNarrationKeys.has(key))
+      .map(({ step }) => step.text)
+      .join("\n\n")
+      .trim();
+    const trimmed = body.trim();
+    return mirrored === trimmed || mirrored.endsWith(`\n\n${trimmed}`);
+  }
+
+  private emit(event: ProviderSessionEvent): void {
+    this.sessionEventCb(event);
+  }
+
+  private emitBatch(events: ProviderSessionEventBatch): void {
+    this.sessionEventsCb(events);
+  }
+}
+
+async function readTranscriptTail(path: string): Promise<string> {
+  try {
+    const { size } = await statIncrementalFile(path);
+    return new TextDecoder().decode(await readIncrementalFileRange(path, Math.max(0, size - QUEUE_SCAN_BYTES), size));
+  } catch {
+    return "";
+  }
+}
+
+export async function collectClaudeTranscriptSessionEvents(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null> {
+  if (!ctx.transcriptPath) return null;
+  let jsonl: string;
+  try {
+    jsonl = await readFile(ctx.transcriptPath, "utf8");
+  } catch {
+    return null;
+  }
+  return collectClaudeSessionEvents(jsonl);
+}
+
+export async function collectClaudeTranscriptArchiveSegment(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null> {
+  if (!ctx.transcriptPath) return null;
+  try {
+    return await readFile(ctx.transcriptPath, "utf8");
+  } catch {
+    return null;
+  }
+}