@monster-orange/den 0.0.0-stage → 0.1.0

package/src/pillars/journeys/observability/events.ts

@@ -0,0 +1,288 @@
+/**
+ * Journeys observability event bus — the single structured timeline of what
+ * a journey did, feeding three sinks from one source:
+ *   1. an in-memory list (the report reads it for the timeline + binding
+ *      summary + denial list),
+ *   2. `events.jsonl` next to the transcript (post-mortem forensics),
+ *   3. an optional condensed live line to stdout (JOURNEYS_VERBOSE) so a
+ *      stuck/looping run is obvious WHILE it runs, not after `report:`.
+ *
+ * The transcript.jsonl remains the raw SDK stream; events.jsonl is the
+ * harness's own interpretation — tool calls with results, ledger bindings
+ * (the `{<type>_id}` question answered directly), network interception hits,
+ * capability/policy denials, agent errors, and turn/token progress.
+ *
+ * Data-minimization (mirrors ledger.ts): events carry ONLY method +
+ * sanitized path + status + extracted id + tool name + a short human
+ * summary. Never bodies, headers, cookies, or credential material. The
+ * caller still passes secret values so the JSONL writer fails closed if one
+ * ever appears (defense in depth alongside TranscriptScrubber).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { HttpMethod, LedgerSource } from "../tools/ledger.js";
+
+/** Monotonic-ish wall clock; injectable for deterministic tests. */
+export type Clock = () => number;
+
+/**
+ * One structured harness event. `kind` discriminates; every event carries a
+ * `seq` (emission order) and `tMs` (ms since bus creation) stamped by the
+ * bus, so consumers never compute timing themselves.
+ */
+export type JourneyEvent = { seq: number; tMs: number } & JourneyEventBody;
+
+export type JourneyEventBody =
+  | {
+      kind: "run_started";
+      journey: string;
+      env: string;
+      surface: string;
+      model: string;
+    }
+  | { kind: "turn_started"; turn: number }
+  | {
+      kind: "turn_ended";
+      turn: number;
+      /** Cumulative total tokens if the runtime reported usage this turn. */
+      totalTokens?: number;
+    }
+  | {
+      kind: "tool_call";
+      /** Tool wire name, e.g. "browser_navigate", "http_request". */
+      tool: string;
+      /** SDK call id, for correlating start/end if both are emitted. */
+      callId?: string;
+      status: "running" | "completed" | "error";
+      /** One-line, secret-free summary of args (e.g. `GET /api/v1/items`). */
+      summary?: string;
+      /** One-line, secret-free summary of the result (status, error code). */
+      result?: string;
+    }
+  | { kind: "thinking"; text: string }
+  | { kind: "assistant_text"; text: string }
+  | {
+      kind: "ledger_binding";
+      resourceType: string;
+      id: string;
+      method: HttpMethod;
+      pathValue: string;
+      status: number;
+      source: LedgerSource;
+    }
+  | {
+      kind: "unmanaged_mutation";
+      method: HttpMethod;
+      pathValue: string;
+      status: number;
+      source: LedgerSource;
+    }
+  | { kind: "interception_error"; message: string }
+  | {
+      kind: "snapshot";
+      action: string;
+      /** null when suppressed/failed — the reason is in `note`. */
+      pathValue: string | null;
+      note?: string;
+    }
+  | {
+      kind: "agent_error";
+      /** SDK RunResult.error.message (secret-redacted by the caller). */
+      message: string;
+      code?: string;
+    }
+  | { kind: "run_ended"; failureKind?: string; durationMs: number };
+
+/**
+ * The surface the runner depends on — lets tests inject a recording fake
+ * without a filesystem. `JourneyEventBus` is the production implementation.
+ */
+export interface JourneyEventSink {
+  emit(body: JourneyEventBody): void;
+  addSecret(value: string): void;
+  readonly events: readonly JourneyEvent[];
+}
+
+/** Sink config; all optional so tests can run the bus headless-silent. */
+export interface JourneyEventBusOptions {
+  /** Absolute path for the JSONL sink; when omitted, nothing is written. */
+  filePath?: string;
+  /** Emit a condensed line per event to this writer (stdout when verbose). */
+  liveWriter?: (line: string) => void;
+  /** Secret values redacted before any event is written/printed. */
+  secrets?: readonly string[];
+  clock?: Clock;
+}
+
+/** A live secret slipped into an event — fail the run loudly (never write). */
+export class EventLeakError extends Error {
+  constructor() {
+    super(
+      "Journey event persist blocked: an event matched a live secret value. " +
+        "The run fails closed (failure_kind=infra_error).",
+    );
+    this.name = "EventLeakError";
+  }
+}
+
+/**
+ * Collects, persists, and (optionally) live-prints structured journey
+ * events. Single-threaded append; the JSONL write is synchronous so an
+ * event is durable the instant it is emitted (a crash mid-run still leaves
+ * a partial timeline on disk).
+ */
+export class JourneyEventBus {
+  private readonly recorded: JourneyEvent[] = [];
+  private readonly filePath?: string;
+  private readonly liveWriter?: (line: string) => void;
+  private readonly secrets: string[];
+  private readonly clock: Clock;
+  private readonly startedAt: number;
+  private seqCounter = 0;
+
+  constructor(options: JourneyEventBusOptions = {}) {
+    this.filePath = options.filePath;
+    this.liveWriter = options.liveWriter;
+    this.secrets = (options.secrets ?? []).filter((v) => v.length > 0);
+    this.clock = options.clock ?? Date.now;
+    this.startedAt = this.clock();
+    if (this.filePath !== undefined) {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    }
+  }
+
+  /** Events in emission order (report timeline reads this). */
+  get events(): readonly JourneyEvent[] {
+    return this.recorded;
+  }
+
+  /**
+   * Add live secret values to redact from future events. The runner learns
+   * the session token only after provisioning, so the bus is constructed
+   * with the Cursor key and the token is added once derived.
+   */
+  addSecret(value: string): void {
+    if (value.length > 0 && !this.secrets.includes(value)) {
+      this.secrets.push(value);
+    }
+  }
+
+  private redact(text: string): string {
+    let out = text;
+    for (const secret of this.secrets) {
+      out = out.split(secret).join("[REDACTED]");
+    }
+    return out;
+  }
+
+  /**
+   * Emit one event: stamp seq + tMs, redact strings, record, persist, and
+   * (if verbose) live-print. Throws EventLeakError if a raw secret survives
+   * redaction anywhere in the serialized event.
+   */
+  emit(body: JourneyEventBody): void {
+    const redactedBody = redactEventStrings(body, (t) => this.redact(t));
+    const event: JourneyEvent = {
+      seq: this.seqCounter++,
+      tMs: this.clock() - this.startedAt,
+      ...redactedBody,
+    };
+    const line = JSON.stringify(event);
+    for (const secret of this.secrets) {
+      if (line.includes(secret)) {
+        throw new EventLeakError();
+      }
+    }
+    this.recorded.push(event);
+    if (this.filePath !== undefined) {
+      fs.appendFileSync(this.filePath, `${line}\n`);
+    }
+    this.liveWriter?.(formatLiveLine(event));
+  }
+}
+
+/**
+ * Map every user-supplied string field of an event through `fn` (redaction).
+ * Kept exhaustive-by-construction: only known string-bearing fields are
+ * touched, numbers/enums pass through.
+ */
+function redactEventStrings(
+  body: JourneyEventBody,
+  fn: (t: string) => string,
+): JourneyEventBody {
+  switch (body.kind) {
+    case "tool_call":
+      return {
+        ...body,
+        summary: body.summary === undefined ? undefined : fn(body.summary),
+        result: body.result === undefined ? undefined : fn(body.result),
+      };
+    case "thinking":
+    case "assistant_text":
+      return { ...body, text: fn(body.text) };
+    case "interception_error":
+      return { ...body, message: fn(body.message) };
+    case "agent_error":
+      return { ...body, message: fn(body.message) };
+    default:
+      return body;
+  }
+}
+
+/** ANSI-free, one-line condensed rendering for the live/verbose stream. */
+export function formatLiveLine(event: JourneyEvent): string {
+  const t = `${(event.tMs / 1000).toFixed(1)}s`;
+  switch (event.kind) {
+    case "run_started":
+      return `  [${t}] ▶ ${event.journey} (${event.surface}) model=${event.model}`;
+    case "turn_started":
+      return `  [${t}] turn ${event.turn}`;
+    case "turn_ended":
+      return `  [${t}] turn ${event.turn} ended${
+        event.totalTokens !== undefined ? ` (${event.totalTokens} tok)` : ""
+      }`;
+    case "tool_call": {
+      const icon =
+        event.status === "completed"
+          ? "✓"
+          : event.status === "error"
+            ? "✗"
+            : "…";
+      const parts = [`  [${t}] ${icon} ${event.tool}`];
+      if (event.summary) parts.push(event.summary);
+      if (event.result) parts.push(`→ ${event.result}`);
+      return parts.join(" ");
+    }
+    case "thinking":
+      return `  [${t}] 💭 ${truncate(event.text, 100)}`;
+    case "assistant_text":
+      return `  [${t}] 🗣  ${truncate(event.text, 100)}`;
+    case "ledger_binding":
+      return `  [${t}] 🔗 bound ${event.resourceType}=${event.id} (${event.method} ${event.pathValue} → ${event.status})`;
+    case "unmanaged_mutation":
+      return `  [${t}] ⚠ unmanaged ${event.method} ${event.pathValue} → ${event.status}`;
+    case "interception_error":
+      return `  [${t}] ⚠ interception error: ${truncate(event.message, 120)}`;
+    case "snapshot":
+      return `  [${t}] 📸 ${event.action}${
+        event.pathValue === null
+          ? ` (no frame${event.note ? `: ${event.note}` : ""})`
+          : ""
+      }`;
+    case "agent_error":
+      return `  [${t}] ✗ agent error${event.code ? ` [${event.code}]` : ""}: ${truncate(event.message, 200)}`;
+    case "run_ended":
+      return `  [${t}] ■ ended${event.failureKind ? ` (${event.failureKind})` : " (ok)"} in ${event.durationMs}ms`;
+    default: {
+      // Exhaustiveness guard: a new event kind must extend this switch.
+      const _never: never = event;
+      return String(_never);
+    }
+  }
+}
+
+function truncate(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}

