@humwick/runner 0.0.0-stage → 0.130.1

package/src/runner-insights.ts

@@ -0,0 +1,105 @@
+import type { WorkspaceMetadata } from "@humwick/sdk";
+import type { ManagedProcess, ProviderAdapter } from "./adapter";
+import type { Outbox } from "./outbox";
+import type { SessionDestroyReason } from "./session-destroy";
+import { resolveProjectName } from "./config";
+import { computeContextRatio } from "./session-insights";
+import { boundContinuationArchiveSegment } from "./continuation-archive";
+
+interface RunnerInsightsDeps {
+  agentId: string;
+  cwd: string;
+  workspace?: WorkspaceMetadata;
+  getOutbox(): Outbox;
+  getProviderSessionId(): string;
+  getProcess(): ManagedProcess | undefined;
+  getAdapter(): ProviderAdapter;
+  getLastTranscriptPath(): string | undefined;
+  sessionLog(message: string): void;
+}
+
+export class RunnerInsights {
+  private insightsObserved = 0;
+  private insightsCursorKey = "";
+  private archiveObservedChars = 0;
+  private archiveCursorKey = "";
+  private projectName?: string;
+
+  constructor(private readonly deps: RunnerInsightsDeps) {}
+
+  project(): string {
+    return (this.projectName ??= resolveProjectName(this.deps.cwd, this.deps.workspace));
+  }
+
+  queueHookFatal(report: { hook: string; error: string }): void {
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "hook_fatal",
+        value: { hook: report.hook, error: report.error },
+        source: "server",
+      },
+    });
+  }
+
+  async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionArchiveSegment || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const archive = await adapter.collectSessionArchiveSegment(process, { transcriptPath });
+    if (!archive) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    if (key !== this.archiveCursorKey || archive.length < this.archiveObservedChars) {
+      this.archiveCursorKey = key;
+      this.archiveObservedChars = 0;
+    }
+    const segment = archive.slice(this.archiveObservedChars).trim();
+    this.archiveObservedChars = archive.length;
+    if (!segment) return;
+    const bounded = boundContinuationArchiveSegment(segment);
+    if (bounded.droppedBytes > 0) this.deps.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes (${reason})`);
+    this.deps.getOutbox().enqueue({
+      kind: "continuation-archive",
+      payload: {
+        agentId: this.deps.agentId,
+        segment: bounded.segment,
+      },
+    });
+    this.deps.sessionLog(`continuation archive queued (${bounded.segment.length} chars, ${reason})`);
+  }
+
+  async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionEvents || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const events = await adapter.collectSessionEvents(process, { transcriptPath });
+    if (!events) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    if (key !== this.insightsCursorKey || events.length < this.insightsObserved) {
+      this.insightsCursorKey = key;
+      this.insightsObserved = 0;
+    }
+    const segment = events.slice(this.insightsObserved);
+    this.insightsObserved = events.length;
+    const analysis = computeContextRatio(segment);
+    if (!analysis) return;
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "context_ratio",
+        value: { ...analysis.metric, endReason: reason },
+        outcome: { ...analysis.outcome },
+        source: "server",
+      },
+    });
+    this.deps.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering, ${reason}) queued`);
+  }
+}

package/src/runner-mcp-proxy.ts

