@tech-leads-club/harness-toolkit 0.2.1

package/src/core/observability/observability.report.ts

@@ -0,0 +1,326 @@
+import { type Row, render, type Screen } from "../../platform/screen.ts";
+import { PLAIN, type Style } from "../../platform/style.ts";
+import type { SessionRollup } from "./observability.store.ts";
+import type { ObsEvent } from "./observability.types.ts";
+
+export type ProviderTotals = {
+  provider: string;
+  events: number;
+  signals: number;
+  denials: number;
+  gates: { pass: number; fail: number };
+  estimated_cost_usd: number;
+};
+
+function emptyTotals(provider: string): ProviderTotals {
+  return { provider, events: 0, signals: 0, denials: 0, gates: { pass: 0, fail: 0 }, estimated_cost_usd: 0 };
+}
+
+export function groupByProvider(events: ObsEvent[]): Record<string, ProviderTotals> {
+  const groups: Record<string, ProviderTotals> = {};
+  for (const event of events) {
+    const totals = groups[event.provider] ?? emptyTotals(event.provider);
+    totals.events += 1;
+    if (event.level === "signal") {
+      totals.signals += 1;
+    }
+    if (event.kind === "policy.deny") {
+      totals.denials += 1;
+    }
+    if (event.kind === "gate.outcome") {
+      if (event.attrs.passed) {
+        totals.gates.pass += 1;
+      } else {
+        totals.gates.fail += 1;
+      }
+    }
+    if (typeof event.gen_ai?.cost_usd === "number") {
+      totals.estimated_cost_usd += event.gen_ai.cost_usd;
+    }
+    groups[event.provider] = totals;
+  }
+  return groups;
+}
+
+/**
+ * why: the count alone is not actionable — "seven interruptions" names no switch. The breakdown renders only when
+ * there is something in it, so a session that was never interrupted reads exactly as it did before.
+ *
+ * invariant: this reports the decisions the harness made. It does not know the operator's answer, and it cannot
+ * know whether a question it never asked would have helped — so it is a rate and an attribution, never a
+ * precision or a recall. Naming it after a metric it cannot compute is the class of claim this project keeps
+ * removing ([/decisions/ad-026.md](/decisions/ad-026.md)).
+ */
+function interruptionsByRule(rollup: SessionRollup): string {
+  const entries = Object.entries(rollup.shell.byRule ?? {}).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) {
+    return "";
+  }
+  return entries.map(([rule, count]) => `| ↳ ${rule} | ${count} |`).join("\n");
+}
+
+/**
+ * why: the question that decides something. A rail that never fired across a session is either working perfectly
+ * or was never needed, and either way it is paying for injected prose on every turn. Naming it is what makes
+ * deletion a decision instead of a feeling ([/decisions/ad-027.md](/decisions/ad-027.md)).
+ *
+ * invariant: the active list is a parameter. Core cannot see which rails a project enabled without reading policy,
+ * and a report that guessed the list would accuse a rail that was never switched on.
+ */
+export function railsNeverFired(rollup: SessionRollup, activeRules: readonly string[]): string[] {
+  const fired = new Set(Object.keys(rollup.railsByRule ?? {}));
+  return activeRules.filter((rule) => !fired.has(rule)).sort();
+}
+
+/**
+ * hazard: one line said `injected_chars` was "the price of the rails above, paid on every turn". On a host that
+ * drops context returned from its session-start hook it is paid never, and the durable rules file — which asks to be
+ * included on every request — was absent from the rollup entirely. The number was wrong in both directions there
+ * ([/decisions/ad-050.md](/decisions/ad-050.md)).
+ *
+ * invariant: every number here was observed. The characters are counted from what the harness emitted and from the
+ * file it wrote; what the host then does with either is stated as the host's declaration, not as a measurement.
+ */
+export function costLines(rollup: SessionRollup): string[] {
+  if (rollup.injected_chars === 0 && rollup.durable_chars === 0) {
+    return [];
+  }
+  // why: its own section rather than a trailing line under the rails table, which is where it was — so a session
+  // with no active rail reported no cost while still paying one.
+  const lines = ["", "## Injected context", ""];
+  if (rollup.hook_context_reliable) {
+    lines.push(
+      `Injected at session start: ${rollup.injected_chars} characters. That is the price of the rails, paid on every turn.`,
+    );
+  } else {
+    lines.push(
+      `Emitted at session start: ${rollup.injected_chars} characters — this provider does not deliver context returned from that hook, so it is not what the model reads.`,
+    );
+  }
+  if (rollup.durable_chars > 0) {
+    lines.push(
+      `Durable lessons view: ${rollup.durable_chars} characters, written as an always-applied rules file. That is what the provider is asked to include on every request.`,
+    );
+  }
+  return lines;
+}
+
+function railActivity(rollup: SessionRollup, activeRules: readonly string[]): string {
+  const fired = Object.entries(rollup.railsByRule ?? {}).sort((a, b) => b[1] - a[1]);
+  const silent = railsNeverFired(rollup, activeRules);
+  if (fired.length === 0 && silent.length === 0) {
+    return "";
+  }
+  const rows = [
+    "",
+    "## Rails",
+    "",
+    "| Rule | Fired |",
+    "|------|-------|",
+    ...fired.map(([rule, count]) => `| ${rule} | ${count} |`),
+    ...silent.map((rule) => `| ${rule} | 0 — enabled and never fired |`),
+  ];
+  return rows.join("\n");
+}
+
+function gateDetail(rollup: SessionRollup): string {
+  const entries = Object.entries(rollup.gatesByName ?? {}).sort((a, b) => b[1].fail - a[1].fail);
+  if (entries.length === 0) {
+    return "";
+  }
+  return entries.map(([gate, s]) => `| ↳ ${gate} | ${s.pass} / ${s.fail} |`).join("\n");
+}
+
+/**
+ * why: the question an operator actually asks when a turn takes thirty minutes. The runs column is what makes the
+ * multiplication visible: the gate cost is paid once per attempt, so six runs of a four-minute suite is the answer
+ * and no amount of hook tuning would have changed it ([/decisions/ad-033.md](/decisions/ad-033.md)).
+ */
+function gateTimeSection(rollup: SessionRollup): string {
+  const entries = Object.entries(rollup.gateTime ?? {}).sort((a, b) => b[1].totalMs - a[1].totalMs);
+  if (entries.length === 0) {
+    return "";
+  }
+  const seconds = (ms: number): string => (ms / 1000).toFixed(1);
+  return [
+    "",
+    "## Gate time",
+    "",
+    "| Gate | Runs | Reused | Total s | Worst run s |",
+    "|------|------|--------|---------|-------------|",
+    ...entries.map(
+      ([gate, t]) =>
+        `| ${gate} | ${t.runs} | ${t.reused ?? 0} | ${seconds(t.totalMs)} | ${seconds(t.worstMs)} |`,
+    ),
+    "",
+    "A gate's cost is paid once per attempt, so the total is the command's own time multiplied by how many times the",
+    "agent had to retry. Lowering it means a faster command or fewer failures, not a faster harness.",
+    "",
+    "**Reused** is a stop where nothing the gate reads had changed, so the previous verdict stood and the command did",
+    "not run. Those are the runs the harness did not make you pay for.",
+  ].join("\n");
+}
+
+export function sessionReportMarkdown(rollup: SessionRollup, activeRules: readonly string[] = []): string {
+  const models = Object.entries(rollup.models)
+    .sort((a, b) => b[1] - a[1])
+    .map(([m, n]) => `| ${m} | ${n} |`)
+    .join("\n");
+  const tools = Object.entries(rollup.tools)
+    .sort((a, b) => b[1].ok + b[1].fail - (a[1].ok + a[1].fail))
+    .map(([t, s]) => `| ${t} | ${s.ok} | ${s.fail} | ${Math.round(s.ms)} |`)
+    .join("\n");
+  const subs = Object.entries(rollup.subagents)
+    .map(([t, s]) => `| ${t} | ${s.count} | ${JSON.stringify(s.models)} |`)
+    .join("\n");
+  const costLabel = rollup.cost_incomplete
+    ? `${rollup.estimated_cost_usd.toFixed(4)} (incomplete — some models lacked catalog rates)`
+    : rollup.estimated_cost_usd.toFixed(4);
+
+  return `# Harness session report
+
+**Provider:** \`${rollup.provider}\`
+**Session:** \`${rollup.session_id}\`
+**Started:** ${rollup.started_at}
+**Updated:** ${rollup.updated_at}
+
+## Cost / tokens (estimated)
+
+| Metric | Value |
+|--------|-------|
+| Estimated USD | ${costLabel} |
+| Input tokens | ${rollup.input_tokens} |
+| Output tokens | ${rollup.output_tokens} |
+| Cost alert sent | ${rollup.cost_alert_sent} |
+
+## Activity
+
+| Metric | Value |
+|--------|-------|
+| Prompts | ${rollup.prompts} |
+| Responses | ${rollup.responses} |
+| Thoughts | ${rollup.thoughts} |
+| Compactions | ${rollup.comped} |
+| Policy denials | ${rollup.denials} |
+| Gates pass/fail | ${rollup.gates.pass} / ${rollup.gates.fail} |
+${gateDetail(rollup)}
+| Shell allow/ask/deny | ${rollup.shell.allow} / ${rollup.shell.ask} / ${rollup.shell.deny} |
+${interruptionsByRule(rollup)}
+
+## Models
+
+| Model | Events |
+|-------|--------|
+${models || "| — | 0 |"}
+
+## Tools
+
+| Tool | OK | Fail | ms |
+|------|----|------|----|
+${tools || "| — | 0 | 0 | 0 |"}
+
+## Subagents
+
+| Type | Count | Models |
+|------|-------|--------|
+${subs || "| — | 0 | {} |"}
+
+## MCP tools
+
+\`\`\`json
+${JSON.stringify(rollup.mcp, null, 2)}
+\`\`\`
+${gateTimeSection(rollup)}
+${railActivity(rollup, activeRules)}
+${costLines(rollup).join("\n")}
+`;
+}
+
+// why: the markdown is an artifact — written to a file and pasted into a pull request — so it stays plain. The
+// terminal gets its own shape over the same rollup, because colouring one string for both would put escapes in
+// the file ([/decisions/ad-063.md](/decisions/ad-063.md)).
+/** The tools whose successes are recorded as shell events, so the tools table can never count them. */
+export const SHELL_TOOLS = new Set(["Bash", "run_terminal_cmd", "terminal"]);
+
+export function sessionReportScreen(rollup: SessionRollup): Screen {
+  const top = (counts: Record<string, number>, limit = 6): string[] =>
+    Object.entries(counts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([name, count]) => `${name} ${count}`);
+
+  const costLabel = rollup.cost_incomplete
+    ? `$${rollup.estimated_cost_usd.toFixed(4)} (incomplete — some models lacked catalog rates)`
+    : `$${rollup.estimated_cost_usd.toFixed(4)}`;
+
+  const shell = rollup.shell;
+  // hazard: `rollup.tools` is fed only by `tool.start|end|fail`. A successful shell call is `shell.end` and a
+  // failed one is `tool.fail`, so a shell tool's row can only ever show failures — it read `Bash: 0 ok, 23 fail`
+  // after hundreds of successful calls. The `shell` row above already answers for it, correctly
+  // ([/decisions/ad-064.md](/decisions/ad-064.md)).
+  const toolRows: Row[] = Object.entries(rollup.tools)
+    .filter(([tool]) => !SHELL_TOOLS.has(tool))
+    .sort((a, b) => b[1].ok + b[1].fail - (a[1].ok + a[1].fail))
+    .slice(0, 8)
+    .map(([tool, stats]) => ({
+      label: tool,
+      value: `${stats.ok} ok, ${stats.fail} fail`,
+      level: stats.fail > 0 ? ("warn" as const) : ("ok" as const),
+    }));
+
+  const ruleRows: Row[] = Object.entries(rollup.shell.byRule ?? {})
+    .sort((a, b) => b[1] - a[1])
+    .map(([rule, count]) => ({ label: rule, value: String(count), level: "warn" as const }));
+
+  return {
+    title: "session report",
+    summary: [`${rollup.provider}/${rollup.session_id}`, rollup.updated_at],
+    sections: [
+      {
+        title: "Cost",
+        rows: [
+          { label: "estimated", value: costLabel, level: rollup.cost_incomplete ? "warn" : "info" },
+          {
+            // why: the reading is the transcript tail's total, not the session's. Labelled for what it is, because
+            // "Input tokens" invited the reading that produced 102.7M ([/decisions/ad-064.md](/decisions/ad-064.md)).
+            label: "tokens in/out",
+            value: `${rollup.input_tokens} / ${rollup.output_tokens} (latest reading, recent transcript only)`,
+          },
+        ],
+      },
+      {
+        title: "Activity",
+        rows: [
+          { label: "prompts", value: String(rollup.prompts) },
+          {
+            label: "gates",
+            value: `${rollup.gates.pass} pass / ${rollup.gates.fail} fail`,
+            level: rollup.gates.fail > 0 ? "fail" : "ok",
+          },
+          {
+            label: "policy denials",
+            value: String(rollup.denials),
+            level: rollup.denials > 0 ? "warn" : "ok",
+          },
+          {
+            label: "shell",
+            value: `${shell.allow} allow / ${shell.ask} ask / ${shell.deny} deny`,
+            level: shell.deny > 0 ? "warn" : "ok",
+          },
+          { label: "compactions", value: String(rollup.comped) },
+        ],
+      },
+      ...(ruleRows.length > 0 ? [{ title: "Interruptions by rule", rows: ruleRows }] : []),
+      ...(toolRows.length > 0 ? [{ title: "Tools", rows: toolRows }] : []),
+      ...(Object.keys(rollup.models).length > 0
+        ? [{ title: "Models", lines: [top(rollup.models).join("  ·  ")] }]
+        : []),
+    ],
+    footer:
+      "tlc harness why for the decisions  ·  --json for the rollup  ·  the markdown copy is under state/reports",
+  };
+}
+
+export function sessionReportText(rollup: SessionRollup, style: Style = PLAIN): string {
+  return render(sessionReportScreen(rollup), style);
+}

