@bivy/bivy 0.20.9-staging.2 → 0.20.9-staging.21

package/dist/session/event-log.js

@@ -17,10 +17,12 @@
 //     text). The base is a SNAPSHOT that is overwritten each turn and SHRINKS on
 //     compaction, so it cannot be appended naively. Instead each snapshot is stored
 //     as a bounded DELTA against the previous one: a `reset:false` record carrying
-//     only the new tail when the snapshot merely extends the last (the common case),
-//     or a `reset:true` record carrying the full snapshot when it shrinks or a
-//     prefix message changed (compaction / in-place mutation). `baseReplay` folds
-//     these back — reset replaces, non-reset extends — reproducing the last snapshot
+//     only the new tail when the snapshot merely extends the last (the common case)
+//     or changes after a shared prefix (`keep` = how much of the prefix survives;
+//     a retried turn replacing its trailing error), or a `reset:true` record
+//     carrying the full snapshot when its first message changed (compaction).
+//     `baseReplay` folds these back — reset replaces, non-reset truncates to `keep`
+//     and extends — reproducing the last snapshot
 //     exactly, so the fold is behaviour-preserving while keeping the file bounded
 //     (~O(total messages)) instead of O(turns × transcript size).
 //
@@ -31,7 +33,6 @@ import path from "node:path";
 import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
 import { DELEGATION_BLOCK, isDelegationCard } from "./delegations.js";
 import { APP_PIN_BLOCK, APP_PUBLICATION_BLOCK, APP_REVIEW_BLOCK, isAppPin, isAppReference, isAppReview } from "../apps/types.js";