@@ -0,0 +1,46 @@
+import { sharedCallmuxToolCallTimeoutMsFromEnv, type HumwickHttpClient, webSearchEnabledFromEnv, webCallLogEnabledFromEnv, errMessage, type WebToolCall, type AgentProfile } from "@humwick/sdk";
+import { RelayMcpProxy, type RelayMcpProxyOptions } from "./relay-mcp-proxy";
+import { runnerManagedRelayOnDemandTools } from "./mcp-tool-deferral";
+import { logger } from "./logger";
+import type { WebToolLogOptions } from "./web-tool-call-proxy";
+
+export function runnerMcpHiddenTools(provider: string, profile: AgentProfile | undefined): Set<string> | undefined {
+  const hidden = runnerManagedRelayOnDemandTools(provider, profile);
+  return profile?.webTools?.brave === false ? new Set([...(hidden ?? []), "web_search"]) : hidden;
+}
+
+export function startRunnerMcpProxy(options: RelayMcpProxyOptions): { proxy?: RelayMcpProxy; endpoint?: string } {
+  try {
+    const proxy = new RelayMcpProxy(options);
+    const endpoint = proxy.start().url;
+    logger.info("mcp-proxy", `runner MCP proxy listening at ${endpoint} (worktree=${options.initialContext?.isolatedWorktree ?? false})`);
+    return { proxy, endpoint };
+  } catch (error) {
+    logger.warn("mcp-proxy", `failed to start MCP proxy; agent will connect to the relay directly: ${errMessage(error)}`);
+    return {};
+  }
+}
+
+export function runnerWebToolLog(
+  enabled: boolean,
+  upstreamUrl: string,
+  identity: () => Pick<WebToolCall, "agentId" | "provider" | "model" | "effort">,
+  record: (call: WebToolCall) => Promise<Response>,
+  env: Record<string, string | undefined> = process.env,
+  search?: WebToolLogOptions["search"],
+): WebToolLogOptions | undefined {
+  if (!enabled || (!webCallLogEnabledFromEnv(env) && !webSearchEnabledFromEnv(env))) return undefined;
+  return { upstreamUrl, ...(webSearchEnabledFromEnv(env) && search ? { search } : {}), record: async row => {
+    if (!webCallLogEnabledFromEnv(env)) return;
+    const response = await record({ ...row, ...identity() });
+    const text = await response.text();
+    if (!response.ok) throw new Error(`web call observation rejected (${response.status}): ${text.slice(0, 1000)}`);
+  } };
+}
+
+/** Search includes both backend attempts; the ordinary HTTP default is too short. */
+export function runnerWebSearch(http: Pick<HumwickHttpClient, "request">, env: Record<string, string | undefined> = process.env): NonNullable<WebToolLogOptions["search"]> {
+  return (args, id, signal) => http.request("POST", "/api/mcp", {
+    jsonrpc: "2.0", id, method: "tools/call", params: { name: "web_search", arguments: args },
+  }, { timeoutMs: sharedCallmuxToolCallTimeoutMsFromEnv(env), signal });
+}

package/src/runner-spawn-config.ts

@@ -0,0 +1,68 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { harnessSubagentsEnabled } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+
+export type RunnerSpawnConfigSource = Pick<RunnerSpawnConfig,
+  | "provider" | "model" | "effort" | "contextWindowTokens" | "modelRecord"
+  | "runnerId" | "instanceId" | "relayUrl" | "cwd" | "headless" | "lifecycle"
+  | "approvalMode" | "label" | "rig" | "profile" | "harnessSubagents" | "agentProfile"
+  | "prompt" | "systemPromptAppend" | "tmuxSession" | "providerArgs" | "providerConfig"
+>;
+
+export interface RunnerSpawnRuntime {
+  getRelayToken?: () => string | undefined;
+  agentId: string;
+  env: Record<string, string>;
+  controlPort: number;
+  resumeId?: string;
+  suppressPrompt?: boolean;
+  systemPromptAppend?: string;
+  relayMcpEndpoint?: string;
+  mcpProxySecret?: string;
+  sharedMcpUrl?: string;
+  monitor?: RunnerSpawnConfig["monitor"];
+}
+
+/** Production-shared, pure construction of the exact config passed to provider adapters. */
+export function buildRunnerSpawnConfig(
+  source: RunnerSpawnConfigSource,
+  runtime: RunnerSpawnRuntime,
+): RunnerSpawnConfig {
+  const prompt = source.prompt && !runtime.resumeId && !runtime.suppressPrompt ? source.prompt : undefined;
+  const systemPromptAppend = runtime.systemPromptAppend ?? source.systemPromptAppend;
+  return {
+    provider: source.provider,
+    ...(source.model ? { model: source.model } : {}),
+    ...(source.effort ? { effort: source.effort } : {}),
+    // #2595 — positive-only gate mirrors the CLI parse; an unset/invalid value stays absent.
+    ...(typeof source.contextWindowTokens === "number" && Number.isSafeInteger(source.contextWindowTokens) && source.contextWindowTokens > 0 ? { contextWindowTokens: source.contextWindowTokens } : {}),
+    // #2599 — the record arrives pre-parsed by the shared parser at the CLI seam; thread it
+    // verbatim. The ADAPTER applies precedence (payload > manifest > undefined), not this builder.
+    ...(source.modelRecord ? { modelRecord: source.modelRecord } : {}),
+    runnerId: source.runnerId,
+    instanceId: source.instanceId,
+    agentId: runtime.agentId,
+    ...(runtime.getRelayToken ? { getRelayToken: runtime.getRelayToken } : {}),
+    relayUrl: source.relayUrl,
+    cwd: source.cwd,
+    headless: source.headless,
+    ...(source.lifecycle ? { lifecycle: source.lifecycle } : {}),
+    approvalMode: source.approvalMode,
+    ...(source.label ? { label: source.label } : {}),
+    ...(source.rig ? { rig: source.rig } : {}),
+    ...(source.profile ? { profile: source.profile } : {}),
+    harnessSubagents: harnessSubagentsEnabled(source),
+    ...(source.agentProfile ? { agentProfile: source.agentProfile } : {}),
+    ...(prompt ? { prompt } : {}),
+    ...(systemPromptAppend ? { systemPromptAppend } : {}),
+    ...(source.tmuxSession ? { tmuxSession: source.tmuxSession } : {}),
+    providerArgs: runtime.resumeId ? [...source.providerArgs, "--resume", runtime.resumeId] : [...source.providerArgs],
+    providerConfig: source.providerConfig,
+    env: writeChildEnv({}, { ...runtime.env }),
+    controlPort: runtime.controlPort,
+    ...(runtime.relayMcpEndpoint ? { relayMcpEndpoint: runtime.relayMcpEndpoint } : {}),
+    ...(runtime.mcpProxySecret ? { mcpProxySecret: runtime.mcpProxySecret } : {}),
+    ...(runtime.sharedMcpUrl ? { sharedMcpUrl: runtime.sharedMcpUrl } : {}),
+    ...(runtime.monitor ? { monitor: runtime.monitor } : {}),
+  };
+}

