@inflexa-ai/harness 0.15.1 → 0.17.0

package/dist/literature/sources/pubmed.js

@@ -0,0 +1,266 @@
+import { XMLParser } from "fast-xml-parser";
+import { z } from "zod";
+import { requestJson, requestText } from "./http.js";
+export const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
+export const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
+const EsearchResponseSchema = z.object({
+    esearchresult: z.object({ idlist: z.array(z.string()).optional(), count: z.string().optional() }).optional(),
+});
+const IdConvResponseSchema = z.object({
+    records: z.array(z.object({ pmid: z.string().optional(), pmcid: z.string().optional() })).optional(),
+});
+export function ncbiUrl(apiKey, base, params) {
+    const url = new URL(base);
+    if (apiKey !== undefined)
+        url.searchParams.set("api_key", apiKey);
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            url.searchParams.set(key, String(value));
+    return url.toString();
+}
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    isArray: (name) => ["PubmedArticle", "Author", "MeshHeading", "AbstractText", "sec", "p", "record"].includes(name),
+    textNodeName: "#text",
+});
+function getItemValue(items, name) {
+    if (items === undefined)
+        return "";
+    const item = (Array.isArray(items) ? items : [items]).find((candidate) => candidate["@_Name"] === name);
+    return item?.["#text"] ?? "";
+}
+function getAuthorsFromDocSum(items) {
+    if (items === undefined)
+        return "";
+    const authorList = (Array.isArray(items) ? items : [items]).find((item) => item["@_Name"] === "AuthorList");
+    if (authorList?.Item === undefined)
+        return "";
+    const names = (Array.isArray(authorList.Item) ? authorList.Item : [authorList.Item]).map((author) => author["#text"] ?? "").filter(Boolean);
+    if (names.length <= 3)
+        return names.join(", ");
+    return `${names[0]} et al.`;
+}
+export function parseEsummary(xml) {
+    const parsed = xmlParser.parse(xml);
+    const docSums = (parsed?.eSummaryResult ?? parsed)?.DocSum;
+    if (docSums === undefined)
+        return [];
+    const documents = Array.isArray(docSums) ? docSums : [docSums];
+    return documents.map((document) => {
+        const publicationDate = getItemValue(document.Item, "PubDate");
+        return {
+            pmid: String(document.Id ?? ""),
+            title: getItemValue(document.Item, "Title"),
+            journal: getItemValue(document.Item, "FullJournalName") || getItemValue(document.Item, "Source"),
+            year: publicationDate.slice(0, 4),
+            authors: getAuthorsFromDocSum(document.Item),
+        };
+    });
+}
+export function parseEfetch(xml) {
+    const articleSet = xmlParser.parse(xml)?.PubmedArticleSet;
+    if (articleSet === undefined)
+        return [];
+    const entries = Array.isArray(articleSet.PubmedArticle)
+        ? articleSet.PubmedArticle
+        : articleSet.PubmedArticle === undefined
+            ? []
+            : [articleSet.PubmedArticle];
+    return entries.map((entry) => {
+        const article = entry;
+        const citation = article.MedlineCitation;
+        const articleData = citation?.Article;
+        const pmidValue = citation?.PMID;
+        const pmid = typeof pmidValue === "object" && pmidValue !== null ? String(pmidValue["#text"] ?? "") : String(pmidValue ?? "");
+        const abstractValue = articleData?.Abstract?.AbstractText;
+        const abstract = (abstractValue === undefined ? [] : Array.isArray(abstractValue) ? abstractValue : [abstractValue])
+            .map((value) => {
+            if (typeof value === "string")
+                return value;
+            if (typeof value !== "object" || value === null)
+                return String(value);
+            const object = value;
+            const text = String(object["#text"] ?? "");
+            return object["@_Label"] === undefined ? text : `${String(object["@_Label"])}: ${text}`;
+        })
+            .join("\n\n");
+        const authorValue = articleData?.AuthorList?.Author;
+        const authors = (authorValue === undefined ? [] : Array.isArray(authorValue) ? authorValue : [authorValue]).map((author) => author.CollectiveName ?? [author.ForeName ?? author.Initials, author.LastName].filter(Boolean).join(" "));
+        const journalData = articleData?.Journal;
+        const publicationDate = journalData?.JournalIssue?.PubDate;
+        let doi = "";
+        const articleIds = article.PubmedData?.ArticleIdList?.ArticleId;
+        for (const id of articleIds === undefined ? [] : Array.isArray(articleIds) ? articleIds : [articleIds]) {
+            if (typeof id === "object" && id !== null && id["@_IdType"] === "doi") {
+                doi = String(id["#text"] ?? "");
+            }
+        }
+        const meshValue = citation?.MeshHeadingList?.MeshHeading;
+        const meshTerms = (meshValue === undefined ? [] : Array.isArray(meshValue) ? meshValue : [meshValue])
+            .map((heading) => {
+            const descriptor = heading.DescriptorName;
+            return typeof descriptor === "string" ? descriptor : (descriptor?.["#text"] ?? "");
+        })
+            .filter(Boolean);
+        return {
+            pmid,
+            title: String(articleData?.ArticleTitle ?? ""),
+            abstract,
+            authors,
+            journal: String(journalData?.Title ?? journalData?.ISOAbbreviation ?? ""),
+            year: String(publicationDate?.Year ?? ""),
+            doi,
+            meshTerms,
+            pmcId: null,
+        };
+    });
+}
+export function parseIdConvResponse(data) {
+    const result = new Map();
+    const records = data?.records ?? [];
+    for (const record of records)
+        if (record.pmid !== undefined && record.pmcid !== undefined)
+            result.set(record.pmid, record.pmcid);
+    return result;
+}
+function flattenTextContent(node) {
+    if (typeof node === "string" || typeof node === "number")
+        return String(node);
+    if (node === null || typeof node !== "object")
+        return "";
+    return Object.entries(node)
+        .flatMap(([key, value]) => {
+        if (key.startsWith("@_") || key === "fig" || key === "table-wrap" || key === "supplementary-material")
+            return [];
+        if (key === "#text")
+            return [String(value)];
+        return Array.isArray(value) ? value.map(flattenTextContent) : [flattenTextContent(value)];
+    })
+        .filter(Boolean)
+        .join("");
+}
+function extractParagraphs(container) {
+    const paragraphs = container.p;
+    if (paragraphs === undefined)
+        return "";
+    return (Array.isArray(paragraphs) ? paragraphs : [paragraphs])
+        .map((paragraph) => (typeof paragraph === "string" ? paragraph : flattenTextContent(paragraph)))
+        .filter(Boolean)
+        .join("\n\n");
+}
+function extractSection(section, output) {
+    if (section === null || typeof section !== "object")
+        return;
+    const object = section;
+    const text = extractParagraphs(object);
+    if (text)
+        output.push({ heading: typeof object.title === "string" ? object.title : "", text });
+    const nested = object.sec;
+    for (const child of nested === undefined ? [] : Array.isArray(nested) ? nested : [nested])
+        extractSection(child, output);
+}
+export function parsePmcFullText(xml) {
+    const article = xmlParser.parse(xml)?.["pmc-articleset"]?.article;
+    const body = article?.body;
+    if (body === undefined)
+        return null;
+    const sections = [];
+    for (const section of body.sec === undefined ? [] : Array.isArray(body.sec) ? body.sec : [body.sec])
+        extractSection(section, sections);
+    if (sections.length === 0) {
+        const text = extractParagraphs(body);
+        if (text)
+            sections.push({ heading: "", text });
+    }
+    return {
+        fullText: sections.map((section) => (section.heading ? `## ${section.heading}\n\n${section.text}` : section.text)).join("\n\n"),
+        sections,
+    };
+}
+export function createPubmedSource(options = {}) {
+    const url = (endpoint, params) => ncbiUrl(options.apiKey, endpoint, params);
+    async function searchIdsWithTotal(query, searchOptions, signal) {
+        const params = {
+            db: "pubmed",
+            term: query,
+            retmax: searchOptions.maxResults ?? 10,
+            retmode: "json",
+            sort: searchOptions.sort === "date" ? "pub+date" : "relevance",
+        };
+        if (searchOptions.dateRange !== undefined) {
+            params.mindate = searchOptions.dateRange.from;
+            params.maxdate = searchOptions.dateRange.to;
+            params.datetype = "pdat";
+        }
+        const result = await requestJson(url(`${NCBI_BASE}/esearch.fcgi`, params), EsearchResponseSchema, options, signal);
+        if (result.status !== "ok")
+            return result;
+        return {
+            status: "ok",
+            value: {
+                totalFound: parseInt(result.value.esearchresult?.count ?? "0", 10),
+                ids: result.value.esearchresult?.idlist ?? [],
+            },
+        };
+    }
+    async function fetchArticles(pmids, signal) {
+        const result = await requestText(url(`${NCBI_BASE}/efetch.fcgi`, { db: "pubmed", id: pmids.join(","), rettype: "xml", retmode: "xml" }), options, signal);
+        if (result.status !== "ok")
+            return result;
+        if (!/<PubmedArticleSet\b/.test(result.value))
+            return { status: "unavailable", detail: "response schema mismatch: missing PubmedArticleSet" };
+        return { status: "ok", value: parseEfetch(result.value) };
+    }
+    return {
+        async search(query, searchOptions = {}, signal) {
+            const search = await searchIdsWithTotal(query, searchOptions, signal);
+            if (search.status !== "ok")
+                return search;
+            if (search.value.ids.length === 0)
+                return { status: "ok", value: { totalFound: search.value.totalFound, results: [] } };
+            const summary = await requestText(url(`${NCBI_BASE}/esummary.fcgi`, { db: "pubmed", id: search.value.ids.join(","), retmode: "xml" }), options, signal);
+            if (summary.status !== "ok")
+                return summary;
+            return { status: "ok", value: { totalFound: search.value.totalFound, results: parseEsummary(summary.value) } };
+        },
+        async searchIds(query, maxResults, signal) {
+            const result = await searchIdsWithTotal(query, { maxResults }, signal);
+            return result.status === "ok" ? { status: "ok", value: result.value.ids } : result;
+        },
+        async matchCitation(fields, signal) {
+            const bdata = [fields.venue ?? "", fields.year ?? "", fields.volume ?? "", fields.firstPage ?? "", fields.firstAuthor ?? "", fields.key, ""].join("|");
+            const result = await requestText(url(`${NCBI_BASE}/ecitmatch.cgi`, { db: "pubmed", rettype: "xml", bdata }), options, signal);
+            if (result.status !== "ok")
+                return result;
+            const pmids = result.value
+                .trim()
+                .split(/\r?\n/)
+                .flatMap((line) => {
+                const value = line.split("|").at(-1)?.trim();
+                return value !== undefined && /^\d+$/.test(value) ? [value] : [];
+            });
+            return { status: "ok", value: pmids };
+        },
+        fetchArticles,
+        async articleDetails(pmids, signal) {
+            const [articlesResult, conversionResult] = await Promise.all([
+                fetchArticles(pmids, signal),
+                requestJson(url(NCBI_IDCONV, { ids: pmids.join(","), format: "json" }), IdConvResponseSchema, options, signal),
+            ]);
+            if (articlesResult.status !== "ok")
+                return articlesResult;
+            if (conversionResult.status === "ok") {
+                const conversions = parseIdConvResponse(conversionResult.value);
+                for (const article of articlesResult.value)
+                    article.pmcId = conversions.get(article.pmid) ?? null;
+            }
+            const found = new Set(articlesResult.value.map((article) => article.pmid));
+            return { status: "ok", value: { articles: articlesResult.value, notFound: pmids.filter((pmid) => !found.has(pmid)) } };
+        },
+        async fetchFullText(pmcId, signal) {
+            const result = await requestText(url(`${NCBI_BASE}/efetch.fcgi`, { db: "pmc", id: pmcId.replace(/^PMC/i, ""), rettype: "xml", retmode: "xml" }), options, signal);
+            return result.status === "ok" ? { status: "ok", value: parsePmcFullText(result.value) } : result;
+        },
+    };
+}

