agent-relay-server 0.121.5 → 0.122.1

package/runner/src/adapters/claude-status-detectors.ts

@@ -0,0 +1,147 @@
+import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
+import type { ProviderStatusUpdate } from "../adapter";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+
+// LEGACY PANE-SCRAPE FALLBACK (#766/#768) — busy/idle is now driven primarily by
+// Claude Code's intrinsic session probe (readClaudeSessionStatus, ./claude-session-probe):
+// `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` carries a machine-readable `status` field
+// on CC ≥2.1.119. These two pane heuristics are the SOLE fallback for pre-2.1.119 /
+// probe-missing sessions, and claudePaneLooksReady still backs the input-readiness gate
+// (waitForClaudeInputReady) + the prompt-gate busy guard — so they stay. They string-match
+// CC's TUI chrome against captured tmux scrollback (~80 lines), so they break whenever CC
+// restyles its footer/banner. Deliberately substring/regex based (no machine-readable
+// signal existed when these were written). Known break conditions, so the next CC restyle
+// is a fast fix rather than a hunt:
+//   readiness (claudePaneLooksReady) breaks if CC renames/removes ALL of: the
+//     "bypass permissions" / "shift+tab to cycle" / "? for shortcuts" footer hints,
+//     the "/effort" hint, or the "Welcome back" / "Claude Code" banner.
+//   busy (claudePaneIsBusy) breaks if CC drops the live "… (<elapsed>" spinner counter
+//     (the cross-version anchor; the "esc to interrupt" hint was already dropped in 2.1.x).
+//   FALSE POSITIVES: agent output that literally QUOTES any of these strings (e.g. a
+//     transcript discussing "esc to interrupt", or this very comment shown in a pane)
+//     reads as ready/busy. Tolerated because the markers are CC-specific enough to be
+//     rare in real output; if it bites, gate on the LAST N lines only (the live footer).
+// History: 18067b5 (busy counter), and the readiness footer-vs-banner fix below.
+export function claudePaneLooksReady(text: string): boolean {
+  // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
+  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
+  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
+  // renders at the prompt. Requiring the banner made every delivery after the first screen
+  // of output time out as "input not ready". Any one of these strong, Claude-specific
+  // markers means the TUI is up and the input box exists.
+  return text.includes("bypass permissions")   // footer in --dangerously-skip-permissions mode
+    || text.includes("shift+tab to cycle")       // mode-cycle footer hint (persistent)
+    || text.includes("? for shortcuts")          // default footer hint (persistent)
+    || text.includes("/effort")
+    || text.includes("Welcome back")
+    || text.includes("Claude Code");
+}
+
+// The working-spinner footer carries a live elapsed-time counter while a turn is in
+// flight, e.g. "✶ Perambulating… (2m 17s · ↓ 8.7k tokens)" — gerund, "… (", then
+// "[Nh ][Nm ]Ns". Anchored on the gerund ellipsis so it can't match the "… +N lines
+// (ctrl+o to expand)" truncation marker, the idle input box, or the persistent
+// "/btw … without interrupting Claude's current work" queue hint.
+const CLAUDE_BUSY_SPINNER_RE = /…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b/;
+
+export function claudePaneIsBusy(text: string): boolean {
+  // Claude Code <2.1.x rendered "(esc to interrupt)" in the spinner footer; 2.1.x
+  // dropped that hint but kept the "(<elapsed>" counter, which is the stable busy
+  // signal across versions. Match either so the busy probe (and the reconciler
+  // backstop that depends on it) keep working as the footer wording changes.
+  return CLAUDE_BUSY_SPINNER_RE.test(text) || text.includes("esc to interrupt");
+}
+
+// #286: detect the subscription usage-limit modal in the pane and turn it into the
+// provider-neutral rate-limit hold (idle + blocked) that the relay's resume sweep lifts
+// at reset. Mirrors claudeModelUnavailableStatus, but non-terminal (idle, not error).
+export function claudeRateLimitStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const parsed = parseClaudeRateLimitPane(text);
+  if (!parsed) return null;
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({
+      errorType: parsed.errorType ?? "session_limit", kind: parsed.kind ?? "usage_limit",
+      ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
+      message: parsed.message,
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+    }),
+  };
+}
+
+// #769 — detect the API connection-retry banner in the live terminal footer and surface a
+// transient blocked hold (non-terminal, clears on recovery). Three stable anchors from the
+// banner text: "Unable to connect to API", "Retrying in <N>s", "attempt <N>/<M>".
+// Gated on the LAST N lines so agent output that merely QUOTES these strings (e.g. quoting
+// this comment, or a discussion of retry logic) doesn't false-positive — the live banner
+// always lives in the footer; quoted strings appear in the scrollback body.
+// Break condition: if CC renames/removes any anchor substring the detector stops firing and
+// sessions return to idle/available — a fast fix once the new footer wording is known.
+const CLAUDE_CONN_RETRY_FOOTER_LINES = 10;
+const CLAUDE_CONN_RETRY_ANCHOR_RE = /Unable to connect to API/;
+const CLAUDE_CONN_RETRY_RATE_RE = /Retrying in \d+s/;
+const CLAUDE_CONN_RETRY_ATTEMPT_RE = /attempt \d+\/\d+/;
+
+export function claudeConnectionRetryStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const footer = text.split("\n").slice(-CLAUDE_CONN_RETRY_FOOTER_LINES).join("\n");
+  if (
+    !CLAUDE_CONN_RETRY_ANCHOR_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_RATE_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_ATTEMPT_RE.test(footer)
+  ) return null;
+  const now = Date.now();
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: {
+      state: "blocked",
+      reason: "conn_retry",
+      kind: "conn_retry",
+      label: "connection degraded · retrying",
+      message: "Claude cannot reach the Anthropic API and is retrying the connection.",
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+      terminal: false,
+      recommendedAction: "Holding; agent-relay will clear this state once the session reconnects.",
+      enteredAt: now,
+      updatedAt: now,
+    },
+  };
+}
+
+export function claudeModelUnavailableStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const message = extractClaudeModelUnavailableMessage(text);
+  if (!message) return null;
+  return {
+    status: "error",
+    clear: ["provider-turn", "subagent"],
+    providerState: {
+      state: "failed",
+      reason: "model-unavailable",
+      message,
+      source: "claude-pane",
+      terminal: true,
+      ...(sessionName ? { sessionName } : {}),
+      recommendedAction: "Choose a different Claude model before restarting this agent.",
+    },
+    metadata: {
+      terminalFailureReason: "model-unavailable",
+      terminalFailureMessage: message,
+    },
+    timeline: {
+      status: "provider.restart_decision",
+      id: `provider-model-unavailable-${Date.now()}`,
+      timestamp: Date.now(),
+      title: "Provider restart skipped",
+      body: message,
+      icon: "ti-player-stop",
+      metadata: {
+        eventType: "provider.restart_decision",
+        decision: "stop-surface",
+        reason: "model-unavailable",
+        modelUnavailable: true,
+        modelUnavailableMessage: message,
+      },
+    },
+  };
+}

