@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/loop/types.d.ts

@@ -1,15 +1,10 @@
 /**
- * Agent-loop seam — shared types.
- *
- * `runAgent` (run-agent.ts) is a pure-async function: it owns the message
- * loop and nothing else. Durability and streaming are *injected* — a
- * `RunStep` wraps each LLM/tool call (`passthroughStep` for chat, a
- * `DBOS.runStep` wrapper in PR #3) and an `EmitFn` is the flat event sink.
- * The loop body itself knows nothing about DBOS, HTTP, or memory.
+ * The shared types of the agent loop: the definition of an agent, its
+ * messages, and the flat event sink.
  */
 import type { ModelMessage } from "ai";
 import type { ToolCallDetail, ToolOutcome } from "../contracts/chat-events.js";
-import type { ChatStreamEvent } from "../providers/types.js";
+import type { ChatStreamEvent, ProviderOptions } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
 import type { CompactionRules } from "./compaction.js";
 /**
@@ -18,37 +13,37 @@ import type { CompactionRules } from "./compaction.js";
  */
 export type LoopMessage = ModelMessage;
 /**
- * Everything `runAgent` needs to drive one agent: identity, the system
+ * Everything the loop needs to drive one agent: identity, the system
  * prompt, the model id (provenance / metric label — the `ChatProvider`
  * owns the wire model), the tool surface, and the runaway-guard cap.
  */
-export interface AgentDefinition {
+export type AgentDefinition = {
     readonly id: string;
     readonly systemPrompt: string;
     readonly model: string;
     readonly tools: readonly Tool[];
-    /** Runaway guard: at the cap the loop runs up to two masked wrap-up requests, until it gets a text answer. */
+    /** Runaway guard: the cap of model requests of one run. The run ends at the cap. */
     readonly maxIterations: number;
     /** The compaction rules of an agent that a chat thread runs. Absent: the conversation never compacts. */
     readonly compaction?: CompactionRules;
-}
-/**
- * The durability seam. `passthroughStep` (`(_, fn) => fn()`) in the chat
- * route; a `DBOS.runStep` wrapper in PR #3. The loop is agnostic — it only
- * promises a deterministic `name` per call (the step-naming contract).
- */
-export type RunStep = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Provider options that each request of the agent sends, beside the options of
+     * the provider. They are part of the agent, thus each request of a
+     * conversation sends the same options.
+     */
+    readonly providerOptions?: ProviderOptions;
+};
 /**
  * Provenance stamped onto every orchestration event — the agent call
  * chain at the point of emission, derived from the `Session` (see the harness-durable-runtime spec).
  * `callPath` is provenance only; nothing branches on it.
  */
-export interface EventSource {
+export type EventSource = {
     readonly agentId: string;
     readonly callPath: readonly string[];
     /** The id of the tool call that runs this loop. For a data profile, the workflow id of its attempt. */
     readonly invocationId?: string;
-}
+};
 /**
  * Orchestration events the loop emits: iteration boundaries and tool-call
  * lifecycle. Distinct from `ChatStreamEvent` (model-output text deltas) —
@@ -57,12 +52,9 @@ export interface EventSource {
 export type EmitEvent = {
     readonly type: "iteration";
     readonly source: EventSource;
-    /** Zero-based. Wrap-up request `k` has index `maxIterations + k`; a continuation counts from 0. */
+    /** Zero-based. A follow-up request counts from 0. */
     readonly index: number;
