@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,114 @@
+/**
+ * Shared builders for the display-card data parts (`data-plan`,
+ * `data-presentation`, `data-run-card`, `data-file-reference`).
+ *
+ * Display tools (`show_plan`, `show_user`, `show_file`) emit these cards live
+ * over the chat SSE stream, but the persisted turn keeps only the Anthropic
+ * transcript (text / tool_use / tool_result) — the cards are not stored. To
+ * re-render a card on reload, `content-to-cortex` reconstructs it from the
+ * tool_use block via these same builders, so the live and replayed cards are
+ * byte-identical (the deterministic `id` matches, enabling downstream
+ * reconciliation).
+ *
+ * The builders return the FLAT wire `data` payload (no `type` wrapper, no
+ * `source`): the tool emits `{ type, source, data }` (the emit pipeline
+ * flattens `data` onto the wire), while the read path spreads the payload
+ * under the part `type` directly.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "../lib/db-result.js";
+export interface PlanCardData {
+    id: string;
+    planId: string;
+    title?: string;
+    steps: unknown;
+    analytical_narrative: unknown;
+    omicsType: unknown;
+    omicsSubtype: unknown;
+}
+export interface PresentationCardData {
+    id: string;
+    title?: string;
+    content: Record<string, unknown>;
+}
+export interface RunCardData {
+    id: string;
+    runId: string;
+    planId: string;
+    title: string;
+    stepCount: number;
+}
+export interface PreviewCardData {
+    id: string;
+    previewId: string;
+    version: number;
+    title: string;
+    previewPath: string;
+    format: "html" | "pdf";
+}
+/** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
+ *  the plan is missing or no longer parses (absence is NOT an error) — the
+ *  caller falls back to a chip. */
+export declare function buildPlanCardData(pool: Pool, planId: string, analysisId: string, title?: string): ResultAsync<PlanCardData | null, DbError>;
+/** Build the `data-run-card` payload for a started analysis run. Loads the
+ *  plan (for `title` + `stepCount`) the same way `buildPlanCardData` does. The
+ *  live emit path passes the freshly-minted `runId`; the reconstruct-on-read
+ *  path omits it and the most recent run for `(analysisId, planId)` is looked
+ *  up from `cortex_runs`. Null when the plan or run cannot be resolved — the
+ *  caller falls back to a chip. */
+export declare function buildRunCardData(pool: Pool, opts: {
+    planId: string;
+    analysisId: string;
+    runId?: string;
+}): ResultAsync<RunCardData | null, DbError>;
+/** Build the `data-presentation` payload from the `show_user` tool input.
+ *  Self-contained — the card lives entirely in the input. */
+export declare function buildPresentationCardData(input: Record<string, unknown>): PresentationCardData | null;
+/** Max files a `show_file` group may reference; multiple render as a gallery. */
+export declare const MAX_FILES = 10;
+/** One referenced file in a `data-file-reference` card. */
+export interface FileReferenceEntryData {
+    path: string;
+    runId?: string;
+    caption?: string;
+}
+/** The `data-file-reference` payload: a group of referenced analysis artifacts. */
+export interface FileReferenceCardData {
+    id: string;
+    title?: string;
+    files: FileReferenceEntryData[];
+}
+/** Extracts `runId` from paths shaped `runs/{runId}/...`; undefined otherwise. */
+export declare function deriveRunId(path: string): string | undefined;
+/** Stable dedup key over sorted paths + optional title. */
+export declare function fileGroupHash(paths: string[], title: string | undefined): string;
+/**
+ * Build the `data-file-reference` payload from the `show_file` tool input. Shared by the live emit
+ * and the reconstruct-on-read path so both cards are byte-identical (same group-hash id, per-entry
+ * `runId` derivation, captions). `null` when no valid group can be built — no files, too many, or ANY
+ * path failing the shared shape rules (leading slash / `..` traversal). The live tool maps `null` to
+ * its `invalid_path` variant and emits nothing; the read path falls back to a generic tool chip.
+ * Validating here is load-bearing: the transcript persists the raw tool_use, so without it a traversal
+ * path the live tool rejected would be resurrected into a card on reload.
+ */
+export declare function buildFileReferenceCardData(input: Record<string, unknown>): FileReferenceCardData | null;
+/**
+ * Build the `data-report-preview` payload for an `iterate_report` tool_use. The
+ * preview's source of truth is the filesystem under
+ * `previews/{previewId}/`: directory layout yields `version`
+ * (latest `vN`) + `previewPath`, and `preview-meta.json` yields title/format.
+ * Mirrors `buildRunCardData` — the live emit knows the server-generated
+ * `previewId`, while the reconstruct-on-read path resolves it (from the
+ * iteration's `previewId` input, or else the analysis's latest preview). The
+ * card is keyed by `previewId` only, so every iteration's tool_use rebuilds
+ * the same card and the frontend groups them into one with all versions selectable.
+ * Null when nothing renders — the caller falls back to a chip.
+ */
+export declare function buildPreviewCardData(
+/** Absolute host root of the analysis's workspace tree (previews live inside it). */
+workspaceRoot: string, opts: {
+    previewId?: string;
+    title?: string;
+    format?: "html" | "pdf";
+}): Promise<PreviewCardData | null>;

