agent-relay-runner 0.22.0 → 0.24.0

package/src/runner.ts

@@ -11,14 +11,45 @@ import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
 import { ReplyObligationCache } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete, analyzeSession } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { computeContextRatio } from "./session-insights";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
-import { RELAY_MCP_TOKEN_ENV } from "./relay-mcp";
+import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint } from "./relay-mcp";
+import { RelayMcpProxy } from "./relay-mcp-proxy";
 import { runtimeMetadata } from "./version";
 import { logger, parseLogLevel } from "./logger";
 import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
 
+// A destructive session transition. The runner runs end-of-session work (Insights
+// capture, #183/#184) before the invasive operation and, during that window, presents a
+// distinct non-addressable lifecycle state. Bus commands and provider hooks (Claude
+// PreCompact / SessionEnd) both normalize to one of these.
+type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill";
+
+// `finalizing-<reason>` is the transient pre-destroy window; the others are the executing
+// teardown states the dashboard already renders.
+type LifecycleAction =
+  | "shutting-down" | "killing" | "restarting"
+  | `finalizing-${SessionDestroyReason}`;
+
+// Pre-destroy work is best-effort and must never hang teardown. Capping it keeps a slow
+// transcript read or a wedged provider from stalling a shutdown the operator asked for.
+const PRE_DESTROY_TIMEOUT_MS = 4_000;
+
+// Map a lifecycle bus command to its destructive boundary reason, or undefined for
+// non-destructive commands (interrupt, inject, reconnect, permission decisions).
+function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
+  switch (type) {
+    case "agent.compact": return "compact";
+    case "agent.clearContext": return "clear";
+    case "agent.restart": return "restart";
+    case "agent.shutdown": return "shutdown";
+    case "agent.kill": return "kill";
+    default: return undefined;
+  }
+}
+
 interface RunnerOptions {
   provider: string;
   model?: string;
@@ -131,6 +162,15 @@ export class AgentRunner {
   private currentTokenProfileId?: string;
   private currentTokenExpiresAt?: number;
   private control?: ControlServer;
+  // Stage 2 (#215): the local MCP endpoint the agent connects to, fronting the relay so the
+  // Runner owns reconnect/backoff + a durable buffer. Disabled via AGENT_RELAY_MCP_PROXY=0
+  // (then the agent connects to the relay directly, Stage-1 behaviour). The proxy secret is the
+  // bearer the agent presents to the localhost proxy — it decouples the agent from the rotating
+  // relay token (the proxy injects the live token relay-side).
+  private proxy?: RelayMcpProxy;
+  private mcpProxyEndpoint?: string;
+  private readonly mcpProxyEnabled: boolean;
+  private readonly mcpProxySecret: string;
   private process?: ManagedProcess;
   private stopped = false;
   private exitCommandInProgress = false;
@@ -154,7 +194,17 @@ export class AgentRunner {
   // Last transcript path seen this session — used by end-of-session Insights (#184)
   // when the SessionEnd hook payload omits it.
   private lastTranscriptPath?: string;
-  private lifecycleAction?: "shutting-down" | "killing" | "restarting";
+  private lifecycleAction?: LifecycleAction;
+  // #183/#184 per-segment cursor: how many of the current session's normalized events
+  // have already been folded into an observation, and the key (transcript path / Codex
+  // session) that count belongs to. A boundary captures only events since the last one,
+  // so each datapoint is one work chunk between context resets; a key change or a shrink
+  // (transcript rotated, Codex buffer trimmed) resets the cursor.
+  private insightsObserved = 0;
+  private insightsCursorKey = "";
+  // Coalesces concurrent pre-session-destroy runs (e.g. the shutdown bus command and the
+  // SessionEnd hook both fire for the same teardown) so the cursor isn't raced.
+  private preDestroyPromise?: Promise<void>;
   private readonly unexpectedExitTimes: number[] = [];
   private readonly pendingMessages = new Map<number, Message>();
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
@@ -200,6 +250,8 @@ export class AgentRunner {
     this.currentTokenJti = options.tokenJti;
     this.currentTokenProfileId = options.tokenProfileId;
     this.currentTokenExpiresAt = options.tokenExpiresAt;
+    this.mcpProxyEnabled = !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
+    this.mcpProxySecret = crypto.randomUUID();
     const runtime = runtimeMetadata(options.provider);
     this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
     this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
@@ -281,9 +333,10 @@ export class AgentRunner {
       onReplyObligations: () => Promise.resolve(this.obligationCache.get()),
       onSessionTurn: (input) => this.publishSessionTurn(input),
       onUserPrompt: (input) => this.handleUserPrompt(input),
-      onSessionEnd: (input) => this.handleSessionEnd(input),
+      onSessionBoundary: (input) => this.handleSessionBoundary(input),
       onHookFatal: (report) => this.reportHookFatal(report),
     });
+    this.startMcpProxy();
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
       if (this.restartInProgress || this.restartPending) return;
@@ -350,10 +403,45 @@ export class AgentRunner {
     this.stopReasoningTail();
     this.obligationCache.stop();
     this.outbox.close();
+    this.proxy?.stop();
     this.control?.stop();
     await this.bus.close();
   }
 
+  // Start the local MCP proxy the agent connects to (Stage 2, #215). Forwards tool calls to the
+  // relay with the runner's LIVE token, buffers bufferable writes durably during a relay outage,
+  // and narrows the tool list to this agent's workspace context. Best-effort: if it can't bind,
+  // we fall back to a direct relay MCP connection (the agent env still works, no resilience).
+  private startMcpProxy(): void {
+    if (!this.mcpProxyEnabled) return;
+    try {
+      this.proxy = new RelayMcpProxy({
+        relayMcpEndpoint: relayMcpEndpoint(this.options.relayUrl),
+        getToken: () => this.currentToken,
+        authSecret: this.mcpProxySecret,
+        enqueueBuffered: (call) => {
+          this.outbox.enqueue({
+            kind: "mcp-tool-call",
+            payload: { tool: call.tool, arguments: call.arguments },
+            idempotencyKey: call.idempotencyKey,
+          });
+        },
+        initialContext: { isolatedWorktree: this.ownsIsolatedWorktree() },
+      });
+      this.mcpProxyEndpoint = this.proxy.start().url;
+      logger.info("mcp-proxy", `runner MCP proxy listening at ${this.mcpProxyEndpoint} (worktree=${this.ownsIsolatedWorktree()})`);
+    } catch (error) {
+      this.proxy = undefined;
+      this.mcpProxyEndpoint = undefined;
+      logger.warn("mcp-proxy", `failed to start MCP proxy; agent will connect to the relay directly: ${errMessage(error)}`);
+    }
+  }
+
+  private ownsIsolatedWorktree(): boolean {
+    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE;
+    return mode === "isolated";
+  }
+
   private async spawnProvider(): Promise<ManagedProcess> {
     this.providerSessionId = crypto.randomUUID();
     this.lastTranscriptPath = undefined;
@@ -369,11 +457,18 @@ export class AgentRunner {
       AGENT_RELAY_URL: this.options.relayUrl,
       AGENT_RELAY_APPROVAL: this.options.approvalMode,
       ...(this.currentToken ? { AGENT_RELAY_TOKEN: this.currentToken } : {}),
-      // Dedicated, un-clobberable credential for the injected relay MCP endpoint. A rig's
+      // Dedicated, un-clobberable credential for the injected MCP endpoint. A rig's
       // settings.json `env.AGENT_RELAY_TOKEN` would override the scoped token above at
       // MCP-parse time → server-actor auth, no identity (#233). The MCP config references
       // ${AGENT_RELAY_SESSION_TOKEN}, which rigs never set. See runner/src/relay-mcp.ts.
-      ...(this.currentToken ? { [RELAY_MCP_TOKEN_ENV]: this.currentToken } : {}),
+      //
+      // Stage 2 (#215): when the proxy is active the agent connects to the LOCAL proxy, so this
+      // holds the per-session PROXY SECRET (not the relay token). The proxy injects the live
+      // relay token itself — the agent never holds it, and token rotation is invisible. With the
+      // proxy disabled this stays the scoped relay token (Stage-1 direct connection).
+      ...(this.proxy
+        ? { [RELAY_MCP_TOKEN_ENV]: this.mcpProxySecret }
+        : (this.currentToken ? { [RELAY_MCP_TOKEN_ENV]: this.currentToken } : {})),
       ...(this.currentTokenJti ? { AGENT_RELAY_TOKEN_JTI: this.currentTokenJti } : {}),
       ...(this.currentTokenProfileId ? { AGENT_RELAY_TOKEN_PROFILE: this.currentTokenProfileId } : {}),
       ...(this.currentTokenExpiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(this.currentTokenExpiresAt) } : {}),
@@ -400,6 +495,9 @@ export class AgentRunner {
       providerConfig: this.options.providerConfig,
       env,
       controlPort: this.control!.port,
+      // Stage 2 (#215): the MCP endpoint the agent's client should target — the runner-local
+      // proxy when active, undefined when disabled (adapters fall back to the direct relay URL).
+      ...(this.mcpProxyEndpoint ? { relayMcpEndpoint: this.mcpProxyEndpoint } : {}),
       monitor: {
         deliver: (messages) => this.control!.deliverToMonitor(messages),
       },
@@ -537,17 +635,22 @@ export class AgentRunner {
     if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "agent.interrupt" && type !== "prompt.inject") return;
 
     const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
-    if (exitAfterCommand) {
-      this.exitCommandInProgress = true;
-      this.lifecycleAction = type === "agent.kill" ? "killing" : "shutting-down";
-    } else if (type === "agent.restart") {
-      this.lifecycleAction = "restarting";
-    }
+    if (exitAfterCommand) this.exitCommandInProgress = true;
     this.claims.startClaim("command", commandId);
-    this.publishStatus();
     try {
       await this.updateCommand(commandId, "accepted");
       await this.updateCommand(commandId, "running");
+      // Pre-session-destroy seam (#183): for destructive transitions, run end-of-session
+      // work (Insights capture, #184) BEFORE the invasive operation, surfaced as a
+      // non-addressable "finalizing" state so the agent isn't mistaken for merely busy.
+      const destroyReason = boundaryReasonForCommand(type);
+      if (destroyReason) await this.runPreSessionDestroy(destroyReason);
+      // Move from the transient finalizing window to the executing teardown state (or drop
+      // it entirely for compact/clear, which complete promptly once capture is done).
+      if (exitAfterCommand) this.lifecycleAction = type === "agent.kill" ? "killing" : "shutting-down";
+      else if (type === "agent.restart") this.lifecycleAction = "restarting";
+      else this.lifecycleAction = undefined;
+      this.publishStatus();
       let providerResult: Record<string, unknown> | void = undefined;
       if (type === "agent.restart") await this.restartProvider();
       else if (type === "agent.reconnect") this.publishStatus();
@@ -1057,6 +1160,10 @@ export class AgentRunner {
         });
         return;
       }
+      if (record.kind === "mcp-tool-call") {
+        await this.deliverBufferedMcpCall(record);
+        return;
+      }
       logger.warn("outbox", `dropping event with unknown kind: ${record.kind}`);
     } catch (error) {
       // 409 = the server intentionally rejected it (e.g. Insights/feature toggled off). That
@@ -1067,6 +1174,40 @@ export class AgentRunner {
     }
   }
 
+  // Replay a buffered MCP tool call (Stage 2, #215) that the proxy queued while the relay was
+  // unreachable. POST it to the relay MCP endpoint with the LIVE token — same path the live call
+  // would have taken. Throw to retry (transient), return to ack (delivered or permanently
+  // rejected). The proxy stamped an idempotencyKey into the arguments so a retry that already
+  // landed server-side is deduped, not double-sent.
+  private async deliverBufferedMcpCall(record: OutboxRecord): Promise<void> {
+    const payload = record.payload as { tool: string; arguments: Record<string, unknown> };
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (this.currentToken) headers.authorization = `Bearer ${this.currentToken}`;
+    const response = await fetch(relayMcpEndpoint(this.options.relayUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: payload.tool, arguments: payload.arguments } }),
+    });
+    if (response.status === 401 || response.status === 403) {
+      this.recoverRuntimeTokenAfterAuthFailure("mcp-outbox");
+      throw new Error(`relay rejected buffered ${payload.tool} with ${response.status}`);
+    }
+    if (response.status >= 500) throw new Error(`relay ${response.status} on buffered ${payload.tool}`);
+    if (!response.ok) {
+      // A 4xx (e.g. target gone, validation) is a permanent rejection — retrying won't help.
+      // Ack so it doesn't block the queue, but log loudly: a queued write did not land.
+      const body = await response.text().catch(() => "");
+      logger.warn("mcp-outbox", `buffered ${payload.tool} permanently rejected (${response.status}); dropping: ${body.slice(0, 200)}`);
+      return;
+    }
+    // HTTP 200 but the JSON-RPC body may still carry a tool-level error. Those reflect the same
+    // permanent-rejection semantics (bad target, validation) — ack and log, don't loop.
+    const json = await response.json().catch(() => null) as { error?: { message?: string } } | null;
+    if (json?.error) {
+      logger.warn("mcp-outbox", `buffered ${payload.tool} returned a tool error; dropping: ${json.error.message ?? "(no detail)"}`);
+    }
+  }
+
   // A hook reported an unhandled failure (#198 seam). Already logged FATAL by the control
   // server; here we additionally surface it durably to the server as a generic insight so
   // it shows up in observability rather than only in the per-agent log (#196).
