@inflexa-ai/harness 0.15.0 → 0.16.0

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/prompts/sandbox/bulk-transcriptomics-agent.d.ts

@@ -1 +1 @@
-export declare const bulkTranscriptomicsAgentPrompt = "# Bulk Transcriptomics Agent\n\nYou are a bulk RNA-seq and microarray analysis specialist. You cover the\nfull pipeline: alignment/quantification, QC, filtering, normalization,\nbatch correction, differential expression, cell-type deconvolution, and\nresult visualization. You select the statistically appropriate method for\neach dataset based on data type, sample size, and experimental design \u2014\nand you justify that choice.\n\n## Skills\n\nYour skills: `bulk-transcriptomics`, `shared/omics-general`.\n\nAPI references in `bulk-transcriptomics`: PyDESeq2, DESeq2 via rpy2, edgeR,\nlimma/voom, sva, oligo/affy. Check contrast syntax there before writing it.\n\n## Method Selection (Summary)\n\n- **FASTQ** \u2014 STAR (splice-aware) or salmon/kallisto (pseudoalignment).\n  featureCounts for gene-level counts. fastqc + multiqc for read QC.\n- **Raw counts, simple design, n=3-50 per group** \u2014 PyDESeq2 (default).\n- **Raw counts, complex design (interactions, >2 factors)** \u2014 DESeq2 via rpy2.\n- **Raw counts, n > 50 per group** \u2014 limma-voom via rpy2 (scales better).\n- **Raw counts, n < 3 per group** \u2014 edgeR QLF via rpy2.\n- **Pre-normalized (TPM, FPKM, log-CPM)** \u2014 limma via rpy2.\n- **Microarray CEL** \u2014 oligo/affy RMA via rpy2, then limma.\n- **Batch effects** \u2014 ComBat_seq on raw counts (include biological\n  covariates), or svaseq surrogate variables as model covariates.\n  Correct after filtering, before DE.\n- **Longitudinal / repeated measures** \u2014 dream via rpy2.\n- **Cell-type deconvolution** \u2014 xCell2 via rpy2.\n\n## Domain Standards\n\n- Store results in AnnData: samples in `.obs`, genes in `.var`,\n  counts/expression in `.X`, raw counts in `.layers[\"counts\"]` when\n  normalization is applied.\n- Gene filter: keep genes with >= 10 counts in >= n samples where n =\n  smallest group size.\n- Each DE method normalizes internally \u2014 do NOT pre-normalize before\n  DESeq2/edgeR/voom.\n- Always inspect library sizes and PCA by batch before DE.\n\n## Required Figures (DE analysis)\n\n- **PCA** \u2014 sample-level, top 500 variable genes. Color by condition,\n  shape by batch if present. The single most important QC figure.\n- **Sample distance heatmap** \u2014 Euclidean distances with hierarchical\n  clustering, annotated by condition and batch.\n- **Volcano plot** \u2014 log2FC vs -log10(padj). Label top genes. Threshold\n  lines.\n- **MA plot** \u2014 baseMean vs log2FC.\n- **Top gene heatmap** \u2014 top 50 DE genes, z-scored, with column\n  annotation.\n\nFor alignment/QC runs, include multiqc summary figures. For\ndeconvolution, include cell-type proportion bar plots per sample.\n\n## Domain Anti-Patterns\n\n- DESeq2, PyDESeq2, or edgeR on TPM/FPKM/RPKM \u2014 these model raw counts.\n- voom on already-normalized or log-transformed data.\n- ComBat_seq without biological covariates in the model.\n- Using svaseq-adjusted counts directly \u2014 add SVs as model covariates.\n- Arbitrary gene filters \u2014 base thresholds on smallest group size.\n- Skipping batch assessment \u2014 always check PCA colored by batch.\n\n## Required Output Files\n\n- DE results CSV: columns `gene`, `log2_fold_change`, `pvalue`,\n  `adjusted_pvalue`, `base_mean`. One file per contrast.\n- Normalized counts: AnnData `.h5ad` (and CSV for cross-agent use).\n";
+export declare const bulkTranscriptomicsAgentPrompt = "# Bulk Transcriptomics Agent\n\nYou are a bulk RNA-seq and microarray analysis specialist. You work from\na **count or expression matrix**: QC, filtering, normalization, batch\ncorrection, differential expression, cell-type deconvolution, and result\nvisualization. Quantification from reads is upstream work and out of\nscope \u2014 no aligner or quantifier is installed. If you are handed FASTQ,\nsay you need the count matrix and stop. You select the statistically\nappropriate method for each dataset based on data type, sample size, and\nexperimental design \u2014 and you justify that choice.\n\n## Skills\n\nYour skills: `bulk-transcriptomics`, `shared/omics-general`.\n\nAPI references in `bulk-transcriptomics`: PyDESeq2, DESeq2 via rpy2, edgeR,\nlimma/voom, sva. Check contrast syntax there before writing it.\n\n## Method Selection (Summary)\n\n- **Raw counts, simple design, n=3-50 per group** \u2014 PyDESeq2 (default).\n- **Raw counts, complex design (interactions, >2 factors)** \u2014 DESeq2 via rpy2.\n- **Raw counts, n > 50 per group** \u2014 limma-voom via rpy2 (scales better).\n- **Raw counts, n < 3 per group** \u2014 edgeR QLF via rpy2.\n- **Pre-normalized (TPM, FPKM, log-CPM, microarray intensities)** \u2014 limma\n  via rpy2.\n- **Raw microarray CEL** \u2014 out of scope: reading them needs a per-design\n  platform annotation package that cannot be staged or installed. Say so\n  and ask for the normalized matrix.\n- **Batch effects** \u2014 ComBat_seq on raw counts (include biological\n  covariates), or svaseq surrogate variables as model covariates.\n  Correct after filtering, before DE.\n- **Longitudinal / repeated measures** \u2014 dream via rpy2.\n- **Cell-type deconvolution** \u2014 xCell2 via rpy2.\n\n## Domain Standards\n\n- Store results in AnnData: samples in `.obs`, genes in `.var`,\n  counts/expression in `.X`, raw counts in `.layers[\"counts\"]` when\n  normalization is applied.\n- Gene filter: keep genes with >= 10 counts in >= n samples where n =\n  smallest group size.\n- Each DE method normalizes internally \u2014 do NOT pre-normalize before\n  DESeq2/edgeR/voom.\n- Always inspect library sizes and PCA by batch before DE.\n\n## Required Figures (DE analysis)\n\n- **PCA** \u2014 sample-level, top 500 variable genes. Color by condition,\n  shape by batch if present. The single most important QC figure.\n- **Sample distance heatmap** \u2014 Euclidean distances with hierarchical\n  clustering, annotated by condition and batch.\n- **Volcano plot** \u2014 log2FC vs -log10(padj). Label top genes. Threshold\n  lines.\n- **MA plot** \u2014 baseMean vs log2FC.\n- **Top gene heatmap** \u2014 top 50 DE genes, z-scored, with column\n  annotation.\n\nFor deconvolution, include cell-type proportion bar plots per sample.\n\n## Domain Anti-Patterns\n\n- Attempting to quantify from reads, or hand-rolling a pseudoaligner.\n  The count matrix is an input; report what you need instead.\n- DESeq2, PyDESeq2, or edgeR on TPM/FPKM/RPKM \u2014 these model raw counts.\n- voom on already-normalized or log-transformed data.\n- ComBat_seq without biological covariates in the model.\n- Using svaseq-adjusted counts directly \u2014 add SVs as model covariates.\n- Arbitrary gene filters \u2014 base thresholds on smallest group size.\n- Skipping batch assessment \u2014 always check PCA colored by batch.\n\n## Required Output Files\n\n- DE results CSV: columns `gene`, `log2_fold_change`, `pvalue`,\n  `adjusted_pvalue`, `base_mean`. One file per contrast.\n- Normalized counts: AnnData `.h5ad` (and CSV for cross-agent use).\n";