-    /**
-     * True when this iteration produced the loop's terminal reply, including
-     * the last wrap-up even when its reply called a tool.
-     */
+    /** True when this request produced the terminal reply of the loop. */
     readonly final: boolean;
 } | {
     readonly type: "tool-started";
@@ -90,16 +82,9 @@ export type EmitEvent = {
     /** The same detail the matching `tool-started` carried. */
     readonly detail?: ToolCallDetail;
     /**
-     * The time around this call's own dispatch, in milliseconds.
-     *
-     * A host cannot measure this itself. The loop emits every
-     * `tool-started` of a round before it dispatches anything, and every
-     * `tool-finished` after the round settles. Thus a host that brackets
-     * the two events measures the round, and each call of a multi-call
-     * round reports the same figure.
-     *
-     * The field is optional, and it is absent when no measurement was
-     * taken. As a result a host can fall back to its own observation.
+     * The time of this call itself, in milliseconds, measured inside its
+     * step. A refused call did not run, thus it has no figure, and a host
+     * can fall back to its own observation.
      */
     readonly durationMs?: number;
 } | {
@@ -107,7 +92,13 @@ export type EmitEvent = {
     readonly type: "message-start";
     readonly source: EventSource;
     readonly messageId: string;
-    readonly role: "user" | "assistant";
+    readonly role: "user";
+    readonly text: string;
+} | {
+    readonly type: "message-start";
+    readonly source: EventSource;
+    readonly messageId: string;
+    readonly role: "assistant";
 };
 /**
  * A UI presentation event a tool streams to chat — an AI-SDK `data-*`
@@ -115,7 +106,7 @@ export type EmitEvent = {
  * synthesized content). The loop and `emit` are agnostic to the payload
  * shape; the typed contract lives in `harness/contracts`.
  */
-export interface ChatDataPart {
+export type ChatDataPart = {
     readonly type: `data-${string}`;
     readonly data: unknown;
     /**
@@ -125,7 +116,7 @@ export interface ChatDataPart {
      * routing envelopes).
      */
     readonly source?: EventSource;
-}
+};
 /**
  * The flat event sink. One function reference flows unchanged through
  * every nesting level. It carries three event categories: orchestration

package/dist/loop/types.js

@@ -1,10 +1,5 @@
 /**
- * Agent-loop seam — shared types.
- *
- * `runAgent` (run-agent.ts) is a pure-async function: it owns the message
- * loop and nothing else. Durability and streaming are *injected* — a
- * `RunStep` wraps each LLM/tool call (`passthroughStep` for chat, a
- * `DBOS.runStep` wrapper in PR #3) and an `EmitFn` is the flat event sink.
- * The loop body itself knows nothing about DBOS, HTTP, or memory.
+ * The shared types of the agent loop: the definition of an agent, its
+ * messages, and the flat event sink.
  */
 export {};

package/dist/memory/ai-sdk-message-storage.d.ts

@@ -118,20 +118,20 @@ declare const CompactionMarkerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     tokensBefore: z.ZodNumber;
     durationMs: z.ZodNumber;
     trigger: z.ZodOptional<z.ZodEnum<{
-        "turn-start": "turn-start";
         "mid-turn": "mid-turn";
+        "turn-start": "turn-start";
     }>>;
     kind: z.ZodLiteral<"summary">;
 }, z.core.$strip>, z.ZodObject<{
-    keptTurns: z.ZodNumber;
     id: z.ZodString;
     tokensBefore: z.ZodNumber;
     durationMs: z.ZodNumber;
     trigger: z.ZodOptional<z.ZodEnum<{
-        "turn-start": "turn-start";
         "mid-turn": "mid-turn";
+        "turn-start": "turn-start";
     }>>;
     kind: z.ZodLiteral<"drop">;
+    keptTurns: z.ZodNumber;
 }, z.core.$strip>], "kind">;
 export type CompactionMarker = z.infer<typeof CompactionMarkerSchema>;
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the input tokens that the provider reported for the request of an assistant message. */
@@ -152,11 +152,11 @@ export declare function dropMarkerMessage(marker: Extract<CompactionMarker, {
 }>): ModelMessage;
 export declare function compactionMarkerOf(message: ModelMessage): CompactionMarker | undefined;
 type LegacyContent = string | Array<Record<string, unknown>>;
-export interface LegacyMessageRow {
+export type LegacyMessageRow = {
     readonly threadId: string;
     readonly seq: number;
     readonly role: string;
     readonly content: LegacyContent;
-}
+};
 export declare function legacyAnthropicToModelMessage(row: LegacyMessageRow): ModelMessage;
 export {};

package/dist/memory/ai-sdk-message-storage.js

@@ -1,5 +1,8 @@
+import { textOf } from "../lib/unknown-text.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { createHash } from "node:crypto";
 import { modelMessageSchema } from "ai";