-import { SUGGESTION_BLOCK, isTaskSuggestion } from "./suggestions.js";
 import { NOTICE_BLOCK, isAgentNotice } from "./notices.js";
 /**
  * Decompose a transcript message into serialization-independent "atoms": the
@@ -292,7 +293,9 @@ function isBase(value) {
     if (!value || typeof value !== "object")
         return false;
     const record = value;
-    return record.bivyKind === "base" && Array.isArray(record.messages) && typeof record.reset === "boolean";
+    const keep = value.keep;
+    return record.bivyKind === "base" && Array.isArray(record.messages) && typeof record.reset === "boolean"
+        && (keep === undefined || (Number.isInteger(keep) && keep >= 0));
 }
 function isForkDisplay(value) {
     if (!value || typeof value !== "object")
@@ -333,12 +336,6 @@ function isAppPublication(value) {
     const entry = value;
     return entry.bivyKind === "app-publication" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppReference(entry.app);
 }
-function isSuggestionEntry(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const entry = value;
-    return entry.bivyKind === "suggestion" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isTaskSuggestion(entry.suggestion);
-}
 function isNoticeEntry(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -364,7 +361,7 @@ function isAppPinEntry(value) {
     return entry.bivyKind === "app-pin" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppPin(entry.pin);
 }
 function isRecord(value) {
-    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isAppPinEntry(value) || isSuggestionEntry(value) || isNoticeEntry(value);
+    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isAppPinEntry(value) || isNoticeEntry(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -507,15 +504,11 @@ export function replayExtras(entries) {
         role: "assistant", content: [{ type: DELEGATION_BLOCK, delegation: entry.delegation }],
         id: `delegation-${entry.id}`, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
-    const suggestions = entries.filter((entry) => entry.bivyKind === "suggestion").map((entry) => ({
-        role: "assistant", content: [{ type: SUGGESTION_BLOCK, suggestion: entry.suggestion }],
-        id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
-    }));
     const notices = entries.filter((entry) => entry.bivyKind === "notice").map((entry) => ({
         role: "assistant", content: [{ type: NOTICE_BLOCK, notice: entry.notice }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
-    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...pinCards, ...delegationCards, ...suggestions, ...notices];
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...pinCards, ...delegationCards, ...notices];
 }
 /**
  * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
@@ -555,34 +548,70 @@ export function baseReplay(entries) {
         if (entry.reset)
             base = [...entry.messages];
         else
-            base = base.concat(entry.messages);
+            base = (entry.keep === undefined ? base : base.slice(0, entry.keep)).concat(entry.messages);
     }
     return base;
 }
-function parseLogDetailed(body, keep = () => true) {
-    const records = [];
+function parseLogDetailed(lines, keep = () => true) {
+    let records = [];
     let malformedLines = 0;
-    for (const line of body.split("\n")) {
+    let superseded = 0;
+    for (const line of lines) {
         const trimmed = line.trim();
         if (!trimmed || !keep(trimmed))
             continue;
         try {
             const value = JSON.parse(trimmed);
-            if (isRecord(value))
-                records.push(value);
-            else
+            if (!isRecord(value)) {
                 malformedLines += 1;
+                continue;
+            }
+            // A full reset replaces every earlier base record (baseReplay discards
+            // them), so don't hold old snapshots and their images in memory.
+            if (isBase(value) && value.reset) {
+                const before = records.length;
+                records = records.filter((record) => record.bivyKind !== "base");
+                superseded += before - records.length;
+            }
+            records.push(value);
         }
         catch {
             malformedLines += 1;
         }
     }
-    return { records, malformedLines };
+    return { records, malformedLines, superseded };
+}
+/** A log this large that carries replaced base snapshots is rewritten without
+ *  them when it's next read. */
+const COMPACT_LOG_BYTES = 32 * 1024 * 1024;
+/** A file's lines, read in chunks: a log can outgrow the longest string V8
+ *  allows (~512 MB), which made the whole session unreadable. */
+function* fileLines(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const chunk = Buffer.allocUnsafe(4 * 1024 * 1024);
+        let partial = [];
+        for (let n = fs.readSync(fd, chunk); n > 0; n = fs.readSync(fd, chunk)) {
+            let start = 0;
+            for (let nl = chunk.indexOf(10, start); nl !== -1 && nl < n; nl = chunk.indexOf(10, start)) {
+                yield Buffer.concat([...partial, chunk.subarray(start, nl)]).toString("utf8");
+                partial = [];
+                start = nl + 1;
+            }
+            if (start < n)
+                partial.push(Buffer.from(chunk.subarray(start, n)));
+        }
+        if (partial.length)
+            yield Buffer.concat(partial).toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
 /** Parse a JSONL log body into valid records. Callers that need corruption
  * diagnostics use EventLog.load, which reports malformed lines via onIssue. */
 export function parseLog(body) {
-    return parseLogDetailed(body).records;
+    return parseLogDetailed(body.split("\n")).records;
 }
 /**
  * Append-only, coalesced, throttled JSONL log store — the write+read companion to
@@ -666,11 +695,14 @@ export class EventLog {
     /** Read + parse a session's log file (lines passing `keep`), reporting problems. */
     readLog(id, keep) {
         try {
-            const body = fs.readFileSync(this.pathFor(id), "utf8");
-            const parsed = parseLogDetailed(body, keep);
+            const file = this.pathFor(id);
+            const bytes = fs.statSync(file).size;
+            const parsed = parseLogDetailed(fileLines(file), keep);
             if (parsed.malformedLines > 0)
                 this.report(id, "parse", new Error(`${parsed.malformedLines} malformed record(s); valid history was recovered`));
-            return { records: parsed.records, bytes: body.length };
+            if (!keep && parsed.superseded > 0 && bytes > COMPACT_LOG_BYTES)
+                return { records: parsed.records, bytes: this.compact(id, parsed.records) ?? bytes };
+            return { records: parsed.records, bytes };
         }
         catch (error) {
             if (error?.code !== "ENOENT")
@@ -678,6 +710,31 @@ export class EventLog {
             return { records: [], bytes: 0 };
         }
     }
+    /** Rewrite a log without the base snapshots a later reset replaced (logs
+     *  written before truncate-and-extend records repeated the whole transcript on
+     *  every retry). Atomic; returns the new size, or undefined if it failed. */
+    compact(id, records) {
+        const file = this.pathFor(id);
+        const tmp = `${file}.compact-${process.pid}`;
+        try {
+            const fd = fs.openSync(tmp, "w");
+            let bytes = 0;
+            try {
+                for (const record of records)
+                    bytes += fs.writeSync(fd, `${JSON.stringify(record)}\n`);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(tmp, file);
+            return bytes;
+        }
+        catch (error) {
+            fs.rmSync(tmp, { force: true });
+            this.report(id, "rewrite", error);
+            return undefined;
+        }
+    }
     load(id) {
         const cached = this.disk.get(id);
         if (cached) {
@@ -773,15 +830,19 @@ export class EventLog {
         // Identical snapshot → nothing to record.
         if (nextKeys.length === prevKeys.length && prevKeys.every((k, i) => k === nextKeys[i]))
             return;
-        // A prefix-EXTEND (strictly longer, every prior message unchanged) appends only
-        // the new tail; anything else — a shrink (compaction), a changed prefix message
-        // (in-place mutation), or the first snapshot (empty prev, nothing to extend) —
+        // Record only what follows the prefix both snapshots share: a plain extend, or
+        // a truncate-and-extend (`keep`) when a later message changed — a retried turn
+        // replacing its trailing error rewrote the whole transcript, images and all,
+        // on every retry. A changed first message (compaction) or the first snapshot
         // appends a full reset. Rebuild the recorded messages from the serialized form:
         // a free deep copy that also matches exactly what will land on disk.
-        const extend = prevKeys.length > 0 && nextKeys.length > prevKeys.length && prevKeys.every((k, i) => k === nextKeys[i]);
-        const record = extend
-            ? { bivyKind: "base", reset: false, createdAt: Date.now(), messages: nextKeys.slice(prevKeys.length).map((s) => JSON.parse(s)) }
-            : { bivyKind: "base", reset: true, createdAt: Date.now(), messages: nextKeys.map((s) => JSON.parse(s)) };
+        let shared = 0;
+        while (shared < prevKeys.length && shared < nextKeys.length && prevKeys[shared] === nextKeys[shared])
+            shared++;
+        const tail = nextKeys.slice(shared).map((s) => JSON.parse(s));
+        const record = shared === 0
+            ? { bivyKind: "base", reset: true, createdAt: Date.now(), messages: tail }
+            : { bivyKind: "base", reset: false, createdAt: Date.now(), messages: tail, ...(shared < prevKeys.length ? { keep: shared } : {}) };
         this.baseKeys.set(id, nextKeys);
         this.enqueue(id, this.syntheticKey(id), record);
     }
@@ -832,10 +893,6 @@ export class EventLog {
         this.load(id);
         this.enqueue(id, `pin:${entry.pin.id}`, { bivyKind: "app-pin", createdAt: entry.createdAt ?? Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.pin.id, pin: structuredClone(entry.pin) });
     }
-    appendSuggestion(id, entry) {
-        this.load(id);
-        this.enqueue(id, `suggestion:${entry.suggestion.id}`, { bivyKind: "suggestion", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.suggestion.id, suggestion: { ...entry.suggestion } });
-    }
     appendNotice(id, entry) {
         this.load(id);
         this.enqueue(id, `notice:${entry.notice.id}`, { bivyKind: "notice", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.notice.id, notice: { ...entry.notice } });

package/dist/session/inline-image-fetch.js

@@ -10,27 +10,21 @@
 // otherwise get the *viewer's* browser/IP to hit an arbitrary URL by embedding
 // it in a reply).
 //
-// This is the PURE-ish, testable half — URL extraction, host/SSRF validation,
-// and the guarded fetch itself — all dependency-injectable so tests never hit
-// the real network or DNS. The server half (src/server.ts) owns the AttachmentStore
+// This is the PURE-ish, testable half — host/SSRF validation and the guarded
+// fetch itself — all dependency-injectable so tests never hit the real network
+// or DNS. Which references a message makes at all is the renderer's and this
+// module's shared concern, so it lives in ./message-components.js (the same file
+// @bivy/core compiles). The server half (src/server.ts) owns the AttachmentStore
 // write, the durable event-log ref, and the live broadcast; see resolveInlineImages.
 import dns from "node:dns/promises";
 import { hostnameIsLocal } from "../auth.js";
 import { sanitizeAttachmentName, sniffMime } from "./attach-to-chat.js";
-/**
- * The image-markdown pattern, `![alt](https://…)` — MUST match the image regex
- * in `inline()` in packages/core/src/markdown.ts exactly. Not a shared import: the
- * node (src/) intentionally does not depend on @bivy/core (a browser/client
- * package — see packages/core's own description). Kept in lock-step by comment
- * instead, the same convention EPHEMERAL_ALLOWED_HOSTS uses in
- * src/ephemeral-exec.ts for its cross-copy host allowlist. If you change one,
- * change the other.
- */
-const INLINE_IMAGE_MD_RE = /!\[[^\]]*\]\((https:\/\/[^)\s]+)\)/g;
-/** Bound how many distinct remote images a single message can trigger a fetch
- *  for — a pathological/malicious message can't fan out into an unbounded
- *  number of outbound requests. */
-export const MAX_INLINE_IMAGES_PER_MESSAGE = 6;
+import { extractImageReferences, extractMessageReferences, MAX_COMPONENTS_PER_MESSAGE } from "./message-components.js";
+/** Bound how many distinct images a single message can trigger a resolve for —
+ *  a pathological/malicious message can't fan out into an unbounded number of
+ *  outbound requests or file reads. Re-exported from the shared grammar, which
+ *  the renderer applies the same cap from. */
+export const MAX_INLINE_IMAGES_PER_MESSAGE = MAX_COMPONENTS_PER_MESSAGE;
 /** Ceiling for a single fetched inline image. Smaller than
  *  MAX_AGENT_ATTACHMENT_BYTES (attach-to-chat.ts) because these bytes come from
  *  an arbitrary, untrusted remote origin rather than the local workspace —
@@ -40,23 +34,20 @@ export const MAX_INLINE_IMAGE_BYTES = 8 * 1024 * 1024;
 const FETCH_TIMEOUT_MS = 10_000;
 /** Hard cap on redirect hops, mirroring execEphemeralRequest's guard. */
 const MAX_REDIRECTS = 5;
-/** Extract the distinct `https://` URLs a message's raw markdown references via
- *  `![alt](url)`, in first-seen order, capped at MAX_INLINE_IMAGES_PER_MESSAGE. */
+/** The distinct `https://` URLs a message's raw markdown references via
+ *  `![alt](url)`, in first-seen order, capped at MAX_INLINE_IMAGES_PER_MESSAGE.
+ *  Workspace-relative references are a different resolver's job (they are read,
+ *  not fetched) — see resolveWorkspaceImageRefs in transcript-persistence.ts. */
 export function extractInlineImageUrls(text) {
-    if (!text)
-        return [];
-    const out = [];
-    const seen = new Set();
-    for (const match of text.matchAll(INLINE_IMAGE_MD_RE)) {
-        const url = match[1];
-        if (!url || seen.has(url))
-            continue;
-        seen.add(url);
-        out.push(url);
-        if (out.length >= MAX_INLINE_IMAGES_PER_MESSAGE)
-            break;
-    }
-    return out;
+    return extractImageReferences(text).filter((i) => i.origin === "remote").map((i) => i.ref);
+}
+/** The distinct workspace references a message makes — from image syntax or a
+ *  `::view{src=…}` directive — in first-seen order, under the same per-message
+ *  cap. `syntax` tells the resolver whether non-image bytes are acceptable. */
+export function extractWorkspaceRefs(text) {
+    return extractMessageReferences(text)
+        .filter((r) => r.origin === "workspace")
+        .map(({ ref, syntax }) => ({ ref, syntax }));
 }
 /** Best-effort plain text for an assistant RuntimeMessage's `content`, which is
  *  either a plain string or an array of typed blocks (`{type:"text", text}`

package/dist/session/message-components.js

@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// The grammar for things an agent places INSIDE its chat message by writing
+// them in the markdown, rather than out-of-band beside it.
+//
+// Three parties have to agree on it, byte for byte:
+//
+//   1. the renderer (packages/core/src/markdown.ts) turns each reference into an
+//      EMPTY placeholder element carrying the reference as a data attribute;
+//   2. the node (src/session/transcript-persistence.ts) finds the same
+//      references in the raw message, resolves each one, and stores the bytes in
+//      the content-addressed AttachmentStore under that same reference string;
+//   3. the view (packages/web ChatView) looks the reference up in the entry's
+//      resolved map and hydrates the placeholder.
+//
+// Those three live in two packages that deliberately do not import each other
+// (src/ is the node; @bivy/core is the client library). The agreement used to be
+// two copies of one regex kept in lock-step by comment — which silently diverges
+// the moment someone edits one. This file is the single source instead: the node
+// compiles THIS file through a symlink at src/session/message-components.ts, and
+// scripts/check-module-boundaries.mjs fails if the two stop being one inode.
+//
+// Being compiled by both builds, it imports nothing at all.
+/** How many components one message may resolve. A pathological or hostile
+ *  message must not fan out into an unbounded number of file reads / outbound
+ *  fetches, nor bloat the event log that replicates to a phone. */
+export const MAX_COMPONENTS_PER_MESSAGE = 6;
+/** Longest reference we will even look at. Generous enough for a signed CDN URL
+ *  and far past any real workspace path, but a hard bound — it is also the
+ *  repetition limit in the pattern below, which is what keeps matching linear. */
+const MAX_REF_LENGTH = 2048;
+/** Longest alt text we will match. Bounded for the same reason, not because a
+ *  caption that long means anything. */
+const MAX_ALT_LENGTH = 500;
+/**
+ * Markdown image syntax. One literal, used by every caller here, so the "keep
+ * these two regexes identical" hazard cannot come back.
+ *
+ * Deliberately matches ANY target, not just the ones we accept:
+ * `classifyImageTarget` decides, and a target it rejects is left in the message
+ * as the literal text the agent wrote. Matching narrowly instead would make a
+ * rejected image silently vanish.
+ *
+ * Returned fresh per call: a shared `g`-flagged regex carries `lastIndex`
+ * between calls, which is exactly the kind of cross-call state that makes two
+ * consumers of one module disagree.
+ *
+ * Both repetitions are BOUNDED, and must stay that way. Unbounded `[^\]]*` and
+ * `[^)\s]+` make matching quadratic in the message length: on input like
+ * `![![![…` every `!` starts a match attempt that scans to the end of the
+ * string. This runs on assistant message text — which a prompt injection or a
+ * tool result echoed into a reply can shape — on the node, at every message
+ * boundary. With fixed upper bounds each attempt costs at most a constant, so
+ * the whole scan is linear. (CodeQL js/polynomial-redos flags the unbounded
+ * form; it was flagging the shape this module inherited.)
+ */
+function imagePattern() {
+    return new RegExp(`!\\[([^\\]]{0,${MAX_ALT_LENGTH}})\\]\\(([^)\\s]{1,${MAX_REF_LENGTH}})\\)`, "g");
+}
+/**
+ * Reverse the entity escaping `esc()` in markdown.ts applies to the whole
+ * message before the image rule ever runs.
+ *
+ * Without this the two sides disagree for any reference containing `&`: the
+ * renderer would key on `…?a=1&b=2` while the node — which scans the raw
+ * message text — keys on `…?a=1&b=2`, and the image never hydrates. (That
+ * mismatch predates this module; it is fixed here because this is now the one
+ * place that derives a reference key.) On already-raw text this is a no-op
+ * unless the text literally contains an entity, in which case both sides
+ * normalise it the same way and still agree.
+ */
+export function unescapeComponentRef(target) {
+    return String(target || "")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * Decide what an image target means, or `null` to refuse it.
+ *
+ * `remote` targets are fetched BY THE NODE under its SSRF checks (see
+ * src/session/inline-image-fetch.ts) — never by the viewer's browser.
+ *
+ * `workspace` targets are read from the session's working directory. This
+ * function is NOT the security boundary for them: `planAttachment()`
+ * (src/session/attach-to-chat.ts) is, because only it can resolve symlinks
+ * against the real workspace root. What this does is refuse the obviously
+ * hostile shapes up front, so an absolute path or a traversal never becomes a
+ * map key or reaches the filesystem at all. Message text is agent-authored and
+ * therefore reachable by prompt injection, so both layers earn their place.
+ */
+export function classifyImageTarget(target) {
+    const t = String(target || "").trim();
+    if (!t || t.length > MAX_REF_LENGTH)
+        return null;
+    if (t.startsWith("https://"))
+        return "remote";
+    // Every other scheme is refused. `http:` would be an unencrypted fetch,
+    // `data:`/`blob:` smuggle bytes past the size and mime checks, `file:` reads
+    // the node's disk outside any workspace, and `javascript:` is self-evident.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(t))
+        return null;
+    if (t.startsWith("//"))
+        return null; // protocol-relative URL
+    if (t.startsWith("/") || t.startsWith("~"))
+        return null; // absolute / home-relative
+    if (t.startsWith("#"))
+        return null; // in-page anchor
+    if (t.includes("\\"))
+        return null;
+    if (t.split("/").some((segment) => segment === ".."))
+        return null; // traversal
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(t))
+        return null;
+    return "workspace";
+}
+/**
+ * Every image reference a message makes, de-duplicated, in first-seen order and
+ * capped at `limit`. Targets `classifyImageTarget` refuses are left out: they
+ * are not components, they are prose.
+ */
+export function extractImageReferences(text, limit = MAX_COMPONENTS_PER_MESSAGE) {
+    if (!text)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const match of String(text).matchAll(imagePattern())) {
+        const ref = unescapeComponentRef(match[2] ?? "");
+        const origin = classifyImageTarget(ref);
+        if (!origin || seen.has(ref))
+            continue;
+        seen.add(ref);
+        out.push({ ref, origin });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/**
+ * Replace each accepted image reference via `render`, leaving refused ones as
+ * the literal text the agent wrote. The renderer uses this so the one pattern
+ * above stays the only place image syntax is recognised.
+ */
+export function replaceImageReferences(text, render) {
+    return String(text || "").replace(imagePattern(), (whole, alt, target) => {
+        const ref = unescapeComponentRef(target);
+        const origin = classifyImageTarget(ref);
+        if (!origin)
+            return whole;
+        return render({ alt: alt ?? "", ref, origin });
+    });
+}
+// ---------------------------------------------------------------------------
+// Components the agent places with a directive or a spec
+//
+// `![alt](path)` says "show this image here" and nothing else. The two forms
+// below are how an agent says anything more — show this FILE, show this CSV as a
+// table — without a second out-of-band channel per kind:
+//
+//   ::view{src=data/sales.csv}         point at something in the workspace
+//   ```bivy … ```                      carry a small spec inline
+//
+// Both land as the same value, a ComponentPlacement, and both render through one
+// table keyed by `kind`. Adding a kind is a row in that table, not another
+// branch here. Anything this file cannot make sense of stays the text the agent
+// wrote, because an agent WILL get the syntax wrong and a message must still
+// read.
+// ---------------------------------------------------------------------------
+/** The info string that marks a fenced block as a component spec. */
+export const COMPONENT_FENCE_LANG = "bivy";
+/** Ceiling for one inline spec. A spec rides in the message and then in every
+ *  rendered copy of it, so it is for a handful of values — a file is the right
+ *  home for real data. Past this the fence stays an ordinary code block. */
+export const MAX_COMPONENT_SPEC_CHARS = 16 * 1024;
+/** Ceiling for a directive's attribute list, bounding the parse below. */
+const MAX_ATTRS_CHARS = 512;
+/** Leaf directives this grammar knows. `view` is the general one; a named leaf
+ *  can be added later without touching the parser. */
+const LEAF_NAMES = new Set(["view"]);
+/**
+ * `{src=a/b.csv height=200 caption="Last quarter" #fig-1 .wide}` →
+ * `{ src: "a/b.csv", height: "200", caption: "Last quarter", id: "fig-1", class: "wide" }`
+ *
+ * Every repetition is bounded (see imagePattern's note — this runs on the same
+ * agent-authored text), and the whole list is length-capped, so a pathological
+ * attribute string is refused rather than parsed slowly.
+ */
+export function parseAttrs(source) {
+    const out = {};
+    const text = String(source || "").trim().replace(/^\{|\}$/g, "");
+    if (!text || text.length > MAX_ATTRS_CHARS)
+        return out;
+    const re = /([#.]?[\w-]{1,64})(?:\s*=\s*(?:"([^"\n]{0,512})"|'([^'\n]{0,512})'|([^\s"'}]{1,512})))?/g;
+    for (const m of text.matchAll(re)) {
+        const key = m[1] ?? "";
+        const value = m[2] ?? m[3] ?? m[4];
+        if (key.startsWith("#"))
+            out.id = key.slice(1);
+        else if (key.startsWith("."))
+            out.class = out.class ? `${String(out.class)} ${key.slice(1)}` : key.slice(1);
+        else if (key)
+            out[key] = value === undefined ? true : value;
+    }
+    return out;
+}
+/**
+ * A whole line that is a leaf directive, or null. Block-level by construction:
+ * the directive must own its line, so a `::view{…}` written mid-sentence is
+ * prose and a half-streamed one cannot render until its line is complete.
+ *
+ * `src` is validated as a WORKSPACE reference. A directive is not a link — it
+ * names something Bivy has to read — so a remote URL is refused here even
+ * though `![](https://…)` accepts one.
+ */
+export function parseComponentDirective(line) {
+    // Surrounding whitespace is trimmed rather than matched, leaving exactly ONE
+    // whitespace quantifier in the pattern. Two of them around an optional group
+    // (`::name[ \t]*{…}?[ \t]*$`) is ambiguous — a run of tabs can be split
+    // between them in as many ways as it is long, which is quadratic on a line
+    // like `::a` followed by whitespace, and this runs on agent-authored text.
+    // See imagePattern's note; the same rule applies to every pattern here.
+    const m = /^::([a-z][\w-]{0,31})[ \t]{0,32}(\{[^}\n]{0,512}\})?$/i.exec(String(line || "").trim());
+    if (!m || !LEAF_NAMES.has((m[1] ?? "").toLowerCase()))
+        return null;
+    const { src, ...attrs } = parseAttrs(m[2] ?? "");
+    const ref = typeof src === "string" ? unescapeComponentRef(src) : "";
+    if (!ref || classifyImageTarget(ref) !== "workspace")
+        return null;
+    return { ref, spec: null, attrs };
+}
+/** True for the info string of a component fence (```bivy). */
+export function isComponentFence(info) {
+    return String(info || "").trim().toLowerCase() === COMPONENT_FENCE_LANG;
+}
+/**
+ * A component fence's body as a spec object, or null to leave the fence as an
+ * ordinary code block — which is what an agent gets for malformed JSON, and is
+ * strictly better than an error: the source stays readable and copyable.
+ */
+export function parseComponentSpec(body) {
+    const text = String(body || "").trim();
+    if (!text || text.length > MAX_COMPONENT_SPEC_CHARS)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * How a component is rendered, from its spec's own `type` or from the file it
+ * points at. One table, so a new kind is a row here plus a row in the view
+ * layer's registry — never a branch in the parser.
+ *
+ * Returns a kind string even for a kind this build cannot render; the registry
+ * decides, and falls back visibly rather than dropping the component.
+ */
+export function componentKind(opts) {
+    const declared = opts.spec?.type;
+    if (typeof declared === "string" && declared.trim())
+        return declared.trim().toLowerCase();
+    if (opts.spec)
+        return "unknown";
+    const mime = String(opts.mimeType || "").toLowerCase();
+    if (mime.startsWith("image/"))
+        return "image";
+    // Everything else is a file the reader can open or download. Rows for richer
+    // readings of a file — a CSV as a table, a notebook, a diff — belong here
+    // alongside the renderer that can actually draw them. A row added early would
+    // promise a kind the view layer has to decline, turning a useful download into
+    // "this version cannot show that yet".
+    return "file";
+}
+/**
+ * Every reference a message makes that Bivy has to resolve — from image syntax
+ * or from a directive — de-duplicated, in first-seen order, under ONE shared
+ * cap. One budget across both forms is deliberate: the cost being bounded is
+ * file reads and persisted bytes, which do not care which syntax asked.
+ */
+export function extractMessageReferences(text, limit = MAX_COMPONENTS_PER_MESSAGE) {
+    if (!text)
+        return [];
+    const source = String(text);
+    const found = [];
+    // Images are matched against the WHOLE text, not line by line: alt text may
+    // contain a newline (an agent wrapping a long caption at 80 columns), and the
+    // renderer — which sees a paragraph with its lines already joined — would
+    // place a mount point the node then never resolved.
+    for (const match of source.matchAll(imagePattern())) {
+        const ref = unescapeComponentRef(match[2] ?? "");
+        const origin = classifyImageTarget(ref);
+        if (origin)
+            found.push({ ref, origin, syntax: "image", at: match.index ?? 0 });
+    }
+    // Directives own a whole line, so they are matched per line; the running
+    // offset keeps them in document order with the images above.
+    let at = 0;
+    for (const line of source.split("\n")) {
+        const directive = parseComponentDirective(line);
+        if (directive?.ref)
+            found.push({ ref: directive.ref, origin: "workspace", syntax: "view", at });
+        at += line.length + 1;
+    }
+    found.sort((a, b) => a.at - b.at);
+    const out = [];
+    const seen = new Set();
+    for (const { ref, origin, syntax } of found) {
+        if (seen.has(ref))
+            continue;
+        seen.add(ref);
+        out.push({ ref, origin, syntax });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}