package/src/pillars/journeys/observability/sdk-mapper.ts

@@ -0,0 +1,306 @@
+/**
+ * Pure SDK-stream → JourneyEvent mapper. The runner streams opaque SDK
+ * messages; this module turns the interesting ones into condensed,
+ * secret-free harness events (tool calls with results, thinking,
+ * assistant text, per-turn usage). Kept pure + injectable-free so it is
+ * exhaustively unit-testable without an SDK or a live agent.
+ *
+ * Only the subset the operator cares about is mapped; system/request/task
+ * bookkeeping messages produce no events (the raw line is still in
+ * transcript.jsonl). Tool args/results are summarized to a single line —
+ * never the full payload — so events.jsonl stays a timeline, not a body
+ * dump (see events.ts data-minimization contract).
+ */
+
+import type { SDKMessage } from "@cursor/sdk";
+import type { JourneyEventBody } from "./events.js";
+
+/**
+ * Stream state threaded across messages. The SDK streams assistant output
+ * one TOKEN per `assistant` message (verified on a staging transcript:
+ * 771 assistant frames for a handful of logical replies — "I'll", " run",
+ * " the", …). Emitting an event per frame produced 771 fake turns + 763
+ * one-word assistant_text lines and buried the real tool timeline. So we
+ * BUFFER consecutive text deltas here and flush a single coalesced
+ * assistant_text when a non-text signal (tool call / thinking / usage /
+ * end-of-stream) arrives. `turn` increments per usage-reported round, the
+ * only honest turn boundary the stream exposes.
+ */
+export interface MapperState {
+  turn: number;
+  /** Accumulated assistant text since the last flush. */
+  textBuffer: string;
+}
+
+export function createMapperState(): MapperState {
+  return { turn: 0, textBuffer: "" };
+}
+
+/**
+ * Flush any buffered assistant text as one coalesced event. Called by the
+ * mapper before emitting a non-text event, and by the runner at end-of-stream
+ * so a trailing reply is not lost.
+ */
+export function flushAssistantText(state: MapperState): JourneyEventBody[] {
+  const text = state.textBuffer.trim();
+  state.textBuffer = "";
+  return text.length > 0 ? [{ kind: "assistant_text", text }] : [];
+}
+
+/**
+ * Map one SDK message to zero or more journey events, mutating `state`.
+ * Returns [] for messages with no operator signal (the buffer may still be
+ * mutated). The runner MUST call flushAssistantText(state) after the stream
+ * ends to emit any trailing buffered reply.
+ */
+export function sdkMessageToEvents(
+  message: SDKMessage,
+  state: MapperState,
+): JourneyEventBody[] {
+  switch (message.type) {
+    case "assistant":
+      return mapAssistant(message, state);
+    case "tool_call": {
+      // Custom tools are routed through the SDK's MCP bridge, so the wire
+      // `name` is the literal "mcp" and the real tool + args are nested under
+      // args.{toolName,args}. Unwrap so the timeline shows `browser_navigate`,
+      // not `mcp` (verified against a staging transcript, 2026-07-16).
+      const { tool, args } = unwrapMcp(message.name, message.args);
+      return [
+        ...flushAssistantText(state),
+        {
+          kind: "tool_call",
+          tool,
+          callId: message.call_id,
+          status: message.status,
+          summary: summarizeArgs(tool, args),
+          result: summarizeResult(message.status, message.result),
+        },
+      ];
+    }
+    case "thinking":
+      return message.text.trim().length > 0
+        ? [
+            ...flushAssistantText(state),
+            { kind: "thinking", text: message.text },
+          ]
+        : [];
+    case "usage":
+      // A usage message is the SDK's real turn boundary — flush the reply,
+      // count the turn, and report cumulative tokens.
+      state.turn += 1;
+      return [
+        ...flushAssistantText(state),
+        {
+          kind: "turn_ended",
+          turn: state.turn,
+          totalTokens: message.usage.totalTokens,
+        },
+      ];
+    default:
+      // system / user / status / request / task — no timeline signal.
+      return [];
+  }
+}
+
+/**
+ * Handle one streamed assistant frame. Text blocks are buffered (coalesced
+ * across the many one-token frames); an inline tool_use block flushes the
+ * buffer and emits a running tool_call (the SDK also emits a standalone
+ * `tool_call` line for execution status, so this is the intent marker).
+ */
+function mapAssistant(
+  message: Extract<SDKMessage, { type: "assistant" }>,
+  state: MapperState,
+): JourneyEventBody[] {
+  // Defensive: a malformed/partial assistant frame (missing message.content)
+  // must never crash the stream loop — the raw line is still in
+  // transcript.jsonl; we just skip block-level events for it.
+  const content = message.message?.content;
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  const events: JourneyEventBody[] = [];
+  for (const block of content) {
+    if (block.type === "text") {
+      state.textBuffer += block.text;
+    } else {
+      events.push(...flushAssistantText(state));
+      const { tool, args } = unwrapMcp(block.name, block.input);
+      events.push({
+        kind: "tool_call",
+        tool,
+        callId: block.id,
+        status: "running",
+        summary: summarizeArgs(tool, args),
+      });
+    }
+  }
+  return events;
+}
+
+/**
+ * Unwrap the SDK's MCP tool envelope. Custom tools surface on the stream as
+ * `name:"mcp"` with `args:{providerIdentifier, toolName, args}`; return the
+ * inner tool name + its real args. Non-MCP calls pass through unchanged.
+ */
+export function unwrapMcp(
+  name: string,
+  args: unknown,
+): { tool: string; args: unknown } {
+  if (name !== "mcp" || typeof args !== "object" || args === null) {
+    return { tool: name, args };
+  }
+  const bag = args as Record<string, unknown>;
+  const toolName = typeof bag.toolName === "string" ? bag.toolName : "mcp";
+  return { tool: toolName, args: bag.args };
+}
+
+/**
+ * Peel the MCP result envelope to the tool's own payload. Custom-tool
+ * results arrive as `{ status, value: { content: [{ text: { text } }],
+ * isError } }`; return either the inner text (browser tools) or the parsed
+ * JSON payload (http_request returns a JSON string) so summarizeResult can
+ * read status codes / error codes. Non-MCP results pass through.
+ */
+function unwrapMcpResult(result: unknown): {
+  payload: unknown;
+  isError: boolean;
+} {
+  if (typeof result !== "object" || result === null) {
+    return { payload: result, isError: false };
+  }
+  const bag = result as Record<string, unknown>;
+  const value = bag.value;
+  if (typeof value !== "object" || value === null) {
+    return { payload: result, isError: false };
+  }
+  const valueBag = value as Record<string, unknown>;
+  const isError = valueBag.isError === true;
+  const content = valueBag.content;
+  if (!Array.isArray(content) || content.length === 0) {
+    return { payload: result, isError };
+  }
+  const first = content[0] as { text?: { text?: unknown } } | undefined;
+  const text = first?.text?.text;
+  if (typeof text !== "string") {
+    return { payload: result, isError };
+  }
+  // http_request returns a JSON string; browser tools return prose.
+  try {
+    return { payload: JSON.parse(text), isError };
+  } catch {
+    return { payload: text, isError };
+  }
+}
+
+/**
+ * Build a one-line, secret-free summary of tool args. For the HTTP tool we
+ * surface `METHOD /sanitized/path`; for browser tools the target
+ * URL/selector; everything else falls back to the arg keys so we never dump
+ * a full payload (which could carry a body/token) into the timeline.
+ */
+export function summarizeArgs(tool: string, args: unknown): string | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const bag = args as Record<string, unknown>;
+
+  if (tool === "http_request" || tool === "journeys_http_request") {
+    const method =
+      typeof bag.method === "string" ? bag.method.toUpperCase() : "GET";
+    const target =
+      typeof bag.path === "string"
+        ? bag.path
+        : typeof bag.url === "string"
+          ? bag.url
+          : "";
+    return `${method} ${sanitizeForSummary(target)}`.trim();
+  }
+
+  if (tool.startsWith("browser_")) {
+    if (typeof bag.url === "string") return sanitizeForSummary(bag.url);
+    if (typeof bag.selector === "string") return `selector=${bag.selector}`;
+    if (typeof bag.text === "string") return `text="${truncate(bag.text, 40)}"`;
+    if (typeof bag.action === "string") return bag.action;
+  }
+
+  const keys = Object.keys(bag);
+  return keys.length > 0 ? `{${keys.join(", ")}}` : undefined;
+}
+
+/**
+ * Summarize a tool result to one line. HTTP results expose their status
+ * code and any structured error code; browser results expose the leading
+ * line of their page summary; errors expose the error code/message. Never
+ * the full body.
+ */
+export function summarizeResult(
+  status: "running" | "completed" | "error",
+  rawResult: unknown,
+): string | undefined {
+  if (status === "running") return undefined;
+  // Peel the MCP envelope (custom tools) → the tool's own payload + isError.
+  const { payload: result, isError } = unwrapMcpResult(rawResult);
+  if (result === undefined || result === null) {
+    return status === "error" || isError ? "ERROR" : undefined;
+  }
+
+  if (typeof result === "string") {
+    return withErrorPrefix(truncate(firstLine(result), 120), isError);
+  }
+
+  if (typeof result === "object") {
+    const bag = result as Record<string, unknown>;
+    // Scoped-tool error envelope: { error: { code, message } }.
+    if (typeof bag.error === "object" && bag.error !== null) {
+      const err = bag.error as Record<string, unknown>;
+      const code = typeof err.code === "string" ? err.code : "ERROR";
+      const msg = typeof err.message === "string" ? ` ${err.message}` : "";
+      return truncate(`${code}${msg}`, 120);
+    }
+    if (typeof bag.error === "string") {
+      return truncate(bag.error, 120);
+    }
+    // HTTP payload: { status, ... }.
+    if (typeof bag.status === "number") {
+      return `HTTP ${bag.status}`;
+    }
+    // Browser summary: { summary: "URL: ...\nTitle: ..." }.
+    if (typeof bag.summary === "string") {
+      return truncate(firstLine(bag.summary), 120);
+    }
+  }
+  return status === "error" ? "error" : "done";
+}
+
+/** Strip query/fragment/origin from a URL-ish string for the summary line. */
+function sanitizeForSummary(pathOrUrl: string): string {
+  if (pathOrUrl.length === 0) return "";
+  try {
+    const url = new URL(pathOrUrl, "http://placeholder.invalid");
+    return url.pathname;
+  } catch {
+    // Not URL-shaped — return as-is minus any query tail.
+    return pathOrUrl.split("?")[0] ?? pathOrUrl;
+  }
+}
+
+/**
+ * Prefix a summary with "ERROR " when the tool flagged an error — but only
+ * if the text doesn't already begin with "ERROR" (browser-tool failures
+ * already start with "ERROR ACTION_FAILED: …", which double-prefixed to the
+ * nonsensical "ERROR ERROR ACTION_FAILED" on the first staging run).
+ */
+function withErrorPrefix(text: string, isError: boolean): string {
+  if (!isError) return text;
+  return /^error\b/i.test(text) ? text : `ERROR ${text}`;
+}
+
+function firstLine(text: string): string {
+  return text.split("\n")[0] ?? text;
+}
+
+function truncate(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}