@jini-ai/chat 0.6.5 → 0.6.7

package/dist/core/question-form/scan.js

@@ -10,19 +10,34 @@
  */
 import { parsePartialJson } from '../partial-json.js';
 import { parseQuotedAttrs } from '../util/markup-attributes.js';
-import { mapRawQuestion } from './normalize.js';
+import { asRecord, mapRawQuestion, nonEmptyString, omitUndefined, stringOrUndefined } from './normalize.js';
 // `question-form` is the canonical tag; `ask-question` is an alias the model
 // occasionally drifts to. The close tag must match the open tag name, so each
 // match captures the name and computes its own close-tag string. Matching is
 // case-insensitive so `<Question-Form>` / `<ASK-QUESTION>` still parse.
 const OPEN_RE = /<(question-form|ask-question)\b([^>]*)>/i;
-// Group 1 is a mandatory (non-optional) alternation and group 2 is an
-// unconditional `*`-quantified capture, so both always participate whenever
-// `m` itself is non-null — `noUncheckedIndexedAccess` just can't see that
-// from the regex alone. Centralized here so the six call sites below don't
-// each repeat the same assertion and reasoning.
-function matchedTagAndAttrs(m) {
-    return { tagName: m[1].toLowerCase(), rawAttrs: m[2] };
+/** The first question-form block opening at or after `from`, or `null` when there is none. */
+function locateBlock({ input, from }) {
+    const m = OPEN_RE.exec(input.slice(from));
+    if (!m)
+        return null;
+    // Group 1 is a mandatory (non-optional) alternation and group 2 is an
+    // unconditional `*`-quantified capture, so both always participate whenever
+    // `m` itself is non-null — `noUncheckedIndexedAccess` just can't see that
+    // from the regex alone.
+    const closeTag = `</${m[1].toLowerCase()}>`;
+    const start = from + m.index;
+    const bodyStart = start + m[0].length;
+    const closeIdx = findCloseTag(input, bodyStart, closeTag);
+    const closed = closeIdx !== -1;
+    return {
+        start,
+        bodyStart,
+        bodyEnd: closed ? closeIdx : input.length,
+        end: closed ? closeIdx + closeTag.length : input.length,
+        closed,
+        rawAttrs: m[2],
+    };
 }
 /**
  * Split `input` into ordered prose/form segments. Scans repeatedly for
@@ -37,37 +52,20 @@ export function splitOnQuestionForms({ input }) {
     const out = [];
     let cursor = 0;
     while (cursor < input.length) {
-        const slice = input.slice(cursor);
-        const m = OPEN_RE.exec(slice);
-        if (!m) {
-            out.push({ kind: 'text', text: slice });
+        const block = locateBlock({ input, from: cursor });
+        if (!block?.closed) {
+            // No block, or an unterminated one — leave the rest as prose so we don't swallow it.
+            out.push({ kind: 'text', text: input.slice(cursor) });
             break;
         }
-        const { tagName, rawAttrs } = matchedTagAndAttrs(m);
-        const closeTag = `</${tagName}>`;
-        const openStart = cursor + m.index;
-        const openEnd = openStart + m[0].length;
-        const closeIdx = findCloseTag(input, openEnd, closeTag);
-        if (closeIdx === -1) {
-            // Unterminated — leave the rest as prose so we don't swallow it.
-            out.push({ kind: 'text', text: slice });
-            break;
-        }
-        if (openStart > cursor) {
-            out.push({ kind: 'text', text: input.slice(cursor, openStart) });
-        }
-        const body = input.slice(openEnd, closeIdx);
-        const attrs = parseQuotedAttrs({ raw: rawAttrs });
-        const form = tryParseForm(body, attrs);
-        const blockEnd = closeIdx + closeTag.length;
-        if (form) {
-            out.push({ kind: 'form', form, raw: input.slice(openStart, blockEnd) });
+        if (block.start > cursor) {
+            out.push({ kind: 'text', text: input.slice(cursor, block.start) });
         }
-        else {
-            // Malformed — keep raw text so the user can still see it.
-            out.push({ kind: 'text', text: input.slice(openStart, blockEnd) });
-        }
-        cursor = blockEnd;
+        const raw = input.slice(block.start, block.end);
+        const form = tryParseForm(input.slice(block.bodyStart, block.bodyEnd), parseQuotedAttrs({ raw: block.rawAttrs }));
+        // Malformed — keep raw text so the user can still see it.
+        out.push(form ? { kind: 'form', form, raw } : { kind: 'text', text: raw });
+        cursor = block.end;
     }
     return out;
 }
@@ -98,19 +96,12 @@ export function parseQuestionForm({ input }) {
 export function stripTrailingOpenQuestionForm({ input }) {
     let cursor = 0;
     while (cursor < input.length) {
-        const slice = input.slice(cursor);
-        const m = OPEN_RE.exec(slice);
-        if (!m)
+        const block = locateBlock({ input, from: cursor });
+        if (!block)
             break;
-        const { tagName } = matchedTagAndAttrs(m);
-        const closeTag = `</${tagName}>`;
-        const openStart = cursor + m.index;
-        const openEnd = openStart + m[0].length;
-        const closeIdx = findCloseTag(input, openEnd, closeTag);
-        if (closeIdx === -1) {
-            return { text: input.slice(0, openStart), hadOpenForm: true };
-        }
-        cursor = closeIdx + closeTag.length;
+        if (!block.closed)
+            return { text: input.slice(0, block.start), hadOpenForm: true };
+        cursor = block.end;
     }
     return { text: input, hadOpenForm: false };
 }
@@ -130,12 +121,10 @@ function findCloseTag(input, from, closeTag) {
     return -1;
 }
 function tryParseForm(body, attrs) {
-    const trimmed = body.trim();
-    if (!trimmed)
-        return null;
     // Allow the JSON to be wrapped in a fenced ```json block — common when the
     // model echoes its own indented body.
-    const stripped = trimmed
+    const stripped = body
+        .trim()
         .replace(/^```(?:json)?\s*/i, '')
         .replace(/```\s*$/i, '')
         .trim();
@@ -146,31 +135,24 @@ function tryParseForm(body, attrs) {
     catch {
         return null;
     }
-    if (!data || typeof data !== 'object')
+    const obj = asRecord(data);
+    if (!obj || !Array.isArray(obj.questions))
         return null;
-    const obj = data;
-    const rawQuestions = Array.isArray(obj.questions) ? obj.questions : null;
-    if (!rawQuestions)
-        return null;
-    const questions = [];
-    rawQuestions.forEach((q, i) => {
-        const mapped = mapRawQuestion({ q: q, index: i });
-        if (mapped)
-            questions.push(mapped);
-    });
+    const questions = obj.questions.flatMap((q, index) => mapRawQuestion({ q, index }) ?? []);
     if (questions.length === 0)
         return null;
-    const id = attrs.id ?? (typeof obj.id === 'string' ? obj.id : 'discovery');
-    const title = attrs.title ?? (typeof obj.title === 'string' ? obj.title : 'A few quick questions');
-    const description = typeof obj.description === 'string' ? obj.description : undefined;
-    const submitLabel = typeof obj.submitLabel === 'string' ? obj.submitLabel : undefined;
-    return {
-        id,
-        title,
+    return assembleForm({ attrs, top: obj, bodyId: stringOrUndefined(obj.id), bodyTitle: stringOrUndefined(obj.title), questions });
+}
+// Form-level fields shared by the complete and streaming parsers: the open
+// tag's attrs win over the body's own id/title, which win over the defaults.
+function assembleForm({ attrs, top, bodyId, bodyTitle, questions }) {
+    return omitUndefined({
+        id: attrs.id ?? bodyId ?? 'discovery',
+        title: attrs.title ?? bodyTitle ?? 'A few quick questions',
         questions,
-        ...(description ? { description } : {}),
-        ...(submitLabel ? { submitLabel } : {}),
-    };
+        description: nonEmptyString(top.description),
+        submitLabel: nonEmptyString(top.submitLabel),
+    });
 }
 /**
  * Tolerant parser for a still-streaming `<question-form>` block. Unlike
@@ -185,15 +167,10 @@ function tryParseForm(body, attrs) {
  *   string-aware brace walk via {@link parsePartialJson}).
  */
 export function parsePartialQuestionForm({ input }) {
-    const m = OPEN_RE.exec(input);
-    if (!m)
+    const block = locateBlock({ input, from: 0 });
+    if (!block)
         return null;
-    const { tagName, rawAttrs } = matchedTagAndAttrs(m);
-    const closeTag = `</${tagName}>`;
-    const openEnd = m.index + m[0].length;
-    const attrs = parseQuotedAttrs({ raw: rawAttrs });
-    const closeIdx = findCloseTag(input, openEnd, closeTag);
-    const rawBody = closeIdx === -1 ? input.slice(openEnd) : input.slice(openEnd, closeIdx);
+    const rawBody = input.slice(block.bodyStart, block.bodyEnd);
     // Strip the fenced ```json wrapper some models emit. The opening fence is
     // removed always; the trailing fence is removed too once it streams in
     // (possibly only a partial ``` so far) — otherwise leftover backticks make
@@ -203,24 +180,18 @@ export function parsePartialQuestionForm({ input }) {
     // Derive form-level metadata from the *parsed top-level object*, not a
     // whole-body regex scan: a nested question/option `id`/`title`/`description`
     // must not masquerade as the form's own.
-    const parsed = parsePartialJson({ buf: body });
-    const top = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-    const topTitle = typeof top.title === 'string' && top.title.trim().length > 0 ? top.title : undefined;
+    const top = asRecord(parsePartialJson({ buf: body })) ?? {};
+    const title = stringOrUndefined(top.title);
     // `id` keys a still-editable panel, so it must be stable for the whole
     // stream — don't adopt it until its string literal is fully terminated,
     // otherwise it would churn character-by-character and remount the panel.
-    const id = attrs.id ?? completeTopLevelString(body, 'id') ?? 'discovery';
-    const title = attrs.title ?? topTitle ?? 'A few quick questions';
-    const description = typeof top.description === 'string' ? top.description : undefined;
-    const submitLabel = typeof top.submitLabel === 'string' ? top.submitLabel : undefined;
-    const questions = shapeStreamingQuestions(top.questions, countClosedQuestionObjects(body));
-    return {
-        id,
-        title,
-        questions,
-        ...(description ? { description } : {}),
-        ...(submitLabel ? { submitLabel } : {}),
-    };
+    return assembleForm({
+        attrs: parseQuotedAttrs({ raw: block.rawAttrs }),
+        top,
+        bodyId: completeTopLevelString(body, 'id'),
+        bodyTitle: title?.trim() ? title : undefined,
+        questions: shapeStreamingQuestions(top.questions, countClosedQuestionObjects(body)),
+    });
 }
 // Strip a trailing ``` fence (possibly only partially streamed) from a form
 // body — but only when those backticks are the closing wrapper, not content
@@ -235,104 +206,82 @@ function stripTrailingFence(body) {
     return before;
 }
 function endsInsideJsonString(s) {
-    let inStr = false;
-    let esc = false;
-    for (let i = 0; i < s.length; i++) {
-        const c = s[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (c === '\\')
-                esc = true;
-            else if (c === '"')
-                inStr = false;
-        }
-        else if (c === '"') {
-            inStr = true;
-        }
+    for (let i = s.indexOf('"'); i !== -1; i = s.indexOf('"', i)) {
+        i = jsonStringEnd({ s, start: i });
+        if (i === -1)
+            return true;
     }
-    return inStr;
+    return false;
 }
+// Index just past the closing quote of the JSON string literal whose opening
+// quote is at `start`, or -1 when that literal hasn't finished streaming.
+function jsonStringEnd({ s, start }) {
+    for (let i = start + 1; i < s.length; i++) {
+        if (s[i] === '\\')
+            i++;
+        else if (s[i] === '"')
+            return i + 1;
+    }
+    return -1;
+}
+const DEPTH_DELTA = { '{': 1, '[': 1, '}': -1, ']': -1 };
 // Return a top-level (depth-1) string field's value ONLY if its string
 // literal is fully terminated in the (possibly partial) body. Depth-aware so
 // a nested question `id` can't be mistaken for the form's own.
 function completeTopLevelString(body, field) {
     const marker = `"${field}"`;
     let depth = 0;
-    let inStr = false;
-    let esc = false;
     for (let i = 0; i < body.length; i++) {
         const c = body[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (c === '\\')
-                esc = true;
-            else if (c === '"')
-                inStr = false;
-            continue;
-        }
-        if (c === '{' || c === '[') {
-            depth++;
-            continue;
-        }
-        if (c === '}' || c === ']') {
-            depth--;
+        if (c !== '"') {
+            depth += DEPTH_DELTA[c] ?? 0;
             continue;
         }
-        if (c === '"') {
-            if (depth === 1 && body.startsWith(marker, i)) {
-                let j = i + marker.length;
-                while (j < body.length && /\s/.test(body[j]))
-                    j++;
-                if (body[j] !== ':') {
-                    inStr = true; // it's a value string, not our key — skip it
-                    continue;
-                }
-                j++;
-                while (j < body.length && /\s/.test(body[j]))
-                    j++;
-                if (body[j] !== '"')
-                    return undefined; // value not a (started) string
-                let value = '';
-                let vesc = false;
-                for (let k = j + 1; k < body.length; k++) {
-                    const vc = body[k];
-                    if (vesc) {
-                        value += vc;
-                        vesc = false;
-                    }
-                    else if (vc === '\\') {
-                        value += vc;
-                        vesc = true;
-                    }
-                    else if (vc === '"') {
-                        try {
-                            return JSON.parse(`"${value}"`);
-                        }
-                        catch {
-                            return value;
-                        }
-                    }
-                    else {
-                        value += vc;
-                    }
-                }
-                return undefined; // closing quote hasn't streamed yet
-            }
-            inStr = true;
-        }
+        const valueStart = depth === 1 ? keyValueStart({ body, at: i, marker }) : -1;
+        if (valueStart !== -1)
+            return readStringLiteral({ body, start: valueStart });
+        // A string that isn't our key (any other key, or a value) — skip it.
+        const end = jsonStringEnd({ s: body, start: i });
+        if (end === -1)
+            return undefined;
+        i = end - 1;
     }
     return undefined;
 }
+const KEY_COLON_RE = /\s*:\s*/y;
+// Where the value starts when the string literal at `at` is the `marker` key,
+// or -1 when it isn't — including a value string that merely spells the key,
+// which no `:` follows.
+function keyValueStart({ body, at, marker }) {
+    if (!body.startsWith(marker, at))
+        return -1;
+    KEY_COLON_RE.lastIndex = at + marker.length;
+    return KEY_COLON_RE.test(body) ? KEY_COLON_RE.lastIndex : -1;
+}
+// The decoded string literal at `start`, or `undefined` when the value isn't
+// a (started) string or its closing quote hasn't streamed yet.
+function readStringLiteral({ body, start }) {
+    if (body[start] !== '"')
+        return undefined; // value not a (started) string
+    const end = jsonStringEnd({ s: body, start });
+    if (end === -1)
+        return undefined; // closing quote hasn't streamed yet
+    const value = body.slice(start + 1, end - 1);
+    try {
+        return JSON.parse(`"${value}"`);
+    }
+    catch {
+        return value;
+    }
+}
 function shapeStreamingQuestions(rawQuestions, closedCount) {
     if (!Array.isArray(rawQuestions))
         return [];
     const out = [];
     rawQuestions.forEach((raw, index) => {
-        if (!raw || typeof raw !== 'object')
+        const q = asRecord(raw);
+        if (!q)
             return;
-        const q = raw;
         const label = q.label;
         if (typeof label !== 'string' || label.trim().length === 0)
             return;
@@ -357,48 +306,37 @@ function countClosedQuestionObjects(body) {
         return 0;
     let i = keyMatch.index + keyMatch[0].length;
     let count = 0;
-    while (i < body.length) {
+    for (;;) {
         while (i < body.length && /[\s,]/.test(body[i]))
             i++;
-        if (i >= body.length || body[i] === ']')
-            break;
+        // Past the end, at `]`, or at a non-object element: nothing more to count.
         if (body[i] !== '{')
-            break;
-        const obj = extractBalancedObject(body, i);
-        if (!obj)
-            break; // trailing object hasn't closed yet
+            return count;
+        i = balancedObjectEnd({ s: body, start: i });
+        if (i === -1)
+            return count; // trailing object hasn't closed yet
         count++;
-        i += obj.length;
     }
-    return count;
 }
-// Return the substring for the balanced `{...}` object starting at `start`,
-// or null if it never closes (string-aware so braces inside strings don't count).
-function extractBalancedObject(s, start) {
+// Index just past the balanced `{...}` object starting at `start`, or -1 if
+// it never closes (string-aware so braces inside strings don't count).
+function balancedObjectEnd({ s, start }) {
     let depth = 0;
-    let inStr = false;
-    let esc = false;
     for (let i = start; i < s.length; i++) {
         const c = s[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (c === '\\')
-                esc = true;
-            else if (c === '"')
-                inStr = false;
-            continue;
+        if (c === '"') {
+            const end = jsonStringEnd({ s, start: i });
+            if (end === -1)
+                return -1;
+            i = end - 1;
         }
-        if (c === '"')
-            inStr = true;
-        else if (c === '{')
+        else if (c === '{') {
             depth++;
-        else if (c === '}') {
-            depth--;
-            if (depth === 0)
-                return s.slice(start, i + 1);
+        }
+        else if (c === '}' && --depth === 0) {
+            return i + 1;
         }
     }
-    return null;
+    return -1;
 }
 //# sourceMappingURL=scan.js.map

package/dist/core/run-activity.js

@@ -77,6 +77,16 @@ function isAnswerCard(scan, name, data) {
     const surfaceId = a2uiSurfaceIdOf({ message: data });
     return surfaceId === undefined || !scan.displayOnlySurfaces.has(surfaceId);
 }
+function scanStatus({ scan, event, index }, _optional = {}) {
+    if (event.code === 'api_retry') {
+        scan.retry = { index, data: event.data };
+    }
+    else if (event.code === 'tool_progress') {
+        const seconds = numberField(event.data, 'elapsedSeconds');
+        if (seconds !== undefined)
+            scan.progress = { index, seconds };
+    }
+}
 function scanEvent(scan, event, index) {
     if (isVisible(event)) {
         scan.lastVisible = { index, kind: event.kind };
@@ -89,17 +99,60 @@ function scanEvent(scan, event, index) {
     else if (event.kind === 'tool_result') {
         scan.open = scan.open.filter((tool) => tool.id !== event.toolUseId);
     }
-    else if (event.kind === 'ext' && isAnswerCard(scan, event.name, event.data)) {
-        scan.lastCardIndex = index;
+    else if (event.kind === 'ext') {
+        if (isAnswerCard(scan, event.name, event.data))
+            scan.lastCardIndex = index;
     }
-    else if (event.kind === 'status' && event.code === 'api_retry') {
-        scan.retry = { index, data: event.data };
+    else if (event.kind === 'status') {
+        scanStatus({ scan, event, index });
     }
-    else if (event.kind === 'status' && event.code === 'tool_progress') {
-        const seconds = numberField(event.data, 'elapsedSeconds');
-        if (seconds !== undefined)
-            scan.progress = { index, seconds };
+}
+/** `{ a: 1, b: undefined }` → `{ a: 1 }`, so optional activity fields are absent rather than undefined. */
+function definedFields({ fields }, _optional = {}) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+function retryingActivity({ data }, _optional = {}) {
+    return {
+        kind: 'retrying',
+        ...definedFields({
+            fields: {
+                attempt: numberField(data, 'attempt'),
+                maxAttempts: numberField(data, 'maxAttempts'),
+                service: stringField(data, 'service'),
+            },
+        }),
+    };
+}
+/** The signal while a tool call is open: a card waiting on the person, tool discovery, or the tool itself. */
+function openToolSignal({ scan, newestOpen }, _optional = {}) {
+    if (scan.lastCardIndex > newestOpen.index) {
+        return { activity: { kind: 'awaiting-answer' }, key: `card:${scan.lastCardIndex}` };
     }
+    const key = `tool:${newestOpen.id}`;
+    if (DISCOVERY_TOOL_NAMES.has(newestOpen.name))
+        return { activity: { kind: 'finding-tool' }, key };
+    const reported = scan.progress && scan.progress.index > newestOpen.index ? scan.progress.seconds : undefined;
+    return {
+        activity: {
+            kind: 'running-tool',
+            tool: humanizeToolName({ name: newestOpen.name }, { input: newestOpen.input }),
+            ...definedFields({ fields: { reportedSeconds: reported } }),
+        },
+        key,
+    };
+}
+function latestSignal({ scan }, _optional = {}) {
+    const lastVisibleIndex = scan.lastVisible?.index ?? -1;
+    if (scan.retry && scan.retry.index > lastVisibleIndex) {
+        return { activity: retryingActivity({ data: scan.retry.data }), key: `retry:${lastVisibleIndex}` };
+    }
+    const newestOpen = scan.open[scan.open.length - 1];
+    if (newestOpen)
+        return openToolSignal({ scan, newestOpen });
+    if (scan.lastVisible?.kind === 'text') {
+        return { activity: { kind: 'writing' }, key: `writing:${lastVisibleIndex}` };
+    }
+    return { activity: { kind: 'thinking' }, key: `thinking:${lastVisibleIndex}` };
 }
 /**
  * The latest signal in a running turn's events.
@@ -114,47 +167,7 @@ function scanEvent(scan, event, index) {
 export function deriveRunActivity({ events }, { isAnsweredCard } = {}) {
     const scan = { open: [], lastVisible: null, lastCardIndex: -1, retry: null, progress: null, visibleCount: 0, displayOnlySurfaces: new Set(), isAnsweredCard };
     (events ?? []).forEach((event, index) => scanEvent(scan, event, index));
-    const visibleCount = scan.visibleCount;
-    const lastVisibleIndex = scan.lastVisible?.index ?? -1;
-    if (scan.retry && scan.retry.index > lastVisibleIndex) {
-        const data = scan.retry.data;
-        const attempt = numberField(data, 'attempt');
-        const maxAttempts = numberField(data, 'maxAttempts');
-        const service = stringField(data, 'service');
-        return {
-            activity: {
-                kind: 'retrying',
-                ...(attempt !== undefined ? { attempt } : {}),
-                ...(maxAttempts !== undefined ? { maxAttempts } : {}),
-                ...(service !== undefined ? { service } : {}),
-            },
-            key: `retry:${lastVisibleIndex}`,
-            visibleCount,
-        };
-    }
-    const newestOpen = scan.open[scan.open.length - 1];
-    if (newestOpen) {
-        if (scan.lastCardIndex > newestOpen.index) {
-            return { activity: { kind: 'awaiting-answer' }, key: `card:${scan.lastCardIndex}`, visibleCount };
-        }
-        if (DISCOVERY_TOOL_NAMES.has(newestOpen.name)) {
-            return { activity: { kind: 'finding-tool' }, key: `tool:${newestOpen.id}`, visibleCount };
-        }
-        const reported = scan.progress && scan.progress.index > newestOpen.index ? scan.progress.seconds : undefined;
-        return {
-            activity: {
-                kind: 'running-tool',
-                tool: humanizeToolName({ name: newestOpen.name }, { input: newestOpen.input }),
-                ...(reported !== undefined ? { reportedSeconds: reported } : {}),
-            },
-            key: `tool:${newestOpen.id}`,
-            visibleCount,
-        };
-    }
-    if (scan.lastVisible?.kind === 'text') {
-        return { activity: { kind: 'writing' }, key: `writing:${lastVisibleIndex}`, visibleCount };
-    }
-    return { activity: { kind: 'thinking' }, key: `thinking:${lastVisibleIndex}`, visibleCount };
+    return { ...latestSignal({ scan }), visibleCount: scan.visibleCount };
 }
 /**
  * Whether the run is waiting on the person: a card (form, confirm, sign-in) arrived while its tool

package/dist/core/run-events/entry.d.ts

@@ -83,6 +83,12 @@ export declare function parseUsageEvent({ payload }: {
  * cannot fall through to `default` — see below). A lookup table would have to carry those as a
  * parallel structure, one step removed from the code they explain. Left as a `switch`, documented
  * here rather than only in this session's report.
+ *
+ * Superseded (2026-10-20, code-health wave 1; bar is ≤10/≤10): the flat switch is now TWO switches —
+ * the chat-core event types here, and the UI-envelope / dropped / `ext` types in
+ * {@link translateEnvelopePayload} below — so each scope stays under the cyclomatic bar while BOTH
+ * keep what the paragraph above argued for: every case is still a `case` with its own comment
+ * attached, not an entry in a parallel lookup table.
  */
 /** Reduce one daemon payload; preserve UI envelopes and drop duplicate input fragments. */
 export declare function translateRunAgentPayload({ payload }: {
@@ -280,7 +286,10 @@ export declare function runContentFromEvents({ events }: {
  * onto the screen; saved, it only repeats the event wrapper per token. Used by every saver (the server
  * finalizer and the chat PUT route the browser saves through), so both write the same shape.
  */
-/** Compact adjacent text/thinking deltas for durable storage. */
+/** Compact adjacent text/thinking deltas and keep the first occurrence of each tool-call ID.
+ * Replayed tool calls must not become duplicate history rows. Other events retain their order.
+ * @complexity O(n + total text length) time and O(n) space for n events.
+ */
 export declare function runEventsForSave({ events }: {
     events: readonly AgentEvent[];
 }, _options?: Record<string, never>): AgentEvent[];