package/dist/memory/card-builders.js

@@ -0,0 +1,231 @@
+/**
+ * Shared builders for the display-card data parts (`data-plan`,
+ * `data-presentation`, `data-run-card`, `data-file-reference`).
+ *
+ * Display tools (`show_plan`, `show_user`, `show_file`) emit these cards live
+ * over the chat SSE stream, but the persisted turn keeps only the Anthropic
+ * transcript (text / tool_use / tool_result) — the cards are not stored. To
+ * re-render a card on reload, `content-to-cortex` reconstructs it from the
+ * tool_use block via these same builders, so the live and replayed cards are
+ * byte-identical (the deterministic `id` matches, enabling downstream
+ * reconciliation).
+ *
+ * The builders return the FLAT wire `data` payload (no `type` wrapper, no
+ * `source`): the tool emits `{ type, source, data }` (the emit pipeline
+ * flattens `data` onto the wire), while the read path spreads the payload
+ * under the part `type` directly.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { okAsync } from "neverthrow";
+import { tryQuery } from "../lib/db-result.js";
+import { tryFs } from "../lib/fs-result.js";
+import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
+import { loadPlan } from "../state/index.js";
+import { validatePath } from "../tools/lib/path-validation.js";
+import { latestPreviewVersion, previewDir, PREVIEWS_ROOT } from "../workspace/paths.js";
+const PREVIEW_META_FILE = "preview-meta.json";
+/** Deterministic presentation id — must match `show_user`'s. */
+function presentationId(input) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify(input, Object.keys(input).sort()))
+        .digest("hex")
+        .slice(0, 16);
+    return `pres-${hash}`;
+}
+/** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
+ *  the plan is missing or no longer parses (absence is NOT an error) — the
+ *  caller falls back to a chip. */
+export function buildPlanCardData(pool, planId, analysisId, title) {
+    return loadPlan(pool, planId, { analysisId }).map((plan) => {
+        if (!plan)
+            return null;
+        const parsed = AnalysisPlanSchema.safeParse(plan);
+        if (!parsed.success)
+            return null;
+        const id = `pres-${createHash("sha256").update(planId).digest("hex").slice(0, 16)}`;
+        // Explicit `show_plan({ title })` overrides; otherwise default to the
+        // planner-set plan title so both cards share one source.
+        const heading = title ?? parsed.data.title;
+        return {
+            id,
+            planId,
+            ...(heading !== undefined ? { title: heading } : {}),
+            steps: parsed.data.steps,
+            analytical_narrative: parsed.data.analytical_narrative,
+            omicsType: parsed.data.omicsType,
+            omicsSubtype: parsed.data.omicsSubtype,
+        };
+    });
+}
+/** Build the `data-run-card` payload for a started analysis run. Loads the
+ *  plan (for `title` + `stepCount`) the same way `buildPlanCardData` does. The
+ *  live emit path passes the freshly-minted `runId`; the reconstruct-on-read
+ *  path omits it and the most recent run for `(analysisId, planId)` is looked
+ *  up from `cortex_runs`. Null when the plan or run cannot be resolved — the
+ *  caller falls back to a chip. */
+export function buildRunCardData(pool, opts) {
+    const { planId, analysisId } = opts;
+    return loadPlan(pool, planId, { analysisId }).andThen((plan) => {
+        if (!plan)
+            return okAsync(null);
+        const parsed = AnalysisPlanSchema.safeParse(plan);
+        if (!parsed.success)
+            return okAsync(null);
+        const finalize = (runId) => {
+            if (!runId)
+                return null;
+            const omicsType = parsed.data.omicsType;
+            const title = parsed.data.title?.trim() || (omicsType ? `${omicsType} analysis` : "Analysis run");
+            const id = `pres-${createHash("sha256").update(runId).digest("hex").slice(0, 16)}`;
+            return {
+                id,
+                runId,
+                planId,
+                title,
+                stepCount: parsed.data.steps.length,
+            };
+        };
+        if (opts.runId)
+            return okAsync(finalize(opts.runId));
+        return tryQuery("cardBuilders.buildRunCardData.latestRun", async () => {
+            const result = await pool.query({
+                text: `SELECT run_id FROM cortex_runs
+               WHERE analysis_id = $1 AND plan_id = $2
+               ORDER BY started_at DESC LIMIT 1`,
+                values: [analysisId, planId],
+            });
+            return result.rows[0]?.run_id;
+        }).map(finalize);
+    });
+}
+/** Build the `data-presentation` payload from the `show_user` tool input.
+ *  Self-contained — the card lives entirely in the input. */
+export function buildPresentationCardData(input) {
+    const { kind, title, ...rest } = input;
+    if (typeof kind !== "string")
+        return null;
+    return {
+        id: presentationId(input),
+        ...(typeof title === "string" ? { title } : {}),
+        content: { kind, ...rest },
+    };
+}
+/** Max files a `show_file` group may reference; multiple render as a gallery. */
+export const MAX_FILES = 10;
+/** Extracts `runId` from paths shaped `runs/{runId}/...`; undefined otherwise. */
+export function deriveRunId(path) {
+    const segments = path.split("/");
+    if (segments.length >= 2 && segments[0] === "runs" && segments[1].length > 0) {
+        return segments[1];
+    }
+    return undefined;
+}
+/** Stable dedup key over sorted paths + optional title. */
+export function fileGroupHash(paths, title) {
+    const sorted = [...paths].sort();
+    const material = JSON.stringify({ title: title ?? null, paths: sorted });
+    return createHash("sha256").update(material).digest("hex").slice(0, 16);
+}
+/**
+ * Build the `data-file-reference` payload from the `show_file` tool input. Shared by the live emit
+ * and the reconstruct-on-read path so both cards are byte-identical (same group-hash id, per-entry
+ * `runId` derivation, captions). `null` when no valid group can be built — no files, too many, or ANY
+ * path failing the shared shape rules (leading slash / `..` traversal). The live tool maps `null` to
+ * its `invalid_path` variant and emits nothing; the read path falls back to a generic tool chip.
+ * Validating here is load-bearing: the transcript persists the raw tool_use, so without it a traversal
+ * path the live tool rejected would be resurrected into a card on reload.
+ */
+export function buildFileReferenceCardData(input) {
+    const title = typeof input.title === "string" ? input.title : undefined;
+    const rawFiles = Array.isArray(input.files) ? input.files : [];
+    if (rawFiles.length === 0 || rawFiles.length > MAX_FILES)
+        return null;
+    const files = [];
+    for (const raw of rawFiles) {
+        const file = (raw ?? {});
+        const path = typeof file.path === "string" ? file.path : "";
+        if (validatePath(path) !== null)
+            return null;
+        const runId = deriveRunId(path);
+        const caption = typeof file.caption === "string" ? file.caption : undefined;
+        files.push({
+            path,
+            ...(runId !== undefined ? { runId } : {}),
+            ...(caption !== undefined ? { caption } : {}),
+        });
+    }
+    const id = `pres-${fileGroupHash(files.map((f) => f.path), title)}`;
+    return { id, ...(title !== undefined ? { title } : {}), files };
+}
+/** The stored preview metadata, or `null` when the file is absent — a malformed
+ *  file is a genuine read failure (`err`), folded to `null` at the call site. */
+function readPreviewMeta(previewRootAbs) {
+    const path = join(previewRootAbs, PREVIEW_META_FILE);
+    return tryFs("cardBuilders.readPreviewMeta", async () => JSON.parse(await readFile(path, "utf8")), { path, onAbsent: () => null });
+}
+/** Directory names (not files) directly under `dir`, or `[]` when absent. */
+function subdirs(dir) {
+    return tryFs("cardBuilders.subdirs", async () => (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name), {
+        path: dir,
+        onAbsent: () => [],
+    });
+}
+/** The most-recently-modified previewId under an analysis, or null when none. */
+function latestPreviewId(previewsRootAbs) {
+    return subdirs(previewsRootAbs).map(async (dirs) => {
+        if (dirs.length <= 1)
+            return dirs[0] ?? null;
+        let best = null;
+        for (const name of dirs) {
+            const path = join(previewsRootAbs, name);
+            const mtimeMs = await tryFs("cardBuilders.latestPreviewId.stat", async () => (await stat(path)).mtimeMs, { path }).unwrapOr(null); // skip an unreadable/absent entry
+            if (mtimeMs !== null && (!best || mtimeMs > best.mtimeMs)) {
+                best = { name, mtimeMs };
+            }
+        }
+        return best?.name ?? dirs[0];
+    });
+}
+/**
+ * Build the `data-report-preview` payload for an `iterate_report` tool_use. The
+ * preview's source of truth is the filesystem under
+ * `previews/{previewId}/`: directory layout yields `version`
+ * (latest `vN`) + `previewPath`, and `preview-meta.json` yields title/format.
+ * Mirrors `buildRunCardData` — the live emit knows the server-generated
+ * `previewId`, while the reconstruct-on-read path resolves it (from the
+ * iteration's `previewId` input, or else the analysis's latest preview). The
+ * card is keyed by `previewId` only, so every iteration's tool_use rebuilds
+ * the same card and the frontend groups them into one with all versions selectable.
+ * Null when nothing renders — the caller falls back to a chip.
+ */
+export async function buildPreviewCardData(
+/** Absolute host root of the analysis's workspace tree (previews live inside it). */
+workspaceRoot, opts) {
+    const previewsRootAbs = join(workspaceRoot, PREVIEWS_ROOT);
+    const resolveId = opts.previewId ? okAsync(opts.previewId) : latestPreviewId(previewsRootAbs);
+    return resolveId
+        .andThen((previewId) => {
+        if (!previewId)
+            return okAsync(null);
+        const previewRootAbs = join(workspaceRoot, previewDir(previewId));
+        return subdirs(previewRootAbs).andThen((versionDirs) => {
+            const version = latestPreviewVersion(versionDirs);
+            if (version === 0)
+                return okAsync(null);
+            return readPreviewMeta(previewRootAbs).map((meta) => {
+                const id = `prev-${createHash("sha256").update(previewId).digest("hex").slice(0, 16)}`;
+                return {
+                    id,
+                    previewId,
+                    version,
+                    title: opts.title ?? meta?.title ?? "Report",
+                    previewPath: `v${version}/index.html`,
+                    format: opts.format ?? (meta?.format === "pdf" ? "pdf" : "html"),
+                };
+            });
+        });
+    })
+        .unwrapOr(null);
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Converter: stored AI SDK model messages → wire `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:
+ *
+ *   - 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
+ *   - 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.
+ *
+ * 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
+ * conversation has no empty bubbles. Storage is never mutated.
+ */
+import type { CortexMessage } from "@inflexa-ai/harness/contracts/message.js";
+import type { ToolCardResolver } from "./reconstruct-cards.js";
+import type { StoredMessage } from "./thread-history.js";
+/**
+ * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
+ * no renderable parts are dropped, and consecutive same-role rows are coalesced
+ * into one message. The first row's `seq` becomes the stable message id.
+ * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ *
+ * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
+ * step (typically a single `tool_use`) as its own row, and the `tool_result`
+ * `user` rows between them drop to zero renderable parts above — so one assistant
+ * turn is stored as a run of adjacent assistant rows. The live chat stream
+ * accumulates that whole turn into a single assistant message whose `parts` hold
+ * every step; reconstructing it row-by-row instead would emit one message per
+ * tool call, which the UI renders as a stack of single-tool boxes. Merging the
+ * run restores the one-bubble-per-turn shape (and lets the UI collapse the tool
+ * calls into one group) regardless of how the loop split the turn into rows.
+ */
+export declare function contentToCortexMessages(messages: readonly StoredMessage[], resolveCard?: ToolCardResolver): Promise<CortexMessage[]>;

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

@@ -0,0 +1,85 @@
+/**
+ * Converter: stored AI SDK model messages → wire `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:
+ *
+ *   - 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
+ *   - 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.
+ *
+ * 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
+ * conversation has no empty bubbles. Storage is never mutated.
+ */
+function genericToolCall(block) {
+    return {
+        type: "tool-call",
+        toolCallId: block.toolCallId,
+        toolName: block.toolName,
+        status: "finished",
+    };
+}
+async function blockToPart(block, resolveCard) {
+    if (block.type === "text")
+        return { type: "text", text: block.text };
+    if (block.type === "tool-call") {
+        const card = resolveCard ? await resolveCard({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.input }) : null;
+        return card ?? genericToolCall(block);
+    }
+    // reasoning, tool_result, file, and any other block — not rendered.
+    return null;
+}
+async function rowToParts(message, resolveCard) {
+    const content = message.content;
+    if (typeof content === "string") {
+        return content.length > 0 ? [{ type: "text", text: content }] : [];
+    }
+    const parts = [];
+    for (const block of content) {
+        const part = await blockToPart(block, resolveCard);
+        if (part)
+            parts.push(part);
+    }
+    return parts;
+}
+/**
+ * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
+ * no renderable parts are dropped, and consecutive same-role rows are coalesced
+ * into one message. The first row's `seq` becomes the stable message id.
+ * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ *
+ * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
+ * step (typically a single `tool_use`) as its own row, and the `tool_result`
+ * `user` rows between them drop to zero renderable parts above — so one assistant
+ * turn is stored as a run of adjacent assistant rows. The live chat stream
+ * accumulates that whole turn into a single assistant message whose `parts` hold
+ * every step; reconstructing it row-by-row instead would emit one message per
+ * tool call, which the UI renders as a stack of single-tool boxes. Merging the
+ * run restores the one-bubble-per-turn shape (and lets the UI collapse the tool
+ * calls into one group) regardless of how the loop split the turn into rows.
+ */
+export async function contentToCortexMessages(messages, resolveCard) {
+    const out = [];
+    for (const message of messages) {
+        const parts = await rowToParts(message.message, resolveCard);
+        if (parts.length === 0)
+            continue;
+        const role = message.message.role === "tool" ? "assistant" : message.message.role;
+        const prev = out[out.length - 1];
+        if (prev && prev.role === role) {
+            prev.parts.push(...parts);
+            continue;
+        }
+        out.push({ id: String(message.seq), role, parts });
+    }
+    return out;
+}

package/dist/memory/count-tokens.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Write-time token counting for the conversation message store.
+ *
+ * `appendTurn` stamps a `tokens` count on every message row so `loadRecent`
+ * windows by token budget without tokenizing on the read path. Counted once
+ * at write, applied at load.
+ *
+ * Providers do not publish one shared offline tokenizer,
+ * so this uses `js-tiktoken`'s `cl100k_base` BPE. It is an approximation:
+ * callers treat the budget as a soft target with a safety margin below the
+ * true context limit.
+ */
+import type { ModelMessage } from "ai";
+/**
+ * Token count of a message's content. Used only at write time. Empty
+ * content (an empty array or empty string) counts as `0`.
+ */
+export declare function countTokens(content: ModelMessage["content"]): number;

package/dist/memory/count-tokens.js

@@ -0,0 +1,64 @@
+/**
+ * Write-time token counting for the conversation message store.
+ *
+ * `appendTurn` stamps a `tokens` count on every message row so `loadRecent`
+ * windows by token budget without tokenizing on the read path. Counted once
+ * at write, applied at load.
+ *
+ * Providers do not publish one shared offline tokenizer,
+ * so this uses `js-tiktoken`'s `cl100k_base` BPE. It is an approximation:
+ * callers treat the budget as a soft target with a safety margin below the
+ * true context limit.
+ */
+import { getEncoding } from "js-tiktoken";
+let encoder;
+function enc() {
+    encoder ??= getEncoding("cl100k_base");
+    return encoder;
+}
+/**
+ * The token-bearing text of one content block. Text-carrying fields are
+ * extracted directly; structural blocks (`tool_use` input, `tool_result`
+ * payload) are JSON-stringified. A signed `thinking` block counts only its
+ * reasoning text — the opaque `signature` is metadata, not prompt tokens.
+ */
+function tokenizableText(block) {
+    if (typeof block === "string")
+        return block;
+    if (typeof block !== "object" || block === null)
+        return JSON.stringify(block);
+    const part = block;
+    switch (part.type) {
+        case "text":
+            return typeof part.text === "string" ? part.text : "";
+        case "reasoning":
+            return typeof part.text === "string" ? part.text : "";
+        case "reasoning-file":
+        case "custom":
+        case "file":
+            return "";
+        case "tool-call":
+            return `${String(part.toolName ?? "")} ${JSON.stringify(part.input ?? {})}`;
+        case "tool-result": {
+            return `${String(part.toolName ?? "")} ${JSON.stringify(part.output ?? {})}`;
+        }
+        default:
+            return JSON.stringify(part);
+    }
+}
+/**
+ * Token count of a message's content. Used only at write time. Empty
+ * content (an empty array or empty string) counts as `0`.
+ */
+export function countTokens(content) {
+    if (typeof content === "string") {
+        return content.length === 0 ? 0 : enc().encode(content).length;
+    }
+    let total = 0;
+    for (const block of content) {
+        const text = tokenizableText(block);
+        if (text.length > 0)
+            total += enc().encode(text).length;
+    }
+    return total;
+}

package/dist/memory/derive-thread-title.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Derive a deterministic thread title from the user's first message.
+ * Pure function — no I/O, no global state.
+ *
+ * Rules:
+ * 1. Collapse runs of whitespace to a single space.
+ * 2. Trim.
+ * 3. Empty / whitespace-only input → `"Untitled"`.
+ * 4. If length ≤ `max`, return unchanged.
+ * 5. Else slice to `max`, walk back to the last space (word boundary),
+ *    append the real ellipsis `…` (U+2026). If no space exists inside
+ *    the window, hard-slice at `max` and append `…`.
+ */
+export declare function deriveThreadTitle(text: string, max?: number): string;

package/dist/memory/derive-thread-title.js

@@ -0,0 +1,26 @@
+/**
+ * Derive a deterministic thread title from the user's first message.
+ * Pure function — no I/O, no global state.
+ *
+ * Rules:
+ * 1. Collapse runs of whitespace to a single space.
+ * 2. Trim.
+ * 3. Empty / whitespace-only input → `"Untitled"`.
+ * 4. If length ≤ `max`, return unchanged.
+ * 5. Else slice to `max`, walk back to the last space (word boundary),
+ *    append the real ellipsis `…` (U+2026). If no space exists inside
+ *    the window, hard-slice at `max` and append `…`.
+ */
+export function deriveThreadTitle(text, max = 40) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0)
+        return "Untitled";
+    if (normalized.length <= max)
+        return normalized;
+    const slice = normalized.slice(0, max);
+    const lastSpace = slice.lastIndexOf(" ");
+    if (lastSpace > 0) {
+        return slice.slice(0, lastSpace) + "…";
+    }
+    return slice + "…";
+}