package/dist/literature/sources/semantic-scholar.d.ts

@@ -0,0 +1,24 @@
+import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+export interface SemanticScholarPaper {
+    id: string;
+    title?: string;
+    abstract?: string;
+    year?: number;
+    venue?: string;
+    citationCount?: number;
+    url?: string;
+    authors: string[];
+    externalIds?: Record<string, string>;
+}
+export interface SemanticScholarSearchPaper extends SemanticScholarPaper {
+    title: string;
+}
+export interface SemanticScholarSourceOptions extends SourceHttpOptions {
+    readonly apiKey?: string;
+}
+export interface SemanticScholarSource {
+    search(query: string, limit: number, signal?: AbortSignal): Promise<SourceHttpResult<SemanticScholarSearchPaper[]>>;
+    lookupIdentifier(identifier: string, signal?: AbortSignal): Promise<SourceHttpResult<SemanticScholarPaper>>;
+}
+export declare function parseSemanticScholarResponse(raw: unknown): SemanticScholarSearchPaper[];
+export declare function createSemanticScholarSource(options?: SemanticScholarSourceOptions): SemanticScholarSource;

package/dist/literature/sources/semantic-scholar.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { requestJson } from "./http.js";
+const BASE_URL = "https://api.semanticscholar.org/graph/v1";
+const FIELDS = "paperId,title,abstract,year,venue,citationCount,url,authors,externalIds";
+const WirePaperSchema = z
+    .object({
+    paperId: z.string().optional(),
+    title: z.string().nullable().optional(),
+    abstract: z.string().nullable().optional(),
+    year: z.number().nullable().optional(),
+    venue: z.string().nullable().optional(),
+    citationCount: z.number().nullable().optional(),
+    url: z.string().nullable().optional(),
+    authors: z.array(z.object({ name: z.string().nullable().optional() })).optional(),
+    externalIds: z.record(z.string(), z.unknown()).nullable().optional(),
+})
+    .passthrough();
+const ExactPaperSchema = WirePaperSchema.extend({ paperId: z.string() });
+const SearchResponseSchema = z.object({ data: z.array(WirePaperSchema).optional() });
+function stringExternalIds(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+function mapPaper(raw) {
+    if (raw.paperId === undefined || raw.paperId.trim() === "")
+        return undefined;
+    const authors = raw.authors?.flatMap((author) => (typeof author.name === "string" && author.name.trim() ? [author.name] : [])) ?? [];
+    const externalIds = stringExternalIds(raw.externalIds);
+    return {
+        id: raw.paperId,
+        ...(typeof raw.title === "string" ? { title: raw.title } : {}),
+        ...(typeof raw.abstract === "string" ? { abstract: raw.abstract } : {}),
+        ...(typeof raw.year === "number" ? { year: raw.year } : {}),
+        ...(typeof raw.venue === "string" ? { venue: raw.venue } : {}),
+        ...(typeof raw.citationCount === "number" ? { citationCount: raw.citationCount } : {}),
+        ...(typeof raw.url === "string" ? { url: raw.url } : {}),
+        authors,
+        ...(externalIds === undefined ? {} : { externalIds }),
+    };
+}
+export function parseSemanticScholarResponse(raw) {
+    const parsed = SearchResponseSchema.safeParse(raw);
+    if (!parsed.success)
+        return [];
+    return (parsed.data.data ?? []).flatMap((paper) => {
+        const mapped = mapPaper(paper);
+        return mapped?.title === undefined ? [] : [mapped];
+    });
+}
+export function createSemanticScholarSource(options = {}) {
+    const headers = options.apiKey === undefined ? {} : { "x-api-key": options.apiKey };
+    return {
+        async search(query, limit, signal) {
+            const params = new URLSearchParams({ query, limit: String(limit), fields: FIELDS });
+            const result = await requestJson(`${BASE_URL}/paper/search?${params}`, SearchResponseSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return result;
+            return { status: "ok", value: parseSemanticScholarResponse(result.value) };
+        },
+        async lookupIdentifier(identifier, signal) {
+            const url = `${BASE_URL}/paper/${encodeURIComponent(identifier)}?fields=${encodeURIComponent(FIELDS)}`;
+            const result = await requestJson(url, ExactPaperSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return result;
+            const paper = mapPaper(result.value);
+            return paper === undefined ? { status: "unavailable", detail: "response schema mismatch: missing paperId" } : { status: "ok", value: paper };
+        },
+    };
+}

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;