@guuey/threads 0.31.0 → 0.32.0

package/dist/fold-rows.js

@@ -1,4 +1,4 @@
-import { readStoredAgMemoryRecords, readStoredAgMessage } from "@silverprotocol/core";
+import { AgProviderMeta, readStoredAgMemoryRecords, readStoredAgMessage } from "@silverprotocol/core";
 import { asUiResource, scanProviderRawForUiResource, toolResultLocator } from "@guuey/mcp-apps-host/narrowing";
 /** AgRole → the row's coarse authorRole projection (secondary; role of record lives in content). */
 function roleToAuthor(role) {
@@ -58,10 +58,24 @@ export function messageFullText(msg) {
  * Split a stored row's `content` into answer, narration and the model's full
  * text, when `content` is a stored `AgMessage` (an object, or the JSON string
  * an AppSync writer stores). Anything else is null, and a reader falls back to
- * the row's `text`. It is read through core's lenient stored-record reader, so
- * an unknown block is omitted rather than failing the row.
+ * the row's `text`. The message is read by {@link readStoredRowMessage}, so an
+ * unknown block is omitted rather than failing the row, and an elided answer
+ * reads from the row's `text`. `text` is required so that every caller passes
+ * the row's `text` on purpose (`undefined` or null when the row has none).
  */
-export function storedTextParts(content) {
+export function storedTextParts(content, text) {
+    const msg = readStoredContentMessage(content, text);
+    if (msg === undefined)
+        return null;
+    return { answer: messageText(msg), narration: messageNarration(msg), all: messageFullText(msg) };
+}
+/**
+ * A stored row's `content` read as its message: a stored `AgMessage` object,
+ * or the JSON string an AppSync writer stores, through
+ * {@link readStoredRowMessage}. `undefined` for anything else (not JSON, or
+ * not a message core can materialize).
+ */
+function readStoredContentMessage(content, text) {
     let raw = content;
     if (typeof content === "string") {
         try {
@@ -69,17 +83,139 @@ export function storedTextParts(content) {
         }
         catch (err) {
             if (err instanceof SyntaxError)
-                return null; // not JSON: not a stored AgMessage
+                return undefined; // not JSON: not a stored AgMessage
             throw err;
         }
     }
-    if (raw === null || typeof raw !== "object")
-        return null;
-    const read = readStoredAgMessage(raw);
+    return readStoredRowMessage(raw, text);
+}
+/**
+ * The tool calls a stored row's message makes, in block order, as
+ * {@link StoredToolCallView}s (guuey#2388). The name rides only the call; a
+ * result carries just the id, and a facet may store the result in a message
+ * (and so a row) of its own, so a reader that names a result reads the calls
+ * of the rows around it (guuey#2487). Empty when `content` is not a stored
+ * message.
+ */
+export function storedToolCallViews(content, text) {
+    const msg = readStoredContentMessage(content, text);
+    if (msg === undefined)
+        return [];
+    const calls = [];
+    for (const block of msg.content) {
+        if (block.type !== "tool-call")
+            continue;
+        const view = { toolCallId: block.toolCallId, name: block.name, input: block.input };
+        if (block.title !== undefined)
+            view.title = block.title;
+        calls.push(view);
+    }
+    return calls;
+}
+/**
+ * The tool results a stored row's message carries that NO card row stands for
+ * (guuey#2487): every `tool-result` block that does not carry a UI resource
+ * ({@link toolResultCarriesUi}), without its `_meta` (guuey#122), in block
+ * order. A host draws from such a result (an in-process tool's
+ * `structuredContent`, or its text) live; this is how a reader finds it again
+ * after a reload. A UI-carrying result is left out: its card row already
+ * carries it. Empty when `content` is not a stored message.
+ */
+export function storedToolResults(content, text) {
+    const msg = readStoredContentMessage(content, text);
+    if (msg === undefined)
+        return [];
+    const results = [];
+    for (const block of msg.content) {
+        if (block.type === "tool-result" && !toolResultCarriesUi(block))
+            results.push(withoutToolResultMeta(block));
+    }
+    return results;
+}
+/**
+ * The call id of EVERY `tool-result` block a stored row's message carries, in
+ * block order, whether it carries a UI resource or not (guuey#2487). A reader
+ * that names results by their calls uses it to tell where a call's results
+ * sit on a page, card-drawn ones included: a call's first result row is
+ * written straight after the call row, and a UI-carrying result's card row
+ * straight after the result (guuey#2396). Empty when `content` is not a
+ * stored message.
+ */
+export function storedToolResultCallIds(content, text) {
+    const msg = readStoredContentMessage(content, text);
+    if (msg === undefined)
+        return [];
+    const ids = [];
+    for (const block of msg.content) {
+        if (block.type === "tool-result")
+            ids.push(block.toolCallId);
+    }
+    return ids;
+}
+/**
+ * A row's stored message as every reader of a row reads it ({@link storedTextParts},
+ * {@link rowToAgMessage}, `classifyStoredRow`): `content` (a stored `AgMessage`
+ * object) through core's lenient stored-record reader, with an ELIDED ANSWER
+ * restored from the row's `text`. `undefined` when core cannot materialize the
+ * message. Like core's reader, it returns a view, never a record to persist.
+ *
+ * A stored message may leave its answer out of `content` because the row's
+ * `text` carries the same words: an answer block whose `text` is the
+ * {@link ELIDED_VALUE_KEY} marker ({@link isElidedAnswerBlock}). Such a message
+ * is rebuilt once, before it is read: the row's `text` (every answer block,
+ * joined) becomes the text of the first answer block, and every later answer
+ * block is left out, since that `text` already holds it. An answer block here
+ * is a block core can read as a text block, not narration, that is elided or
+ * non-empty. Every other block stays as stored. When the answer blocks stand
+ * together, as a reply's do, the rebuilt message reads the same text as the
+ * unelided one.
+ *
+ * Only the marker reads the row's `text`: a message with no answer blocks reads
+ * as it always has, with an empty answer, whatever the row's `text` says. On a
+ * row with no `text` (absent, NULL or empty) there is nothing to restore: only
+ * the elided blocks are left out and every other block reads as stored, so a
+ * stored word is never erased. An elided answer alone then reads as an empty
+ * answer in {@link storedTextParts} and `classifyStoredRow`, as its unelided
+ * twin with an empty answer would; the rebuilt message leaves the block out.
+ */
+export function readStoredRowMessage(content, text) {
+    if (!isStoredMessageObject(content) || !content.content.some(isElidedAnswerBlock)) {
+        return readStoredAgMessage(content).value;
+    }
+    const stored = content.content;
+    if (!text) {
+        return readStoredAgMessage({ ...content, content: stored.filter((element) => !isElidedAnswerBlock(element)) }).value;
+    }
+    // Each elided answer opened to an empty string first, so core judges every other field of it.
+    const opened = stored.map((element) => (isElidedAnswerBlock(element) ? { ...element, text: "" } : element));
+    const read = readStoredAgMessage({ ...content, content: opened });
     if (read.value === undefined)
-        return null;
-    const msg = read.value;
-    return { answer: messageText(msg), narration: messageNarration(msg), all: messageFullText(msg) };
+        return undefined;
+    const unread = new Set(read.reports.flatMap((r) => (r.path[0] === "content" && typeof r.path[1] === "number" ? [r.path[1]] : [])));
+    const isAnswer = (element, at) => !unread.has(at) && isAnswerTextElement(element) && (element.text !== "" || isElidedAnswerBlock(stored[at]));
+    const first = opened.findIndex(isAnswer);
+    const rebuilt = opened.flatMap((element, at) => {
+        if (at === first && isAnswerTextElement(element))
+            return [{ ...element, text }];
+        return isAnswer(element, at) ? [] : [element];
+    });
+    return readStoredAgMessage({ ...content, content: rebuilt }).value;
+}
+/** A stored value with a `content` array: the shape a stored `AgMessage` has, before core reads it. */
+function isStoredMessageObject(value) {
+    return value !== null && typeof value === "object" && "content" in value && Array.isArray(value.content);
+}
+/** A stored element shaped as a text block that is not interim narration. */
+function isNonNarrationTextElement(element) {
+    if (element === null || typeof element !== "object" || Array.isArray(element))
+        return false;
+    if (!("type" in element) || element.type !== "text" || !("text" in element))
+        return false;
+    return !("phase" in element && element.phase === "interim");
+}
+/** A stored answer block that carries its words: a non-narration text element whose `text` is a string. */
+function isAnswerTextElement(element) {
+    return isNonNarrationTextElement(element) && typeof element.text === "string";
 }
 export function agMessageToRow(msg, ctx) {
     const text = messageText(msg);
@@ -109,6 +245,241 @@ export function agMessageToRow(msg, ctx) {
         ...(ctx.untrustedOrigin === true ? { untrustedOrigin: true } : {}),
     };
 }
+/**
+ * The key of the marker a stored value is replaced by when the row would not
+ * fit its store's {@link RowBudget}: `{ "com.guuey/elided": { bytes } }`, where
+ * `bytes` is the UTF-8 length of the elided value's JSON. It stands in for the
+ * value whole (a tool-call `input`, its `providerMetadata.wireInput`, or a
+ * tool-result `uiData` the turn's card row also carries), so the block keeps
+ * an object where an object was.
+ */
+export const ELIDED_VALUE_KEY = "com.guuey/elided";
+/**
+ * A row cannot fit its store's {@link RowBudget}, even with every value it
+ * carries that may be elided elided. Counts only, never row content.
+ */
+export class StoredRowTooLargeError extends Error {
+    bytes;
+    maxBytes;
+    rowKind;
+    index;
+    name = "StoredRowTooLargeError";
+    constructor(bytes, maxBytes, rowKind, 
+    /** The row's index among the turn's message or card rows (0 for an append). */
+    index) {
+        super(`stored ${rowKind} row ${index} is ${bytes} bytes; the store's row budget is ${maxBytes}`);
+        this.bytes = bytes;
+        this.maxBytes = maxBytes;
+        this.rowKind = rowKind;
+        this.index = index;
+    }
+}
+/**
+ * A row carries a number its store cannot hold as written (see
+ * {@link RowBudget.numberFits}) outside any tool-call value that could be
+ * elided. Never names the number: it may be part of a tool's input or result.
+ */
+export class StoredRowUnstorableNumberError extends Error {
+    rowKind;
+    index;
+    name = "StoredRowUnstorableNumberError";
+    constructor(rowKind, 
+    /** The row's index among the turn's message or card rows (0 for an append). */
+    index) {
+        super(`stored ${rowKind} row ${index} carries a number its store cannot hold`);
+        this.rowKind = rowKind;
+        this.index = index;
+    }
+}
+export function isStoredRowRefusal(err) {
+    return err instanceof StoredRowTooLargeError || err instanceof StoredRowUnstorableNumberError;
+}
+/** Whether `value` (any JSON-shaped data) holds a number `fits` refuses, at any depth. */
+export function carriesUnfitNumber(value, fits) {
+    if (typeof value === "number")
+        return !fits(value);
+    if (value === null || typeof value !== "object")
+        return false;
+    const children = Array.isArray(value) ? value : Object.values(value);
+    return children.some((child) => carriesUnfitNumber(child, fits));
+}
+/**
+ * Throw when `row` cannot be stored under `budget`: {@link StoredRowUnstorableNumberError}
+ * when it carries a number the store cannot hold, {@link StoredRowTooLargeError}
+ * when it measures over the budget. No-op without a budget.
+ */
+export function assertRowFits(row, budget, rowKind, index) {
+    if (budget === undefined)
+        return;
+    if (budget.numberFits !== undefined && carriesUnfitNumber(row, budget.numberFits)) {
+        throw new StoredRowUnstorableNumberError(rowKind, index);
+    }
+    const bytes = budget.bytesOf(row);
+    if (bytes > budget.maxBytes)
+        throw new StoredRowTooLargeError(bytes, budget.maxBytes, rowKind, index);
+}
+function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function elidedMarker(bytes) {
+    return { [ELIDED_VALUE_KEY]: { bytes } };
+}
+function withElided(block, field, bytes) {
+    if (field === "input")
+        return { ...block, input: elidedMarker(bytes) };
+    return {
+        ...block,
+        providerMetadata: AgProviderMeta.parse({ ...block.providerMetadata, wireInput: elidedMarker(bytes) }),
+    };
+}
+/** The tool-call value `field` of `block`, when it has one. */
+function toolCallValue(block, field) {
+    return field === "input" ? block.input : block.providerMetadata?.["wireInput"];
+}
+function isElidedMarker(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) && ELIDED_VALUE_KEY in value;
+}
+/** {@link CardUiDataByCallId} over a turn's card rows (rows of another kind are skipped). */
+export function cardUiDataByCallId(cardRows) {
+    const byCallId = new Map();
+    for (const row of cardRows) {
+        if (row.kind !== "card" || row.toolName === undefined)
+            continue;
+        const art = cardRowToAgArtifact(row);
+        if (art === undefined)
+            continue;
+        for (const part of art.parts) {
+            if (part.type !== "tool-result" || part.uiData === undefined)
+                continue;
+            const entry = { name: row.toolName, uiData: part.uiData };
+            const known = byCallId.get(part.toolCallId);
+            if (known === undefined)
+                byCallId.set(part.toolCallId, [entry]);
+            else
+                known.push(entry);
+        }
+    }
+    return byCallId;
+}
+/**
+ * The card row's copy of a tool-result block's `uiData`, when the block's
+ * `uiData` is an inline UI resource with text (`{ uri, text }`, bare or as
+ * `{ resource: {...} }`) and a card row of the turn carries the same value for
+ * the same call. Only then is the message row's copy a pure duplicate.
+ */
+function cardCopyOf(block, cards) {
+    const uiData = block.uiData;
+    if (uiData === undefined || isElidedMarker(uiData) || asUiResource(uiData)?.text === undefined)
+        return undefined;
+    return cards.get(block.toolCallId)?.find((card) => jsonEqual(card.uiData, uiData));
+}
+/**
+ * A stored ANSWER block left out because the row's `text` carries the same
+ * words: a `text` block whose `text` is the {@link ELIDED_VALUE_KEY} marker
+ * (`{ "com.guuey/elided": { bytes } }`, `bytes` the UTF-8 length of the
+ * elided string's JSON) in place of the string. A narration block
+ * (`phase: "interim"`) is never one: the row's `text` is the answer only, so
+ * it holds no narration to read back. Read on the raw stored element, since
+ * core's lenient reader leaves such a block out (its `text` is not a string).
+ */
+export function isElidedAnswerBlock(element) {
+    return isNonNarrationTextElement(element) && isElidedMarker(element.text);
+}
+/**
+ * {@link agMessageToRow}, bounded by the store's {@link RowBudget}. Under the
+ * budget (or with none) the row is exactly `agMessageToRow(msg, ctx)`.
+ *
+ * First, when the budget declares `numberFits`, every tool-call value that
+ * carries a number the store cannot hold is replaced by the
+ * {@link ELIDED_VALUE_KEY} marker (`reason: "number"`; after `JSON.parse` such
+ * a number has already lost its digits, so storing it would store a wrong
+ * one). A row that still carries one elsewhere throws
+ * {@link StoredRowUnstorableNumberError}.
+ *
+ * Then, over the size budget, values are replaced one at a time
+ * (`reason: "size"`) until the row fits. Pure duplicates go first: a
+ * tool-result's `uiData` that is an inline UI resource with text, when a card
+ * row of the turn (`cards`, see {@link cardUiDataByCallId}) carries the same
+ * value for the same call. Then every `providerMetadata.wireInput` (a second
+ * copy of the input, carried only when it differs), then every `input`.
+ * Within each tier the largest goes first, ties in block order. A row that
+ * still does not fit throws {@link StoredRowTooLargeError}.
+ */
+export function agMessageToBoundedRow(msg, ctx, budget, index, cards = new Map()) {
+    let row = agMessageToRow(msg, ctx);
+    if (budget === undefined)
+        return { row, elided: [] };
+    const content = [...msg.content];
+    const elided = [];
+    const elide = (at, field, reason) => {
+        const block = content[at];
+        if (block === undefined)
+            return;
+        if (block.type === "tool-result") {
+            const card = field === "uiData" ? cardCopyOf(block, cards) : undefined;
+            if (card === undefined)
+                return;
+            const bytes = jsonBytes(card.uiData);
+            content[at] = { ...block, uiData: elidedMarker(bytes) };
+            elided.push({ toolCallId: block.toolCallId, name: card.name, field, reason, bytes });
+            return;
+        }
+        if (block.type !== "tool-call" || field === "uiData")
+            return;
+        const value = toolCallValue(block, field);
+        if (value === undefined)
+            return;
+        const bytes = jsonBytes(value);
+        content[at] = withElided(block, field, bytes);
+        elided.push({ toolCallId: block.toolCallId, name: block.name, field, reason, bytes });
+    };
+    const fits = budget.numberFits;
+    if (fits !== undefined && carriesUnfitNumber(row, fits)) {
+        msg.content.forEach((block, at) => {
+            if (block.type !== "tool-call")
+                return;
+            for (const field of ["wireInput", "input"]) {
+                const current = content[at];
+                if (current === undefined || current.type !== "tool-call")
+                    continue;
+                if (carriesUnfitNumber(toolCallValue(current, field), fits))
+                    elide(at, field, "number");
+            }
+        });
+        row = agMessageToRow({ ...msg, content }, ctx);
+        if (carriesUnfitNumber(row, fits))
+            throw new StoredRowUnstorableNumberError("message", index);
+    }
+    let bytes = budget.bytesOf(row);
+    if (bytes <= budget.maxBytes)
+        return { row, elided };
+    const candidates = [];
+    content.forEach((block, at) => {
+        if (block.type === "tool-result") {
+            const card = cardCopyOf(block, cards);
+            if (card !== undefined)
+                candidates.push({ at, field: "uiData", bytes: jsonBytes(card.uiData), tier: 0 });
+            return;
+        }
+        if (block.type !== "tool-call")
+            return;
+        const wire = toolCallValue(block, "wireInput");
+        if (wire !== undefined && !isElidedMarker(wire)) {
+            candidates.push({ at, field: "wireInput", bytes: jsonBytes(wire), tier: 1 });
+        }
+        if (!isElidedMarker(block.input))
+            candidates.push({ at, field: "input", bytes: jsonBytes(block.input), tier: 2 });
+    });
+    candidates.sort((a, b) => a.tier - b.tier || b.bytes - a.bytes || a.at - b.at);
+    for (const c of candidates) {
+        elide(c.at, c.field, "size");
+        row = agMessageToRow({ ...msg, content }, ctx);
+        bytes = budget.bytesOf(row);
+        if (bytes <= budget.maxBytes)
+            return { row, elided };
+    }
+    throw new StoredRowTooLargeError(bytes, budget.maxBytes, "message", index);
+}
 /**
  * A turn's `displayRequired` is content a model provider requires the host to
  * show to the person who asked, under that provider's terms, and those terms
@@ -169,6 +540,55 @@ function withoutToolResultMeta(block) {
     const { _meta: _dropped, ...rest } = block;
     return rest;
 }
+/**
+ * Whether a tool-result block carries a UI resource, and so becomes a card row
+ * ({@link uiCardArtifactsFromMessages}) rather than a stored tool result
+ * ({@link storedToolResults}). The one predicate both share, so a result is a
+ * card or a stored tool result, never both and never neither.
+ *
+ * It judges the block AS STORED: without its `_meta` (guuey#122), which never
+ * persists. The card projection sees the live block and the stored-row reader
+ * sees the stored one, so a predicate that read `_meta` would answer the two
+ * differently (a `_meta.ui` locator is visible to the first only). Judging the
+ * stored view gives one answer on both sides by construction.
+ *
+ * A block carries UI only on DURABLE evidence, what a card row needs to mount
+ * after a reload. As stored:
+ *  - its `uiData` is an MCP resource payload (`{ uri, text|blob }`, bare or as
+ *    `{ resource }`), which mounts inline;
+ *  - its `uiData` or `structuredContent` names a `ui://` locator, which mounts
+ *    by a fresh read of the uri (`structuredContent` for a producer that
+ *    withholds `_meta`, guuey#209);
+ *  - its `uiData` is the {@link ELIDED_VALUE_KEY} marker, which stands in for
+ *    an inline resource the turn's card row carries whole
+ *    ({@link agMessageToBoundedRow});
+ *  - or a `provider-raw` part carries a `ui://` resource.
+ *
+ * Anything else is a stored tool result, which a host reads by its tool name.
+ * That includes plain view data in `uiData`: AgJSON §2.1 routes a result's
+ * payload there whenever the producer set any `_meta.ui` sibling, so an
+ * object in `uiData` alone is no evidence that a card can mount. When
+ * `_meta.ui` named no `ui://` locator, nothing could ever mount it; when it
+ * did, the locator rode `_meta` alone and the writer strips it, so the stored
+ * row cannot mount it either. A card row for either would draw as an expired
+ * chip on every reload. (A writer that persisted that locator would make it a
+ * card here, by this same rule.)
+ *
+ * `_meta` alone never mints a card (the guuey#170 pin). Across a rolling
+ * release: a writer before this predicate minted a card row from a `_meta.ui`
+ * locator, so a thread written then holds that card row while this predicate
+ * reads the same stored result as one with no UI resource. A reader that
+ * serves both kinds keeps one item per result by leaving out a stored tool
+ * result whose call already has a card row on its read (the public transcript
+ * read does).
+ */
+export function toolResultCarriesUi(block) {
+    const stored = withoutToolResultMeta(block);
+    return (asUiResource(stored.uiData) !== undefined ||
+        isElidedMarker(stored.uiData) ||
+        toolResultLocator(stored) !== undefined ||
+        stored.content.some((part) => part.type === "provider-raw" && scanProviderRawForUiResource(part.raw) !== undefined));
+}
 export function uiCardArtifactsFromMessages(messages) {
     const artifacts = [];
     for (const msg of messages) {
@@ -187,11 +607,10 @@ export function uiCardArtifactsFromMessages(messages) {
             // read the render's own locator would never mint a placeholder row and
             // the read plane 404s it. Mount MATERIAL still never rides `_meta` here
             // (see the metaOnly pin in fold-rows.test.ts): a bare locator persists
-            // as a placeholder whose mount is a re-fetch.
-            const carriesUi = asUiResource(block.uiData) !== undefined ||
-                toolResultLocator(block) !== undefined ||
-                block.content.some((part) => part.type === "provider-raw" && scanProviderRawForUiResource(part.raw) !== undefined);
-            if (!carriesUi)
+            // as a placeholder whose mount is a re-fetch. A locator named ONLY in
+            // `_meta.ui` mints nothing: it does not persist, so its card could not
+            // mount after a reload (toolResultCarriesUi judges durable evidence).
+            if (!toolResultCarriesUi(block))
                 continue;
             artifacts.push({
                 artifactId: `${msg.id}#ui#${i}`,
@@ -238,6 +657,40 @@ export function producingToolName(art, toolNames) {
     }
     return undefined;
 }
+/**
+ * toolCallId → the index of the fold message that carries that call's
+ * `tool-result` block (guuey#2396). A card is drawn when its tool-result
+ * arrives, so this is where its card row belongs in the turn's stored order.
+ * First message wins on a duplicate id, as in {@link toolNamesByCallId}.
+ */
+export function toolResultMessageIndexByCallId(messages) {
+    const indices = new Map();
+    messages.forEach((msg, index) => {
+        for (const block of msg.content) {
+            if (block.type === "tool-result" && !indices.has(block.toolCallId)) {
+                indices.set(block.toolCallId, index);
+            }
+        }
+    });
+    return indices;
+}
+/**
+ * The index of the fold message a card artifact was drawn with: the message
+ * holding the tool-result its first tool-result part names (guuey#2396).
+ * `undefined` when unresolvable (a first-class `artifact.*` event with no
+ * tool-result part, or a call outside this fold): such a card keeps the
+ * turn's tail.
+ */
+export function producingMessageIndex(art, resultIndices) {
+    for (const part of art.parts) {
+        if (isJsonObjectLike(part) && part.type === "tool-result" && typeof part.toolCallId === "string") {
+            const index = resultIndices.get(part.toolCallId);
+            if (index !== undefined)
+                return index;
+        }
+    }
+    return undefined;
+}
 export function agArtifactToCardRow(art, ctx, toolName) {
     // guuey#122: the projection lane strips tool-result _meta upstream, but
     // REAL artifact.* events land here verbatim — apply the same persistence
@@ -278,12 +731,13 @@ function isJsonObjectLike(v) {
  * undefined value in a closed set, is omitted whole and the rest restores in
  * order; unknown fields pass through untouched. Only a record the reader
  * cannot materialize (no string `id`, an undefined `role`, no `content`
- * array) falls to the text projection.
+ * array) falls to the text projection. A stored message whose answer block is
+ * elided reads its answer from the row's `text` ({@link readStoredRowMessage}).
  */
 export function rowToAgMessage(row) {
-    const stored = readStoredAgMessage(row.content);
-    if (stored.value !== undefined)
-        return stored.value;
+    const stored = readStoredRowMessage(row.content, row.text);
+    if (stored !== undefined)
+        return stored;
     const role = row.authorRole === "user" ? "user" : row.authorRole === "system" ? "system" : "assistant";
     const text = row.text ?? "";
     return {
@@ -389,7 +843,7 @@ export function joinStoredThreadMemory(row) {
     return [...(row.carriedThreadMemory ?? []), ...row.threadMemory];
 }
 /** Structural equality over JSON values (object key order does not matter). */
-function jsonEqual(a, b) {
+export function jsonEqual(a, b) {
     if (a === b)
         return true;
     if (a === undefined || b === undefined || a === null || b === null)

package/dist/http-read.d.ts

@@ -0,0 +1,47 @@
+import { type ThreadMessageRow, type ThreadRow, type ThreadSnapshotRow } from "./rows.js";
+import type { ThreadScope } from "./http.js";
+/**
+ * A JSON object as it came off the wire: every member is unread until narrowed.
+ *
+ * `@guuey/agent-client` keeps the same guard (`wire-object.ts`). It is not
+ * shared because no package both depend on exports one that reads an
+ * `unknown`: `@guuey/mcp-apps-host`'s `isJsonObject` takes a `JsonValue` and
+ * narrows its members to `JsonValue`, which a parsed body is not proven to be,
+ * and the two packages do not depend on each other. The guard is one line and
+ * every member it yields is narrowed at its read.
+ */
+export interface WireObject {
+    readonly [key: string]: unknown;
+}
+/** Whether `value` is a JSON object: not `null`, not an array, not a scalar. */
+export declare function isWireObject(value: unknown): value is WireObject;
+/** `scope`'s result: the three strings the server binds the token to. */
+export declare function readThreadScope(value: unknown): ThreadScope | undefined;
+/** `incrementSeq`'s result: the integer seq the server allocated. */
+export declare function readAllocatedSeq(value: unknown): number | undefined;
+/** A `getThread` row. */
+export declare function readThreadRow(value: unknown): ThreadRow | undefined;
+/**
+ * A message row as read off the wire: a legacy row may carry no `userId`, which
+ * the binding fills in (`HttpThreadPersistence`) before the row leaves it.
+ */
+export type WireThreadMessageRow = Omit<ThreadMessageRow, "userId"> & {
+    userId?: string;
+};
+/** A message row (`listRecentMessages`, `findByClientMessageId`). */
+export declare function readThreadMessageRow(value: unknown): WireThreadMessageRow | undefined;
+/**
+ * `listRecentMessages`' result: every row must read, or the list is refused. A
+ * row reads unless it lacks a member that identifies it or carries a malformed
+ * `untrustedOrigin` (see the module doc); a vocabulary value or a `userId` this
+ * release does not know never refuses it.
+ */
+export declare function readThreadMessageRows(value: unknown): WireThreadMessageRow[] | undefined;
+/**
+ * A `getSnapshot` row. Its memory arrays are JSON (checked, never assumed); the
+ * thread records are re-read through the one stored-memory reader
+ * (`splitStoredThreadMemory`), and any element this release cannot read as a
+ * thread record joins the carried elements, so it is kept, never dropped.
+ */
+export declare function readThreadSnapshotRow(value: unknown): ThreadSnapshotRow | undefined;
+//# sourceMappingURL=http-read.d.ts.map

package/dist/http-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-read.d.ts","sourceRoot":"","sources":["../src/http-read.ts"],"names":[],"mappings":"AAwCA,OAAO,EAQL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,iBAAiB,EAEvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AA0BD,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAKvE;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED,yBAAyB;AACzB,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAmDnE;AAsCD;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CA0CrF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,EAAE,GAAG,SAAS,CASxF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CA8BnF"}