package/src/runner-stale-scratch-sweep.ts

@@ -0,0 +1,21 @@
+import { runnerFsOffload } from "./fs-offload";
+import { sweepStaleLaunchersAsync, sweepStaleSessionsAsync } from "./session-scratch";
+
+export async function sweepRunnerStaleScratch(input: {
+  listAgents(): Promise<Array<{ id: string }>>;
+  agentId: string;
+  cwd: string;
+  fallbackBaseDir?: string;
+  log(message: string): void;
+}): Promise<void> {
+  try {
+    const agents = await input.listAgents().catch(() => []);
+    const keep = new Set(agents.map((agent) => agent.id)); keep.add(input.agentId); const now = Date.now();
+    const [sessions, launchers] = await Promise.all([
+      runnerFsOffload().run("runner-stale-session-scratch-sweep", () => sweepStaleSessionsAsync({ cwd: input.cwd, fallbackBaseDir: input.fallbackBaseDir, keepAgentIds: keep, now, maxEntries: 100 })),
+      runnerFsOffload().run("runner-stale-launcher-sweep", () => sweepStaleLaunchersAsync({ keepAgentIds: keep, now, maxEntries: 100 })),
+    ]);
+    if (sessions.length) input.log(`swept ${sessions.length} stale session scratch dir(s)`);
+    if (launchers.length) input.log(`swept ${launchers.length} stale launcher script(s)`);
+  } catch {}
+}

package/src/runner.ts

@@ -0,0 +1,9 @@
+export { AgentRunner, type RunnerOptions } from "./runner-core";
+export {
+  latestResumeIdFromText,
+  runnerMessageMatches,
+  runnerShouldResolveProviderExit,
+  runnerShouldRestartUnexpectedProviderExit,
+  runtimeTokenRenewDelayMs,
+  runtimeTokenRenewTimerSchedule,
+} from "./runner-helpers";

package/src/runtime-token-file.ts