+import { isJSONValue } from "@ai-sdk/provider";
 import { z } from "zod";
 export const SUPPORTED_AI_SDK_MAJOR = 7;
 export const StoredMessageEnvelopeSchema = z.object({
@@ -52,6 +55,7 @@ export const CONTEXT_KIND_KEY = "contextKind";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the SHA-256 hex hash of the text of a context record. */
 export const CONTEXT_HASH_KEY = "contextHash";
 const CONTEXT_KINDS = ["analysis-context", "run-activity", "working-memory"];
+const ContextKindSchema = z.enum(CONTEXT_KINDS);
 /**
  * A context record: a synthetic `user` message, and no host record, thus it opens no turn and the
  * display does not show it.
@@ -64,17 +68,14 @@ export function contextRecordMessage(kind, text) {
         providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true, [CONTEXT_KIND_KEY]: kind, [CONTEXT_HASH_KEY]: hash } },
     };
 }
-function isContextKind(value) {
-    return CONTEXT_KINDS.some((kind) => kind === value);
-}
 /** The kind and the hash of a context record, or `undefined` for a message that is no record. */
 export function contextRecordOf(message) {
     const harness = message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE];
-    const kind = harness?.[CONTEXT_KIND_KEY];
+    const kind = ContextKindSchema.safeParse(harness?.[CONTEXT_KIND_KEY]);
     const hash = harness?.[CONTEXT_HASH_KEY];
-    if (typeof hash !== "string" || !isContextKind(kind))
+    if (typeof hash !== "string" || !kind.success)
         return undefined;
-    return { kind, hash };
+    return { kind: kind.data, hash };
 }
 /**
  * Return a copy of `message` carrying the interruption marker in the harness namespace.
@@ -232,8 +233,9 @@ function providerOptionsFromLegacy(block) {
     const anthropic = {};
     if (typeof block.signature === "string")
         anthropic.signature = block.signature;
-    if (typeof block.cache_control === "object" && block.cache_control !== null) {
-        anthropic.cacheControl = block.cache_control;
+    const cacheControl = block.cache_control;
+    if (cacheControl !== null && isJSONValue(cacheControl) && parseUnknownRecord(cacheControl) !== undefined) {
+        anthropic.cacheControl = cacheControl;
     }
     return Object.keys(anthropic).length > 0 ? { anthropic } : undefined;
 }
@@ -268,9 +270,9 @@ export function legacyAnthropicToModelMessage(row) {
         }
         const unrepresentable = content.find((block) => !(block.type === "text" && typeof block.text === "string"));
         if (unrepresentable !== undefined) {
-            throw new Error(`Legacy user row ${row.threadId}/${row.seq} contains unrepresentable block type "${String(unrepresentable.type)}"; failing rather than writing a lossy envelope`);
+            throw new Error(`Legacy user row ${row.threadId}/${row.seq} contains unrepresentable block type "${textOf(unrepresentable.type)}"; failing rather than writing a lossy envelope`);
         }
-        const userContent = content.map((block) => ({ type: "text", text: String(block.text), providerOptions: providerOptionsFromLegacy(block) }));
+        const userContent = content.map((block) => ({ type: "text", text: textOf(block.text), providerOptions: providerOptionsFromLegacy(block) }));
         return {
             role: "user",
             content: userContent,
@@ -304,7 +306,7 @@ export function legacyAnthropicToModelMessage(row) {
             }
             // Any other block (e.g. redacted_thinking) may carry signed provider
             // data required for continuation; fail the row instead of dropping it.
-            throw new Error(`Legacy assistant row ${row.threadId}/${row.seq} contains unrepresentable block type "${String(block.type)}"; failing rather than writing a lossy envelope`);
+            throw new Error(`Legacy assistant row ${row.threadId}/${row.seq} contains unrepresentable block type "${textOf(block.type)}"; failing rather than writing a lossy envelope`);
         }
         return {
             role: "assistant",

package/dist/memory/card-builders.d.ts

@@ -14,11 +14,11 @@
  * under the part `type` directly.
  */
 import { type ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import { type DbError } from "../lib/db-result.js";
 import type { PlanPart } from "../contracts/chat-parts.js";
-import { type PlanRecord } from "../state/index.js";
-export interface PlanCardData {
+import { type PlanRecord, type PlanRowQuerier } from "../state/index.js";
+export type PlanCardData = {
     id: string;
     planId: string;
     parentPlanId?: string;
@@ -27,19 +27,19 @@ export interface PlanCardData {
     analytical_narrative: unknown;
     omicsType: unknown;
     omicsSubtype: unknown;
-}
-export interface PresentationCardData {
+};
+export type PresentationCardData = {
     id: string;
     title?: string;
     content: Record<string, unknown>;
-}
-export interface RunCardData {
+};
+export type RunCardData = {
     id: string;
     runId: string;
     planId: string;
     title: string;
     stepCount: number;
-}
+};
 /** Build the `data-plan` payload of a stored plan record. `null` when the
  *  document no longer parses. An explicit `title` overrides the plan title. */
 export declare function planCardOf(record: PlanRecord, title?: string): PlanCardData | null;
@@ -51,14 +51,14 @@ export declare function planPartOf(record: PlanRecord): PlanPart | null;
 /** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
  *  the plan is missing or no longer parses (absence is NOT an error) — the
  *  caller falls back to a chip. */
-export declare function buildPlanCardData(pool: Pool, planId: string, analysisId: string, title?: string): ResultAsync<PlanCardData | null, DbError>;
+export declare function buildPlanCardData(pool: PlanRowQuerier, planId: string, analysisId: string, title?: string): ResultAsync<PlanCardData | null, DbError>;
 /** Build the `data-run-card` payload for a started analysis run. Loads the
  *  plan (for `title` + `stepCount`) the same way `buildPlanCardData` does. The
  *  live emit path passes the freshly-minted `runId`; the reconstruct-on-read
  *  path omits it and the most recent run for `(analysisId, planId)` is looked
  *  up from `cortex_runs`. Null when the plan or run cannot be resolved — the
  *  caller falls back to a chip. */
-export declare function buildRunCardData(pool: Pool, opts: {
+export declare function buildRunCardData(pool: Querier, opts: {
     planId: string;
     analysisId: string;
     runId?: string;
@@ -82,17 +82,17 @@ export declare function buildPresentationCardData(input: Record<string, unknown>
 /** Max files a `show_file` group may reference; multiple render as a gallery. */
 export declare const MAX_FILES = 10;
 /** One referenced file in a `data-file-reference` card. */
-export interface FileReferenceEntryData {
+export type FileReferenceEntryData = {
     path: string;
     runId?: string;
     caption?: string;
-}
+};
 /** The `data-file-reference` payload: a group of referenced analysis artifacts. */
-export interface FileReferenceCardData {
+export type FileReferenceCardData = {
     id: string;
     title?: string;
     files: FileReferenceEntryData[];
-}
+};
 /** Extracts `runId` from paths shaped `runs/{runId}/...`; undefined otherwise. */
 export declare function deriveRunId(path: string): string | undefined;
 /** Stable dedup key over sorted paths + optional title. */

package/dist/memory/card-builders.js

@@ -16,15 +16,13 @@
 import { createHash } from "node:crypto";
 import { okAsync } from "neverthrow";
 import { tryQuery } from "../lib/db-result.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { PlanPartSchema } from "../contracts/schemas/chat-parts.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { loadPlan, loadPlanRecord } from "../state/index.js";
 import { parseStructureUrl } from "../contracts/structure-source.js";
 import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
 import { validatePath } from "../tools/lib/path-validation.js";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** Deterministic presentation id — must match `show_user`'s. */
 function presentationId(input) {
     const hash = createHash("sha256")
@@ -43,16 +41,18 @@ export function planCardOf(record, title) {
     // Explicit `show_plan({ title })` overrides; otherwise default to the
     // planner-set plan title so both cards share one source.
     const heading = title ?? parsed.data.title;
-    return {
+    const card = {
         id,
         planId: record.planId,
-        ...(record.parentPlanId !== null ? { parentPlanId: record.parentPlanId } : {}),
-        ...(heading !== undefined ? { title: heading } : {}),
+        title: heading,
         steps: parsed.data.steps,
         analytical_narrative: parsed.data.analytical_narrative,
         omicsType: parsed.data.omicsType,
         omicsSubtype: parsed.data.omicsSubtype,
     };
+    if (record.parentPlanId !== null)
+        card.parentPlanId = record.parentPlanId;
+    return card;
 }
 /** The `data-plan` part of a stored plan record, with the title of the plan. The
  *  part schema drops each key that it does not name, thus the part equals the
@@ -139,8 +139,9 @@ export function buildPresentationCardData(input) {
             return null;
         content = { kind, format: source.format, url: source.url, provider: source.provider, accession: source.accession, version: source.version };
     }
-    else if (kind === "echart" && isRecord(rest.spec)) {
-        content = { kind, ...rest, spec: normalizeEchartSpec(rest.spec, { title: cardTitle }) };
+    else if (kind === "echart") {
+        const spec = parseUnknownRecord(rest.spec);
+        content = spec !== undefined ? { kind, ...rest, spec: normalizeEchartSpec(spec, { title: cardTitle }) } : { kind, ...rest };
     }
     else {
         // Every other kind (and an echart the model called without a `spec`) is carried through
@@ -149,7 +150,7 @@ export function buildPresentationCardData(input) {
     }
     return {
         id: presentationId(input),
-        ...(cardTitle !== undefined ? { title: cardTitle } : {}),
+        title: cardTitle,
         content,
     };
 }
@@ -158,8 +159,9 @@ export const MAX_FILES = 10;
 /** Extracts `runId` from paths shaped `runs/{runId}/...`; undefined otherwise. */
 export function deriveRunId(path) {
     const segments = path.split("/");
-    if (segments.length >= 2 && segments[0] === "runs" && segments[1].length > 0) {
-        return segments[1];
+    const runId = segments[1];
+    if (segments.length >= 2 && segments[0] === "runs" && runId !== undefined && runId.length > 0) {
+        return runId;
     }
     return undefined;
 }
@@ -185,7 +187,9 @@ export function buildFileReferenceCardData(input) {
         return null;
     const files = [];
     for (const raw of rawFiles) {
-        const file = (raw ?? {});
+        const file = parseUnknownRecord(raw);
+        if (file === undefined)
+            return null;
         const path = typeof file.path === "string" ? file.path : "";
         if (validatePath(path) !== null)
             return null;
@@ -193,10 +197,10 @@ export function buildFileReferenceCardData(input) {
         const caption = typeof file.caption === "string" ? file.caption : undefined;
         files.push({
             path,
-            ...(runId !== undefined ? { runId } : {}),
-            ...(caption !== undefined ? { caption } : {}),
+            runId,
+            caption,
         });
     }
     const id = `pres-${fileGroupHash(files.map((f) => f.path), title)}`;
-    return { id, ...(title !== undefined ? { title } : {}), files };
+    return { id, title, files };
 }

package/dist/memory/conversation-display-recorder.d.ts

@@ -1,8 +1,18 @@
 import type { ModelMessage } from "ai";
+import type { ChatFrame } from "../contracts/chat-events.js";
 import type { EmitFn } from "../loop/types.js";
 import { type ConversationUIMessage } from "./conversation-display-storage.js";
-export interface ConversationDisplayRecorder {
+export type ConversationDisplayRecorder = {
     readonly emit: EmitFn;
+    /**
+     * Record one frame that reached the stream of the turn by another path, and forward nothing. A turn workflow
+     * records each frame of its stream with it, the frames that a replay of a tool step gives again included.
+     */
+    observe(frame: ChatFrame): void;
+    /** The id of the assistant message that the next parts go to. A marker of a round gives the next message a new id. */
+    assistantMessageId(): string;
+    /** The id of the user message of the turn. */
+    userMessageId(): string;
     /** The user message of the turn. */
     takeOpening(): ConversationUIMessage[];
     /** The assistant message of one round, when the recorder got parts after the last take, and the divider of a marker of the round. */
@@ -12,15 +22,23 @@ export interface ConversationDisplayRecorder {
         readonly fallbackText?: string;
         readonly interrupted?: boolean;
     }): ConversationUIMessage[];
-}
-export interface ConversationDisplayRecorderOptions {
+};
+export type ConversationDisplayRecorderOptions = {
     readonly userText: string;
     /** The root agent of the turn. Its call path is `[agentId]`, and an event with a longer path is from a sub-agent. */
     readonly agentId: string;
     readonly sink: EmitFn;
     /** The clock for the times of the sub-agent activity, in milliseconds. The default is the wall clock. */
     readonly now?: () => number;
-}
+    /**
+     * The ids of the messages of the turn: the user message, and the assistant message after each marker, from 0 on.
+     * A turn workflow gives ids from its turn id, thus a replay gives the same ids. The default is a random id.
+     */
+    readonly messageIds?: {
+        readonly user: string;
+        readonly assistant: (index: number) => string;
+    };
+};
 /**
  * Record the display of a turn through the same translation path as a live surface: each event becomes a
  * frame (`toChatFrame`), and the frames build the messages of the round (`applyChatFrame`). Only a part that

package/dist/memory/conversation-display-recorder.js

@@ -3,15 +3,19 @@ import { applyChatFrame, checkChatPart, isRootFrame, toChatFrame } from "../cont
 import { PART_REGISTRY } from "../contracts/part-registry.js";
 import { createSubAgentActivityTracker } from "../contracts/subagent-activity.js";
 import { compactionExchangeOf, compactionMarkerOf } from "./ai-sdk-message-storage.js";
-import { conversationDisplayPart } from "./conversation-display-storage.js";
+import { conversationDisplayPart, isStoredSourcePart } from "./conversation-display-storage.js";
 function jsonCopy(value) {
-    return JSON.parse(JSON.stringify(value));
+    return structuredClone(value);
 }
+const DURABLE_CONVERSATION_PART_TYPES = new Set(Object.entries(PART_REGISTRY)
+    .filter(([, descriptor]) => descriptor.emitter === "conversation" && descriptor.consumer === "conversation" && !descriptor.transient)
+    .map(([type]) => type));
 function durableConversationType(type) {
-    if (!Object.hasOwn(PART_REGISTRY, type))
-        return false;
-    const descriptor = PART_REGISTRY[type];
-    return descriptor.emitter === "conversation" && descriptor.consumer === "conversation" && !descriptor.transient;
+    return DURABLE_CONVERSATION_PART_TYPES.has(type);
+}
+/** Each chat event type is named without the `data-` prefix, thus a `data-` frame is a part frame. */
+function isPartFrame(frame) {
+    return frame.type.startsWith("data-");
 }
 /** The checked part of a data frame, copied at receipt, because the emitter keeps its own reference to the payload. */
 function recordedPart(frame) {
@@ -28,6 +32,8 @@ function displayParts(parts) {
     return parts.flatMap((part) => {
         if (part.type === "text")
             return part.text.length === 0 ? [] : [{ type: "text", text: part.text, state: "done" }];
+        if (!isStoredSourcePart(part))
+            return [];
         if (part.type === "data-ask" && part.status === "pending")
             return [conversationDisplayPart({ ...part, status: "aborted" })];
         return [conversationDisplayPart(part)];
@@ -47,14 +53,16 @@ function assistantText(messages) {
 }
 /** The divider of a compaction marker: a `system` message with the part at the final status of the compaction. */
 function compactionDivider(marker) {
-    const part = conversationDisplayPart({
+    const compaction = {
         type: "data-compaction",
         id: marker.id,
         status: marker.kind === "summary" ? "done" : "failed",
         tokensBefore: marker.tokensBefore,
         durationMs: marker.durationMs,
-        ...(marker.trigger === undefined ? {} : { trigger: marker.trigger }),
-    });
+    };
+    if (marker.trigger !== undefined)
+        compaction.trigger = marker.trigger;
+    const part = conversationDisplayPart(compaction);
     return { id: marker.id, role: "system", parts: [part] };
 }
 /**
@@ -64,8 +72,10 @@ function compactionDivider(marker) {
  */
 export function createConversationDisplayRecorder(options) {
     // One id for each message of the turn, thus the rounds of a turn replay as one assistant message.
-    const userMessageId = randomUUID();
-    let assistantMessageId = randomUUID();
+    const userMessageId = options.messageIds?.user ?? randomUUID();
+    let assistantIndex = 0;
+    const assistantIdAt = (index) => options.messageIds?.assistant(index) ?? randomUUID();
+    let assistantMessageId = assistantIdAt(assistantIndex);
     let userAnnounced = false;
     let announcedAssistantId;
     const rootSource = { agentId: options.agentId, callPath: [options.agentId] };
@@ -89,7 +99,11 @@ export function createConversationDisplayRecorder(options) {
     }
     function record(event) {
         const frame = toChatFrame(event, rootSource);
-        if (frame === null)
+        if (frame !== null)
+            observe(frame);
+    }
+    function observe(frame) {
+        if (finished)
             return;
         // The tracker reads the frames of the sub-agents, and `applyChatFrame` ignores them.
         const activity = subAgentActivity.track(frame, now());
@@ -97,27 +111,29 @@ export function createConversationDisplayRecorder(options) {
             apply(recordedPart(activity));
         if (!isRootFrame(frame))
             return;
-        if (frame.type.startsWith("data-")) {
-            // Each chat event type is named without the `data-` prefix, thus a `data-` frame is a part frame.
+        if (isPartFrame(frame)) {
             if (durableConversationType(frame.type))
                 apply(recordedPart(frame));
             return;
         }
         apply(frame);
     }
-    function messageStart(messageId, role) {
-        return { type: "message-start", messageId, role, source: rootSource };
+    function userMessageStart() {
+        return { type: "message-start", messageId: userMessageId, role: "user", text: options.userText, source: rootSource };
+    }
+    function assistantMessageStart(messageId) {
+        return { type: "message-start", messageId, role: "assistant", source: rootSource };
     }
     /** The `message-start` of each id that the sink did not get yet. */
     function announcements() {
         const starts = [];
         if (!userAnnounced) {
             userAnnounced = true;
-            starts.push(messageStart(userMessageId, "user"));
+            starts.push(userMessageStart());
         }
         if (announcedAssistantId !== assistantMessageId) {
             announcedAssistantId = assistantMessageId;
-            starts.push(messageStart(assistantMessageId, "assistant"));
+            starts.push(assistantMessageStart(assistantMessageId));
         }
         return starts;
     }
@@ -131,7 +147,7 @@ export function createConversationDisplayRecorder(options) {
             return options.sink(event);
         // The calls start in the order of the stream with no await between them: a later emit that its caller does
         // not await, for example a text delta, must not reach the sink before them.
-        return Promise.all([...starts, event].map((next) => options.sink(next))).then(() => undefined);
+        return Promise.all([...starts, event].map((next) => Promise.resolve(options.sink(next)))).then(() => undefined);
     };
     function takeOpening() {
         return [{ id: userMessageId, role: "user", parts: [{ type: "text", text: options.userText, state: "done" }] }];
@@ -146,7 +162,8 @@ export function createConversationDisplayRecorder(options) {
         if (marker !== undefined) {
             taken.push(compactionDivider(marker));
             // The divider splits the turn into two assistant messages of the replay, and two messages must not share an id.
-            assistantMessageId = randomUUID();
+            assistantIndex += 1;
+            assistantMessageId = assistantIdAt(assistantIndex);
         }
         return taken;
     }
@@ -159,14 +176,16 @@ export function createConversationDisplayRecorder(options) {
         const messages = takeOpening();
         const parts = displayParts(roundParts());
         if (parts.length > 0) {
-            messages.push({
+            const message = {
                 id: assistantMessageId,
                 role: "assistant",
-                ...(finishOptions?.interrupted ? { metadata: { interrupted: true } } : {}),
                 parts: jsonCopy(parts),
-            });
+            };
+            if (finishOptions?.interrupted)
+                message.metadata = { interrupted: true };
+            messages.push(message);
         }
         return messages;
     }
-    return { emit, takeOpening, takeRound, finish };
+    return { emit, observe, assistantMessageId: () => assistantMessageId, userMessageId: () => userMessageId, takeOpening, takeRound, finish };
 }

package/dist/memory/conversation-display-replay.js

@@ -46,10 +46,11 @@ export function storedMessagesToChat(messages) {
             // spreads the message acquires one that overwrites a real value. `Date`
             // does not survive the JSON crossing typed, hence the ISO string here.
             const createdAt = row.createdAt === undefined ? {} : { createdAt: row.createdAt.toISOString() };
-            const author = row.author === undefined ? {} : { author: row.author };
             groupLast = undefined;
             for (const message of conversationUIToChatMessages(row.displayEnvelope.messages)) {
-                const stamped = { ...message, ...createdAt, ...(message.role === "user" ? author : {}) };
+                const stamped = { ...message, ...createdAt };
+                if (message.role === "user" && row.author !== undefined)
+                    stamped.author = row.author;
                 const previous = out.at(-1);
                 // The merged message keeps the creation time of its first round.
                 if (stamped.role === "assistant" && previous?.role === "assistant" && previous.id === stamped.id)