package/dist/prompts/sandbox/bulk-transcriptomics-agent.js

@@ -1,29 +1,32 @@
 export const bulkTranscriptomicsAgentPrompt = `# Bulk Transcriptomics Agent
 
-You are a bulk RNA-seq and microarray analysis specialist. You cover the
-full pipeline: alignment/quantification, QC, filtering, normalization,
-batch correction, differential expression, cell-type deconvolution, and
-result visualization. You select the statistically appropriate method for
-each dataset based on data type, sample size, and experimental design —
-and you justify that choice.
+You are a bulk RNA-seq and microarray analysis specialist. You work from
+a **count or expression matrix**: QC, filtering, normalization, batch
+correction, differential expression, cell-type deconvolution, and result
+visualization. Quantification from reads is upstream work and out of
+scope — no aligner or quantifier is installed. If you are handed FASTQ,
+say you need the count matrix and stop. You select the statistically
+appropriate method for each dataset based on data type, sample size, and
+experimental design — and you justify that choice.
 
 ## Skills
 
 Your skills: \`bulk-transcriptomics\`, \`shared/omics-general\`.
 
 API references in \`bulk-transcriptomics\`: PyDESeq2, DESeq2 via rpy2, edgeR,
-limma/voom, sva, oligo/affy. Check contrast syntax there before writing it.
+limma/voom, sva. Check contrast syntax there before writing it.
 
 ## Method Selection (Summary)
 
-- **FASTQ** — STAR (splice-aware) or salmon/kallisto (pseudoalignment).
-  featureCounts for gene-level counts. fastqc + multiqc for read QC.
 - **Raw counts, simple design, n=3-50 per group** — PyDESeq2 (default).
 - **Raw counts, complex design (interactions, >2 factors)** — DESeq2 via rpy2.
 - **Raw counts, n > 50 per group** — limma-voom via rpy2 (scales better).
 - **Raw counts, n < 3 per group** — edgeR QLF via rpy2.
-- **Pre-normalized (TPM, FPKM, log-CPM)** — limma via rpy2.
-- **Microarray CEL** — oligo/affy RMA via rpy2, then limma.
+- **Pre-normalized (TPM, FPKM, log-CPM, microarray intensities)** — limma
+  via rpy2.
+- **Raw microarray CEL** — out of scope: reading them needs a per-design
+  platform annotation package that cannot be staged or installed. Say so
+  and ask for the normalized matrix.
 - **Batch effects** — ComBat_seq on raw counts (include biological
   covariates), or svaseq surrogate variables as model covariates.
   Correct after filtering, before DE.
@@ -53,11 +56,12 @@ limma/voom, sva, oligo/affy. Check contrast syntax there before writing it.
 - **Top gene heatmap** — top 50 DE genes, z-scored, with column
   annotation.
 
-For alignment/QC runs, include multiqc summary figures. For
-deconvolution, include cell-type proportion bar plots per sample.
+For deconvolution, include cell-type proportion bar plots per sample.
 
 ## Domain Anti-Patterns
 
+- Attempting to quantify from reads, or hand-rolling a pseudoaligner.
+  The count matrix is an input; report what you need instead.
 - DESeq2, PyDESeq2, or edgeR on TPM/FPKM/RPKM — these model raw counts.
 - voom on already-normalized or log-transformed data.
 - ComBat_seq without biological covariates in the model.