@@ -0,0 +1,45 @@
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { runtimeTokenExpiresAtFileFromEnv, runtimeTokenFileFromEnv } from "./config";
+
+function replaceFile(path: string, value: string): void {
+  const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, value, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+/**
+ * Publish the runner's live credential to CLI children. A provider's process
+ * environment is immutable after it starts, but each CLI invocation can read
+ * these stable paths afresh. The orchestrator creates the initial files when
+ * it materializes the session launch script (#2318).
+ */
+export function persistRuntimeTokenFiles(token: string, expiresAt?: number): void {
+  const tokenFile = runtimeTokenFileFromEnv();
+  if (tokenFile) replaceFile(tokenFile, token);
+  const expiresAtFile = runtimeTokenExpiresAtFileFromEnv();
+  if (expiresAtFile && expiresAt !== undefined) replaceFile(expiresAtFile, String(expiresAt));
+}
+
+/**
+ * Keep CLI credential publication best-effort: failure to update a provider child
+ * must never undo a successfully renewed runner transport credential.
+ */
+export function publishRuntimeTokenForCli(
+  token: string,
+  expiresAt: number | undefined,
+  reportFailure: (message: string) => void,
+): void {
+  try {
+    persistRuntimeTokenFiles(token, expiresAt);
+  } catch (error) {
+    reportFailure(`[runner] failed to publish renewed runtime token for CLI: ${String(error)}`);
+  }
+}

package/src/runtime-token-remint.ts

@@ -0,0 +1,56 @@
+import { errMessage, type HumwickHttpClient } from "@humwick/sdk";
+
+type RemintedRecord = { jti: string; profileId?: string; expiresAt?: number };
+
+/** One token rotation at a time: a renewal, an orchestrator re-mint and a boundary re-derive replace the same token. */
+export class TokenRotation {
+  private current?: Promise<unknown>;
+
+  get inFlight(): boolean {
+    return this.current !== undefined;
+  }
+
+  async run<T>(rotate: () => Promise<T>): Promise<T> {
+    const rotation = rotate();
+    this.current = rotation;
+    try {
+      return await rotation;
+    } finally {
+      if (this.current === rotation) this.current = undefined;
+    }
+  }
+
+  /** Runs `rotate` once no rotation is in flight, so it starts from the token the previous one installed. */
+  async runNext<T>(rotate: () => Promise<T>): Promise<T> {
+    while (this.current) await this.current.catch(() => {});
+    return this.run(rotate);
+  }
+}
+
+/**
+ * #1245 — re-derive the runner's token from the agent's CURRENT profile at a clear/compact boundary and
+ * report the outcome for the command result. Never throws: a failed re-mint keeps the still-valid token.
+ */
+export async function rederiveRuntimeToken(
+  http: Pick<HumwickHttpClient, "remintRuntimeToken">,
+  reason: "clear" | "compact",
+  apply: (token: string, record: RemintedRecord) => void,
+  log: (message: string) => void,
+): Promise<Record<string, unknown>> {
+  let outcome: Record<string, unknown> | undefined;
+  try {
+    // A replayed successor (an earlier response was lost) can predate the current profile, so derive once more from it.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const result = await http.remintRuntimeToken(reason);
+      if ("unchanged" in result) return outcome ?? { status: "unchanged", jti: result.jti };
+      apply(result.token, result.record);
+      log(`[runner] runtime token re-derived at ${reason} (jti ${result.previous.jti} -> ${result.record.jti}${result.replayed ? ", replayed" : ""})`);
+      outcome = { status: "rotated", jti: result.record.jti, previousJti: result.previous.jti, ...result.delta };
+      if (!result.replayed) break;
+    }
+    return outcome!;
+  } catch (error) {
+    log(`[runner] runtime token re-derive at ${reason} failed: ${errMessage(error)}`);
+    return { ...outcome, status: outcome ? "rotated" : "failed", error: errMessage(error) };
+  }
+}

package/src/service-access.ts

