tinybeeai 0.0.0-stage → 0.16.1

package/dist/agent/chat-views.js

@@ -0,0 +1,781 @@
+// Composed views on the server (KAT-366, docs/CHAT-UI.md "Composed views"). The model calls `compose_view` with a view spec.
+// This module checks the spec (src/view-spec.ts), binds it to the tool results of the turn, and streams it.
+//
+// - Data comes from tool results only. Each lookup result of a turn gets an id (r1, r2, ...), and the model refers to it. The
+//   server holds the full rows; the model sees the columns, a count, and a sample. A record node (runs, pulls, ...) gets the block
+//   the server builds from the result, the same block the lookup tool shows alone, so the model never writes a row, a link, or an
+//   approval id. A table, stats, or chart node reads a dataset: the rows of a result run through the steps of src/view-compute.ts.
+// - The server runs the pipelines once to check them (a column that is not there drops the dataset and its nodes, and the model is
+//   told why). The client runs them again in a Web Worker for what it draws. Nothing computed here reaches an action: a button of a
+//   block calls the route of that block, and the route reads the server's own records.
+// - The view streams as a `loading` view block, then one `view_node` event per node of the root, then the finished block, which
+//   replaces the rest. A node that has not arrived shows as a placeholder.
+import { get } from '../db.js';
+import { config } from '../config.js';
+import { parseChatBlock } from '../chat-blocks.js';
+import { isObj } from '../chat-parse-util.js';
+import { computeView } from '../view-compute.js';
+import { MAX_CELL_TEXT, MAX_SOURCE_CELLS, MAX_SOURCE_COLUMNS, MAX_SOURCE_ROWS, VIEW_RECORD_TYPES, fieldsUsed, isResultId, parseViewHead, parseViewNode, parseViewTree, rawNodes, viewBlocks, viewKinds, viewNodes, viewSpecGuide, } from '../view-spec.js';
+import { blocksFromToolResult } from './chat-tool-blocks.js';
+export const COMPOSE_VIEW_TOOL = 'compose_view';
+/** Tools whose result a view may read: the lookups, the stats tools, and the test results. */
+export const VIEW_SOURCE_TOOLS = [
+    'list_runs',
+    'runs_in_progress',
+    'open_prs',
+    'pending_approvals',
+    'recent_defects',
+    'probe_status',
+    'get_memory',
+    'list_tickets_reviewed',
+    'get_ticket',
+    'list_cases',
+    'pass_rate',
+    'flaky_by_spec',
+    'test_results',
+    'release_call',
+];
+/** The results of one chat turn, by id. */
+export class ResultRegistry {
+    entries = new Map();
+    add(name, input, value, blocks) {
+        const id = `r${this.entries.size + 1}`;
+        const entry = { id, name, input, value, blocks: [...blocks, ...(value && typeof value === 'object' ? (viewBlocksHeld.get(value) ?? []) : [])] };
+        this.entries.set(id, entry);
+        return entry;
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    ids() {
+        return [...this.entries.keys()];
+    }
+}
+const rowsHeld = new WeakMap();
+const refusedHeld = new WeakMap();
+const viewBlocksHeld = new WeakMap();
+const idsHeld = new WeakMap();
+/** Hands the full rows of a result to a view without putting them in what the model reads. */
+export function holdRows(value, table) {
+    rowsHeld.set(value, table);
+    return value;
+}
+/** Hands blocks the call built (the cards of get_ticket) to a view without streaming them alone. */
+export function holdViewBlocks(value, blocks) {
+    viewBlocksHeld.set(value, blocks);
+    return value;
+}
+/**
+ * The dot a result was looked up for when that is not the dot the chat is scoped to, else undefined. A composed view binds only the
+ * results of the chat's own dot: a lookup with an explicit `dotId` of another dot (test_results, list_runs, ...) would show that
+ * dot's data in this chat. A chat with no dot (the overview) has no dot to protect.
+ */
+export function foreignDotOf(input, watch) {
+    if (!watch)
+        return undefined;
+    const id = typeof input.dotId === 'string' ? input.dotId.trim() : '';
+    return id && id !== watch.id ? id : undefined;
+}
+/** The line the model reads for a lookup result that no view may read, and why. */
+export function foreignSourceLine(otherDot, watch) {
+    const other = get('watches', otherDot)?.name ?? otherDot;
+    return `Not a view source: this result is for dot ${other}, and this chat is for dot ${watch.name}. A view reads only results for ${watch.name}, so look the data up again without dotId (or with ${watch.id}) before you compose the view.`;
+}
+/** Marks a result as one that no view may read, with the line the model reads (see foreignSourceLine). */
+export function refuseResult(value, line) {
+    if (value && typeof value === 'object')
+        refusedHeld.set(value, line);
+}
+export function tagResult(value, id) {
+    if (value && typeof value === 'object')
+        idsHeld.set(value, id);
+}
+export function resultIdOf(value) {
+    return value && typeof value === 'object' ? idsHeld.get(value) : undefined;
+}
+/** The rows a result holds for a view: the held table, or the first list of objects in the value. */
+export function rowsOfResult(value) {
+    return value && typeof value === 'object' ? rowsHeld.get(value) : undefined;
+}
+/** What the model reads for a result: the value with its id, so it can name the result in compose_view. */
+export function modelFacing(value) {
+    const refused = value && typeof value === 'object' ? refusedHeld.get(value) : undefined;
+    if (refused)
+        return Array.isArray(value) ? { viewSource: refused, rows: value } : { ...value, viewSource: refused };
+    const id = resultIdOf(value);
+    if (id && value && typeof value === 'object')
+        return Array.isArray(value) ? { resultId: id, rows: value } : { resultId: id, ...value };
+    if (isObj(value) && value.repeated === true && 'result' in value)
+        return { ...value, result: modelFacing(value.result) };
+    return value;
+}
+// ---------- Rows of a result, as a table ----------
+const LIST_KEYS = ['rows', 'runs', 'prs', 'approvals', 'defects', 'probes', 'items', 'results', 'cases'];
+function listOf(value) {
+    if (Array.isArray(value))
+        return value.filter(isObj);
+    if (!isObj(value))
+        return [];
+    for (const k of LIST_KEYS)
+        if (Array.isArray(value[k]) && value[k].some(isObj))
+            return value[k].filter(isObj);
+    for (const v of Object.values(value))
+        if (Array.isArray(v) && v.some(isObj))
+            return v.filter(isObj);
+    return [];
+}
+/** An object as dotted keys, two levels deep. A list of plain values becomes one text; a list of objects is left out. */
+function flatten(o, prefix = '', depth = 0, out = {}) {
+    for (const [k, v] of Object.entries(o)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (v === null || v === undefined)
+            out[key] = null;
+        else if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+            out[key] = typeof v === 'number' && !Number.isFinite(v) ? null : v;
+        else if (Array.isArray(v)) {
+            if (v.every((x) => x === null || typeof x !== 'object'))
+                out[key] = v.join(', ');
+        }
+        else if (isObj(v) && depth < 2)
+            flatten(v, key, depth + 1, out);
+    }
+    return out;
+}
+/** The columns of a result a view can read, in the order they first show. */
+export function columnsOfResult(value) {
+    const held = rowsOfResult(value);
+    if (held)
+        return held.columns;
+    const cols = [];
+    for (const row of listOf(value).slice(0, 200))
+        for (const k of Object.keys(flatten(row)))
+            if (!cols.includes(k))
+                cols.push(k);
+    return cols;
+}
+/** The result cut to the columns the view uses (all of them when `fields` is null), and to the rows and cells the client takes. */
+function sourceTable(value, fields) {
+    const held = rowsOfResult(value);
+    let columns;
+    let rows;
+    if (held) {
+        columns = held.columns.filter((c) => !fields || fields.has(c));
+        const at = columns.map((c) => held.columns.indexOf(c));
+        rows = held.rows.map((r) => at.map((i) => r[i] ?? null));
+    }
+    else {
+        const flat = listOf(value).map((r) => flatten(r));
+        columns = columnsOfResult(value).filter((c) => !fields || fields.has(c));
+        rows = flat.map((r) => columns.map((c) => r[c] ?? null));
+    }
+    columns = columns.slice(0, MAX_SOURCE_COLUMNS);
+    // A long text (a test title) is cut as the client cuts it, so a stored view is no bigger than the client keeps.
+    rows = rows.map((r) => r.slice(0, columns.length).map((c) => (typeof c === 'string' && c.length > MAX_CELL_TEXT ? `${c.slice(0, MAX_CELL_TEXT - 1)}…` : c)));
+    const keep = Math.min(MAX_SOURCE_ROWS, Math.floor(MAX_SOURCE_CELLS / Math.max(1, columns.length)));
+    const more = (held?.more ?? 0) + Math.max(0, rows.length - keep);
+    return { columns, rows: rows.slice(0, keep), ...(more > 0 ? { more } : {}) };
+}
+// ---------- What the model is told about a result ----------
+/** The part of a tool result the model reads for the rows a view holds: the columns, a count, and a few rows. */
+export function rowsSummary(table, total) {
+    const sample = table.rows.slice(0, 5).map((r) => Object.fromEntries(table.columns.map((c, i) => [c, r[i] ?? null])));
+    return { count: total, rowsHeld: table.rows.length, columns: table.columns, sample };
+}
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+function dotOf(entry, host) {
+    const id = typeof entry.input.dotId === 'string' ? entry.input.dotId : undefined;
+    return (id ? get('watches', id) : undefined) ?? host.watch;
+}
+/** The blocks a result can show: the ones its call built, then what the lookup tool would show for it. */
+function blocksOf(entry, host) {
+    const dot = dotOf(entry, host);
+    // A view that names a ticket review asks for it, so the stored review of get_ticket shows.
+    const built = blocksFromToolResult(entry.name, entry.value, { ...entry.input, context: false }, { ...(dot ? { dot } : {}), showTicketReview: true });
+    return [...entry.blocks, ...built];
+}
+/** A block cut to `limit` rows, the rest counted in `more`. */
+function trim(block, limit) {
+    if (!limit)
+        return block;
+    const cut = (rows) => [rows.slice(0, limit), Math.max(0, rows.length - limit)];
+    const more = (n) => (n > 0 ? { more: (block.more ?? 0) + n } : {});
+    switch (block.kind) {
+        case 'runs': {
+            const [runs, n] = cut(block.runs);
+            return { ...block, runs, ...more(n) };
+        }
+        case 'pulls': {
+            const [pulls, n] = cut(block.pulls);
+            return { ...block, pulls, ...more(n) };
+        }
+        case 'approvals': {
+            const [approvals, n] = cut(block.approvals);
+            return { ...block, approvals, ...more(n) };
+        }
+        case 'defects': {
+            const [defects, n] = cut(block.defects);
+            return { ...block, defects, ...more(n) };
+        }
+        case 'probes': {
+            const [probes, n] = cut(block.probes);
+            return { ...block, probes, ...more(n) };
+        }
+        case 'memory': {
+            const [items, n] = cut(block.items);
+            return { ...block, items, ...more(n) };
+        }
+        case 'test_cases': {
+            const [cases, n] = cut(block.cases);
+            return { ...block, cases, ...more(n) };
+        }
+        case 'cards': {
+            const [cards, n] = cut(block.cards);
+            return { ...block, cards, ...more(n) };
+        }
+        case 'table': {
+            const [rows, n] = cut(block.rows);
+            return { ...block, rows, ...more(n) };
+        }
+        default:
+            return block;
+    }
+}
+/** Binds the record, triage, and `from` nodes of a parsed tree to blocks. A node that cannot be bound is dropped and noted. */
+function bindTree(root, host, notes) {
+    const bind = (node) => {
+        switch (node.type) {
+            case 'column':
+            case 'row': {
+                const children = node.children.map(bind).filter((n) => n !== null);
+                return children.length || node === root ? { ...node, children } : null;
+            }
+            case 'section': {
+                const children = node.children.map(bind).filter((n) => n !== null);
+                return children.length ? { ...node, children } : null;
+            }
+            case 'tabs': {
+                const tabs = node.tabs.map((t) => ({ ...t, children: t.children.map(bind).filter((n) => n !== null) })).filter((t) => t.children.length);
+                return tabs.length ? { ...node, tabs } : null;
+            }
+            case 'text':
+                return node;
+            case 'triage': {
+                const parsed = host.triage ? parseChatBlock(host.triage(node.window)) : undefined;
+                if (!parsed?.ok || parsed.block.kind !== 'triage') {
+                    notes.push('triage: the failure triage could not be built');
+                    return null;
+                }
+                return { ...node, block: node.title ? { ...parsed.block, title: node.title } : parsed.block };
+            }
+            case 'table':
+            case 'stats':
+            case 'chart':
+                if (!node.from)
+                    return node;
+                return bindFrom(node, node.type, node.from);
+            default:
+                return bindFrom(node, node.type, node.from ?? '');
+        }
+    };
+    const bindFrom = (node, kind, from) => {
+        const entry = host.results.get(from);
+        if (!entry) {
+            notes.push(`${kind}: there is no result ${from} in this turn. The results are ${host.results.ids().join(', ') || 'none yet'}`);
+            return null;
+        }
+        const foreign = foreignDotOf(entry.input, host.watch);
+        if (foreign) {
+            notes.push(`${kind}: ${from} (${entry.name}) is for dot ${foreign}, not the dot of this chat, so it is not shown`);
+            return null;
+        }
+        const nth = 'nth' in node && typeof node.nth === 'number' ? node.nth : 0;
+        const block = blocksOf(entry, host).filter((b) => b.kind === kind)[nth];
+        if (!block) {
+            notes.push(`${kind}: ${from} (${entry.name}) has no ${kind} block to show${nth ? ` at ${nth}` : ''}`);
+            return null;
+        }
+        const limited = trim(block, 'limit' in node && typeof node.limit === 'number' ? node.limit : undefined);
+        const title = 'title' in node && typeof node.title === 'string' ? node.title : undefined;
+        return { ...node, block: title ? { ...limited, title } : limited };
+    };
+    return bind(root);
+}
+/** Drops the nodes that read a dataset that failed, or a column the dataset does not have. */
+function checkNodes(root, out, notes) {
+    const check = (node) => {
+        switch (node.type) {
+            case 'column':
+            case 'row': {
+                const children = node.children.map(check).filter((n) => n !== null);
+                return children.length || node === root ? { ...node, children } : null;
+            }
+            case 'section': {
+                const children = node.children.map(check).filter((n) => n !== null);
+                return children.length ? { ...node, children } : null;
+            }
+            case 'tabs': {
+                const tabs = node.tabs
+                    .map((t) => ({ ...t, children: t.children.map(check).filter((n) => n !== null) }))
+                    .filter((t) => t.children.length);
+                return tabs.length ? { ...node, tabs } : null;
+            }
+            case 'chart':
+            case 'table': {
+                if (!node.data)
+                    return node;
+                const table = Object.hasOwn(out.datasets, node.data) ? out.datasets[node.data] : undefined;
+                if (!table) {
+                    notes.push(`${node.type}: dataset ${node.data} could not be computed: ${out.errors.datasets[node.data] ?? 'unknown'}`);
+                    return null;
+                }
+                // A chart or a table of no rows says nothing, so the view leaves it out and the answer says so in words.
+                if (!table.rows.length) {
+                    notes.push(`${node.type}: dataset ${node.data} has no rows`);
+                    return null;
+                }
+                const wanted = node.type === 'chart' ? [node.x ?? '', ...(node.series ?? []).map((s) => s.field)] : (node.columns ?? []).map((c) => c.field);
+                const missing = wanted.find((f) => f && !table.columns.includes(f));
+                if (missing) {
+                    notes.push(`${node.type}: dataset ${node.data} has no column "${missing}". It has ${table.columns.join(', ')}`);
+                    return null;
+                }
+                return node;
+            }
+            default:
+                return node;
+        }
+    };
+    return check(root);
+}
+/** What the model learns from the server's own run of the view: the vars, and the first rows of each dataset. */
+function factsOf(out) {
+    const vars = Object.fromEntries(Object.entries(out.vars).map(([k, v]) => [k, v.text]));
+    const datasets = Object.fromEntries(Object.entries(out.datasets).map(([k, t]) => [
+        k,
+        { columns: t.columns, rows: t.rows.slice(0, 8), ...(t.rows.length > 8 ? { moreRows: t.rows.length - 8 } : {}) },
+    ]));
+    return { ...(Object.keys(vars).length ? { vars } : {}), ...(Object.keys(datasets).length ? { datasets } : {}) };
+}
+const LINK_TEXT = 'The full view is in the chat';
+/**
+ * The line a Slack thread or a call carries in place of the view: where it opens. Undefined in the app chat, which shows it. With the
+ * id of the stored reply the link opens that answer, not only the chat of the dot. Slack has no link without a public address, like every
+ * other link from the app, so the line says where to look.
+ */
+export function viewLinkLine(watch, channel, messageId) {
+    if (channel !== 'slack' && channel !== 'call')
+        return undefined;
+    const path = `#/chat${watch ? `/${encodeURIComponent(watch.id)}` : ''}${messageId ? `?m=${encodeURIComponent(messageId)}` : ''}`;
+    if (channel === 'call')
+        return `[${LINK_TEXT}](${path})`;
+    const base = config.publicUrl?.replace(/\/$/, '');
+    return base ? `[${LINK_TEXT}](${base}/${path})` : `${LINK_TEXT} of ${watch ? watch.name : 'the dot'}, in the localdost app.`;
+}
+const LEAF_TYPES = [...VIEW_RECORD_TYPES, 'triage', 'table', 'stats', 'chart'];
+/**
+ * A failed spec falls back to the blocks it holds, then to text (docs/CHAT-UI.md, Composed views: Fallback). Every node of a block kind
+ * that reads a tool result by id comes back as the block the server builds from it: the record kinds, the triage, and a stats, chart, or
+ * table with `from`. A node built from a dataset has no block of its own, so it is left out.
+ */
+function fallbackBlocks(raw, host) {
+    const out = [];
+    const notes = [];
+    for (const n of rawNodes(raw)) {
+        if (!LEAF_TYPES.includes(String(n.type)))
+            continue;
+        const node = parseViewNode(n, {});
+        if (!node)
+            continue;
+        const bound = bindTree(node, host, notes);
+        if (bound && 'block' in bound && bound.block)
+            out.push(bound.block);
+    }
+    return out;
+}
+/**
+ * The rows each dataset reads, cut to the columns the view uses (`fields` null keeps them all), and the datasets that can be built. A
+ * dataset whose result is not there is dropped with a note, and so is one that reads a dropped dataset.
+ */
+function prepare(raw, host, fields, notes) {
+    const sources = {};
+    const datasets = {};
+    const { results } = host;
+    for (const [name, d] of Object.entries(raw ?? {})) {
+        if (isResultId(d.from)) {
+            const entry = results.get(d.from);
+            if (!entry) {
+                notes.push(`dataset ${name} dropped: there is no result ${d.from} in this turn. The results are ${results.ids().join(', ') || 'none yet'}`);
+                continue;
+            }
+            const foreign = foreignDotOf(entry.input, host.watch);
+            if (foreign) {
+                notes.push(`dataset ${name} dropped: result ${d.from} (${entry.name}) is for dot ${foreign}, not the dot of this chat`);
+                continue;
+            }
+            if (!Object.hasOwn(sources, d.from))
+                sources[d.from] = sourceTable(entry.value, fields);
+        }
+        else if (!Object.hasOwn(datasets, d.from)) {
+            notes.push(`dataset ${name} dropped: ${d.from} was dropped`);
+            continue;
+        }
+        datasets[name] = d;
+    }
+    return { sources, datasets };
+}
+/** Runs the pipelines once, on the server. What fails is dropped and noted; the client runs them again for what it draws. */
+function runPipelines(prep, rawVars, tzOffsetMin, notes) {
+    const out = computeView({ sources: prep.sources, datasets: prep.datasets, tzOffsetMin, ...(rawVars ? { vars: rawVars } : {}) });
+    for (const [name, why] of Object.entries(out.errors.datasets))
+        notes.push(`dataset ${name} dropped: ${why}`);
+    for (const [name, why] of Object.entries(out.errors.vars))
+        notes.push(`var ${name} dropped: ${why}`);
+    const datasets = Object.fromEntries(Object.entries(prep.datasets).filter(([name]) => !Object.hasOwn(out.errors.datasets, name)));
+    const vars = Object.fromEntries(Object.entries(rawVars ?? {}).filter(([k]) => !Object.hasOwn(out.errors.vars, k)));
+    // Only the rows of the results a surviving dataset reads go to the client.
+    const wanted = new Set(Object.values(datasets).map((d) => d.from));
+    const sources = Object.fromEntries(Object.entries(prep.sources).filter(([id]) => wanted.has(id)));
+    return { out, datasets, vars, sources };
+}
+/** The results a view reads whose rows were cut: the source holds fewer rows than the tool found, so counts and rates cover part of the data. */
+export function partialSources(sources, results) {
+    return Object.entries(sources)
+        .filter(([, t]) => (t.more ?? 0) > 0)
+        .map(([id, t]) => ({ result: id, ...(results.get(id) ? { tool: results.get(id).name } : {}), rows: t.rows.length, more: t.more }));
+}
+// ---------- Streaming while the model writes the call ----------
+/** Characters of a call input the stream reads before it gives up. The finished view does not depend on it. */
+const MAX_STREAM_CHARS = 96_000;
+function tryParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reads the JSON of a compose_view input as far as it has come, without waiting for the end. It finds the complete top-level values
+ * of `title`, `datasets`, and `vars`, and each child of `root.children` the moment its closing brace arrives. Nothing is run or
+ * evaluated: this only walks the brackets, and a half-written node is left for the next chunk.
+ */
+export function scanViewInput(text) {
+    const head = {};
+    const children = [];
+    let rootStarted = false;
+    const stack = [];
+    const starts = [];
+    let inString = false;
+    let escaped = false;
+    let strStart = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (c === '\\')
+                escaped = true;
+            else if (c === '"') {
+                inString = false;
+                const top = stack[stack.length - 1];
+                if (top?.open === '{' && top.expectKey) {
+                    const key = tryParse(text.slice(strStart, i + 1));
+                    if (typeof key === 'string')
+                        top.key = key;
+                    else
+                        delete top.key;
+                    top.expectKey = false;
+                }
+                else if (stack.length === 1 && top?.open === '{' && top.key === 'title')
+                    head.title = tryParse(text.slice(strStart, i + 1));
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            strStart = i;
+        }
+        else if (c === '{' || c === '[') {
+            stack.push({ open: c, expectKey: c === '{' });
+            starts.push(i);
+            if (stack.length === 2 && c === '{' && stack[0].key === 'root')
+                rootStarted = true;
+        }
+        else if (c === '}' || c === ']') {
+            const closed = stack.pop();
+            const start = starts.pop();
+            if (!closed || start === undefined)
+                break;
+            const key = stack[0]?.key;
+            if (stack.length === 1 && key && (key === 'datasets' || key === 'vars'))
+                head[key] = tryParse(text.slice(start, i + 1));
+            else if (stack.length === 3 && closed.open === '{' && key === 'root' && stack[1].key === 'children' && stack[2].open === '[')
+                children.push(tryParse(text.slice(start, i + 1)));
+        }
+        else if (c === ',') {
+            const top = stack[stack.length - 1];
+            if (top?.open === '{')
+                top.expectKey = true;
+        }
+    }
+    return { head, rootStarted, children };
+}
+/**
+ * Sends a view to the client while the model is still writing the compose_view call: the shell once the first node of the root has
+ * closed, then each node as its closing brace arrives (docs/CHAT-UI.md, Composed views: Streaming). Each node goes through the checks of
+ * the finished view: the registry, the binding to a tool result, and the run of the pipelines. It is a preview. When the call ends,
+ * composeView checks the whole spec, and the finished block replaces what streamed, with the same id, so a node the full check drops
+ * disappears then. Anything this class cannot read, or reads wrong, only means fewer nodes stream; it never changes what is stored.
+ */
+export class ViewStream {
+    host;
+    /** The id of the view block, set when the shell has been sent. */
+    id;
+    text = '';
+    done = 0;
+    sent = 0;
+    stopped = false;
+    claimed = false;
+    finalInput;
+    ready;
+    constructor(host) {
+        this.host = host;
+    }
+    /** True once the shell has been sent. */
+    get started() {
+        return this.id !== undefined;
+    }
+    /** Nodes sent so far. */
+    get nodes() {
+        return this.sent;
+    }
+    /** A piece of the input, as it arrives. Never throws: a stream that cannot go on stops, and the finished view is unaffected. */
+    feed(chunk) {
+        if (this.stopped)
+            return;
+        this.text += chunk;
+        if (this.text.length > MAX_STREAM_CHARS) {
+            this.stopped = true;
+            return;
+        }
+        // Nothing closes without a closing bracket, so a piece with none changes nothing and the walk is skipped.
+        if (!/[}\]]/.test(chunk))
+            return;
+        try {
+            this.advance();
+        }
+        catch {
+            this.stopped = true;
+        }
+    }
+    /** The input is complete. */
+    end() {
+        if (this.stopped)
+            return;
+        try {
+            this.advance();
+            this.finalInput = JSON.stringify(JSON.parse(this.text));
+        }
+        catch {
+            this.stopped = true;
+        }
+    }
+    /** True when the finished call carries the input this stream read, and nothing else has claimed the stream. */
+    claim(input) {
+        if (this.claimed || this.finalInput === undefined)
+            return false;
+        try {
+            this.claimed = JSON.stringify(input) === this.finalInput;
+        }
+        catch {
+            this.claimed = false;
+        }
+        return this.claimed;
+    }
+    /** Takes a streamed view away from the client: the call failed, or no call came to finish it. */
+    drop() {
+        if (this.id === undefined)
+            return;
+        const id = this.id;
+        this.id = undefined;
+        this.host.emit({ type: 'view_drop', id });
+    }
+    /** The turn is over: a stream no call claimed has no finished view to replace it, so it goes. */
+    close() {
+        if (!this.claimed)
+            this.drop();
+        this.stopped = true;
+    }
+    advance() {
+        const scan = scanViewInput(this.text);
+        if (!scan.rootStarted || scan.children.length <= this.done)
+            return;
+        if (!this.started && !this.begin(scan.head)) {
+            this.stopped = true;
+            return;
+        }
+        for (; this.done < scan.children.length; this.done++)
+            this.send(scan.children[this.done]);
+    }
+    /** Sends the shell: the title, the datasets the tool results can feed, and their rows. False when it cannot be sent. */
+    begin(head) {
+        if (this.host.channel === 'call')
+            return false;
+        const notes = [];
+        const h = parseViewHead(head);
+        // Every column goes in the shell: which ones the nodes read is not known yet. The finished view cuts them down.
+        const prep = prepare(h.datasets, this.host, null, notes);
+        const tz = this.host.tzOffsetMin ?? new Date().getTimezoneOffset();
+        const computed = runPipelines(prep, h.vars, tz, notes);
+        const id = this.host.nextId();
+        const shell = parseChatBlock({
+            id,
+            kind: 'view',
+            tool: COMPOSE_VIEW_TOOL,
+            ...(this.host.watch ? { dotId: this.host.watch.id } : {}),
+            state: 'loading',
+            view: {
+                v: 1,
+                ...(h.title ? { title: h.title } : {}),
+                tzOffsetMin: tz,
+                ...(Object.keys(computed.sources).length ? { sources: computed.sources } : {}),
+                ...(Object.keys(computed.datasets).length ? { datasets: computed.datasets } : {}),
+                ...(Object.keys(computed.vars).length ? { vars: computed.vars } : {}),
+                root: { type: 'column', children: [] },
+            },
+        });
+        if (!shell.ok)
+            return false;
+        this.id = id;
+        this.ready = { datasets: computed.datasets, vars: computed.vars, out: computed.out };
+        this.host.emit({ type: 'block', block: shell.block });
+        return true;
+    }
+    /** Checks one closed child of the root, binds it to its tool result, and sends it. A child that fails any check is skipped. */
+    send(raw) {
+        if (!this.ready || this.id === undefined || raw === undefined)
+            return;
+        const notes = [];
+        const node = parseViewNode(raw, { datasets: this.ready.datasets, vars: this.ready.vars });
+        if (!node)
+            return;
+        const wrapper = { type: 'column', children: [node] };
+        const bound = bindTree(wrapper, this.host, notes);
+        const checked = bound ? checkNodes(bound, this.ready.out, notes) : null;
+        const child = checked && checked.type === 'column' ? checked.children[0] : undefined;
+        if (!child)
+            return;
+        this.host.emit({ type: 'view_node', id: this.id, at: this.sent++, node: child });
+    }
+}
+// ---------- compose_view ----------
+/**
+ * Runs compose_view: checks the spec, binds it, streams it, and answers the model with what showed and what was dropped. A spec that
+ * fails shows the blocks it holds, and when it holds none the answer is an error and the chat answers in text.
+ */
+export async function composeView(rawInput, host) {
+    const input = isObj(rawInput) ? rawInput : {};
+    // The spec is the input itself, or sits under `spec` for a model that wraps it.
+    const raw = isObj(input.spec) && input.root === undefined ? input.spec : input;
+    const parsed = parseViewTree(raw);
+    const notes = [...parsed.notes];
+    const failWith = (reason) => {
+        // Nodes that streamed while the model wrote the call were a preview of a view that cannot be built.
+        host.stream?.drop();
+        const blocks = host.channel === 'call' ? [] : fallbackBlocks(raw, host);
+        if (blocks.length) {
+            for (const b of blocks)
+                host.finish({ ...b, tool: COMPOSE_VIEW_TOOL });
+            return {
+                ok: true,
+                fallback: true,
+                shown: blocks.map((b) => b.kind),
+                dropped: notes,
+                note: `The view could not be built (${reason}), so the blocks it holds show as they are. Write one or two sentences.`,
+            };
+        }
+        return { error: `The view could not be built: ${reason}. Answer in text instead.`, dropped: notes };
+    };
+    if (!parsed.ok)
+        return failWith(parsed.reason);
+    const view = parsed.view;
+    // 1. Blocks for the record nodes.
+    const bound = bindTree(view.root, host, notes);
+    if (!bound || bound.type !== 'column')
+        return failWith('no node could be bound to a result');
+    // 2. The rows each dataset reads, cut to the columns the view uses. A table that names no columns shows every column of its
+    //    dataset, so its sources keep all of theirs.
+    const used = fieldsUsed({ ...view, root: bound });
+    const allColumns = viewNodes(bound).some((n) => n.type === 'table' && n.data && !n.columns);
+    const prep = prepare(view.datasets, host, allColumns ? null : used, notes);
+    // 3. The server runs the pipelines once to check them.
+    const tzOffsetMin = host.tzOffsetMin ?? new Date().getTimezoneOffset();
+    const { out, datasets, vars, sources } = runPipelines(prep, view.vars, tzOffsetMin, notes);
+    const checked = checkNodes(bound, out, notes);
+    if (!checked || checked.type !== 'column' || !checked.children.length)
+        return failWith('no node had data to show');
+    const full = {
+        v: 1,
+        ...(view.title ? { title: view.title } : {}),
+        tzOffsetMin,
+        ...(Object.keys(sources).length ? { sources } : {}),
+        ...(Object.keys(datasets).length ? { datasets } : {}),
+        ...(Object.keys(vars).length ? { vars } : {}),
+        root: { type: 'column', children: checked.children },
+        total: checked.children.length,
+    };
+    // 4. Stream it: the shell with the datasets, each node of the root, then the finished block, which replaces the rest. A view whose
+    //    nodes already went out while the model wrote the call has its shell and nodes on the client, so only the finished block goes.
+    const streamed = host.stream?.started === true;
+    const id = streamed ? host.stream.id : host.nextId();
+    const base = { id, kind: 'view', tool: COMPOSE_VIEW_TOOL, ...(host.watch ? { dotId: host.watch.id } : {}) };
+    const quiet = host.channel === 'call';
+    if (!quiet && !streamed) {
+        const shell = parseChatBlock({ ...base, state: 'loading', view: { ...full, root: { type: 'column', children: [] } } });
+        if (shell.ok)
+            host.emit({ type: 'block', block: shell.block });
+        for (const [at, node] of checked.children.entries()) {
+            await tick();
+            host.emit({ type: 'view_node', id, at, node });
+        }
+        await tick();
+    }
+    const finished = host.finish({ ...base, state: 'ready', view: full }, { quiet });
+    if (!finished) {
+        host.stream?.drop();
+        return { error: 'The view could not be shown.', dropped: notes };
+    }
+    host.hide(viewBlocks(full).map((b) => b.id));
+    const link = viewLinkLine(host.watch, host.channel, host.messageId);
+    if (link)
+        host.line(link);
+    // A source cut to its first rows makes every count and rate cover part of the data. The view says so, and so does the model's note.
+    const partial = partialSources(sources, host.results);
+    const cut = partial.map((p) => `${p.result} holds ${p.rows.toLocaleString('en-US')} of ${(p.rows + p.more).toLocaleString('en-US')} rows`).join(', ');
+    return {
+        ok: true,
+        shown: viewKinds(full),
+        ...(notes.length ? { dropped: notes } : {}),
+        ...(partial.length ? { partial } : {}),
+        ...factsOf(out),
+        note: partial.length
+            ? `The view is in the answer with a notice that its numbers cover part of the data: ${cut}. Say so in your sentence and give no total as a fact. Or call the lookup again with fewer days, one branch, or one spec, and compose the view again. Write one or two sentences of judgement, and do not repeat what the view shows.`
+            : 'The view is in the answer. Write one or two sentences of judgement with the key number, and do not repeat what the view shows.',
+    };
+}
+/** The tool definition of compose_view. The description is the format, written from the registry in src/view-spec.ts. */
+export const COMPOSE_VIEW_DEFINITION = {
+    name: COMPOSE_VIEW_TOOL,
+    description: viewSpecGuide(),
+    input_schema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string', description: 'A short title for the view.' },
+            datasets: { type: 'object', description: 'Named tables: { name: { from: "r1", steps: [...] } }.' },
+            vars: { type: 'object', description: 'Named values out of a dataset, for {name} marks in text.' },
+            root: { type: 'object', description: 'A column node: { "type": "column", "children": [ ...nodes ] }.' },
+        },
+        required: ['root'],
+    },
+};
+//# sourceMappingURL=chat-views.js.map