omnirush 0.7.0 → 0.8.0

package/assets/extensions/omnirush/commands.ts

@@ -17,7 +17,7 @@
  * which is exactly how /grant and /verify broke the first time.
  */
 
-import { readSessionLedger, SESSION_LEDGER_FILE } from "./collector-lib";
+import { readSessionLedger, SESSION_LEDGER_FILE } from "./capture/workspace-collector";
 import { deviceMe, omniDir, resolveOrigin } from "./auth";
 import { sharedRefresher } from "./refresh";
 import { formatCollectorLine, formatStatusLines } from "./status-lib";

package/assets/extensions/omnirush/pi-engine.ts

@@ -0,0 +1,655 @@
+// The CLI's session, in the desktop app's engine message format.
+//
+// The desktop collector records the conversation as the engine (opencode)
+// keeps it: one message per user prompt and per model step,
+//
+//   {info: {id, sessionID, role, time: {created, completed}, modelID,
+//           providerID, agent, mode, variant, path, cost, tokens, finish,
+//           error?},
+//    parts: [step-start, reasoning, text, tool, patch, file, compaction,
+//            step-finish, ...]}
+//
+// and the omnirush.ai backend rebuilds the viewer's turns from exactly that
+// (public_trace.py). The pi agent keeps its session as a tree of entries
+// (user, assistant and toolResult messages, compactions, summaries, model
+// and thinking-level changes). This module maps the entries on the active
+// branch onto engine messages, one to one and without inventing content:
+//
+//   user message            -> user message: text parts, image file parts
+//                              (bytes not embedded, as the desktop's
+//                              engine.request records attachments)
+//   assistant message       -> assistant message: step-start, reasoning
+//                              (the model's thinking), text and tool parts
+//                              in the model's order, a patch part for the
+//                              files its edit/write tools changed, and
+//                              step-finish with the step's token usage and
+//                              cost; model, provider, variant (thinking
+//                              effort) and finish reason on its info
+//   toolResult message      -> the output (or error) of its call's tool
+//                              part, with the call's start and end time
+//   bashExecution (`!cmd`)  -> user message with the engine's shell-command
+//                              marker text, answered by an assistant message
+//                              with the bash tool part (as the engine keeps
+//                              a command the user ran)
+//   custom / branch summary -> user message with synthetic text parts (what
+//                              the model was shown; never a turn opener)
+//   compaction              -> user message with a compaction part and the
+//                              summary as an assistant `summary` message
+//   system prompt           -> not a message (the desktop records it in
+//                              the prompt's engine.request event)
+//
+// Ids are stable across processes (derived from the pi entry ids), so a
+// resumed session or a repeated flush merges instead of duplicating.
+//
+// Also here, pure and shared with the tests: the helpers the desktop's turn
+// observer (apps/server/src/collector-observer.ts) applies to the engine's
+// messages when a turn settles: the turn's model, the message budget of a
+// flush and its split into `turn.messages` parts.
+
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+
+export type EngineMessage = { info: Record<string, unknown>; parts: Array<Record<string, unknown>> };
+
+/** One pi session entry (loosely typed: the files are parsed without validation). */
+export type PiEntry = {
+  type?: string;
+  id?: string;
+  parentId?: string | null;
+  timestamp?: string;
+  message?: Record<string, any>;
+  [key: string]: any;
+};
+
+export type EngineConvertOptions = {
+  /** The session the messages belong to (info.sessionID). */
+  sessionId: string;
+  /** info.agent / info.mode of every message: "omnirush-cli" for a root session, the role for a sub-agent. */
+  agent: string;
+  /** The session's working directory (info.path; relative tool paths resolve against it). */
+  cwd: string;
+  /** Tool call start times seen live (toolCallId -> epoch ms), for the calls of this process. */
+  toolStarts?: ReadonlyMap<string, number>;
+  /** The session's model before its first model_change entry, if known. */
+  initialModel?: { providerID: string; modelID: string } | null;
+  /** The session's thinking level before its first thinking_level_change entry, if known. */
+  initialThinkingLevel?: string | null;
+};
+
+/** The shell-command marker the engine writes on a user message holding a command the user ran (public_trace.py `_USER_SHELL_TEXT`). */
+export const USER_SHELL_TEXT = "The following tool was executed by the user";
+/** Tools whose successful calls change files (the patch part of their step). */
+const FILE_TOOLS = new Set(["edit", "write"]);
+/** A tool result's details are kept as the tool part's metadata up to this size. */
+const MAX_TOOL_METADATA_BYTES = 64 * 1024;
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function epochMs(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+/** The engine id of the message made from pi entry `entryId` (ascending ids are not needed: the backend orders by time). */
+export function engineMessageId(entryId: string, suffix = ""): string {
+  return `msg_${entryId}${suffix}`;
+}
+
+function partId(messageId: string, index: number): string {
+  return `prt_${messageId.slice(4)}_${index.toString().padStart(3, "0")}`;
+}
+
+/** The text of a content value (a string, or text blocks), non-text blocks aside. */
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block) => isRecord(block) && block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text as string)
+    .join("\n\n");
+}
+
+const IMAGE_EXTENSIONS: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+};
+
+/**
+ * A pi image block as an engine file part. The bytes are not embedded: the
+ * desktop records attachments by identity in their own `attachment` trace
+ * events, and replaces inline data with this marker in its request log.
+ */
+function imagePart(block: Record<string, any>, index: number): Record<string, unknown> {
+  const mime = typeof block.mimeType === "string" && block.mimeType ? block.mimeType : "application/octet-stream";
+  const data = typeof block.data === "string" ? block.data : "";
+  return {
+    type: "file",
+    mime,
+    filename: `image-${index + 1}.${IMAGE_EXTENSIONS[mime] ?? "bin"}`,
+    url: `data:${mime};omitted`,
+    omitted_url_chars: data.length,
+    ...(data ? { sha256: createHash("sha256").update(Buffer.from(data, "base64")).digest("hex"), bytes: Buffer.from(data, "base64").length } : {}),
+  };
+}
+
+/** Content blocks (user or tool result) as engine parts: text parts and file parts. */
+function contentParts(content: unknown, extra: Record<string, unknown> = {}): Array<Record<string, unknown>> {
+  if (typeof content === "string") return content ? [{ type: "text", text: content, ...extra }] : [];
+  if (!Array.isArray(content)) return [];
+  const parts: Array<Record<string, unknown>> = [];
+  let images = 0;
+  for (const block of content) {
+    if (typeof block === "string") {
+      if (block) parts.push({ type: "text", text: block, ...extra });
+    } else if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+      if (block.text) parts.push({ type: "text", text: block.text, ...extra });
+    } else if (isRecord(block) && block.type === "image") {
+      parts.push(imagePart(block, images));
+      images += 1;
+    }
+  }
+  return parts;
+}
+
+/** pi stop reasons as the engine's finish reasons (the AI SDK's). */
+function finishReason(stopReason: unknown): string | undefined {
+  switch (stopReason) {
+    case "stop":
+      return "stop";
+    case "length":
+      return "length";
+    case "toolUse":
+      return "tool-calls";
+    case "error":
+      return "error";
+    default:
+      return undefined;
+  }
+}
+
+/** The engine's error record of a failed or aborted step (the backend reads only its name). */
+function assistantError(message: Record<string, any>): Record<string, unknown> | undefined {
+  if (message.stopReason === "aborted") {
+    return { name: "MessageAbortedError", data: { message: typeof message.errorMessage === "string" ? message.errorMessage : "aborted" } };
+  }
+  if (message.stopReason === "error") {
+    return { name: "APIError", data: { message: typeof message.errorMessage === "string" ? message.errorMessage : "error" } };
+  }
+  return undefined;
+}
+
+/** pi usage as the engine's step tokens: input excludes cache reads and writes in both. */
+function stepTokens(usage: unknown): Record<string, unknown> {
+  const value = isRecord(usage) ? usage : {};
+  const number = (key: string) => (typeof value[key] === "number" && Number.isFinite(value[key]) ? (value[key] as number) : 0);
+  return {
+    total: number("totalTokens"),
+    input: number("input"),
+    output: number("output"),
+    reasoning: number("reasoning"),
+    cache: { read: number("cacheRead"), write: number("cacheWrite") },
+  };
+}
+
+function stepCost(usage: unknown): number {
+  const cost = isRecord(usage) && isRecord(usage.cost) ? usage.cost.total : 0;
+  return typeof cost === "number" && Number.isFinite(cost) ? cost : 0;
+}
+
+/** A tool result's details as tool-part metadata, when small enough to keep. */
+function toolMetadata(details: unknown): Record<string, unknown> | undefined {
+  if (details === undefined || details === null) return undefined;
+  let text: string;
+  try {
+    text = JSON.stringify(details);
+  } catch {
+    return undefined;
+  }
+  if (text === undefined || Buffer.byteLength(text) > MAX_TOOL_METADATA_BYTES) return undefined;
+  return isRecord(details) ? { ...details } : { details };
+}
+
+/** The sub-agent session ids a spawn_agents result names (details.results[].session_id). */
+export function spawnedSessionIds(details: unknown): string[] {
+  if (!isRecord(details) || !Array.isArray(details.results)) return [];
+  const ids: string[] = [];
+  for (const result of details.results) {
+    const id = isRecord(result) ? result.session_id : undefined;
+    if (typeof id === "string" && id && !ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+
+type ToolResult = { message: Record<string, any>; at: number | null };
+
+/**
+ * The engine messages of a pi session branch (entries root to leaf, as
+ * SessionManager.getBranch() returns them or a session file lists them).
+ */
+export function engineMessagesFromEntries(entries: readonly PiEntry[], options: EngineConvertOptions): EngineMessage[] {
+  const { sessionId, agent, cwd } = options;
+  // Tool results by call id: they fill in the calls of the step before them.
+  const results = new Map<string, ToolResult>();
+  for (const entry of entries) {
+    const message = entry.type === "message" && isRecord(entry.message) ? entry.message : null;
+    if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
+      results.set(message.toolCallId, { message, at: epochMs(message.timestamp) ?? epochMs(entry.timestamp) });
+    }
+  }
+  // The model a prompt went to: the model that answered it (its turn's first
+  // assistant message: pi records no model change for a `--model` flag on
+  // a resumed session), else the latest model change before it.
+  const nextAssistantModel = new Map<number, { providerID: string; modelID: string }>();
+  let upcoming: { providerID: string; modelID: string } | null = null;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const message = entries[index]?.type === "message" && isRecord(entries[index]!.message) ? entries[index]!.message! : null;
+    if (message?.role === "assistant" && typeof message.provider === "string" && typeof message.model === "string") {
+      upcoming = { providerID: message.provider, modelID: message.model };
+    }
+    if (upcoming) nextAssistantModel.set(index, upcoming);
+    // An earlier prompt was answered by its own turn, never by this one's.
+    if (message?.role === "user") upcoming = null;
+  }
+
+  const out: EngineMessage[] = [];
+  let model: { providerID: string; modelID: string } | null = options.initialModel ?? null;
+  let thinkingLevel: string | null = options.initialThinkingLevel ?? null;
+  let lastUserId: string | null = null;
+  const variant = () => (thinkingLevel && thinkingLevel !== "off" ? thinkingLevel : null);
+
+  const userMessage = (id: string, created: number | null, parts: Array<Record<string, unknown>>, index: number, extraInfo: Record<string, unknown> = {}): void => {
+    const messageModel = nextAssistantModel.get(index) ?? model ?? null;
+    const info: Record<string, unknown> = {
+      id,
+      sessionID: sessionId,
+      role: "user",
+      time: { created: created ?? 0 },
+      agent,
+      ...(messageModel ? { model: { providerID: messageModel.providerID, modelID: messageModel.modelID } } : {}),
+      ...(variant() ? { variant: variant() } : {}),
+      ...extraInfo,
+    };
+    out.push({
+      info,
+      parts: parts.map((part, partIndex) => ({ id: partId(id, partIndex), sessionID: sessionId, messageID: id, ...part })),
+    });
+    lastUserId = id;
+  };
+
+  entries.forEach((entry, index) => {
+    const entryId = typeof entry.id === "string" && entry.id ? entry.id : null;
+    if (!entryId) return;
+    const at = epochMs(entry.timestamp);
+    if (entry.type === "model_change") {
+      if (typeof entry.provider === "string" && typeof entry.modelId === "string") model = { providerID: entry.provider, modelID: entry.modelId };
+      return;
+    }
+    if (entry.type === "thinking_level_change") {
+      if (typeof entry.thinkingLevel === "string") thinkingLevel = entry.thinkingLevel;
+      return;
+    }
+    if (entry.type === "compaction") {
+      const id = engineMessageId(entryId);
+      userMessage(id, at, [{ type: "compaction" }], index);
+      const summaryId = engineMessageId(entryId, "_summary");
+      const summaryParts: Array<Record<string, unknown>> = [];
+      if (typeof entry.summary === "string" && entry.summary) summaryParts.push({ type: "text", text: entry.summary });
+      if (isRecord(entry.usage)) summaryParts.push({ type: "step-finish", reason: "stop", tokens: stepTokens(entry.usage), cost: stepCost(entry.usage) });
+      out.push({
+        info: {
+          id: summaryId,
+          sessionID: sessionId,
+          role: "assistant",
+          parentID: id,
+          time: { created: at ?? 0, completed: at ?? 0 },
+          summary: true,
+          agent: "compaction",
+          mode: "compaction",
+          path: { cwd, root: cwd },
+          ...(isRecord(entry.usage) ? { tokens: stepTokens(entry.usage), cost: stepCost(entry.usage) } : {}),
+          finish: "stop",
+        },
+        parts: summaryParts.map((part, partIndex) => ({ id: partId(summaryId, partIndex), sessionID: sessionId, messageID: summaryId, ...part })),
+      });
+      return;
+    }
+    if (entry.type === "branch_summary") {
+      if (typeof entry.summary === "string" && entry.summary) {
+        userMessage(engineMessageId(entryId), at, [{ type: "text", text: entry.summary, synthetic: true, metadata: { branchSummary: true } }], index);
+      }
+      return;
+    }
+    if (entry.type === "custom_message") {
+      const parts = contentParts(entry.content, { synthetic: true, metadata: { customType: entry.customType ?? null } });
+      if (parts.length > 0) userMessage(engineMessageId(entryId), at, parts, index);
+      return;
+    }
+    if (entry.type !== "message" || !isRecord(entry.message)) return;
+    const message = entry.message;
+    const id = engineMessageId(entryId);
+    const created = epochMs(message.timestamp) ?? at;
+    switch (message.role) {
+      case "user": {
+        const parts = contentParts(message.content);
+        if (parts.length > 0) userMessage(id, created, parts, index);
+        return;
+      }
+      case "custom": {
+        const parts = contentParts(message.content, { synthetic: true, metadata: { customType: message.customType ?? null } });
+        if (parts.length > 0) userMessage(id, created, parts, index);
+        return;
+      }
+      case "branchSummary":
+      case "compactionSummary": {
+        if (typeof message.summary === "string" && message.summary) {
+          userMessage(id, created, [{ type: "text", text: message.summary, synthetic: true, metadata: { [message.role]: true } }], index);
+        }
+        return;
+      }
+      case "bashExecution": {
+        // As the engine records a command the user ran: a user message with
+        // its shell-command marker, answered by an assistant message holding
+        // the bash tool call and its output (no model step, no tokens).
+        const command = typeof message.command === "string" ? message.command : "";
+        const output = typeof message.output === "string" ? message.output : "";
+        userMessage(id, created, [{ type: "text", text: USER_SHELL_TEXT, synthetic: true }], index);
+        const shellId = engineMessageId(entryId, "_shell");
+        const shellModel = model ?? nextAssistantModel.get(index) ?? null;
+        const time = created ?? 0;
+        const parts: Array<Record<string, unknown>> = [
+          {
+            type: "tool",
+            callID: `user_bash_${entryId}`,
+            tool: "bash",
+            state: {
+              status: "completed",
+              input: { command },
+              output,
+              metadata: {
+                ...(typeof message.exitCode === "number" ? { exit: message.exitCode } : {}),
+                ...(message.truncated === true ? { truncated: true } : {}),
+                ...(message.cancelled === true ? { cancelled: true } : {}),
+                ...(message.excludeFromContext === true ? { excludeFromContext: true } : {}),
+              },
+              time: { start: time, end: time },
+            },
+          },
+        ];
+        out.push({
+          info: {
+            id: shellId,
+            sessionID: sessionId,
+            role: "assistant",
+            parentID: id,
+            time: { created: time, completed: time },
+            ...(shellModel ? { modelID: shellModel.modelID, providerID: shellModel.providerID } : {}),
+            agent,
+            mode: agent,
+            path: { cwd, root: cwd },
+            cost: 0,
+            tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+            finish: "stop",
+          },
+          parts: parts.map((part, partIndex) => ({ id: partId(shellId, partIndex), sessionID: sessionId, messageID: shellId, ...part })),
+        });
+        return;
+      }
+      case "assistant": {
+        const completed = at ?? created;
+        const parts: Array<Record<string, unknown>> = [{ type: "step-start" }];
+        const changed: string[] = [];
+        const content = Array.isArray(message.content) ? message.content : [];
+        for (const block of content) {
+          if (!isRecord(block)) continue;
+          if (block.type === "thinking") {
+            if (typeof block.thinking === "string" && block.thinking.trim()) {
+              parts.push({ type: "reasoning", text: block.thinking, ...(block.redacted === true ? { metadata: { redacted: true } } : {}) });
+            }
+          } else if (block.type === "text") {
+            if (typeof block.text === "string" && block.text) parts.push({ type: "text", text: block.text });
+          } else if (block.type === "toolCall") {
+            const callId = typeof block.id === "string" ? block.id : "";
+            const input = isRecord(block.arguments) ? block.arguments : {};
+            const result = callId ? results.get(callId) : undefined;
+            const start = (callId ? options.toolStarts?.get(callId) : undefined) ?? completed ?? 0;
+            let state: Record<string, unknown>;
+            if (!result) {
+              state = { status: "running", input, time: { start } };
+            } else {
+              const text = contentText(result.message.content);
+              const attachments = contentParts(result.message.content).filter((part) => part.type === "file");
+              const metadata = toolMetadata(result.message.details);
+              const spawned = block.name === "spawn_agents" ? spawnedSessionIds(result.message.details) : [];
+              const meta = {
+                ...(metadata ?? {}),
+                // The viewer links a tool part to its sub-agent through metadata.sessionId.
+                ...(spawned.length === 1 ? { sessionId: spawned[0] } : {}),
+                ...(spawned.length > 0 ? { sessionIds: spawned } : {}),
+              };
+              const time = { start, end: result.at ?? start };
+              state = result.message.isError === true
+                ? { status: "error", input, error: text, ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}), time }
+                : {
+                    status: "completed",
+                    input,
+                    output: text,
+                    ...(Object.keys(meta).length > 0 ? { metadata: meta } : {}),
+                    ...(attachments.length > 0 ? { attachments } : {}),
+                    time,
+                  };
+              const target = typeof input.path === "string" ? input.path : null;
+              if (result.message.isError !== true && FILE_TOOLS.has(String(block.name)) && target) {
+                const absolute = isAbsolute(target) ? target : resolve(cwd, target);
+                if (!changed.includes(absolute)) changed.push(absolute);
+              }
+            }
+            parts.push({ type: "tool", callID: callId, tool: typeof block.name === "string" ? block.name : "tool", state });
+          }
+        }
+        if (changed.length > 0) parts.push({ type: "patch", files: changed });
+        const finish = finishReason(message.stopReason);
+        const tokens = stepTokens(message.usage);
+        const cost = stepCost(message.usage);
+        parts.push({ type: "step-finish", ...(finish ? { reason: finish } : {}), tokens, cost });
+        if (typeof message.provider === "string" && typeof message.model === "string") {
+          model = model ?? { providerID: message.provider, modelID: message.model };
+        }
+        const error = assistantError(message);
+        const effort = typeof message.providerThinkingLevel === "string" && message.providerThinkingLevel ? message.providerThinkingLevel : variant();
+        out.push({
+          info: {
+            id,
+            sessionID: sessionId,
+            role: "assistant",
+            ...(lastUserId ? { parentID: lastUserId } : {}),
+            time: { created: created ?? 0, completed: completed ?? 0 },
+            ...(typeof message.model === "string" ? { modelID: message.model } : {}),
+            ...(typeof message.provider === "string" ? { providerID: message.provider } : {}),
+            ...(typeof message.responseModel === "string" && message.responseModel && message.responseModel !== message.model
+              ? { responseModelID: message.responseModel }
+              : {}),
+            agent,
+            mode: agent,
+            ...(effort ? { variant: effort } : {}),
+            path: { cwd, root: cwd },
+            cost,
+            tokens,
+            ...(finish ? { finish } : {}),
+            ...(error ? { error } : {}),
+          },
+          parts: parts.map((part, partIndex) => ({ id: partId(id, partIndex), sessionID: sessionId, messageID: id, ...part })),
+        });
+        return;
+      }
+      default:
+        // toolResult messages fill in their calls above; system prompts are
+        // recorded with the prompt's engine.request event.
+        return;
+    }
+  });
+  return out;
+}
+
+/** The active branch of a pi session file's entries: from the last entry up its parent chain. */
+export function branchOfEntries(entries: readonly PiEntry[]): PiEntry[] {
+  const withIds = entries.filter((entry) => entry.type !== "session" && typeof entry.id === "string");
+  if (withIds.length === 0) return [];
+  const byId = new Map(withIds.map((entry) => [entry.id as string, entry]));
+  const branch: PiEntry[] = [];
+  const seen = new Set<string>();
+  let current: PiEntry | undefined = withIds[withIds.length - 1];
+  while (current && !seen.has(current.id as string)) {
+    seen.add(current.id as string);
+    branch.push(current);
+    current = typeof current.parentId === "string" ? byId.get(current.parentId) : undefined;
+  }
+  return branch.reverse();
+}
+
+/** A pi session file (JSON lines) as its header and entries; malformed lines are skipped. */
+export function parseSessionFile(text: string): { header: PiEntry | null; entries: PiEntry[] } {
+  let header: PiEntry | null = null;
+  const entries: PiEntry[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(value)) continue;
+    if (value.type === "session") header ??= value as PiEntry;
+    else entries.push(value as PiEntry);
+  }
+  return { header, entries };
+}
+
+// --- the turn observer's helpers (collector-observer.ts) -------------------------
+
+/** Latest model selection of a turn, as the collector's session.model event records it. */
+export type TurnModel = { provider_id: string | null; model_id: string | null; variant: string | null; agent: string | null };
+
+function optionalText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+/**
+ * The model the turn ran on, read from the turn's first assistant message
+ * (providerID / modelID / mode or agent); the user message that opened the
+ * turn supplies the variant and agent when the assistant record lacks them.
+ * (collector-observer.ts `turnModelFromMessages`.)
+ */
+export function turnModelFromMessages(messages: unknown): TurnModel | null {
+  if (!Array.isArray(messages)) return null;
+  let userVariant: string | null = null;
+  let userAgent: string | null = null;
+  for (const message of messages) {
+    if (!isRecord(message)) continue;
+    const info = isRecord(message.info) ? message.info : message;
+    const model = isRecord(info.model) ? info.model : {};
+    const role = info.role ?? info.type;
+    if (role === "user") {
+      userVariant = optionalText(info.variant) ?? optionalText(model.variant) ?? userVariant;
+      userAgent = optionalText(info.agent) ?? userAgent;
+      continue;
+    }
+    if (role !== "assistant") continue;
+    const providerId = optionalText(info.providerID) ?? optionalText(model.providerID);
+    const modelId = optionalText(info.modelID) ?? optionalText(model.modelID) ?? optionalText(model.id);
+    if (!providerId && !modelId) continue;
+    return {
+      provider_id: providerId,
+      model_id: modelId,
+      variant: optionalText(info.variant) ?? optionalText(model.variant) ?? userVariant,
+      agent: optionalText(info.agent) ?? optionalText(info.mode) ?? userAgent,
+    };
+  }
+  return null;
+}
+
+/** The messages one trace flush carries at most (a trace document holds 16 MiB in all). */
+export const MAX_TURN_MESSAGE_BYTES = 8 * 1024 * 1024;
+/** The messages after the checkpoint kept whole when a settled turn is read, the newest first. */
+export const MAX_BACKLOG_MESSAGE_BYTES = 4 * MAX_TURN_MESSAGE_BYTES;
+
+export type TurnHistory = {
+  /** The messages after the checkpoint, oldest first: the newest of them, up to the budget, plus every older user prompt that fits on its own. */
+  delta: EngineMessage[];
+  /** The JSON size of each message in `delta`. */
+  sizes: number[];
+  /** Messages after the checkpoint left out of `delta` for the budget. */
+  omitted: number;
+};
+
+/**
+ * The part of a session's messages a settled turn records: every message
+ * after the checkpoint message (all of them without one, or when the
+ * checkpoint is not on the branch), newest first up to `budget` bytes, and
+ * once the budget is spent only the user's own prompts. (collector-observer.ts
+ * `readEngineHistory`, over messages already in memory.)
+ */
+export function turnHistory(messages: readonly EngineMessage[], checkpoint: string | undefined, budget = MAX_BACKLOG_MESSAGE_BYTES): TurnHistory {
+  let start = 0;
+  if (checkpoint) {
+    const at = messages.findIndex((message) => message.info.id === checkpoint);
+    if (at >= 0) start = at + 1;
+  }
+  const delta: EngineMessage[] = [];
+  const sizes: number[] = [];
+  let used = 0;
+  let spent = false;
+  let omitted = 0;
+  for (let index = messages.length - 1; index >= start; index -= 1) {
+    const message = messages[index]!;
+    const bytes = Buffer.byteLength(JSON.stringify(message));
+    const user = message.info.role === "user";
+    if (!spent && used + bytes <= budget) {
+      delta.push(message);
+      sizes.push(bytes);
+      used += bytes;
+      continue;
+    }
+    spent = true;
+    if (user && bytes <= budget) {
+      delta.push(message);
+      sizes.push(bytes);
+      continue;
+    }
+    omitted += 1;
+  }
+  return { delta: delta.reverse(), sizes: sizes.reverse(), omitted };
+}
+
+export type MessagePart = { messages: unknown[]; bytes: number };
+
+/**
+ * A settled turn's messages (oldest first) cut into the parts its trace
+ * flushes carry, oldest part first: the newest messages up to `maxBytes` make
+ * the last part, and each earlier part takes the next older ones. One part,
+ * empty, when there are no messages. (collector-observer.ts `messageParts`.)
+ */
+export function messageParts(messages: readonly unknown[], sizes: readonly number[], maxBytes = MAX_TURN_MESSAGE_BYTES): MessagePart[] {
+  const parts: MessagePart[] = [];
+  let part: MessagePart = { messages: [], bytes: 0 };
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const bytes = sizes[index] ?? 0;
+    if (part.messages.length > 0 && part.bytes + bytes > maxBytes) {
+      parts.push(part);
+      part = { messages: [], bytes: 0 };
+    }
+    part.messages.push(messages[index]);
+    part.bytes += bytes;
+  }
+  parts.push(part);
+  for (const each of parts) each.messages.reverse();
+  return parts.reverse();
+}