@@ -0,0 +1,88 @@
+import { rootCertificates } from "node:tls";
+import type { ServiceAccessHandoff } from "@humwick/sdk";
+import type { HumwickHttpClient } from "@humwick/sdk/http-client";
+import type { ProviderAdapter, RunnerSpawnConfig } from "./adapter";
+import { prepareServiceAccessConfig } from "./adapters/service-access";
+import { fireAndForget } from "./async-guard";
+import { startVaultProxyHop } from "./vault-proxy-hop";
+
+type LaunchHttp = Pick<HumwickHttpClient, "request">;
+type LaunchIdentity = { instanceId: string; launchId: string };
+
+const RENEW_RETRY_MS = 60_000;
+/** One provider launch per runner; a replacement launch closes its predecessor's hop and renewal. */
+const liveLaunches = new WeakMap<object, { close(): void }>();
+
+/** Launch only: transport reconnects must keep the child's original token. */
+export async function withServiceAccessLaunch<T>(
+  http: LaunchHttp,
+  identity: LaunchIdentity,
+  enabled: boolean,
+  launch: (handoff?: ServiceAccessHandoff) => Promise<T>,
+): Promise<T> {
+  if (!enabled) return launch();
+  try {
+    const response = await http.request("POST", "/api/service-access/exchange", identity, { timeoutMs: 30_000 });
+    if (!response.ok) throw new Error(`Vault launch exchange failed (${response.status})`);
+    const handoff = await response.json() as ServiceAccessHandoff | null;
+    return await launch(handoff ?? undefined);
+  }
+  catch (error) {
+    await http.request("POST", "/api/service-access/release", identity).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * #3577: the provider gets a loopback proxy URL and local credential for its whole life; the session
+ * token behind it renews at half its remaining lifetime (retrying each minute) until the launch ends.
+ * A 409 means the launch is no longer live, so exit cleanup owns the session from there.
+ */
+export async function startServiceAccessRenewal(http: LaunchHttp, identity: LaunchIdentity, handoff: ServiceAccessHandoff) {
+  const hop = await startVaultProxyHop(handoff.proxyUrl, handoff.vault, handoff.token, handoff.caPem ? [...rootCertificates, handoff.caPem] : undefined);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let closed = false;
+  const schedule = (delayMs: number) => {
+    if (closed) return;
+    timer = setTimeout(() => fireAndForget("vault access renewal", renew), Math.max(0, delayMs));
+    timer.unref?.();
+  };
+  const renew = async () => {
+    try {
+      const response = await http.request("POST", "/api/service-access/renew", { ...identity, tokenId: handoff.tokenId }, { timeoutMs: 30_000 });
+      if (response.status === 409) return;
+      if (!response.ok) throw new Error(`Vault access renewal failed (${response.status})`);
+      const renewed = await response.json() as { token: string; expiresAt: number };
+      if (closed) return;
+      hop.setToken(renewed.token);
+      schedule((renewed.expiresAt - Date.now()) / 2);
+    } catch (error) {
+      console.warn(`[agent-relay] ${error instanceof Error ? error.message : "Vault access renewal failed"}; retrying in ${RENEW_RETRY_MS / 1000}s`);
+      schedule(RENEW_RETRY_MS);
+    }
+  };
+  schedule((handoff.expiresAt - Date.now()) / 2);
+  return {
+    handoff: { ...handoff, proxyUrl: hop.url, token: hop.secret },
+    close() { closed = true; clearTimeout(timer); hop.close(); },
+  };
+}
+
+export function spawnWithServiceAccess(http: LaunchHttp, config: RunnerSpawnConfig, adapter: ProviderAdapter, launchId: string, managed: boolean) {
+  liveLaunches.get(http)?.close();
+  liveLaunches.delete(http);
+  const identity = { instanceId: config.instanceId, launchId };
+  return withServiceAccessLaunch(http, identity, managed, async (handoff) => {
+    const renewal = handoff ? await startServiceAccessRenewal(http, identity, handoff) : undefined;
+    try {
+      const launchConfig = prepareServiceAccessConfig({ ...config, ...(renewal ? { serviceAccess: renewal.handoff } : {}) });
+      const hydratedConfig = await adapter.hydrateSpawnConfig?.(launchConfig) ?? launchConfig;
+      const managedProcess = await adapter.spawn(hydratedConfig);
+      if (renewal) liveLaunches.set(http, renewal);
+      return { hydratedConfig, managedProcess };
+    } catch (error) {
+      renewal?.close();
+      throw error;
+    }
+  });
+}

package/src/session-destroy.ts

@@ -0,0 +1,27 @@
+export type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
+
+export type LifecycleAction =
+  | "shutting-down" | "killing" | "restarting"
+  // #1746 — a TERMINAL marker: the graceful+force-kill path ran and the provider process
+  // still could not be confirmed dead. The runner deliberately keeps the agent registered
+  // (a roster removal must imply the process is gone), so this pill replaces an indefinite
+  // "shutting-down" with an operator-visible "the kill did not take" state.
+  | "kill-failed"
+  | `finalizing-${SessionDestroyReason}`;
+
+export const PRE_DESTROY_TIMEOUT_MS = 4_000;
+
+export function reasonExitsRunner(reason: SessionDestroyReason): boolean {
+  return reason === "shutdown" || reason === "kill" || reason === "crash";
+}
+
+export 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;
+  }
+}

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__brave__brave_web_search).
+  return GATHERING_NAME.test(name);
+}
+
+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;
+}
+
+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 },
+  };
+}