@inflexa-ai/harness 0.15.1 → 0.16.0

package/dist/contracts/chat-events.d.ts

@@ -37,6 +37,22 @@ export interface TextDeltaEvent {
  * admit the impossible "not an error, but denied".
  */
 export type ToolOutcome = "ok" | "error" | "denied";
+/**
+ * How a RECORDED call ended — the three live outcomes plus `incomplete`.
+ *
+ * `incomplete` is the state a live event cannot carry and a record cannot avoid:
+ * the harness observed a dispatch and no completion, because the turn was cut off
+ * mid-call. A `tool-finished` is never incomplete, which is why this widens
+ * {@link ToolOutcome} rather than replacing it.
+ *
+ * It is a fourth value of ONE field rather than a second field beside the outcome,
+ * for the same reason the outcome is three-way instead of `isError` plus `denied`:
+ * a call has exactly one terminal state, and splitting that across two fields both
+ * admits impossible pairs and leaves every consumer to invent the meaning of the
+ * combination. A consumer switches on this one field, and a consumer that forgets
+ * a case fails to compile rather than silently reporting a success.
+ */
+export type ToolCallOutcome = ToolOutcome | "incomplete";
 /**
  * One line naming what a tool call is doing, produced by the tool's own
  * `describeCall` hook and normalized at the emit site.

package/dist/contracts/message.d.ts

@@ -6,7 +6,7 @@
  * discriminant is `type`, so `switch (part.type) { case "data-report-preview": ... }`
  * narrows the union member without any `as` cast.
  */
-import type { ToolCallDetail, ToolOutcome } from "./chat-events.js";
+import type { ToolCallDetail, ToolCallOutcome } from "./chat-events.js";
 import type { CortexChatPart } from "./chat-parts.js";
 import type { TokenUsageRollup } from "./usage.js";
 /** A plain assistant/user text run. */
@@ -17,20 +17,25 @@ export interface TextPart {
 /**
  * A tool call observed during the turn (or replayed from history).
  *
- * Live frames collapse a `tool-started`+`tool-finished` pair into a single
- * part keyed by `toolCallId`. History-replayed calls always arrive with
- * `status: "finished"`.
+ * Live frames collapse a `tool-started`+`tool-finished` pair into a single part
+ * keyed by `toolCallId`.
+ *
+ * `outcome` carries the call's whole terminal state in one field, and its absence
+ * means exactly one thing: the call is still in flight. A REPLAYED call therefore
+ * always has one — a turn cut off mid-call replays as `incomplete`, not as an
+ * absent outcome a reader would have to interpret. That is what lets a consumer
+ * switch on this single field and be told by the compiler when it misses a case,
+ * rather than each host inventing what "no outcome" means and disagreeing.
  */
 export interface ToolCallPart {
     type: "tool-call";
     toolCallId: string;
     toolName: string;
-    status: "started" | "finished";
     /**
-     * How the call ended. Absent while `status` is `"started"` — the outcome is
-     * not known yet. See {@link ToolOutcome}.
+     * How the call ended. Absent ONLY while the call is in flight on a live
+     * surface; every replayed call carries one. See {@link ToolCallOutcome}.
      */
-    outcome?: ToolOutcome;
+    outcome?: ToolCallOutcome;
     /** See {@link ToolCallDetail}. Absent when no detail was produced. */
     detail?: ToolCallDetail;
 }

package/dist/contracts/schemas/chat-events.d.ts

@@ -20,6 +20,13 @@ export declare const ToolOutcomeSchema: z.ZodEnum<{
     ok: "ok";
     denied: "denied";
 }>;
+/** Mirrors `ToolCallOutcome` — the live three plus the record-only `incomplete`. */
+export declare const ToolCallOutcomeSchema: z.ZodEnum<{
+    error: "error";
+    ok: "ok";
+    denied: "denied";
+    incomplete: "incomplete";
+}>;
 export declare const ToolStartedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"tool-started">;
     toolUseId: z.ZodString;

package/dist/contracts/schemas/chat-events.js

@@ -14,6 +14,8 @@ export const TextDeltaEventSchema = z.object({
 });
 /** Mirrors the `ToolOutcome` union — three states, never a boolean. */
 export const ToolOutcomeSchema = z.enum(["ok", "error", "denied"]);
+/** Mirrors `ToolCallOutcome` — the live three plus the record-only `incomplete`. */
+export const ToolCallOutcomeSchema = z.enum(["ok", "error", "denied", "incomplete"]);
 export const ToolStartedEventSchema = z.object({
     type: z.literal("tool-started"),
     toolUseId: z.string(),

package/dist/index.d.ts

@@ -57,16 +57,15 @@ export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
-export { createThreadHistory } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
+export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome, ConversationTurn } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
-export { contentToCortexMessages } from "./memory/content-to-cortex.js";
-export type { ContentToCortexOptions } from "./memory/content-to-cortex.js";
-export { createCardResolver } from "./memory/reconstruct-cards.js";
-export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";
-export { createDetailResolver } from "./tools/detail-resolver.js";
-export type { ToolDetailResolver } from "./tools/detail-resolver.js";
-export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
+export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
+export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions } from "./memory/conversation-display-recorder.js";
+export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
+export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMessage, StoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
+export { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
+export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
 export type { TokenUsageRollup } from "./contracts/usage.js";
 export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, PreviewPart, DataPreviewFailedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";

package/dist/index.js

@@ -80,15 +80,13 @@ export { toProviderError, isProviderError } from "./providers/errors.js";
 // gets live token streaming out of the otherwise non-streaming loop.
 export { createStreamingChat } from "./providers/streaming-chat.js";
 // Conversation turn + thread memory — the transport-free halves of one chat
-// turn a same-process host drives itself. `prepareChatTurn` assembles the
-// message array (thread-ownership resolution, title seed, analysis-context
-// injection); the caller runs `runAgent` with its own `emit`; `appendTurn`
-// (`createThreadHistory`) persists the turn. `createThreadStore` owns thread
-// metadata (create/list/title). `contentToCortexMessages` + `createCardResolver`
-// reconstruct display cards from a persisted thread on reload.
+// turn a same-process host drives itself. `prepareChatTurn` assembles the model
+// message array; `createConversationDisplayRecorder` records the independently
+// replayable UI projection while forwarding live events; `appendTurn` persists
+// both atomically. `createThreadStore` owns thread metadata (create/list/title).
 export { prepareChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export { createThreadHistory } from "./memory/thread-history.js";
+export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 // The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's
 // outcome) into a thread through `appendTurn`, and needs a message the model reads but that is not
 // user input — which is exactly what the marker denotes. The constructor is exported rather than
@@ -96,16 +94,19 @@ export { createThreadHistory } from "./memory/thread-history.js";
 // (`isGenuineUserStart` and its SQL twin) would then fail to recognise; `isSyntheticUserMessage`
 // lets a host renderer tell such a message apart from a genuine user turn on the way back out.
 // `syntheticRecordMessage` is the one a HOST reaches for: equally non-turn-opening, but rendered —
-// the display reconstruction emits it as a `system` message rather than dropping it as loop
-// machinery, so an appended run outcome is visible in the transcript instead of silently absent.
+// it displays as a `system` message rather than being dropped as loop machinery, so an appended run
+// outcome is visible in the transcript instead of silently absent. `conversationRecordTurn` wraps it
+// as a complete append (model message plus its display projection), which is what a host should
+// reach for: a record appended without one would be stored but never replayed.
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
-export { contentToCortexMessages } from "./memory/content-to-cortex.js";
-export { createCardResolver } from "./memory/reconstruct-cards.js";
-// The call-detail resolver, the reload counterpart of the `describeCall` hook a
-// tool declares. Built over a tool list the HOST supplies — its own composed
-// roster, `HarnessRuntime.conversationAgent.tools` — because tools contributed
-// through the host-tools seam are invisible to any map the harness holds.
-export { createDetailResolver } from "./tools/detail-resolver.js";
+export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
+export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
+// The transcript read. Every append persists what it displayed, so replay concatenates stored
+// projections and consults nothing else — no tool names, no card builders, no workspace or database
+// lookups. The migration renderer that DOES consult those (`content-to-cortex.js`,
+// `reconstruct-cards.js`, `tools/detail-resolver.js`) is deliberately absent from this barrel: it
+// runs once per legacy row at startup and has no runtime caller.
+export { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 // Embedder runtime surface — what a same-process host needs to run durable
 // workflows itself: the DBOS lifecycle, per-workflow registration + triggers,

package/dist/memory/content-to-cortex.d.ts

@@ -1,26 +1,27 @@
 /**
- * Converter: stored AI SDK model messages → wire `CortexMessage[]`.
+ * The MIGRATION renderer: stored AI SDK model messages → `CortexMessage[]`.
  *
- * The display read (`ThreadHistory.loadPage`) returns rows whose `content`
- * is the AI SDK `ModelMessage` that `appendTurn` persisted. This maps each
- * row to a `CortexMessage` for the chat wire:
+ * This is how a conversation written before display projections were persisted
+ * is rendered ONCE, at startup, so it can be frozen into a display envelope
+ * (`conversation-display-backfill.ts`). It is not a runtime read path — the
+ * runtime reads the stored projection (`conversation-display-replay.ts`) and
+ * never consults a tool name, a card builder, or the filesystem.
+ *
+ * Everything it does is inference from a transcript that was never meant to
+ * carry display, which is why it belongs to the migration and nothing else:
  *
  *   - text part         → text part
  *   - tool-call part    → a reconstructed display card (`data-plan`,
  *                         `data-presentation`) when `resolveCard` recognises
- *                         the tool, else a generic tool-call part
+ *                         the tool, else a generic tool-call part whose detail
+ *                         `resolveDetail` recomputes from the persisted input
  *   - everything else   → dropped (reasoning, tool-result, etc.) — the UI
  *                         does not render them
  *
- * Display cards are emitted live over the chat SSE stream but never persisted
- * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload,
- * and `resolveDetail` rebuilds each call's one-line detail the same way.
- *
  * A `tool-result` block is not rendered, but it is not ignored either: it is the
  * only record of how its call ended. The blocks are indexed by `toolCallId`
  * before conversion so each tool-call part can report its own outcome — without
- * that pass every reloaded call reported success, including the failed ones.
+ * that pass every migrated call would report success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered

package/dist/memory/content-to-cortex.js

@@ -1,26 +1,27 @@
 /**
- * Converter: stored AI SDK model messages → wire `CortexMessage[]`.
+ * The MIGRATION renderer: stored AI SDK model messages → `CortexMessage[]`.
  *
- * The display read (`ThreadHistory.loadPage`) returns rows whose `content`
- * is the AI SDK `ModelMessage` that `appendTurn` persisted. This maps each
- * row to a `CortexMessage` for the chat wire:
+ * This is how a conversation written before display projections were persisted
+ * is rendered ONCE, at startup, so it can be frozen into a display envelope
+ * (`conversation-display-backfill.ts`). It is not a runtime read path — the
+ * runtime reads the stored projection (`conversation-display-replay.ts`) and
+ * never consults a tool name, a card builder, or the filesystem.
+ *
+ * Everything it does is inference from a transcript that was never meant to
+ * carry display, which is why it belongs to the migration and nothing else:
  *
  *   - text part         → text part
  *   - tool-call part    → a reconstructed display card (`data-plan`,
  *                         `data-presentation`) when `resolveCard` recognises
- *                         the tool, else a generic tool-call part
+ *                         the tool, else a generic tool-call part whose detail
+ *                         `resolveDetail` recomputes from the persisted input
  *   - everything else   → dropped (reasoning, tool-result, etc.) — the UI
  *                         does not render them
  *
- * Display cards are emitted live over the chat SSE stream but never persisted
- * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload,
- * and `resolveDetail` rebuilds each call's one-line detail the same way.
- *
  * A `tool-result` block is not rendered, but it is not ignored either: it is the
  * only record of how its call ended. The blocks are indexed by `toolCallId`
  * before conversion so each tool-call part can report its own outcome — without
- * that pass every reloaded call reported success, including the failed ones.
+ * that pass every migrated call would report success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered
@@ -50,14 +51,16 @@ function indexOutcomes(messages) {
 }
 function genericToolCall(block, outcomes, resolveDetail) {
     // No paired result is the shape of a transcript whose `tool` row was never
-    // appended (an aborted turn). Nothing failed, so `ok` is the honest report.
-    const outcome = outcomes.get(block.toolCallId) ?? "ok";
+    // appended — an aborted turn. That is not a success: the call was dispatched and
+    // never completed, which is exactly `incomplete`. Reporting `ok` would claim a
+    // result the tool never returned, and it is the one outcome the transcript
+    // genuinely cannot supply, so it is named rather than guessed at.
+    const outcome = outcomes.get(block.toolCallId) ?? "incomplete";
     const detail = resolveDetail?.(block.toolName, block.input);
     return {
         type: "tool-call",
         toolCallId: block.toolCallId,
         toolName: block.toolName,
-        status: "finished",
         outcome,
         ...(detail === undefined ? {} : { detail }),
     };

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

@@ -0,0 +1,25 @@
+import type { Pool } from "pg";
+import type { Tool } from "../tools/define-tool.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+export interface ConversationDisplayBackfillDeps {
+    readonly pool: Pool;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /**
+     * The conversation agent's composed roster, used to recover each legacy call's
+     * one-line detail from its persisted input. Tools contributed through the
+     * host-tools seam are invisible to any map the harness holds on its own, so the
+     * list has to come from the assembled runtime.
+     */
+    readonly tools: readonly Tool[];
+    readonly batchSize?: number;
+}
+/**
+ * Freeze the migration renderer's output into display envelopes, once per legacy
+ * turn, so the runtime read path never has to reconstruct anything.
+ *
+ * Missing mutable resources degrade to a generic, cardless display — a workspace
+ * that has moved is normal historical absence, not a fault. Malformed stored rows
+ * and database faults remain startup-fatal: a turn that cannot be migrated must
+ * not be silently skipped and then read as if it had no display.
+ */
+export declare function backfillConversationDisplayEnvelopes(deps: ConversationDisplayBackfillDeps): Promise<number>;

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

@@ -0,0 +1,97 @@
+import { createDetailResolver } from "../tools/detail-resolver.js";
+import { envelopeDisplayMessages, cortexMessagesToConversationUI, parseStoredDisplayEnvelope } from "./conversation-display-storage.js";
+import { parseStoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+import { contentToCortexMessages } from "./content-to-cortex.js";
+import { createCardResolver } from "./reconstruct-cards.js";
+const BATCH_SIZE = 100;
+const GENUINE_USER_SQL = `m.message_envelope->'message'->>'role' = 'user'
+  AND m.message_envelope->'message'->'providerOptions'->'cortex'->>'synthetic' IS DISTINCT FROM 'true'`;
+/**
+ * Freeze the migration renderer's output into display envelopes, once per legacy
+ * turn, so the runtime read path never has to reconstruct anything.
+ *
+ * Missing mutable resources degrade to a generic, cardless display — a workspace
+ * that has moved is normal historical absence, not a fault. Malformed stored rows
+ * and database faults remain startup-fatal: a turn that cannot be migrated must
+ * not be silently skipped and then read as if it had no display.
+ */
+export async function backfillConversationDisplayEnvelopes(deps) {
+    const batchSize = Math.max(1, deps.batchSize ?? BATCH_SIZE);
+    const resolveDetail = createDetailResolver(deps.tools);
+    let migrated = 0;
+    let validationOffset = 0;
+    for (;;) {
+        const { rows } = await deps.pool.query(`SELECT thread_id, seq::text AS seq, display_envelope
+               FROM messages
+              WHERE display_envelope IS NOT NULL
+              ORDER BY thread_id, seq
+              LIMIT $1 OFFSET $2`, [batchSize, validationOffset]);
+        await Promise.all(rows.map((row) => parseStoredDisplayEnvelope(row.display_envelope, `${row.thread_id}/${row.seq}/display`)));
+        if (rows.length < batchSize)
+            break;
+        validationOffset += rows.length;
+    }
+    for (;;) {
+        const { rows: heads } = await deps.pool.query(`SELECT m.thread_id, m.seq::text AS seq, t.analysis_id
+               FROM messages m
+               LEFT JOIN cortex_analysis_threads t ON t.thread_id = m.thread_id
+              WHERE ${GENUINE_USER_SQL}
+                AND m.display_envelope IS NULL
+              ORDER BY m.thread_id, m.seq
+              LIMIT $1`, [batchSize]);
+        if (heads.length === 0)
+            return migrated;
+        for (const head of heads) {
+            const { rows } = await deps.pool.query(`SELECT m.seq::text AS seq, m.message_envelope
+                   FROM messages m
+                  WHERE m.thread_id = $1
+                    AND m.seq >= $2::bigint
+                    AND m.seq < COALESCE(
+                      (
+                        SELECT MIN(next.seq)
+                          FROM messages next
+                         WHERE next.thread_id = m.thread_id
+                           AND next.seq > $2::bigint
+                           AND next.message_envelope->'message'->>'role' = 'user'
+                           AND next.message_envelope->'message'->'providerOptions'->'cortex'->>'synthetic' IS DISTINCT FROM 'true'
+                      ),
+                      9223372036854775807
+                    )
+                  ORDER BY m.seq`, [head.thread_id, head.seq]);
+            const stored = rows.map((row) => {
+                const envelope = parseStoredMessageEnvelope(row.message_envelope, `${head.thread_id}/${row.seq}`);
+                return { seq: Number(row.seq), envelope, message: envelope.message };
+            });
+            let resolveCard;
+            if (head.analysis_id !== null) {
+                try {
+                    resolveCard = createCardResolver(deps.pool, head.analysis_id, deps.resolveWorkspaceRoot(head.analysis_id));
+                }
+                catch {
+                    // A removed/moved workspace is normal historical absence.
+                    resolveCard = undefined;
+                }
+            }
+            const cortex = await contentToCortexMessages(stored, { resolveCard, resolveDetail });
+            const uiMessages = cortexMessagesToConversationUI(cortex);
+            // A genuine turn always contributes at least its user message. Keep a
+            // defensive model-derived fallback so absence can never strand a NULL
+            // envelope and make startup retry forever.
+            const display = uiMessages.length > 0
+                ? uiMessages
+                : [
+                    {
+                        id: head.seq,
+                        role: "user",
+                        parts: [{ type: "text", text: "", state: "done" }],
+                    },
+                ];
+            const envelope = envelopeDisplayMessages(display);
+            const result = await deps.pool.query(`UPDATE messages
+                    SET display_envelope = $1::jsonb
+                  WHERE thread_id = $2 AND seq = $3::bigint
+                    AND display_envelope IS NULL`, [JSON.stringify(envelope), head.thread_id, head.seq]);
+            migrated += result.rowCount ?? 0;
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { EmitFn } from "../loop/types.js";
+import { type ConversationUIMessage } from "./conversation-display-storage.js";
+export interface ConversationDisplayRecorder {
+    readonly emit: EmitFn;
+    finish(options?: {
+        readonly fallbackText?: string;
+        readonly interrupted?: boolean;
+    }): ConversationUIMessage[];
+}
+export interface ConversationDisplayRecorderOptions {
+    readonly userText: string;
+    readonly topLevelCallPath: readonly string[];
+    readonly sink: EmitFn;
+    readonly userMessageId?: string;
+    readonly assistantMessageId?: string;
+}
+export declare function createConversationDisplayRecorder(options: ConversationDisplayRecorderOptions): ConversationDisplayRecorder;

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

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { PART_REGISTRY } from "../contracts/part-registry.js";
+import { CortexChatPartSchema } from "../contracts/schemas/chat-parts.js";
+import { conversationDisplayPart } from "./conversation-display-storage.js";
+function jsonCopy(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isSubAgent(event, topLevelCallPath) {
+    if (!("source" in event) || event.source === undefined)
+        return false;
+    const path = event.source.callPath;
+    return path.length > topLevelCallPath.length && topLevelCallPath.every((entry, index) => path[index] === entry);
+}
+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;
+}
+function dataPart(event) {
+    const parsed = CortexChatPartSchema.safeParse({ type: event.type, ...event.data });
+    if (!parsed.success)
+        throw new Error(`Invalid emitted conversation part ${event.type}: ${parsed.error.message}`);
+    const { type, ...data } = parsed.data;
+    return {
+        type,
+        id: "id" in data && typeof data.id === "string" ? data.id : undefined,
+        data: jsonCopy(data),
+    };
+}
+export function createConversationDisplayRecorder(options) {
+    const assistantParts = [];
+    // Where a reconciling part lives, keyed by `type:id`. Type-qualified because a
+    // stable id is only unique within its own family — a plan and a run card may
+    // legitimately share one.
+    const reconcileIndexes = new Map();
+    let finished = false;
+    /**
+     * Place a part, replacing the one it reconciles with when it has a stable id.
+     * A tool call reaching its `finished` state and an `ask` reaching its resolved
+     * status are the same operation: latest-wins, in the position the part first
+     * took, so a later part never jumps the ordering the user saw.
+     */
+    function upsert(part, reconciling) {
+        if (!reconciling || part.id === undefined) {
+            assistantParts.push(part);
+            return;
+        }
+        const key = `${part.type}:${part.id}`;
+        const index = reconcileIndexes.get(key);
+        if (index !== undefined) {
+            assistantParts[index] = part;
+            return;
+        }
+        reconcileIndexes.set(key, assistantParts.length);
+        assistantParts.push(part);
+    }
+    /**
+     * Place or update a call's recorded state.
+     *
+     * A call is recorded `incomplete` the moment it is dispatched and overwritten with
+     * its real outcome when it finishes. The record is therefore honest at every
+     * instant, and a turn that ends mid-call needs no closing pass — the calls that
+     * never finished are already saying so.
+     */
+    function recordToolCall(toolCallId, toolName, outcome, detail) {
+        upsert(conversationDisplayPart({
+            type: "tool-call",
+            toolCallId,
+            toolName,
+            outcome,
+            ...(detail === undefined ? {} : { detail }),
+        }), true);
+    }
+    function appendText(text) {
+        if (text.length === 0)
+            return;
+        const previous = assistantParts.at(-1);
+        if (previous?.type === "text") {
+            previous.text += text;
+            return;
+        }
+        assistantParts.push({ type: "text", text, state: "streaming" });
+    }
+    function recordData(event) {
+        if (!durableConversationType(event.type))
+            return;
+        upsert(dataPart(event), PART_REGISTRY[event.type].reconciling);
+    }
+    const emit = (event) => {
+        if (finished)
+            return options.sink(event);
+        if (!isSubAgent(event, options.topLevelCallPath)) {
+            switch (event.type) {
+                case "text-delta":
+                    appendText(event.text);
+                    break;
+                // The detail the loop computed at dispatch is recorded as shown. It is
+                // NOT re-derived on reload: doing that would need the tool's schema and
+                // the raw input, which is the tool-name coupling the display projection
+                // exists to remove.
+                case "tool-started":
+                    recordToolCall(event.toolUseId, event.name, "incomplete", event.detail);
+                    break;
+                case "tool-finished":
+                    recordToolCall(event.toolUseId, event.name, event.outcome, event.detail);
+                    break;
+                case "done":
+                case "iteration":
+                    break;
+                default:
+                    recordData(event);
+                    break;
+            }
+        }
+        return options.sink(event);
+    };
+    function finish(finishOptions) {
+        if (!finished) {
+            finished = true;
+            if (!assistantParts.some((part) => part.type === "text") && finishOptions?.fallbackText) {
+                appendText(finishOptions.fallbackText);
+            }
+            // Calls need no closing pass: one that never reached `tool-finished` still holds
+            // the `incomplete` it was recorded with at dispatch, which is the whole of what
+            // the harness observed. An approval does need one — `pending` is a question, and
+            // a turn that ends without answering it aborted it.
+            for (const part of assistantParts) {
+                if (part.type === "data-ask" && part.data.status === "pending") {
+                    part.data.status = "aborted";
+                }
+            }
+            for (const part of assistantParts) {
+                if (part.type === "text")
+                    part.state = "done";
+            }
+        }
+        const messages = [
+            {
+                id: options.userMessageId ?? randomUUID(),
+                role: "user",
+                parts: [{ type: "text", text: options.userText, state: "done" }],
+            },
+        ];
+        if (assistantParts.length > 0) {
+            messages.push({
+                id: options.assistantMessageId ?? randomUUID(),
+                role: "assistant",
+                ...(finishOptions?.interrupted ? { metadata: { interrupted: true } } : {}),
+                parts: jsonCopy(assistantParts),
+            });
+        }
+        return messages;
+    }
+    return { emit, finish };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The runtime transcript read: stored display projections → `CortexMessage[]`.
+ *
+ * `ThreadHistory.loadPage` returns a thread's rows in `seq` order, and every
+ * append's first row carries the display projection for that append. Replay is
+ * therefore a concatenation: walk the rows, emit each envelope's messages in
+ * order, done. No turn grouping, no tool-name recognition, no card rebuilding,
+ * no filesystem or database lookup — nothing that could render a reloaded
+ * conversation differently from the one the user was shown.
+ *
+ * A row with no envelope predates the display projection and is skipped. The
+ * startup backfill (`conversation-display-backfill.ts`) writes one for every such
+ * row before the runtime serves traffic, so in a booted harness there are none;
+ * skipping rather than falling back to the migration renderer is what keeps the
+ * reconstruction path out of the runtime entirely.
+ */
+import type { CortexMessage } from "../contracts/message.js";
+import type { StoredMessage } from "./thread-history.js";
+export declare function storedMessagesToCortex(messages: readonly StoredMessage[]): CortexMessage[];

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

@@ -0,0 +1,39 @@
+/**
+ * The runtime transcript read: stored display projections → `CortexMessage[]`.
+ *
+ * `ThreadHistory.loadPage` returns a thread's rows in `seq` order, and every
+ * append's first row carries the display projection for that append. Replay is
+ * therefore a concatenation: walk the rows, emit each envelope's messages in
+ * order, done. No turn grouping, no tool-name recognition, no card rebuilding,
+ * no filesystem or database lookup — nothing that could render a reloaded
+ * conversation differently from the one the user was shown.
+ *
+ * A row with no envelope predates the display projection and is skipped. The
+ * startup backfill (`conversation-display-backfill.ts`) writes one for every such
+ * row before the runtime serves traffic, so in a booted harness there are none;
+ * skipping rather than falling back to the migration renderer is what keeps the
+ * reconstruction path out of the runtime entirely.
+ */
+import { conversationUIToCortexMessages } from "./conversation-display-storage.js";
+export function storedMessagesToCortex(messages) {
+    const out = [];
+    // The messages the append currently being walked produced. A row bearing an
+    // envelope opens one; every row after it belongs to it until the next does.
+    let append = null;
+    for (const row of messages) {
+        if (row.displayEnvelope) {
+            append = conversationUIToCortexMessages(row.displayEnvelope.messages);
+            out.push(...append);
+        }
+        // The turn's reported rollup rides the model row that ENDED the turn, not the
+        // display projection — it is a fact about what the turn cost, not about what it
+        // showed, and persisting it in both places would let the two disagree. Fold it
+        // onto the assistant reply a reader associates with the figure.
+        if (row.usage && append) {
+            const last = append.at(-1);
+            if (last?.role === "assistant")
+                last.usage = row.usage;
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The durable conversation display projection — what the user was shown,
+ * persisted verbatim.
+ *
+ * AI SDK `UIMessage` is the CONTAINER: it supplies message identity, role,
+ * ordering, metadata, and `validateUIMessages` for runtime validation. The PARTS
+ * vocabulary is Cortex's own, because ours is the richer one — a `CortexPart`
+ * carries a tool call's four-way outcome and its one-line detail, and AI SDK's
+ * `dynamic-tool` part has nowhere to put either. Mapping through `dynamic-tool`
+ * would silently drop both on every reload, so every non-text part rides as a
+ * typed `DataUIPart` whose payload IS the Cortex part minus its discriminant.
+ *
+ * The projection is therefore lossless in both directions, and the read path
+ * ({@link conversationUIToCortexMessages}) is a near-identity rather than a
+ * reconstruction.
+ */
+import { type DataUIPart, type UIMessage } from "ai";
+import type { AskPart, FileReferencePart, PlanPart, PresentationPart, PreviewPart, DataPreviewFailedPart, RunCardPart } from "../contracts/chat-parts.js";
+import type { ToolCallOutcome } from "../contracts/chat-events.js";
+import type { CortexMessage, CortexPart, ToolCallPart } from "../contracts/message.js";
+export declare const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
+type Payload<T extends {
+    type: string;
+}> = Omit<T, "type">;
+/**
+ * The AI SDK custom-data vocabulary persisted for one conversation display.
+ *
+ * Each key `k` becomes a `data-${k}` part whose payload is the matching Cortex
+ * part without its `type` field, so a stored part and a wire part differ only in
+ * where the discriminant lives.
+ */
+export type ConversationUIData = {
+    "tool-call": Omit<Payload<ToolCallPart>, "outcome"> & {
+        outcome: ToolCallOutcome;
+    };
+    presentation: Payload<PresentationPart>;
+    plan: Payload<PlanPart>;
+    "run-card": Payload<RunCardPart>;
+    "file-reference": Payload<FileReferencePart>;
+    ask: Payload<AskPart>;
+    "report-preview": Payload<PreviewPart>;
+    "report-preview-failed": Payload<DataPreviewFailedPart>;
+};
+export interface ConversationDisplayMetadata {
+    interrupted?: boolean;
+}
+export type ConversationUIMessage = UIMessage<ConversationDisplayMetadata, ConversationUIData>;
+export interface StoredDisplayEnvelope {
+    readonly kind: "ai-sdk-ui-messages";
+    readonly aiSdkMajor: 7;
+    readonly schemaVersion: typeof SUPPORTED_DISPLAY_SCHEMA_VERSION;
+    readonly messages: ConversationUIMessage[];
+}
+export declare function envelopeDisplayMessages(messages: readonly ConversationUIMessage[]): StoredDisplayEnvelope;
+export declare function parseStoredDisplayEnvelope(value: unknown, identity: string): Promise<StoredDisplayEnvelope>;
+/**
+ * Build the stored form of one non-text Cortex part.
+ *
+ * A tool call is the one part whose stored payload is not simply the Cortex part
+ * minus its discriminant: `outcome` is optional on the live part (absent means in
+ * flight) and required here, because a record is of a call that is no longer
+ * running. An in-flight call being recorded is one the turn never saw finish, so
+ * absence resolves to `incomplete` at exactly this boundary — once, where the
+ * lifetime changes — rather than at each reader.
+ */
+export declare function conversationDisplayPart(part: Exclude<CortexPart, {
+    type: "text";
+}>): DataUIPart<ConversationUIData>;
+/**
+ * Project Cortex display messages into the durable representation.
+ *
+ * The startup backfill's only path into storage: it renders a legacy turn from
+ * the model transcript and freezes the result. The live recorder builds the same
+ * shape directly from the event stream instead of round-tripping through
+ * `CortexMessage`.
+ */
+export declare function cortexMessagesToConversationUI(messages: readonly CortexMessage[]): ConversationUIMessage[];
+/**
+ * Read the durable representation back as Cortex display messages.
+ *
+ * Every part round-trips by moving its discriminant back out of the part type,
+ * so nothing here consults a tool name, a registry, or the filesystem. A message
+ * whose parts all render empty is dropped so the transcript has no empty bubbles.
+ */
+export declare function conversationUIToCortexMessages(messages: readonly ConversationUIMessage[]): CortexMessage[];
+export {};

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

@@ -0,0 +1,168 @@
+/**
+ * The durable conversation display projection — what the user was shown,
+ * persisted verbatim.
+ *
+ * AI SDK `UIMessage` is the CONTAINER: it supplies message identity, role,
+ * ordering, metadata, and `validateUIMessages` for runtime validation. The PARTS
+ * vocabulary is Cortex's own, because ours is the richer one — a `CortexPart`
+ * carries a tool call's four-way outcome and its one-line detail, and AI SDK's
+ * `dynamic-tool` part has nowhere to put either. Mapping through `dynamic-tool`
+ * would silently drop both on every reload, so every non-text part rides as a
+ * typed `DataUIPart` whose payload IS the Cortex part minus its discriminant.
+ *
+ * The projection is therefore lossless in both directions, and the read path
+ * ({@link conversationUIToCortexMessages}) is a near-identity rather than a
+ * reconstruction.
+ */
+import { validateUIMessages } from "ai";
+import { z } from "zod";
+import { AskPartSchema, DataPreviewFailedPartSchema, FileReferencePartSchema, PlanPartSchema, PresentationPartSchema, PreviewPartSchema, RunCardPartSchema, } from "../contracts/schemas/chat-parts.js";
+import { ToolCallOutcomeSchema } from "../contracts/schemas/chat-events.js";
+export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
+const DisplayEnvelopeHeaderSchema = z.object({
+    kind: z.literal("ai-sdk-ui-messages"),
+    aiSdkMajor: z.literal(7),
+    schemaVersion: z.literal(SUPPORTED_DISPLAY_SCHEMA_VERSION),
+    messages: z.array(z.unknown()).min(1),
+});
+/**
+ * Declared here rather than derived from `contracts/schemas/chat-parts.ts`: a
+ * tool call is not a chat DATA part on the wire — it reaches a host as the
+ * `tool-started`/`tool-finished` event pair — so `chat-parts.ts` has no member to
+ * omit a discriminant from. Storage is the only place the pair is flattened into
+ * one part, and this is that shape.
+ *
+ * `outcome` is REQUIRED, and carries the whole terminal state including
+ * `incomplete`. A record describes a call that is no longer running, so "still in
+ * flight" is not a state it can be in — a turn cut off mid-call recorded a
+ * dispatch with no completion, which is what `incomplete` says. Storing a
+ * lifecycle field beside an optional outcome instead would put the meaning of the
+ * combination in each reader's head, and readers would disagree.
+ */
+const ToolCallDisplaySchema = z
+    .object({
+    toolCallId: z.string(),
+    toolName: z.string(),
+    outcome: ToolCallOutcomeSchema,
+    detail: z.string().optional(),
+})
+    .strict();
+const dataSchemas = {
+    "tool-call": ToolCallDisplaySchema,
+    presentation: PresentationPartSchema.omit({ type: true }).strict(),
+    plan: PlanPartSchema.omit({ type: true }).strict(),
+    "run-card": RunCardPartSchema.omit({ type: true }).strict(),
+    "file-reference": FileReferencePartSchema.omit({ type: true }).strict(),
+    ask: AskPartSchema.omit({ type: true }).strict(),
+    "report-preview": PreviewPartSchema.omit({ type: true }).strict(),
+    "report-preview-failed": DataPreviewFailedPartSchema.omit({ type: true }).strict(),
+};
+export function envelopeDisplayMessages(messages) {
+    if (messages.length === 0)
+        throw new Error("A conversation display envelope must contain at least one UI message");
+    return {
+        kind: "ai-sdk-ui-messages",
+        aiSdkMajor: 7,
+        schemaVersion: SUPPORTED_DISPLAY_SCHEMA_VERSION,
+        messages: structuredClone(messages),
+    };
+}
+export async function parseStoredDisplayEnvelope(value, identity) {
+    const header = DisplayEnvelopeHeaderSchema.safeParse(value);
+    if (!header.success) {
+        throw new Error(`Invalid stored conversation display envelope at ${identity}: ${header.error.message}`);
+    }
+    try {
+        const messages = await validateUIMessages({
+            messages: header.data.messages,
+            dataSchemas,
+            metadataSchema: z.object({ interrupted: z.boolean().optional() }).optional(),
+        });
+        return { ...header.data, messages };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid stored conversation display envelope at ${identity}: ${message}`, { cause: error });
+    }
+}
+/** The data-part key a Cortex part is stored under — its `type` minus the `data-` prefix. */
+function displayPartType(part) {
+    return (part.type === "tool-call" ? "data-tool-call" : part.type);
+}
+/** The id a part reconciles on: a tool call by its call id, a card by its own stable id. */
+function displayPartId(part) {
+    if (part.type === "tool-call")
+        return part.toolCallId;
+    return "id" in part && typeof part.id === "string" ? part.id : undefined;
+}
+/**
+ * Build the stored form of one non-text Cortex part.
+ *
+ * A tool call is the one part whose stored payload is not simply the Cortex part
+ * minus its discriminant: `outcome` is optional on the live part (absent means in
+ * flight) and required here, because a record is of a call that is no longer
+ * running. An in-flight call being recorded is one the turn never saw finish, so
+ * absence resolves to `incomplete` at exactly this boundary — once, where the
+ * lifetime changes — rather than at each reader.
+ */
+export function conversationDisplayPart(part) {
+    const { type: _type, ...rest } = part;
+    const data = part.type === "tool-call" ? { ...rest, outcome: part.outcome ?? "incomplete" } : rest;
+    return { type: displayPartType(part), id: displayPartId(part), data };
+}
+/**
+ * Project Cortex display messages into the durable representation.
+ *
+ * The startup backfill's only path into storage: it renders a legacy turn from
+ * the model transcript and freezes the result. The live recorder builds the same
+ * shape directly from the event stream instead of round-tripping through
+ * `CortexMessage`.
+ */
+export function cortexMessagesToConversationUI(messages) {
+    return messages.map((message) => {
+        const parts = message.parts.map((part) => part.type === "text" ? { type: "text", text: part.text, state: "done" } : conversationDisplayPart(part));
+        return {
+            id: message.id,
+            role: message.role,
+            ...(message.interrupted ? { metadata: { interrupted: true } } : {}),
+            parts,
+        };
+    });
+}
+/**
+ * Read the durable representation back as Cortex display messages.
+ *
+ * Every part round-trips by moving its discriminant back out of the part type,
+ * so nothing here consults a tool name, a registry, or the filesystem. A message
+ * whose parts all render empty is dropped so the transcript has no empty bubbles.
+ */
+export function conversationUIToCortexMessages(messages) {
+    const out = [];
+    for (const message of messages) {
+        const parts = [];
+        for (const part of message.parts) {
+            if (part.type === "text") {
+                if (part.text.length > 0)
+                    parts.push({ type: "text", text: part.text });
+                continue;
+            }
+            if (part.type === "data-tool-call") {
+                parts.push({ type: "tool-call", ...part.data });
+                continue;
+            }
+            if (part.type.startsWith("data-")) {
+                const data = part;
+                parts.push({ type: data.type, ...data.data });
+            }
+        }
+        if (parts.length === 0)
+            continue;
+        out.push({
+            id: message.id,
+            role: message.role,
+            parts,
+            ...(message.metadata?.interrupted ? { interrupted: true } : {}),
+        });
+    }
+    return out;
+}

package/dist/memory/reconstruct-cards.d.ts

@@ -1,5 +1,8 @@
 /**
- * Read-path reconstruction of display cards from a persisted turn.
+ * @deprecated Compatibility-only reconstruction for pre-display-envelope
+ * turns. New runtime reads use stored AI SDK UI messages. Retain this module
+ * through the pre-v1 direct-upgrade window, then remove its runtime fallback
+ * in a dedicated compatibility change.
  *
  * `show_plan` / `show_user` / `show_file` / `execute_analysis` / `iterate_report` emit
  * `data-plan` / `data-presentation` / `data-file-reference` / `data-run-card` /
@@ -13,11 +16,14 @@
  */
 import type { CortexPart } from "@inflexa-ai/harness/contracts/message.js";
 import type { Pool } from "pg";
+/** @deprecated Used only by the legacy display backfill/fallback. */
 export interface StoredToolCallForCard {
     readonly type: "tool_use";
     readonly id: string;
     readonly name: string;
     readonly input: unknown;
 }
+/** @deprecated Used only by the legacy display backfill/fallback. */
 export type ToolCardResolver = (block: StoredToolCallForCard) => Promise<CortexPart | null>;
+/** @deprecated Use persisted conversation display envelopes for runtime reads. */
 export declare function createCardResolver(pool: Pool, analysisId: string, workspaceRoot: string): ToolCardResolver;

package/dist/memory/reconstruct-cards.js

@@ -1,5 +1,8 @@
 /**
- * Read-path reconstruction of display cards from a persisted turn.
+ * @deprecated Compatibility-only reconstruction for pre-display-envelope
+ * turns. New runtime reads use stored AI SDK UI messages. Retain this module
+ * through the pre-v1 direct-upgrade window, then remove its runtime fallback
+ * in a dedicated compatibility change.
  *
  * `show_plan` / `show_user` / `show_file` / `execute_analysis` / `iterate_report` emit
  * `data-plan` / `data-presentation` / `data-file-reference` / `data-run-card` /
@@ -15,6 +18,7 @@ import { unwrapOrThrow } from "../lib/result.js";
 import { adHocPlanId, adHocRunId } from "../tools/analysis-invocation.js";
 import { validatePath } from "../tools/lib/path-validation.js";
 import { buildFileReferenceCardData, buildPlanCardData, buildPresentationCardData, buildPreviewCardData, buildRunCardData } from "./card-builders.js";
+/** @deprecated Use persisted conversation display envelopes for runtime reads. */
 export function createCardResolver(pool, analysisId, workspaceRoot) {
     return async (block) => {
         if (block.type !== "tool_use")

package/dist/memory/thread-history.d.ts

@@ -26,11 +26,18 @@ import type { Pool } from "pg";
 import type { TokenUsageRollup } from "../contracts/usage.js";
 import { type DbError } from "../lib/db-result.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+import { type ConversationUIMessage, type StoredDisplayEnvelope } from "./conversation-display-storage.js";
 /** One stored message, as returned by the display read (`loadPage`). */
 export interface StoredMessage {
     readonly seq: number;
     readonly envelope: StoredMessageEnvelope;
     readonly message: ModelMessage;
+    /**
+     * The display projection of the append this row OPENED — present on the first
+     * row of each `appendTurn` and absent on every other row. A conversation turn
+     * and a host-appended record are both appends, so both carry one.
+     */
+    readonly displayEnvelope?: StoredDisplayEnvelope;
     /**
      * What providers reported for the whole TURN this row completed — present
      * only on the last assistant row of a turn appended with a rollup, absent
@@ -41,6 +48,41 @@ export interface StoredMessage {
      */
     readonly usage?: TokenUsageRollup;
 }
+/**
+ * One atomic append: the exact provider-facing history, the display projection of
+ * what the user was shown, and what the turn reported spending.
+ *
+ * The two message projections are independent by design. `modelMessages` is what
+ * the provider sees and the only input to token accounting; `displayMessages` is
+ * what the transcript replays. Neither is derived from the other, and a failed
+ * write commits neither.
+ */
+export interface ConversationTurn {
+    /** Exact provider-facing history; token accounting and model reads use only this projection. */
+    readonly modelMessages: readonly ModelMessage[];
+    /** Complete ordered AI SDK UI messages recorded from the live display event stream. */
+    readonly displayMessages: readonly ConversationUIMessage[];
+    /**
+     * The turn's reported rollup, as `AgentFinish.turnUsage` carries it out of the
+     * loop. Stored on the LAST assistant message of the turn — the row a reader
+     * associates with the reply. Omitting it, and supplying one that reports no
+     * quantity at all, both leave the row without one: a turn that reported nothing
+     * must not read back as a turn that cost zero.
+     */
+    readonly turnUsage?: TokenUsageRollup;
+}
+/**
+ * The append a host uses to record out-of-band work in a thread — an analysis
+ * run's outcome, typically.
+ *
+ * Both projections are built here because a record has no live turn behind it:
+ * no recorder observed it, so nothing else would produce its display projection,
+ * and a record appended without one would be stored, read by the model, and
+ * never shown. The harness owns the record-to-`system` mapping for the same
+ * reason it owns the marker — a host that hand-assembled either could produce a
+ * message the turn-boundary predicates fail to recognise.
+ */
+export declare function conversationRecordTurn(text: string): ConversationTurn;
 /**
  * A page of stored messages plus pagination metadata. Pagination is
  * turn-based: `total` is the thread's turn count and `page`/`perPage` index
@@ -74,20 +116,13 @@ export type RetractOutcome = {
  */
 export interface ThreadHistory {
     /**
-     * Append one conversation turn — every message written in a single
+     * Append one {@link ConversationTurn} — every message written in a single
      * transaction with a `seq` monotonically increasing per thread.
      *
-     * `turnUsage` is the turn's reported rollup, as `AgentFinish.turnUsage`
-     * carries it out of the loop and the `finish` event carries it to a live
-     * surface. It is stored on the LAST assistant message of the turn — the row a
-     * reader associates with the reply — so a reloaded transcript renders the
-     * figure the live turn showed. Optional at every layer: omitting it, and
-     * supplying one that reports no quantity at all, both leave the row without
-     * one, because a turn that reported nothing must not read back as a turn that
-     * cost zero. A turn writing no assistant message stores none and still
-     * succeeds — there is no row on which the figure would mean anything.
+     * A turn writing no assistant message stores no rollup and still succeeds:
+     * there is no row on which the figure would mean anything.
      */
-    appendTurn(threadId: string, messages: readonly ModelMessage[], turnUsage?: TokenUsageRollup): ResultAsync<void, DbError>;
+    appendTurn(threadId: string, turn: ConversationTurn): ResultAsync<void, DbError>;
     /**
      * Return a recent-turns window that fits `tokenBudget`, oldest-first,
      * snapped to a valid AI SDK model-message sequence. The window START advances

package/dist/memory/thread-history.js

@@ -20,17 +20,36 @@
  * is the atomic unit; `appendTurn` writes one atomically and `loadRecent`
  * rounds the budget walk to turn boundaries.
  */
+import { randomUUID } from "node:crypto";
 import { metrics } from "@opentelemetry/api";
 import { ResultAsync, ok, okAsync } from "neverthrow";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.js";
-import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, } from "./ai-sdk-message-storage.js";
+import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, syntheticRecordMessage, } from "./ai-sdk-message-storage.js";
+import { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./conversation-display-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
 }
+/**
+ * The append a host uses to record out-of-band work in a thread — an analysis
+ * run's outcome, typically.
+ *
+ * Both projections are built here because a record has no live turn behind it:
+ * no recorder observed it, so nothing else would produce its display projection,
+ * and a record appended without one would be stored, read by the model, and
+ * never shown. The harness owns the record-to-`system` mapping for the same
+ * reason it owns the marker — a host that hand-assembled either could produce a
+ * message the turn-boundary predicates fail to recognise.
+ */
+export function conversationRecordTurn(text) {
+    return {
+        modelMessages: [syntheticRecordMessage(text)],
+        displayMessages: [{ id: randomUUID(), role: "system", parts: [{ type: "text", text, state: "done" }] }],
+    };
+}
 /**
  * A turn starts on a `user` message that a human actually sent. Two kinds of
  * message carry the `user` role without opening a turn, and both are excluded
@@ -156,9 +175,16 @@ export const EVICTION_BLOCK_TURNS = 4;
  * provisioned by the project's state-init DDL.
  */
 export function createThreadHistory(pool) {
-    function appendTurn(threadId, messages, turnUsage) {
+    function appendTurn(threadId, turn) {
+        const { modelMessages: messages, displayMessages, turnUsage } = turn;
         if (messages.length === 0)
             return okVoid();
+        // The display projection rides the append's FIRST row, so one SELECT of a
+        // thread's rows yields every envelope in order with no join and no grouping.
+        // Whichever row that is — a genuine user message opening a turn, or the lone
+        // record row of an out-of-band append — is the row a tail retraction removes
+        // the envelope with, because it is the row the projection describes.
+        const displayEnvelope = displayMessages.length > 0 ? JSON.stringify(envelopeDisplayMessages(displayMessages)) : null;
         // A rollup that reports no quantity is stored as absent, not as a rollup of
         // absences, so "no figure" has exactly one representation in storage.
         // `hasReportedUsage` is the loop's own predicate for the same question,
@@ -185,14 +211,23 @@ export function createThreadHistory(pool) {
         // re-throws it to force ROLLBACK (a returned `err` that does not
         // reach `withTransaction` would COMMIT silently).
         messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(
-        // `message_envelope::json`, never `::jsonb`, and `reported_usage::jsonb`,
-        // never `::json` — see the column comments in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, tokens, reported_usage)
-                     VALUES ($1, $2, $3::json, $4, $5::jsonb)
+        // `message_envelope::json`, never `::jsonb`; `display_envelope` and
+        // `reported_usage::jsonb`, never `::json` — see the column comments
+        // in the state-init DDL.
+        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage)
+                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
+                           display_envelope = EXCLUDED.display_envelope,
                            tokens = EXCLUDED.tokens,
-                           reported_usage = EXCLUDED.reported_usage`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content), i === rollupRow ? rollup : null])).map(() => undefined)), okVoid()))
+                           reported_usage = EXCLUDED.reported_usage`, [
+            threadId,
+            startSeq + i,
+            serializeEnvelope(message),
+            i === 0 ? displayEnvelope : null,
+            countTokens(message.content),
+            i === rollupRow ? rollup : null,
+        ])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
         // the only other writer of it is the title update — so without this
@@ -311,15 +346,22 @@ export function createThreadHistory(pool) {
             // `seq::text AS seq` output alias (Postgres resolves an unqualified
             // ORDER BY name to the output column), sorting the bigint as text:
             // "10" before "2". The qualified name forces the bigint column.
-            `SELECT seq::text AS seq, message_envelope, reported_usage
+            `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
-            const stored = rows.map((r) => {
+            // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+            // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+            const stored = await Promise.all(rows.map(async (r) => {
                 const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-                // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
-                // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-                return { seq: Number(r.seq), envelope, message: envelope.message, ...(r.reported_usage === null ? {} : { usage: r.reported_usage }) };
-            });
+                const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`);
+                return {
+                    seq: Number(r.seq),
+                    envelope,
+                    message: envelope.message,
+                    ...(displayEnvelope ? { displayEnvelope } : {}),
+                    ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
+                };
+            }));
             const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
             const total = turns.length;
             const offset = safePage * safePerPage;

package/dist/runtime/boot.d.ts

@@ -20,11 +20,17 @@
  *      misconfigured pool fails loudly at boot, not under load.
  *   5. `assembleCoreRuntime(core)` — registers the durable-workflow cohort and
  *      builds the conversation agent (register-before-launch invariant).
- *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
+ *   6. `backfillConversationDisplayEnvelopes(...)` — validates every stored
+ *      display envelope and freezes one for each legacy turn that has none, so
+ *      the runtime read path never meets a row without a display projection.
+ *      Runs AFTER assembly because migrating a legacy call's one-line detail
+ *      needs the assembled conversation roster, embedder-contributed tools
+ *      included; assembly starts no traffic, so this is still before any read.
+ *   7. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
  *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
- *   7. `launchDbos(...)` — the last registration-dependent step.
+ *   8. `launchDbos(...)` — the last registration-dependent step.
  *
  * Boot-step errors PROPAGATE (the embedder's composition root catches them and
  * releases whatever it acquired). Only `shutdown` swallows per-step failures —

package/dist/runtime/boot.js

@@ -20,11 +20,17 @@
  *      misconfigured pool fails loudly at boot, not under load.
  *   5. `assembleCoreRuntime(core)` — registers the durable-workflow cohort and
  *      builds the conversation agent (register-before-launch invariant).
- *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
+ *   6. `backfillConversationDisplayEnvelopes(...)` — validates every stored
+ *      display envelope and freezes one for each legacy turn that has none, so
+ *      the runtime read path never meets a row without a display projection.
+ *      Runs AFTER assembly because migrating a legacy call's one-line detail
+ *      needs the assembled conversation roster, embedder-contributed tools
+ *      included; assembly starts no traffic, so this is still before any read.
+ *   7. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
  *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
- *   7. `launchDbos(...)` — the last registration-dependent step.
+ *   8. `launchDbos(...)` — the last registration-dependent step.
  *
  * Boot-step errors PROPAGATE (the embedder's composition root catches them and
  * releases whatever it acquired). Only `shutdown` swallows per-step failures —
@@ -33,6 +39,7 @@
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
 import { initCortexState } from "../state/init.js";
+import { backfillConversationDisplayEnvelopes } from "../memory/conversation-display-backfill.js";
 import { assembleCoreRuntime } from "./assemble.js";
 import { assertConnectionBudget } from "./connection-budget.js";
 import { launchDbos, shutdownDbos } from "./dbos.js";
@@ -47,6 +54,11 @@ export async function bootHarness(deps) {
     await initCortexState(pool);
     await assertConnectionBudget({ pool, logger, config: deps.connectionBudget });
     const runtime = assembleCoreRuntime(core);
+    await backfillConversationDisplayEnvelopes({
+        pool,
+        resolveWorkspaceRoot: core.conversation.resolveWorkspaceRoot,
+        tools: runtime.conversationAgent.tools,
+    });
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });
     logger.named("boot").info("harness booted", { executorId: deps.dbos.executorId });

package/dist/state/init.js

@@ -255,6 +255,9 @@ CREATE TABLE IF NOT EXISTS messages (
   role          TEXT,
   content_jsonb JSONB,
   message_envelope JSON,
+  -- Versioned AI SDK UIMessage projection for the whole turn. Present only
+  -- on the genuine-user-start row. Model-history reads never select it.
+  display_envelope JSONB,
   tokens        INTEGER NOT NULL,
   reported_usage JSONB,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -475,6 +478,7 @@ export async function initCortexState(pool, injected) {
                     ALTER TABLE messages ALTER COLUMN message_envelope TYPE JSON USING message_envelope::text::json;
                   END IF;
                 END $$`,
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS display_envelope JSONB",
                 // Grant key an 'always' records the standing grant under. Nullable
                 // and unbackfilled: every new row writes it (command when absent), and
                 // orphaned legacy pending rows are swept to 'expired' before any answer

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.15.1",
+    "version": "0.16.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",