@@ -1110,26 +1251,71 @@ export class AgentRunner {
     if (input.transcriptPath) this.startReasoningTail(input.transcriptPath);
   }
 
-  // SessionEnd: compute end-of-session Insights signals (#184 context-gathering
-  // ratio) from the full transcript and record them with the relay. Mechanical and
-  // model-free — costs zero agent tokens and the agent can't game it. The relay drops
-  // the observation if Insights or this signal is toggled off. Best-effort: never
-  // blocks or fails provider shutdown.
-  private async handleSessionEnd(input: { reason?: string; transcriptPath?: string }): Promise<void> {
-    // Only Claude transcripts have this shape; Codex sessions are skipped for now.
-    if (this.options.provider !== "claude") return;
-    const transcriptPath = input.transcriptPath || this.lastTranscriptPath;
-    if (!transcriptPath) return;
-    let jsonl: string;
-    try {
-      jsonl = await readFile(transcriptPath, "utf8");
-    } catch {
-      return;
+  // A provider lifecycle hook reported a session boundary (Claude PreCompact / SessionEnd
+  // → control server). Normalize the raw provider reason to a SessionDestroyReason and run
+  // the same pre-destroy seam the bus commands use. `clear`/`compact` continue the session;
+  // anything else (logout, prompt_input_exit, other) is a real termination.
+  private async handleSessionBoundary(input: { reason?: string; transcriptPath?: string }): Promise<void> {
+    const reason = input.reason === "compact" ? "compact"
+      : input.reason === "clear" ? "clear"
+      : "shutdown";
+    await this.runPreSessionDestroy(reason, { transcriptPath: input.transcriptPath });
+  }
+
+  // The pre-session-destroy seam (#183): the single place end-of-session work runs before
+  // an invasive transition (compact/clear/restart/shutdown/kill). Best-effort and
+  // time-boxed so it never hangs teardown; concurrent calls for the same teardown coalesce
+  // (a shutdown bus command and the SessionEnd hook can both fire). During the window the
+  // agent is published non-addressable so the operator sees "wrapping up", not "busy".
+  private runPreSessionDestroy(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    if (this.preDestroyPromise) return this.preDestroyPromise;
+    const run = (async () => {
+      this.publishFinalizing(reason);
+      try {
+        await Promise.race([
+          this.captureContextRatio(reason, opts),
+          new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
+        ]);
+      } catch (error) {
+        this.sessionLog(`insights: pre-destroy capture failed: ${errMessage(error)}`);
+      }
+    })();
+    this.preDestroyPromise = run;
+    void run.finally(() => { this.preDestroyPromise = undefined; });
+    return run;
+  }
+
+  // Publish the transient pre-destroy state: a non-offline status with ready:false (so the
+  // agent drops out of isAgentOnline fan-out targeting without going "offline") plus a
+  // finalizing-<reason> lifecycleAction the dashboard renders as "wrapping up" with the
+  // composer disabled.
+  private publishFinalizing(reason: SessionDestroyReason): void {
+    this.lifecycleAction = `finalizing-${reason}`;
+    void this.bus.statusAsync({ agentStatus: "busy", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } });
+  }
+
+  // Compute the #184 context-gathering ratio for the segment since the last boundary and
+  // queue it (durable outbox, #196). Provider-agnostic: the adapter normalizes its session
+  // into the shared SessionEvent stream; the math + classifier live in session-insights.ts.
+  // Per-segment via a runner-side cursor, so each datapoint is one work chunk between
+  // context resets. Mechanical, model-free → zero agent tokens, un-gameable.
+  private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.options.adapter;
+    if (!adapter.collectSessionEvents || !this.process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.lastTranscriptPath;
+    const events = await adapter.collectSessionEvents(this.process, { transcriptPath });
+    if (!events) return;
+    // Reset the cursor when the underlying log changed identity (transcript rotated on
+    // resume) or shrank (Codex buffer trimmed) — otherwise the slice would be wrong.
+    const key = transcriptPath ?? `session:${this.providerSessionId}`;
+    if (key !== this.insightsCursorKey || events.length < this.insightsObserved) {
+      this.insightsCursorKey = key;
+      this.insightsObserved = 0;
     }
-    const analysis = analyzeSession(jsonl);
-    if (!analysis) return; // no tool calls = nothing substantive to measure
-    // Durable + non-blocking (#196): queue it. SessionEnd can race provider shutdown, so a
-    // direct POST risked being dropped if the server hiccuped; the outbox survives that.
+    const segment = events.slice(this.insightsObserved);
+    this.insightsObserved = events.length;
+    const analysis = computeContextRatio(segment);
+    if (!analysis) return; // no tool calls this segment = nothing substantive to measure
     this.outbox.enqueue({
       kind: "insight",
       payload: {
@@ -1137,12 +1323,12 @@ export class AgentRunner {
         project: this.options.cwd,
         agentId: this.agentId,
         signal: "context_ratio",
-        value: { ...analysis.metric, ...(input.reason ? { endReason: input.reason } : {}) },
+        value: { ...analysis.metric, endReason: reason },
         outcome: { ...analysis.outcome },
         source: "server",
       },
     });
-    this.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering) queued`);
+    this.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering, ${reason}) queued`);
   }
 
   // Route a provider-emitted session event (Codex app-server) into the chat mirror.
