@inflexa-ai/harness 0.15.1 → 0.17.0

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/memory/reconstruct-cards.js

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

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

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