package/dist/memory/message-backfill.d.ts

@@ -0,0 +1,2 @@
+import type { PoolClient } from "pg";
+export declare function backfillAiSdkMessageEnvelopes(client: PoolClient): Promise<void>;

package/dist/memory/message-backfill.js

@@ -0,0 +1,38 @@
+import { envelopeMessage, legacyAnthropicToModelMessage } from "./ai-sdk-message-storage.js";
+export async function backfillAiSdkMessageEnvelopes(client) {
+    // Legacy Anthropic columns (`role`, `content_jsonb`) are temporary and
+    // should be removed after the AI SDK message-envelope migration window.
+    const { rows } = await client.query(`SELECT thread_id, seq::text AS seq, role, content_jsonb
+         FROM messages
+         WHERE message_envelope IS NULL
+         ORDER BY thread_id, seq`);
+    for (const row of rows) {
+        const identity = `${row.thread_id}/${row.seq}`;
+        try {
+            const message = legacyAnthropicToModelMessage({
+                threadId: row.thread_id,
+                seq: Number(row.seq),
+                role: row.role,
+                content: row.content_jsonb,
+            });
+            await client.query("UPDATE messages SET message_envelope = $1::jsonb WHERE thread_id = $2 AND seq = $3::bigint", [
+                JSON.stringify(envelopeMessage(message)),
+                row.thread_id,
+                row.seq,
+            ]);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to backfill AI SDK message envelope for ${identity}: ${message}`, { cause: err });
+        }
+    }
+    const remaining = await client.query(`SELECT thread_id, seq::text AS seq
+         FROM messages
+         WHERE message_envelope IS NULL
+         ORDER BY thread_id, seq
+         LIMIT 1`);
+    if (remaining.rows.length > 0) {
+        const row = remaining.rows[0];
+        throw new Error(`AI SDK message backfill left an unmigrated row at ${row.thread_id}/${row.seq}`);
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Read-path reconstruction of display cards from a persisted turn.
+ *
+ * `show_plan` / `show_user` / `show_file` / `execute_plan` / `iterate_report` emit
+ * `data-plan` / `data-presentation` / `data-file-reference` / `data-run-card` /
+ * `data-report-preview` cards
+ * live over the chat SSE stream. On reload, `content-to-cortex` calls this
+ * resolver for each AI SDK tool-call part: a recognised display tool yields its card (rebuilt via the
+ * shared `card-builders`); anything else yields `null` and falls back to a
+ * generic `tool-call` chip. Keyed by the analysis `Pool` + id (plan / run) or
+ * the analysis's workspace root (preview, filesystem-backed) so the card can
+ * be re-loaded.
+ */
+import type { CortexPart } from "@inflexa-ai/harness/contracts/message.js";
+import type { Pool } from "pg";
+export interface StoredToolCallForCard {
+    readonly type: "tool_use";
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+export type ToolCardResolver = (block: StoredToolCallForCard) => Promise<CortexPart | null>;
+export declare function createCardResolver(pool: Pool, analysisId: string, workspaceRoot: string): ToolCardResolver;