@@ -1607,6 +1793,10 @@ export class AgentRunner {
     this.options.tokenExpiresAt = this.currentTokenExpiresAt;
     this.http.setToken(token);
     this.bus.setToken(token);
+    // The proxy reads the token live via getToken(), so forwarding already uses the new one.
+    // A re-mint can change scope (e.g. a profile change), so refresh the relay tool list and
+    // emit tools/list_changed if the visible set changed (#215 — token-scope transition).
+    void this.proxy?.refreshTools().catch(() => {});
     this.httpLivenessAuthFailed = false;
     this.reactiveTokenRecoveryAt = undefined;
     // An earlier auth failure may have stopped the liveness loop; restart it so the

package/src/session-insights.ts

@@ -0,0 +1,118 @@
+// Provider-agnostic core for the #184 context-gathering signal (epic #183).
+//
+// The transcript *format* is provider-specific (Claude JSONL, Codex app-server items,
+// future providers), so each adapter normalizes its session into the same `SessionEvent`
+// stream via `collectSessionEvents`. Everything downstream — the gathering/action
+// classifier and the ratio math — lives here once and is shared, so a tool reclassified
+// for one provider is reclassified for all, and a new provider only implements the
+// normalization.
+//
+// The classifier is model-free and runs in the runner, so it costs zero agent tokens and
+// the agent can't game it.
+
+// A normalized, ordered session event. Order is significant: `leadingGather` counts the
+// run of gathering tools before the first action.
+export type SessionEvent =
+  // A tool invocation. Gathering-vs-action is decided here by `isGatheringTool(name)`.
+  | { type: "tool"; name: string }
+  // A failed tool result (paired outcome proxy — failures/workarounds the agent hit).
+  | { type: "tool_error" }
+  // A real user prompt (paired outcome proxy — more back-and-forth ~ clarification/correction).
+  | { type: "user_prompt" }
+  // A substantive assistant turn (one that produced text or a tool call).
+  | { type: "turn" };
+
+// Tools that acquire context without changing anything. Anything not matched here is
+// treated as an action (mutation, execution, or a delegation/direction decision) — Bash
+// counts as an action because it executes (a conservative, documented choice for v0;
+// `cat`/`ls` via Bash are misclassified, refine later if the data warrants it).
+const GATHERING_TOOLS = new Set([
+  "Read", "Grep", "Glob", "LS", "NotebookRead", "WebFetch", "WebSearch",
+]);
+const GATHERING_NAME = /(?:^|[._-])(read|get|list|search|grep|glob|find|fetch|query|browse|view|show|cat|status|inspect|lookup|symbols|snippet)/i;
+
+export function isGatheringTool(name: string): boolean {
+  if (GATHERING_TOOLS.has(name)) return true;
+  // MCP / custom tools: classify by name shape (e.g. mcp__callmux__searxng_web_search).
+  return GATHERING_NAME.test(name);
+}
+
+export interface ContextRatioMetric {
+  /** Session-wide gathering fraction: gatheringCalls / totalToolCalls. The headline metric. */
+  ratio: number;
+  gatheringCalls: number;
+  actionCalls: number;
+  totalToolCalls: number;
+  /** Consecutive gathering calls before the first action — the "read N files before moving" signal. */
+  leadingGather: number;
+  /** Substantive assistant turns (turns that produced text or a tool call). */
+  turns: number;
+}
+
+export interface SessionOutcomeProxy {
+  /** Real user prompts in the session — more back-and-forth ~ more clarification/correction. */
+  userPrompts: number;
+  /** tool_result blocks flagged is_error — failures/workarounds the agent hit. */
+  toolErrors: number;
+}
+
+export interface SessionAnalysis {
+  metric: ContextRatioMetric;
+  outcome: SessionOutcomeProxy;
+}
+
+/**
+ * Reduce a normalized event stream to the context-gathering ratio plus paired outcome
+ * proxies. Returns null when there's nothing substantive to measure (no tool calls) —
+ * trivial segments have nothing to learn from and shouldn't pollute the baselines.
+ *
+ * Per-segment by construction: callers pass only the events since the last capture
+ * boundary (compact/clear/restart/shutdown), so each result describes one work chunk.
+ */
+export function computeContextRatio(events: SessionEvent[]): SessionAnalysis | null {
+  let gatheringCalls = 0;
+  let actionCalls = 0;
+  let leadingGather = 0;
+  let sawAction = false;
+  let userPrompts = 0;
+  let toolErrors = 0;
+  let turns = 0;
+
+  for (const event of events) {
+    switch (event.type) {
+      case "user_prompt":
+        userPrompts++;
+        break;
+      case "tool_error":
+        toolErrors++;
+        break;
+      case "turn":
+        turns++;
+        break;
+      case "tool":
+        if (isGatheringTool(event.name)) {
+          gatheringCalls++;
+          if (!sawAction) leadingGather++;
+        } else {
+          actionCalls++;
+          sawAction = true;
+        }
+        break;
+    }
+  }
+
+  const totalToolCalls = gatheringCalls + actionCalls;
+  if (totalToolCalls === 0) return null;
+
+  return {
+    metric: {
+      ratio: gatheringCalls / totalToolCalls,
+      gatheringCalls,
+      actionCalls,
+      totalToolCalls,
+      leadingGather,
+      turns,
+    },
+    outcome: { userPrompts, toolErrors },
+  };
+}