@workos/quickstudy 0.0.1

package/src/store/db.ts

@@ -0,0 +1,318 @@
+/**
+ * bun:sqlite results store for the eval × experiment schema (v3, THE schema —
+ * the legacy five-axis store was deleted with the authoring stack).
+ * Concurrency contract: single writer, WAL so readers never block on the
+ * writer.
+ *
+ * Schema versioning is enforced by refusal: a database whose tables exist at
+ * any other user_version is refused with archive/export instructions, never
+ * migrated.
+ */
+
+import { Database } from "bun:sqlite";
+import type { EvalResult, EvalSuite } from "../evals/types.ts";
+import type { ComparisonGroup } from "../experiments/groups.ts";
+import type { RunManifest } from "../manifest.ts";
+import type { SurfaceUsage, SurfaceUsageConfig } from "../surface-usage.ts";
+import { SCHEMA_SQL } from "./schema.ts";
+
+export type AttemptStatus = "completed" | "incomplete" | "error";
+
+/** The run-level configuration recorded in `runs.config_json`. */
+export interface RunConfig {
+  scheduler?: { concurrency: number; seed: string; policy: "seeded-hash-v1"; order: import("../plan.ts").AttemptPlan[] };
+  trials: number;
+  evalIds: string[];
+  experimentIds: string[];
+  evalsRoot?: string;
+  experimentsRoot?: string;
+  /** Egress policy the run enforced — what it could reach is part of its record. */
+  egress?: { proxy: boolean; allowlist: string[] };
+  /**
+   * The comparison groups computed at run time (withhold-and-diff state
+   * included). Recorded here — NOT in the manifest — so reading them back
+   * never perturbs run identity; the report and the Compare view render
+   * exactly what the run saw.
+   */
+  groups?: ComparisonGroup[];
+  /**
+   * Offered surfaces per experiment id (docs hosts, CLI commands, MCP server
+   * names), recorded at run time like `egress` — what a run offered is part
+   * of its record. Absent on older runs and when nothing was declared
+   * (absent ≠ empty-offered).
+   */
+  surfaces?: Record<string, SurfaceUsageConfig>;
+}
+
+export interface RunRecord {
+  id: string;
+  /** Epoch milliseconds. */
+  startedAt: number;
+  /** NULL means the run is incomplete; reporting warns loudly. */
+  finishedAt: number | null;
+  config: RunConfig;
+  manifest: RunManifest;
+  manifestHash: string;
+}
+
+/** Everything the runner persists for one attempt. */
+export interface NewAttempt {
+  /** Explicit retry of a non-completed trial; original evidence is retained. */
+  retryOf?: string | null;
+  judgeRecords?: import("../evals/types.ts").JudgeRecord[];
+  id: string;
+  runId: string;
+  evalId: string;
+  experimentId: string;
+  suite: EvalSuite;
+  trialIndex: number;
+  attemptIdentityHash: string;
+  status: AttemptStatus;
+  result?: EvalResult | null;
+  /** Omitted or null = no supported raw stream — stored as NULL, never as an all-zero object. */
+  surfaceUsage?: SurfaceUsage | null;
+  transcriptRef?: string | null;
+  diffRef?: string | null;
+  /** Omitted or null = telemetry unavailable — stored as NULL, never as 0. */
+  costUsd?: number | null;
+  tokensIn?: number | null;
+  tokensOut?: number | null;
+  /** Agent steps (adapter-counted); omitted or null = no parseable stream. */
+  turns?: number | null;
+  startedAt?: number | null;
+  finishedAt?: number | null;
+  error?: string | null;
+}
+
+export interface AttemptRecord {
+  retryOf?: string | null;
+  judgeRecords?: import("../evals/types.ts").JudgeRecord[];
+  id: string;
+  runId: string;
+  evalId: string;
+  experimentId: string;
+  suite: EvalSuite;
+  trialIndex: number;
+  attemptIdentityHash: string;
+  status: AttemptStatus;
+  result: EvalResult | null;
+  surfaceUsage: SurfaceUsage | null;
+  transcriptRef: string | null;
+  diffRef: string | null;
+  costUsd: number | null;
+  tokensIn: number | null;
+  tokensOut: number | null;
+  turns: number | null;
+  startedAt: number | null;
+  finishedAt: number | null;
+  error: string | null;
+}
+
+interface RunRow {
+  id: string;
+  started_at: number;
+  finished_at: number | null;
+  config_json: string;
+  manifest_json: string;
+  manifest_hash: string;
+}
+
+interface AttemptRow {
+  retry_of: string | null;
+  judge_usage_json: string | null;
+  id: string;
+  run_id: string;
+  eval_id: string;
+  experiment_id: string;
+  suite: string;
+  trial_index: number;
+  attempt_identity_hash: string;
+  status: string;
+  result_json: string | null;
+  surface_usage_json: string | null;
+  transcript_ref: string | null;
+  diff_ref: string | null;
+  cost_usd: number | null;
+  tokens_in: number | null;
+  tokens_out: number | null;
+  turns: number | null;
+  started_at: number | null;
+  finished_at: number | null;
+  error: string | null;
+}
+
+function toRunRecord(row: RunRow): RunRecord {
+  return {
+    id: row.id,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    config: JSON.parse(row.config_json) as RunConfig,
+    manifest: JSON.parse(row.manifest_json) as RunManifest,
+    manifestHash: row.manifest_hash,
+  };
+}
+
+function toAttemptRecord(row: AttemptRow): AttemptRecord {
+  return {
+    id: row.id,
+    ...(row.judge_usage_json ? { judgeRecords: JSON.parse(row.judge_usage_json) } : {}),
+    ...(row.retry_of ? { retryOf: row.retry_of } : {}),
+    runId: row.run_id,
+    evalId: row.eval_id,
+    experimentId: row.experiment_id,
+    suite: row.suite as EvalSuite,
+    trialIndex: row.trial_index,
+    attemptIdentityHash: row.attempt_identity_hash,
+    status: row.status as AttemptStatus,
+    result: row.result_json === null ? null : (JSON.parse(row.result_json) as EvalResult),
+    surfaceUsage: row.surface_usage_json === null ? null : (JSON.parse(row.surface_usage_json) as SurfaceUsage),
+    transcriptRef: row.transcript_ref,
+    diffRef: row.diff_ref,
+    costUsd: row.cost_usd,
+    tokensIn: row.tokens_in,
+    tokensOut: row.tokens_out,
+    turns: row.turns,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    error: row.error,
+  };
+}
+
+/** Read a database file's schema version without creating or migrating it. */
+export function storeSchemaVersion(path: string): number | null {
+  try {
+    const db = new Database(path, { readonly: true });
+    try {
+      return db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version ?? 0;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
+export class ResultsStore {
+  private readonly db: Database;
+
+  constructor(path: string) {
+    this.db = new Database(path, { create: true });
+    const existing = this.db
+      .query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type='table' AND name IN ('runs', 'attempts')")
+      .all();
+    const version = this.db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version ?? 0;
+    if (existing.length > 0 && version !== 3) {
+      this.db.close();
+      throw new Error(
+        `results database at ${path} uses schema v${version || "legacy"}; this command requires schema v3.\n` +
+          `Old results are never migrated. Either archive the database and keep your previous quickstudy\n` +
+          `binary to read it, or run \`quickstudy export\` with that binary first — then point --db at a\n` +
+          `fresh file for v3 runs.`,
+      );
+    }
+    this.db.exec("PRAGMA journal_mode = WAL;");
+    this.db.exec("PRAGMA foreign_keys = ON;");
+    this.db.exec(SCHEMA_SQL);
+    // Additive column repair within v3: `turns` joined the schema after v3
+    // shipped. Adding a nullable column rewrites nothing — existing rows read
+    // NULL, the standard "telemetry unavailable" value — so this is not the
+    // cross-version migration the refusal above exists to prevent.
+    const attemptColumns = this.db
+      .query<{ name: string }, []>("SELECT name FROM pragma_table_info('attempts')")
+      .all()
+      .map((column) => column.name);
+    if (!attemptColumns.includes("turns")) {
+      this.db.exec("ALTER TABLE attempts ADD COLUMN turns INTEGER;");
+    }
+    if (!attemptColumns.includes("judge_usage_json")) this.db.exec("ALTER TABLE attempts ADD COLUMN judge_usage_json TEXT;");
+    if (!attemptColumns.includes("retry_of")) this.db.exec("ALTER TABLE attempts ADD COLUMN retry_of TEXT;");
+    this.db.exec("PRAGMA user_version = 3;");
+  }
+
+  insertRun(run: { id: string; startedAt: number; config: RunConfig; manifest: RunManifest }): void {
+    this.db
+      .query("INSERT INTO runs (id, started_at, finished_at, config_json, manifest_json, manifest_hash) VALUES (?, ?, NULL, ?, ?, ?)")
+      .run(run.id, run.startedAt, JSON.stringify(run.config), JSON.stringify(run.manifest), run.manifest.hash);
+  }
+
+  reopenRun(id: string): void { this.db.query("UPDATE runs SET finished_at = NULL WHERE id = ?").run(id); }
+
+  finishRun(id: string, finishedAt: number): void {
+    const changed = this.db.query("UPDATE runs SET finished_at = ? WHERE id = ?").run(finishedAt, id);
+    if (changed.changes === 0) throw new Error(`cannot finish run "${id}": no such run`);
+  }
+
+  getRun(id: string): RunRecord | null {
+    const row = this.db.query<RunRow, [string]>("SELECT * FROM runs WHERE id = ?").get(id);
+    return row ? toRunRecord(row) : null;
+  }
+
+  /** All runs, newest first. */
+  listRuns(): RunRecord[] {
+    return this.db.query<RunRow, []>("SELECT * FROM runs ORDER BY started_at DESC, id DESC").all().map(toRunRecord);
+  }
+
+  /** Most recent run, or null on an empty database (`report --latest`). */
+  latestRun(): RunRecord | null {
+    const row = this.db.query<RunRow, []>("SELECT * FROM runs ORDER BY started_at DESC, id DESC LIMIT 1").get();
+    return row ? toRunRecord(row) : null;
+  }
+
+  insertAttempt(attempt: NewAttempt): void {
+    this.db
+      .query(
+        `INSERT INTO attempts (
+           id, run_id, eval_id, experiment_id, suite, trial_index, attempt_identity_hash, status,
+           result_json, surface_usage_json, transcript_ref, diff_ref, cost_usd, tokens_in, tokens_out,
+           turns, started_at, finished_at, error, retry_of, judge_usage_json
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        attempt.id,
+        attempt.runId,
+        attempt.evalId,
+        attempt.experimentId,
+        attempt.suite,
+        attempt.trialIndex,
+        attempt.attemptIdentityHash,
+        attempt.status,
+        attempt.result === undefined || attempt.result === null ? null : JSON.stringify(attempt.result),
+        attempt.surfaceUsage === undefined || attempt.surfaceUsage === null ? null : JSON.stringify(attempt.surfaceUsage),
+        attempt.transcriptRef ?? null,
+        attempt.diffRef ?? null,
+        attempt.costUsd ?? null,
+        attempt.tokensIn ?? null,
+        attempt.tokensOut ?? null,
+        attempt.turns ?? null,
+        attempt.startedAt ?? null,
+        attempt.finishedAt ?? null,
+        attempt.error ?? null,
+        attempt.retryOf ?? null,
+        attempt.judgeRecords ? JSON.stringify(attempt.judgeRecords) : null,
+      );
+  }
+
+  listAttempts(runId: string): AttemptRecord[] {
+    return this.db
+      .query<AttemptRow, [string]>("SELECT * FROM attempts WHERE run_id = ? ORDER BY id")
+      .all(runId)
+      .map(toAttemptRecord);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+/** Only explicit, valid retry links supersede a row. Accidental duplicates remain visible. */
+export function activeAttempts(attempts: AttemptRecord[]): AttemptRecord[] {
+  const superseded = new Set<string>();
+  for (const row of attempts) if (row.retryOf) {
+    const previous = attempts.find((a) => a.id === row.retryOf);
+    if (!previous || previous.status === "completed" || previous.runId !== row.runId || previous.evalId !== row.evalId || previous.experimentId !== row.experimentId || previous.trialIndex !== row.trialIndex || previous.attemptIdentityHash !== row.attemptIdentityHash || superseded.has(previous.id)) {
+      throw new Error(`invalid retry lineage for attempt ${row.id}`);
+    }
+    superseded.add(previous.id);
+  }
+  return attempts.filter((a) => !superseded.has(a.id));
+}

package/src/store/schema.ts

@@ -0,0 +1,39 @@
+/**
+ * The results-store schema (v3: eval × experiment), as code.
+ *
+ * Inlined here (rather than read from a `schema.sql` file at runtime) so the
+ * compiled single-file binary carries it in its bundle — a `readFileSync`
+ * against `import.meta.dir` resolves to a path that does not exist inside the
+ * binary's `$bunfs` virtual filesystem. It's small and changes rarely, so a
+ * TypeScript string is the simplest portable home for it.
+ */
+export const SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS runs (
+  id TEXT PRIMARY KEY,            -- ulid
+  started_at INTEGER NOT NULL,    -- epoch milliseconds
+  finished_at INTEGER,            -- NULL = run incomplete; reporting warns loudly
+  config_json TEXT NOT NULL,      -- selectors, trials, roots, comparison groups
+  manifest_json TEXT NOT NULL,
+  manifest_hash TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS attempts (
+  id TEXT PRIMARY KEY,            -- ulid
+  run_id TEXT NOT NULL REFERENCES runs(id),
+  eval_id TEXT NOT NULL,
+  experiment_id TEXT NOT NULL,
+  suite TEXT NOT NULL DEFAULT 'benchmark',
+  trial_index INTEGER NOT NULL,
+  attempt_identity_hash TEXT NOT NULL,
+  status TEXT NOT NULL,           -- 'completed' | 'incomplete' | 'error'
+  result_json TEXT,               -- the scorer's EvalResult (completed attempts)
+  surface_usage_json TEXT,        -- NULL = telemetry unavailable (never zero-filled)
+  transcript_ref TEXT, diff_ref TEXT,
+  cost_usd REAL,                  -- NULL = telemetry unavailable (never zero-filled)
+  tokens_in INTEGER, tokens_out INTEGER,
+  turns INTEGER,                  -- agent steps; NULL = no adapter stream (scripted commands)
+  started_at INTEGER, finished_at INTEGER,
+  error TEXT                      -- only when status = 'error'
+);
+
+CREATE INDEX IF NOT EXISTS idx_attempts_run_pair ON attempts(run_id, eval_id, experiment_id);
+`;

package/src/surface-usage.ts

@@ -0,0 +1,297 @@
+/**
+ * Observable use of the developer surfaces offered to an attempt.
+ *
+ * Availability is recorded in the experiment manifest; this module answers a
+ * different question: did the agent actually call an MCP tool, invoke the
+ * product CLI, or open a product documentation URL? Extraction is deliberately
+ * conservative and stores only redacted identifiers. Full shell commands and
+ * URL query strings can contain credentials and must remain in the protected
+ * raw transcript, never in aggregate telemetry.
+ */
+
+import { parseJsonlLines } from "./adapters/parse.ts";
+
+export type SurfaceUsageVendor = "claude" | "codex" | "cursor" | "gemini";
+
+export interface SurfaceUsage {
+  docs: { count: number; urls: string[] };
+  mcp: { count: number; tools: string[] };
+  cli: { count: number; commands: string[] };
+}
+
+export interface SurfaceUsageConfig {
+  /** Exact host or parent domain; subdomains also match. */
+  docsHosts?: readonly string[];
+  /** Product CLI executable names, without arguments. */
+  cliCommands?: readonly string[];
+  /** MCP server names as configured for the attempt. */
+  mcpServers?: readonly string[];
+}
+
+interface ToolInvocation {
+  id?: string;
+  name: string;
+  input: unknown;
+  kind?: "command" | "mcp" | "web";
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function pushUnique(signal: { count: number }, values: string[], value: string): void {
+  signal.count += 1;
+  if (!values.includes(value)) values.push(value);
+}
+
+function claudeInvocations(event: Record<string, unknown>): ToolInvocation[] {
+  if (event["type"] !== "assistant") return [];
+  const message = record(event["message"]);
+  const content = Array.isArray(message["content"]) ? message["content"] : [];
+  return content.flatMap((part): ToolInvocation[] => {
+    const item = record(part);
+    if (item["type"] !== "tool_use" || typeof item["name"] !== "string") return [];
+    return [{
+      ...(typeof item["id"] === "string" ? { id: item["id"] } : {}),
+      name: item["name"],
+      input: item["input"],
+    }];
+  });
+}
+
+function codexInvocations(event: Record<string, unknown>): ToolInvocation[] {
+  if (event["type"] !== "item.started" && event["type"] !== "item.completed") return [];
+  const item = record(event["item"]);
+  const identity = typeof item["id"] === "string" ? { id: item["id"] } : {};
+  const type = item["type"];
+  if (type === "command_execution" && typeof item["command"] === "string") {
+    return [{ ...identity, name: "command_execution", input: item["command"], kind: "command" }];
+  }
+  if (type === "mcp_tool_call") {
+    const server = typeof item["server"] === "string" ? item["server"] : "";
+    const tool = typeof item["tool"] === "string" ? item["tool"] : typeof item["name"] === "string" ? item["name"] : "tool";
+    return [{ ...identity, name: server === "" ? tool : `${server}__${tool}`, input: item["arguments"] ?? item["input"], kind: "mcp" }];
+  }
+  if (type === "web_search") {
+    return [{ ...identity, name: "web_search", input: item, kind: "web" }];
+  }
+  return [];
+}
+
+function cursorInvocations(event: Record<string, unknown>): ToolInvocation[] {
+  if (event["type"] !== "tool_call") return [];
+  const call = record(event["tool_call"]);
+  const entry = Object.entries(call)[0];
+  if (!entry) return [];
+  const [name, body] = entry;
+  return [{
+    ...(typeof event["call_id"] === "string" ? { id: event["call_id"] } : {}),
+    name,
+    input: record(body)["args"] ?? body,
+  }];
+}
+
+function geminiInvocations(event: Record<string, unknown>): ToolInvocation[] {
+  if (event["type"] !== "tool_use" || typeof event["tool_name"] !== "string") return [];
+  return [{
+    ...(typeof event["tool_id"] === "string" ? { id: event["tool_id"] } : {}),
+    name: event["tool_name"],
+    input: event["parameters"],
+  }];
+}
+
+function invocationsFor(vendor: SurfaceUsageVendor, event: Record<string, unknown>): ToolInvocation[] {
+  if (vendor === "claude") return claudeInvocations(event);
+  if (vendor === "codex") return codexInvocations(event);
+  if (vendor === "cursor") return cursorInvocations(event);
+  return geminiInvocations(event);
+}
+
+function allStrings(value: unknown, out: string[] = []): string[] {
+  if (typeof value === "string") {
+    out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) allStrings(item, out);
+  } else if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value as Record<string, unknown>)) allStrings(item, out);
+  }
+  return out;
+}
+
+const URL_PATTERN = /https?:\/\/[^\s"'<>)}\]]+/giu;
+
+function sanitizedDocsUrls(input: unknown, hosts: readonly string[]): string[] {
+  if (hosts.length === 0) return [];
+  const configured = hosts.map((host) => host.trim().toLowerCase().replace(/^\.+|\.+$/g, "")).filter(Boolean);
+  const urls: string[] = [];
+  for (const text of allStrings(input)) {
+    for (const raw of text.match(URL_PATTERN) ?? []) {
+      try {
+        const url = new URL(raw);
+        const host = url.hostname.toLowerCase();
+        if (!configured.some((allowed) => host === allowed || host.endsWith(`.${allowed}`))) continue;
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        const safe = url.toString();
+        if (!urls.includes(safe)) urls.push(safe);
+      } catch {
+        // A transcript fragment that merely resembles a URL is not evidence.
+      }
+    }
+  }
+  return urls;
+}
+
+function shellSegments(command: string): string[] {
+  // Unwrap the common structured-stream representation `bash -lc '<body>'`.
+  // This is intentionally not a full shell parser; it only finds the leading
+  // executable of each simple pipeline/list segment and never executes text.
+  const wrapped = /^\s*(?:\/bin\/)?(?:ba|z|da)?sh\s+-[a-z]*c\s+(['"])([\s\S]*)\1\s*$/u.exec(command);
+  const body = wrapped?.[2] ?? command;
+  return body.split(/(?:&&|\|\||[;|\n])/u).map((segment) => segment.trim().replace(/^['"(]+|['")]+$/g, ""));
+}
+
+/** Return a non-secret command label such as `product widgets`, or null. */
+function cliLabel(input: unknown, executables: readonly string[]): string | null {
+  const command = typeof input === "string" ? input : allStrings(input).join("\n");
+  for (const segment of shellSegments(command)) {
+    // Remove command prefixes without retaining their values. Environment
+    // assignments, `env`, and `sudo` commonly precede the real executable.
+    const tokens = segment.split(/\s+/u).filter(Boolean);
+    let index = 0;
+    while (tokens[index] === "sudo" || tokens[index] === "env" || /^[A-Za-z_][A-Za-z0-9_]*=.*/u.test(tokens[index] ?? "")) {
+      index += 1;
+    }
+    const invoked = (tokens[index] ?? "").replace(/^['"]|['"]$/g, "");
+    for (const executable of executables) {
+      const trimmed = executable.trim();
+      if (trimmed === "") continue;
+      const basename = invoked.split("/").at(-1);
+      if (invoked !== trimmed && basename !== trimmed) continue;
+      const rawSubcommand = tokens[index + 1]?.replace(/^['"]|['"]$/g, "");
+      const subcommand = rawSubcommand && !rawSubcommand.startsWith("-") ? rawSubcommand : undefined;
+      return subcommand ? `${trimmed} ${subcommand}` : trimmed;
+    }
+  }
+  return null;
+}
+
+function isMcpInvocation(invocation: ToolInvocation, serverNames: readonly string[]): boolean {
+  if (invocation.kind === "mcp") return true;
+  const name = invocation.name.toLowerCase();
+  if (name.startsWith("mcp__") || name.includes("mcp_tool")) return true;
+  return serverNames.some((server) => {
+    const normalized = server.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+    return normalized !== "" && (name.startsWith(`${normalized}__`) || name.includes(`__${normalized}__`));
+  });
+}
+
+function mcpLabel(name: string): string {
+  // Tool names are identifiers, but cap them so a malformed stream cannot
+  // bloat report JSON. No tool inputs are ever retained here.
+  return name.replace(/[^a-zA-Z0-9_.:/-]+/g, "_").slice(0, 160) || "mcp_tool";
+}
+
+/** The adapter names whose raw streams extraction understands; null = store NULL usage. */
+export function surfaceUsageVendor(adapter: string): SurfaceUsageVendor | null {
+  return adapter === "claude" || adapter === "codex" || adapter === "cursor" || adapter === "gemini"
+    ? adapter
+    : null;
+}
+
+/**
+ * Derive the OFFERED surface configuration from an experiment's runtime
+ * config. By convention the treatment's identity-bearing settings live at
+ * `runtime.config[treatment]`; rather than hard-coding treatment names, the
+ * derivation scans every config subtree for the well-known keys `hosts`
+ * (documentation hosts) and `commands` (product CLI executables). MCP server
+ * names come from the runner's already-resolved server map — calling
+ * `runtime.mcpServers()` here could re-trigger credential checks.
+ */
+export function surfaceUsageConfigFromRuntime(
+  config: Record<string, unknown> | undefined,
+  mcpServerNames: readonly string[],
+): SurfaceUsageConfig {
+  const docsHosts: string[] = [];
+  const cliCommands: string[] = [];
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return;
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      if ((key === "hosts" || key === "docsHosts") && Array.isArray(item)) {
+        // Wildcard entries ("*.example.com") reduce to their parent domain —
+        // the matcher already covers subdomains of a configured parent.
+        for (const host of item) if (typeof host === "string") docsHosts.push(host.replace(/^\*\./u, ""));
+      } else if ((key === "commands" || key === "cliCommands") && Array.isArray(item)) {
+        for (const command of item) if (typeof command === "string") cliCommands.push(command);
+      } else {
+        visit(item);
+      }
+    }
+  };
+  visit(config);
+  return {
+    docsHosts: [...new Set(docsHosts)],
+    cliCommands: [...new Set(cliCommands)],
+    mcpServers: [...new Set(mcpServerNames)],
+  };
+}
+
+/**
+ * Extract aggregate, redacted usage from a vendor's raw JSONL stream.
+ *
+ * A returned all-zero object means the supported stream was inspected and no
+ * configured product surface was observed. Callers must store `null`, rather
+ * than an all-zero object, when no supported raw stream was available.
+ */
+export function extractSurfaceUsage(
+  vendor: SurfaceUsageVendor,
+  raw: string,
+  config: SurfaceUsageConfig,
+): SurfaceUsage {
+  const usage: SurfaceUsage = {
+    docs: { count: 0, urls: [] },
+    mcp: { count: 0, tools: [] },
+    cli: { count: 0, commands: [] },
+  };
+  const docsHosts = config.docsHosts ?? [];
+  const cliCommands = config.cliCommands ?? [];
+  const mcpServers = config.mcpServers ?? [];
+  const seenInvocations = new Set<string>();
+
+  for (const rawEvent of parseJsonlLines(raw)) {
+    const event = record(rawEvent);
+    for (const invocation of invocationsFor(vendor, event)) {
+      if (invocation.id !== undefined) {
+        if (seenInvocations.has(invocation.id)) continue;
+        seenInvocations.add(invocation.id);
+      }
+      if (isMcpInvocation(invocation, mcpServers)) {
+        pushUnique(usage.mcp, usage.mcp.tools, mcpLabel(invocation.name));
+      }
+
+      const command = invocation.kind === "command" || /bash|shell|terminal|command/i.test(invocation.name)
+        ? cliLabel(invocation.input, cliCommands)
+        : null;
+      if (command) pushUnique(usage.cli, usage.cli.commands, command);
+
+      for (const url of sanitizedDocsUrls(invocation.input, docsHosts)) {
+        pushUnique(usage.docs, usage.docs.urls, url);
+      }
+    }
+  }
+
+  return usage;
+}
+
+/** Observe offered surfaces plus explicitly shared targets, without changing offered state. */
+export function observationConfig(offered: SurfaceUsageConfig, targets?: SurfaceUsageConfig): SurfaceUsageConfig {
+  return {
+    docsHosts: [...new Set([...(offered.docsHosts ?? []), ...(targets?.docsHosts ?? [])])].sort(),
+    cliCommands: [...new Set([...(offered.cliCommands ?? []), ...(targets?.cliCommands ?? [])])].sort(),
+    mcpServers: [...new Set([...(offered.mcpServers ?? []), ...(targets?.mcpServers ?? [])])].sort(),
+  };
+}

package/src/ui-bundle.generated.ts

@@ -0,0 +1,12 @@
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ *
+ * Holds the built UI shell (`ui/dist/index.html`, a single self-contained file
+ * with JS/CSS inlined), base64-encoded, so the compiled single-file binary can
+ * serve `quickstudy ui` / `quickstudy export` with no `ui/dist` on disk.
+ *
+ * Empty in a source checkout (where the CLI reads `ui/dist` directly).
+ * `bun run build` repopulates this for the duration of the `--compile` step,
+ * then restores this placeholder so the working tree stays clean.
+ */
+export const UI_INDEX_HTML_BASE64 = "";