package/src/core/observability/observability.service.ts

@@ -0,0 +1,328 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { HarnessEvent } from "../../contracts/harness-event.ts";
+import { appendAuditRecord, appendObsRecord, loadRollup, saveRollup } from "./observability.store.ts";
+import {
+  DEFAULT_OBS,
+  EVENT_KIND_TO_OBS_KIND,
+  type ObsEvent,
+  type ObservabilityConfig,
+  type ObsKind,
+  type ObsLevel,
+  redactDeep,
+  resolveObsLevel,
+} from "./observability.types.ts";
+
+export type RecordObsInput = {
+  provider: string;
+  kind: ObsKind;
+  sessionKey?: string;
+  model?: string;
+  level?: ObsLevel;
+  parentSpanId?: string;
+  attrs?: Record<string, unknown>;
+  gen_ai?: ObsEvent["gen_ai"];
+  forceDebug?: boolean;
+};
+
+function shortId(): string {
+  return randomUUID().replace(/-/g, "").slice(0, 16);
+}
+
+function deriveTraceId(sessionKey?: string): string {
+  const seed = sessionKey || randomUUID();
+  return createHash("sha256").update(seed).digest("hex").slice(0, 32);
+}
+
+function truncateAttrs(attrs: Record<string, unknown>, max: number): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    out[k] = typeof v === "string" && v.length > max ? `${v.slice(0, max)}\n…(truncated)` : v;
+  }
+  return out;
+}
+
+const PAYLOAD_KEYS = new Set(["tool_input", "tool_output", "prompt", "text", "content", "output"]);
+
+function stripPayloads(attrs: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (!PAYLOAD_KEYS.has(k)) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export function recordObs(root: string, config: ObservabilityConfig, input: RecordObsInput): ObsEvent | null {
+  if (!config.enabled) {
+    return null;
+  }
+
+  const level = input.level ?? resolveObsLevel(input.kind, input.attrs ?? {}, !!input.forceDebug);
+  if (level === "debug" && !config.debugEnabled && !input.forceDebug) {
+    return null;
+  }
+
+  let attrs = truncateAttrs(redactDeep(input.attrs ?? {}) as Record<string, unknown>, config.maxAttrChars);
+  if (!config.includePayloads) {
+    attrs = stripPayloads(attrs);
+  }
+
+  const event: ObsEvent = {
+    schema: "harness.observability.v1",
+    provider: input.provider,
+    kind: input.kind,
+    level,
+    ts: new Date().toISOString(),
+    trace_id: deriveTraceId(input.sessionKey),
+    span_id: shortId(),
+    parent_span_id: input.parentSpanId,
+    session_id: input.sessionKey,
+    model: input.model,
+    attrs,
+    gen_ai: input.gen_ai,
+  };
+
+  const file = level === "signal" ? config.signalPath : config.debugPath;
+  if (!appendObsRecord(root, file, event, config.globalSpool)) {
+    return null;
+  }
+
+  if (input.sessionKey) {
+    updateRollup(root, config, event);
+  }
+
+  return event;
+}
+
+function updateRollup(root: string, config: ObservabilityConfig, event: ObsEvent): void {
+  const sessionKey = event.session_id;
+  if (!sessionKey) {
+    return;
+  }
+  const rollup = loadRollup(root, sessionKey, event.provider);
+
+  if (event.model) {
+    rollup.models[event.model] = (rollup.models[event.model] ?? 0) + 1;
+  }
+
+  if (event.kind === "tool.start" || event.kind === "tool.end" || event.kind === "tool.fail") {
+    const name = String(event.attrs.tool_name ?? "unknown");
+    const slot = rollup.tools[name] ?? { ok: 0, fail: 0, ms: 0 };
+    if (event.kind === "tool.end") {
+      slot.ok += 1;
+      slot.ms += Number(event.attrs.duration_ms ?? event.gen_ai?.duration_ms ?? 0);
+    }
+    if (event.kind === "tool.fail") {
+      slot.fail += 1;
+    }
+    rollup.tools[name] = slot;
+  }
+
+  if (event.kind === "subagent.start") {
+    const type = String(event.attrs.subagent_type ?? "unknown");
+    const slot = rollup.subagents[type] ?? { count: 0, models: {} };
+    slot.count += 1;
+    const m = String(event.attrs.subagent_model ?? event.model ?? "unset");
+    slot.models[m] = (slot.models[m] ?? 0) + 1;
+    rollup.subagents[type] = slot;
+  }
+
+  if (event.kind === "gate.outcome") {
+    const passed = Boolean(event.attrs.passed);
+    if (passed) {
+      rollup.gates.pass += 1;
+    } else {
+      rollup.gates.fail += 1;
+    }
+    // hazard: a rollup written by an older build has neither map, and incrementing into `undefined` would throw
+    // on the path that must never break a turn.
+    const name = String(event.attrs.gate ?? "unknown");
+    const byName = rollup.gatesByName ?? {};
+    const slot = byName[name] ?? { pass: 0, fail: 0 };
+    if (passed) {
+      slot.pass += 1;
+    } else {
+      slot.fail += 1;
+    }
+    byName[name] = slot;
+    rollup.gatesByName = byName;
+
+    const ms = Number(event.attrs.duration_ms ?? 0);
+    const timing = rollup.gateTime ?? {};
+    const cell = timing[name] ?? { runs: 0, totalMs: 0, worstMs: 0, reused: 0 };
+    // invariant: a reused verdict is counted apart and adds no time. Counting it as a run would divide the total
+    // by a larger number and make the command look faster than it is ([/decisions/ad-045.md](/decisions/ad-045.md)).
+    if (event.attrs.reused === true) {
+      cell.reused = (cell.reused ?? 0) + 1;
+    } else {
+      cell.runs += 1;
+      cell.totalMs += ms;
+      cell.worstMs = Math.max(cell.worstMs, ms);
+    }
+    timing[name] = cell;
+    rollup.gateTime = timing;
+  }
+  if (event.kind === "policy.deny") {
+    rollup.denials += 1;
+  }
+  if (event.kind === "session.start" && typeof event.attrs.injected_chars === "number") {
+    rollup.injected_chars = event.attrs.injected_chars;
+  }
+  if (event.kind === "session.start" && typeof event.attrs.durable_chars === "number") {
+    rollup.durable_chars = event.attrs.durable_chars;
+  }
+  if (event.kind === "session.start" && typeof event.attrs.hook_context_reliable === "boolean") {
+    rollup.hook_context_reliable = event.attrs.hook_context_reliable;
+  }
+  // invariant: one place counts refusals by rule, whichever rail produced them. Two counters for one fact is how
+  // they come to disagree.
+  if (event.kind === "policy.deny" || event.kind === "shell.start" || event.kind === "shell.end") {
+    const permission = String(event.attrs.permission ?? "");
+    if (permission === "ask" || permission === "deny") {
+      const rule = String(event.attrs.rule ?? "none");
+      const byRule = rollup.railsByRule ?? {};
+      byRule[rule] = (byRule[rule] ?? 0) + 1;
+      rollup.railsByRule = byRule;
+    }
+  }
+  if (event.kind === "prompt.submit") {
+    rollup.prompts += 1;
+  }
+  if (event.kind === "agent.response") {
+    rollup.responses += 1;
+  }
+  if (event.kind === "agent.thought") {
+    rollup.thoughts += 1;
+  }
+  if (event.kind === "compact") {
+    rollup.comped += 1;
+  }
+
+  if (event.kind === "shell.end" || event.kind === "shell.start") {
+    const perm = String(event.attrs.permission ?? "");
+    if (perm === "ask") {
+      rollup.shell.ask += 1;
+    } else if (perm === "deny") {
+      rollup.shell.deny += 1;
+    } else if (event.kind === "shell.end") {
+      rollup.shell.allow += 1;
+    }
+    // hazard: a rollup written by an older build has no `byRule`, and incrementing into `undefined` would throw
+    // inside the one path that must never break a turn.
+    if (perm === "ask" || perm === "deny") {
+      const rule = String(event.attrs.rule ?? "none");
+      const byRule = rollup.shell.byRule ?? {};
+      byRule[rule] = (byRule[rule] ?? 0) + 1;
+      rollup.shell.byRule = byRule;
+    }
+  }
+
+  if (event.kind === "mcp.end" || event.kind === "mcp.start") {
+    const tool = String(event.attrs.tool_name ?? "unknown");
+    rollup.mcp[tool] = (rollup.mcp[tool] ?? 0) + 1;
+  }
+
+  /**
+   * hazard: this added each reading to a running total, and the reading is not a delta. The transcript reader sums
+   * the tail of the transcript, so every value is a snapshot of a sliding window, and it is attached to every tool
+   * event. Summing 3,488 snapshots reported 102.7M output tokens against 559k input — a number nobody can act on
+   * ([/decisions/ad-064.md](/decisions/ad-064.md)).
+   *
+   * invariant: the latest reading replaces the previous one. A snapshot is assigned, never accumulated.
+   */
+  const inTok = event.gen_ai?.input_tokens ?? 0;
+  const outTok = event.gen_ai?.output_tokens ?? 0;
+  if (inTok || outTok) {
+    rollup.input_tokens = inTok;
+    rollup.output_tokens = outTok;
+    const cost = event.gen_ai?.cost_usd;
+    if (typeof cost === "number") {
+      rollup.estimated_cost_usd = cost;
+    } else if (event.gen_ai?.cost_source === "missing") {
+      rollup.cost_incomplete = true;
+    }
+  }
+
+  if (
+    config.sessionCostAlertUsd != null &&
+    !rollup.cost_alert_sent &&
+    rollup.estimated_cost_usd >= config.sessionCostAlertUsd
+  ) {
+    rollup.cost_alert_sent = true;
+    saveRollup(root, rollup);
+    recordObs(root, config, {
+      provider: event.provider,
+      kind: "cost.session_alert",
+      sessionKey,
+      attrs: {
+        session_cost_usd: rollup.estimated_cost_usd,
+        threshold_usd: config.sessionCostAlertUsd,
+        cost_incomplete: rollup.cost_incomplete,
+      },
+    });
+    return;
+  }
+
+  saveRollup(root, rollup);
+}
+
+export function recordAudit(root: string, event: string, payload: unknown, spool = false): void {
+  appendAuditRecord(
+    root,
+    {
+      ts: new Date().toISOString(),
+      event,
+      payload: redactDeep(payload),
+    },
+    spool,
+  );
+}
+
+export function recordFromEvent(
+  root: string,
+  config: ObservabilityConfig,
+  event: HarnessEvent,
+  extra: { gen_ai?: ObsEvent["gen_ai"]; forceDebug?: boolean } = {},
+): ObsEvent | null {
+  const kind = EVENT_KIND_TO_OBS_KIND[event.event];
+  return recordObs(root, config, {
+    provider: event.provider,
+    kind,
+    sessionKey: event.sessionKey,
+    model: event.model,
+    forceDebug: extra.forceDebug,
+    gen_ai: extra.gen_ai,
+    attrs: {
+      tool_name: event.toolName,
+      command: event.command,
+      file_path: event.filePath,
+      subagent_type: event.subagentType,
+      status: event.status,
+      context_usage_percent: event.contextUsagePercent,
+      text_chars: typeof event.text === "string" ? event.text.length : undefined,
+    },
+  });
+}
+
+export { DEFAULT_OBS };
+
+// invariant: what `recordRollup` branches on. Fed inline at record time, so it sees every event before plane
+// routing — which is why the contract marks it `inline` rather than naming planes.
+export const ROLLUP_KINDS = [
+  "agent.response",
+  "agent.thought",
+  "compact",
+  "gate.outcome",
+  "mcp.end",
+  "mcp.start",
+  "policy.deny",
+  "prompt.submit",
+  "session.start",
+  "shell.end",
+  "shell.start",
+  "subagent.start",
+  "tool.end",
+  "tool.fail",
+  "tool.start",
+] as const;