@open-everywhere/core 0.1.0

package/agent/control/transcript-render.ts

@@ -0,0 +1,164 @@
+// Transcript RENDER — one session's durable eve event stream folded into readable prose (OPE-153).
+//
+// The operator route (control/read-route.ts) serves transcripts as raw JSON events, which is right
+// for a harness and useless for a model: a 400-event stream is mostly per-step token accounting and
+// streaming deltas, and the JSON alone would blow the context before it said anything. This module
+// is the projection that answers the actual question — "what did that run DO?" — in the smallest
+// text that still contains the evidence: the wake it was fired with, what it thought, which tools it
+// called with which arguments, what those tools returned, and what it finally said.
+//
+// 🔴 EVERYTHING THIS MODULE PRODUCES IS UNTRUSTED. Not "mostly", not "the tool results" — all of it.
+// The wake body can be a webhook payload an outsider authored; a tool result can be a fetched issue
+// body; the assistant prose quotes both. Callers MUST pass the whole render through the untrusted
+// funnel (access/untrusted.ts). This module deliberately does NOT wrap it itself, for the reason the
+// repo states everywhere else: one funnel, at the tool-result seam, where the OPE-73 projection can
+// re-attach it — a second wrap site here would be a second thing to keep in sync.
+//
+// Pure (no I/O, no clock), so the unit test drives every branch off crafted events.
+//
+// EVENT SHAPES are eve's own, at the deployment's eve version (pre-1.0, carries a wire version) —
+// NOT an OE-stable schema. Everything below reads defensively through `asRecord`/`str`: an unknown
+// event type renders as a bare type line rather than throwing, and a renamed field degrades to an
+// empty string. A transcript reader that crashes on an eve upgrade would take the forensic answer
+// away exactly when someone is trying to work out what broke.
+
+/** One event as control/read-route.ts's envelope carries it (index/at ours, type/data eve's). */
+export interface RenderableTranscriptEvent {
+  readonly index: number;
+  readonly at: string | null;
+  readonly type: string;
+  readonly data: unknown;
+}
+
+/** Per-field ceilings. Chosen so a busy fire renders in a few thousand tokens rather than tens of
+ *  thousands: the result body is where injected instructions would live, so it gets the largest
+ *  budget (truncating it to nothing would hide the very content this read exists to show), while
+ *  reasoning — the highest-volume, lowest-evidence field — gets the smallest. The whole render is
+ *  additionally capped by access/result-cap.ts inside the untrusted wrap, so these bound the SHAPE
+ *  of the output; that one bounds its total size. */
+export const TRANSCRIPT_FIELD_CAPS = {
+  wake: 2000,
+  assistant: 2000,
+  reasoning: 600,
+  toolInput: 600,
+  toolResult: 1500,
+} as const;
+
+/** Truncate with a byte-honest marker, so a reader can tell "it said nothing more" from "we cut it". */
+function clip(text: string, max: number): string {
+  const t = text.replace(/\s+$/u, "");
+  return t.length <= max ? t : `${t.slice(0, max)}… [+${t.length - max} chars truncated]`;
+}
+
+function asRecord(v: unknown): Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : v === undefined || v === null ? "" : JSON.stringify(v);
+}
+
+/** `HH:MM:SS` off an ISO stamp — the whole date on every line is noise when a fire lasts seconds. */
+function clock(at: string | null): string {
+  const m = /T(\d{2}:\d{2}:\d{2})/u.exec(at ?? "");
+  return m ? m[1] : "--:--:--";
+}
+
+/** What the render says about a session it could only read part of. */
+export interface TranscriptRenderMeta {
+  /** False when the drain stopped on the page/idle/wall-clock bound rather than a terminal event. */
+  readonly complete: boolean;
+  /** Total events drained (the render drops the noisy ones, so this is not the line count). */
+  readonly eventCount: number;
+}
+
+/**
+ * Fold a drained event stream into readable lines.
+ *
+ * WHAT IS DROPPED, and why each is a deliberate omission rather than an oversight:
+ *   • `reasoning.appended` / `message.appended` — streaming DELTAS. Each carries the full text so
+ *     far, so rendering them would repeat the same paragraph once per chunk. The `*.completed`
+ *     event carries the final text; that is the one rendered.
+ *   • `step.started` / `step.completed` — per-step token accounting. Cost is already answerable
+ *     (`session_cost`, `list_routines`' 7-day tokens) and says nothing about what the run did.
+ *   • `session.waiting` — a park, which recurs at every idle stop and is not an event in the run's
+ *     story. Its ABSENCE is not silence: `complete: false` in the meta is what says the tail is cut.
+ * Everything else renders, including types this module has never seen, as `[<type>]` — so a new eve
+ * event shows up as a gap-with-a-name instead of vanishing.
+ */
+export function renderTranscript(events: readonly RenderableTranscriptEvent[], meta: TranscriptRenderMeta): string {
+  const lines: string[] = [];
+  // actions.requested carries the tool NAME + input; action.result carries only the callId + output,
+  // so the name has to be carried across. An unmatched result (the request fell outside the page)
+  // renders with its callId rather than being dropped — a tool result with no visible call is
+  // exactly the kind of thing a forensic read must not hide.
+  const toolNameByCallId = new Map<string, string>();
+
+  for (const ev of events) {
+    const d = asRecord(ev.data);
+    const ts = clock(ev.at);
+    switch (ev.type) {
+      case "message.received":
+        lines.push(`${ts} [woken with] ${clip(str(d.message), TRANSCRIPT_FIELD_CAPS.wake)}`);
+        break;
+      case "reasoning.completed": {
+        const text = clip(str(d.reasoning), TRANSCRIPT_FIELD_CAPS.reasoning);
+        if (text.length > 0) lines.push(`${ts} [thought] ${text}`);
+        break;
+      }
+      case "message.completed": {
+        const text = clip(str(d.message), TRANSCRIPT_FIELD_CAPS.assistant);
+        if (text.length > 0) lines.push(`${ts} [said] ${text}`);
+        break;
+      }
+      case "actions.requested": {
+        for (const a of Array.isArray(d.actions) ? d.actions : []) {
+          const action = asRecord(a);
+          const name = str(action.toolName) || "?";
+          const callId = str(action.callId);
+          if (callId.length > 0) toolNameByCallId.set(callId, name);
+          lines.push(`${ts} [called] ${name}(${clip(str(action.input), TRANSCRIPT_FIELD_CAPS.toolInput)})`);
+        }
+        break;
+      }
+      case "action.result": {
+        const result = asRecord(d.result);
+        const callId = str(result.callId);
+        const name = toolNameByCallId.get(callId) ?? (callId.length > 0 ? `callId ${callId}` : "?");
+        const status = str(d.status) || "completed";
+        lines.push(`${ts} [${name} returned:${status}] ${clip(str(result.output), TRANSCRIPT_FIELD_CAPS.toolResult)}`);
+        break;
+      }
+      case "session.failed":
+        lines.push(`${ts} [run FAILED] ${clip(str(d.error ?? d.reason), TRANSCRIPT_FIELD_CAPS.assistant)}`);
+        break;
+      case "session.completed":
+        lines.push(`${ts} [run ended]`);
+        break;
+      // Deliberately silent (see the doc comment): deltas, per-step usage, parks.
+      case "reasoning.appended":
+      case "message.appended":
+      case "step.started":
+      case "step.completed":
+      case "session.waiting":
+      case "session.started":
+      case "turn.started":
+      case "turn.completed":
+        break;
+      default:
+        lines.push(`${ts} [${ev.type}]`);
+    }
+  }
+
+  if (lines.length === 0) {
+    lines.push(
+      meta.eventCount === 0
+        ? "(no recorded events — the run left no durable trace in the window read)"
+        : `(${meta.eventCount} events recorded, none of them content — the run started but produced no message, tool call or result)`,
+    );
+  }
+  if (!meta.complete) {
+    lines.push("(transcript truncated — this is the start of the run, not all of it; the session was still open or the page bound was reached)");
+  }
+  return lines.join("\n");
+}