@inflexa-ai/harness 0.15.0 → 0.16.0

package/dist/agents/sandbox/drug-repurposing-agent.js

@@ -16,7 +16,11 @@ export const meta = {
         "preclinical target intelligence (KO + expression)",
     ],
     suitableFor: ["drug-repurposing", "drug-repositioning", "indication-expansion", "target-drug-mapping", "therapeutic-candidates", "perturbation-signatures"],
-    skills: ["drug-repurposing", "cheminformatics", "shared/omics-general"],
+    // `genomic-variants` carries the Mendelian randomization reference. The
+    // genetics-based repurposing strategy turns on whether a target's disease
+    // association is causal, and MR is the test — without this the pack points at
+    // a reference the agent cannot read.
+    skills: ["drug-repurposing", "cheminformatics", "genomic-variants", "shared/omics-general"],
     tools: [
         ...BASE_SANDBOX_TOOLS,
         "targetSafety",

package/dist/agents/sandbox/immune-profiling-agent.js

@@ -23,7 +23,10 @@ export const meta = {
         "tcr-bcr-data",
         "immune-cell-composition",
     ],
-    skills: ["immune-profiling", "shared/omics-general"],
+    // `single-cell` carries the scirpy reference, which is the route from 10x
+    // VDJ / AIRR files to called clonotypes — the input every repertoire metric
+    // in `immune-profiling` assumes it already has.
+    skills: ["immune-profiling", "single-cell", "shared/omics-general"],
     tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGene", "lookupAnnotation", "searchInteractions", "searchGeoDatasets", "opentargets"],
 };
 export function createImmuneProfilingAgent(deps) {

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[];