package/runner/src/adapters/claude-transcript-tail.ts

@@ -0,0 +1,128 @@
+import { open, stat } from "node:fs/promises";
+import { LatestTurnStepAccumulator, type TurnStep } from "./claude-transcript";
+
+const FINGERPRINT_BYTES = 4096;
+
+export interface ClaudeTranscriptFileIdentity {
+  dev: number;
+  ino: number;
+  birthtimeMs: number;
+}
+
+interface TailFingerprint {
+  offset: number;
+  bytes: Buffer;
+}
+
+export interface IncrementalTranscriptPollResult {
+  available: boolean;
+  changed: boolean;
+  reset: boolean;
+  steps: TurnStep[];
+  transcriptLooksComplete: boolean;
+}
+
+export class IncrementalClaudeTranscriptTail {
+  private offset = 0;
+  private pending = Buffer.alloc(0);
+  private identity: ClaudeTranscriptFileIdentity | undefined;
+  private fingerprint: TailFingerprint | undefined;
+  private readonly accumulator = new LatestTurnStepAccumulator();
+
+  async poll(path: string): Promise<IncrementalTranscriptPollResult> {
+    let fileStat: Awaited<ReturnType<typeof stat>>;
+    try {
+      fileStat = await stat(path);
+    } catch {
+      return this.result({ available: false, changed: false, reset: false });
+    }
+
+    const nextIdentity = { dev: fileStat.dev, ino: fileStat.ino, birthtimeMs: fileStat.birthtimeMs };
+    const replaced = this.identity !== undefined && !sameIdentity(this.identity, nextIdentity);
+    const truncated = this.offset > fileStat.size;
+    let reset = replaced || truncated;
+    if (!reset && this.identity && this.fingerprint && fileStat.size >= this.offset) {
+      reset = !(await this.fingerprintMatches(path));
+    }
+    if (reset) this.reset(nextIdentity);
+    else if (!this.identity) this.identity = nextIdentity;
+
+    if (this.offset === fileStat.size) {
+      return this.result({ available: true, changed: false, reset });
+    }
+
+    const length = fileStat.size - this.offset;
+    const buffer = Buffer.alloc(length);
+    let bytesRead = 0;
+    const handle = await open(path, "r");
+    try {
+      const read = await handle.read(buffer, 0, length, this.offset);
+      bytesRead = read.bytesRead;
+    } finally {
+      await handle.close();
+    }
+
+    this.offset += bytesRead;
+    const delta = buffer.subarray(0, bytesRead);
+    this.updateFingerprint(delta);
+    const changed = bytesRead > 0 && this.consume(delta);
+    return this.result({ available: true, changed, reset });
+  }
+
+  private reset(identity: ClaudeTranscriptFileIdentity): void {
+    this.offset = 0;
+    this.pending = Buffer.alloc(0);
+    this.fingerprint = undefined;
+    this.identity = identity;
+    this.accumulator.reset();
+  }
+
+  private async fingerprintMatches(path: string): Promise<boolean> {
+    if (!this.fingerprint) return true;
+    const buffer = Buffer.alloc(this.fingerprint.bytes.length);
+    const handle = await open(path, "r");
+    try {
+      const read = await handle.read(buffer, 0, buffer.length, this.fingerprint.offset);
+      return read.bytesRead === buffer.length && buffer.equals(this.fingerprint.bytes);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private updateFingerprint(delta: Buffer): void {
+    if (!delta.length) return;
+    const previous = this.fingerprint?.bytes ?? Buffer.alloc(0);
+    const combined = previous.length ? Buffer.concat([previous, delta]) : delta;
+    const bytes = Buffer.from(combined.subarray(Math.max(0, combined.length - FINGERPRINT_BYTES)));
+    this.fingerprint = { offset: this.offset - bytes.length, bytes };
+  }
+
+  private consume(delta: Buffer): boolean {
+    if (!delta.length) return false;
+    const combined = this.pending.length ? Buffer.concat([this.pending, delta]) : delta;
+    const lastNewline = combined.lastIndexOf(0x0a);
+    if (lastNewline === -1) {
+      this.pending = Buffer.from(combined);
+      return false;
+    }
+
+    const complete = combined.subarray(0, lastNewline + 1);
+    this.pending = Buffer.from(combined.subarray(lastNewline + 1));
+    this.accumulator.appendJsonl(complete.toString("utf8"));
+    return true;
+  }
+
+  private result(input: { available: boolean; changed: boolean; reset: boolean }): IncrementalTranscriptPollResult {
+    return {
+      ...input,
+      steps: this.accumulator.steps,
+      transcriptLooksComplete: this.accumulator.transcriptLooksComplete,
+    };
+  }
+}
+
+function sameIdentity(a: ClaudeTranscriptFileIdentity, b: ClaudeTranscriptFileIdentity): boolean {
+  return a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+}
+
+export const sameClaudeTranscriptFileIdentityForTests = sameIdentity;

package/runner/src/adapters/claude-transcript.ts

@@ -0,0 +1,414 @@
+// Phase 1 live-session lane: extract the user-visible assistant turn from a
+// Claude Code transcript JSONL so it can be surfaced in the dashboard chat
+// without the agent re-emitting it via /reply (zero agent tokens).
+//
+// Transcript shape (one JSON object per line):
+//   { type: "user", message: { content: "..." | [{type:"text"|"tool_result", ...}] } }
+//   { type: "assistant", message: { content: [{type:"thinking"|"text"|"tool_use", ...}], stop_reason } }
+//
+// The "current turn" is everything after the last *real* user prompt (a user
+// entry carrying text, not just tool_result blocks). We collect the assistant
+// `text` blocks from that turn — thinking and tool_use are dropped.
+
+import { computeContextRatio, type SessionAnalysis, type SessionEvent } from "../session-insights";
+
+interface TranscriptBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  is_error?: boolean;
+}
+
+export interface TurnStep {
+  type: "narration" | "reasoning" | "tool";
+  text: string;
+  label?: string;
+}
+
+interface TranscriptMessage {
+  role?: string;
+  content?: string | TranscriptBlock[];
+  stop_reason?: string;
+}
+
+interface TranscriptEntry {
+  type?: string;
+  message?: TranscriptMessage;
+  // Claude Code stamps every transcript entry with `isSidechain`: true for
+  // entries belonging to a Task (subagent) run, false for the root session.
+  // Current CC writes sidechains to a separate subagents/*.jsonl so they don't
+  // reach the root transcript the runner tails — but older CC inlined them, and
+  // the behavior can revert, so the chat-mirror parsers below defensively skip
+  // sidechain entries to keep a subagent's reasoning/tools/responses from
+  // leaking into the parent agent's chat. Insights parsers (collectClaudeSession-
+  // Events/countSubstantiveTurns) intentionally do NOT filter — changing them
+  // would shift the #184/#185 baselines, a separate concern.
+  isSidechain?: boolean;
+}
+
+function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
+  if (!message || !Array.isArray(message.content)) return [];
+  return message.content.filter((b): b is TranscriptBlock => Boolean(b) && typeof b === "object");
+}
+
+/** True for a subagent (Task) transcript entry — see the note on TranscriptEntry.isSidechain. */
+function isSidechainEntry(entry: TranscriptEntry): boolean {
+  return entry.isSidechain === true;
+}
+
+function isRealUserPrompt(entry: TranscriptEntry): boolean {
+  if (entry.type !== "user") return false;
+  const content = entry.message?.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  // An array user entry is a real prompt only if it carries a text block;
+  // pure tool_result entries are mid-turn plumbing, not a new prompt.
+  return blocks(entry.message).some((b) => b.type === "text" && Boolean(b.text?.trim()));
+}
+
+function assistantText(entry: TranscriptEntry): string {
+  if (entry.type !== "assistant") return "";
+  return blocks(entry.message)
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text!.trim())
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+/**
+ * Returns true when the transcript's final parseable entry is an assistant
+ * message with stop_reason "end_turn", meaning the full turn has been flushed.
+ * Used to detect a race where the Stop hook reads the file before the last
+ * assistant block is written to disk.
+ */
+export function transcriptLooksComplete(jsonl: string): boolean {
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.transcriptLooksComplete;
+}
+
+/**
+ * Returns the concatenated assistant `text` for the most recent turn (since the
+ * last real user prompt), or "" if there is nothing user-visible to surface.
+ */
+export function extractLastAssistantTurn(jsonl: string): string {
+  const lines = jsonl.split("\n");
+  let collected: string[] = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      collected = [];
+      continue;
+    }
+    const text = assistantText(entry);
+    if (text) collected.push(text);
+  }
+  return collected.join("\n\n").trim();
+}
+
+/**
+ * Like extractLastAssistantTurn but skips the first `afterEntry` valid JSON entries.
+ * Used when a partial transcript flush already emitted entries 1..afterEntry so the
+ * Stop-hook full-mode capture doesn't re-emit the already-published text.
+ */
+export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: number): string {
+  const lines = jsonl.split("\n");
+  const collected: string[] = [];
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      collected.length = 0;
+      continue;
+    }
+    if (entryIndex <= afterEntry) continue;
+    const text = assistantText(entry);
+    if (text) collected.push(text);
+  }
+  return collected.join("\n\n").trim();
+}
+
+/**
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
+/**
+ * Returns only the text from the LAST assistant entry in the current turn.
+ * Unlike extractLastAssistantTurn which collects all intermediate text between
+ * tool calls, this returns just the final response — what the user sees as the
+ * concluding message.
+ */
+export function extractFinalAssistantMessage(jsonl: string): string {
+  const lines = jsonl.split("\n");
+  let lastText = "";
+  let pastLastUserPrompt = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      pastLastUserPrompt = true;
+      lastText = "";
+      continue;
+    }
+    if (!pastLastUserPrompt) continue;
+    const text = assistantText(entry);
+    if (text) lastText = text;
+  }
+  return lastText.trim();
+}
+
+/**
+ * Like extractFinalAssistantMessage but skips the first `afterEntry` valid JSON
+ * entries. Used when a PreToolUse pre-flush already emitted the text before a
+ * blocking control, so final-mode Stop capture only sees later assistant text.
+ */
+export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry: number): string {
+  const lines = jsonl.split("\n");
+  let lastText = "";
+  let pastLastUserPrompt = afterEntry > 0;
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (isSidechainEntry(entry)) continue;
+    if (entryIndex <= afterEntry) continue;
+    if (isRealUserPrompt(entry)) {
+      pastLastUserPrompt = true;
+      lastText = "";
+      continue;
+    }
+    if (!pastLastUserPrompt) continue;
+    const text = assistantText(entry);
+    if (text) lastText = text;
+  }
+  return lastText.trim();
+}
+
+/**
+ * Extract text from the `last_assistant_message` field in the Stop hook
+ * payload. This is the content of the final assistant message — either a plain
+ * string or an array of content blocks (same shape as transcript entries).
+ * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
+ */
+/**
+ * Extract the ordered narration, reasoning, and tool steps for the most recent
+ * turn (since the last real user prompt). Used by the reasoning tailer to stream
+ * progress into chat while a turn is in flight. `narration` is the assistant's
+ * intermediate `text` between tool calls (the terminal's `●` lines); it is the
+ * primary, default-visible turn content. Returns steps in transcript order so the
+ * tailer can emit only the ones it hasn't seen yet.
+ */
+export function extractLatestTurnSteps(jsonl: string): TurnStep[] {
+  const state = new LatestTurnStepAccumulator();
+  state.appendJsonl(jsonl);
+  return state.steps;
+}
+
+export class LatestTurnStepAccumulator {
+  private latestSteps: TurnStep[] = [];
+  private lastAssistantStopReason: string | undefined;
+  private parsedEntries = 0;
+
+  get steps(): TurnStep[] {
+    return [...this.latestSteps];
+  }
+
+  get transcriptLooksComplete(): boolean {
+    return this.lastAssistantStopReason === "end_turn";
+  }
+
+  get entryCount(): number {
+    return this.parsedEntries;
+  }
+
+  reset(): void {
+    this.latestSteps = [];
+    this.lastAssistantStopReason = undefined;
+    this.parsedEntries = 0;
+  }
+
+  appendJsonl(jsonl: string): void {
+    for (const line of jsonl.split("\n")) this.appendLine(line);
+  }
+
+  appendLine(line: string): void {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      return;
+    }
+    this.parsedEntries += 1;
+    if (isSidechainEntry(entry)) return;
+    if (entry.type === "assistant") this.lastAssistantStopReason = entry.message?.stop_reason;
+    if (isRealUserPrompt(entry)) {
+      this.latestSteps = [];
+      return;
+    }
+    if (entry.type !== "assistant") return;
+    for (const b of blocks(entry.message)) {
+      if (b.type === "text" && typeof b.text === "string" && b.text.trim()) {
+        this.latestSteps.push({ type: "narration", text: b.text.trim() });
+      } else if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
+        this.latestSteps.push({ type: "reasoning", text: b.thinking.trim() });
+      } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
+        this.latestSteps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
+      }
+    }
+  }
+}
+
+/**
+ * Stable dedup keys for a turn's steps, in order. Each key is salted with how many
+ * identical (type,label,text) steps preceded it in the same window — so running the
+ * same tool twice with identical input within a turn yields two distinct keys and
+ * both show in the activity trace (#265). Keying on occurrence-within-window rather
+ * than raw transcript index keeps the reasoning tailer idempotent when the "latest
+ * turn" window shrinks/resets mid-poll: a surviving step recomputes to the same or a
+ * lower occurrence, so an already-emitted step never re-fires.
+ */
+export function stepDedupKeys(steps: TurnStep[]): string[] {
+  const counts = new Map<string, number>();
+  return steps.map((step) => {
+    const base = JSON.stringify([step.type, step.label ?? "", step.text]);
+    const occ = counts.get(base) ?? 0;
+    counts.set(base, occ + 1);
+    return JSON.stringify([step.type, step.label ?? "", step.text, occ]);
+  });
+}
+
+/** Compact one-line summary of a tool invocation for the discreet activity row. */
+export function summarizeToolUse(name: string, input: Record<string, unknown> | undefined): string {
+  const str = (key: string): string | undefined => (input && typeof input[key] === "string" ? (input[key] as string) : undefined);
+  const candidate = str("command") ?? str("file_path") ?? str("path") ?? str("pattern") ?? str("query") ?? str("url") ?? str("description") ?? str("prompt");
+  const summary = candidate ? candidate.replace(/\s+/g, " ").trim() : "";
+  if (!summary) return name;
+  return summary.length > 200 ? `${summary.slice(0, 197)}…` : summary;
+}
+
+// --- Insights #184: context-gathering ratio (epic #183, docs/self-improvement.md) ---
+//
+// Computed mechanically from the whole-session transcript at session end — no model
+// involvement, so it costs zero agent tokens and the agent can't game it. The ratio is
+// paired with cheap outcome proxies (user re-prompts, tool errors) so it's never read
+// alone — see the anti-Goodhart constraint in the epic.
+
+/**
+ * Normalize a full Claude transcript into the provider-agnostic `SessionEvent` stream
+ * (#183/#184). The classifier and ratio math live in `session-insights.ts` and are shared
+ * across providers; this only knows the Claude JSONL shape. Events are emitted in
+ * transcript order so `leadingGather` is meaningful.
+ */
+export function collectClaudeSessionEvents(jsonl: string): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isRealUserPrompt(entry)) events.push({ type: "user_prompt" });
+    if (entry.type === "user") {
+      for (const b of blocks(entry.message)) {
+        if (b.type === "tool_result" && b.is_error === true) events.push({ type: "tool_error" });
+      }
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    let producedSomething = false;
+    for (const b of blocks(entry.message)) {
+      if (b.type === "text" && b.text?.trim()) producedSomething = true;
+      if (b.type !== "tool_use" || typeof b.name !== "string" || !b.name) continue;
+      producedSomething = true;
+      events.push({ type: "tool", name: b.name });
+    }
+    if (producedSomething) events.push({ type: "turn" });
+  }
+  return events;
+}
+
+/**
+ * Walk the full transcript and compute the context-gathering ratio plus paired outcome
+ * proxies. Returns null when there's nothing substantive to measure (no tool calls) —
+ * trivial sessions have nothing to learn from and shouldn't pollute the baselines.
+ */
+export function analyzeSession(jsonl: string): SessionAnalysis | null {
+  return computeContextRatio(collectClaudeSessionEvents(jsonl));
+}
+
+/** Count substantive assistant turns — used by the #185 introspection gate. */
+export function countSubstantiveTurns(jsonl: string): number {
+  let turns = 0;
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    const hasContent = blocks(entry.message).some(
+      (b) => (b.type === "text" && b.text?.trim()) || (b.type === "tool_use" && b.name),
+    );
+    if (hasContent) turns++;
+  }
+  return turns;
+}
+
+export function extractHookAssistantMessage(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return (content as TranscriptBlock[])
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text!.trim())
+    .filter(Boolean)
+    .join("\n\n");
+}