@bivy/bivy 0.20.9-staging.9 → 0.21.0

package/dist/session/message-components.js

@@ -0,0 +1,429 @@
+// 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;
+/** An app id as the apps registry mints them. Narrow on purpose: an id is the
+ *  only thing about an app the chat ever holds, so anything that is not plainly
+ *  one is not treated as an app reference. */
+const APP_ID = /^[\w-]{1,64}$/;
+/** 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, app, ...attrs } = parseAttrs(m[2] ?? "");
+    // `app=<id>` names something the MACHINE already published, not a file, so it
+    // is not a workspace reference and the node resolves nothing for it: the id
+    // travels in the transcript exactly as `AppMessage` has always stored it, and
+    // the view layer turns it into a preview. Kept as a spec rather than a `ref`
+    // so nothing downstream mistakes it for a path to read.
+    if (typeof app === "string" && APP_ID.test(app)) {
+        return { ref: null, spec: { type: "app", appId: app }, attrs };
+    }
+    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;
+}
+/**
+ * A Vega-Lite spec, recognised by its own shape rather than by a `type` an
+ * agent would have to remember to add. A spec written for anywhere else works
+ * here unchanged, which is the point of using Vega-Lite instead of a dialect
+ * only Bivy reads.
+ */
+function isVegaLite(spec) {
+    if (typeof spec.$schema === "string" && /vega-lite/i.test(spec.$schema))
+        return true;
+    return ["mark", "layer", "hconcat", "vconcat", "concat", "facet", "repeat"].some((key) => key in spec);
+}
+/**
+ * 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 isVegaLite(opts.spec) ? "chart" : "unknown";
+    const mime = String(opts.mimeType || "").toLowerCase();
+    if (mime.startsWith("image/"))
+        return "image";
+    const ext = String(opts.path || "").toLowerCase().split(".").pop() ?? "";
+    if (ext === "csv" || ext === "tsv")
+        return "table";
+    // Everything else is a file the reader can open or download. Rows for richer
+    // readings of a file — 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";
+}
+/** How deep into a spec to look for references. Bounded so a pathological
+ *  nesting cannot turn one message into an unbounded walk. */
+const MAX_SPEC_DEPTH = 8;
+/**
+ * Workspace files a SPEC references, by putting a relative path in a `url`
+ * field. That is Vega-Lite's `data.url`, which is how a chart points at a
+ * dataset rather than carrying every row inline — and the whole spec is walked
+ * because Vega-Lite allows one per layer, facet and lookup, not just at the top.
+ *
+ * Deliberately keyed on the field NAME, not on anything Vega-specific: this
+ * file must not learn one kind's schema, and "a `url` field holding a
+ * workspace path is a reference" is a rule any future kind can use.
+ *
+ * A `url` that is not a workspace path (an `https://` address, say) is not
+ * returned, and so is never resolved — the view layer refuses those outright
+ * rather than letting a chart make the reader's browser fetch it.
+ */
+export function specReferences(spec, limit = MAX_COMPONENTS_PER_MESSAGE) {
+    const out = [];
+    const seen = new Set();
+    const walk = (value, depth) => {
+        if (out.length >= limit || depth > MAX_SPEC_DEPTH || !value || typeof value !== "object")
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item, depth + 1);
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "url" && typeof child === "string") {
+                const ref = unescapeComponentRef(child);
+                if (classifyImageTarget(ref) === "workspace" && !seen.has(ref)) {
+                    seen.add(ref);
+                    out.push(ref);
+                    if (out.length >= limit)
+                        return;
+                }
+                continue;
+            }
+            walk(child, depth + 1);
+        }
+    };
+    walk(spec, 0);
+    return out;
+}
+/** Each ```bivy fence in `text`, as a parsed spec with its offset. Line-wise,
+ *  because that is how a fence is defined; an unterminated one yields nothing,
+ *  which is also how a half-streamed message behaves. */
+function componentFences(text) {
+    const out = [];
+    const lines = String(text).split("\n");
+    let at = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const start = at;
+        at += line.length + 1;
+        if (!isComponentFence(line.trim().replace(/^```+/, "")))
+            continue;
+        const body = [];
+        let j = i + 1;
+        for (; j < lines.length && !lines[j].trim().startsWith("```"); j++) {
+            body.push(lines[j]);
+            at += lines[j].length + 1;
+        }
+        if (j < lines.length)
+            at += lines[j].length + 1;
+        const spec = parseComponentSpec(body.join("\n"));
+        if (spec)
+            out.push({ spec, at: start });
+        i = j;
+    }
+    return out;
+}
+/**
+ * Every reference a message makes that Bivy has to resolve — from image syntax,
+ * from a directive, or from a `url` inside a spec — de-duplicated, in first-seen
+ * order, under ONE shared cap. One budget across all three 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;
+    }
+    // A spec can point at a dataset instead of carrying it (a chart's data.url).
+    for (const { spec, at: offset } of componentFences(source)) {
+        for (const ref of specReferences(spec, limit)) {
+            found.push({ ref, origin: "workspace", syntax: "spec", at: offset });
+        }
+    }
+    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;
+}

package/dist/session/run-terminal.js

@@ -146,7 +146,7 @@ export function createRunTerminals(deps) {
         deps.broadcast({ type: "terminal.closed", termId });
     }
     async function runTerminalList() {
-        const runs = terminals.list((meta) => meta.kind === "run").filter((t) => runTerminals.has(t.id));
+        const runs = terminals.list((meta) => meta.kind === "run" && !meta.background).filter((t) => runTerminals.has(t.id));
         let saved = [];
         if (runs.some((t) => t.meta.autoName)) {
             try {
@@ -294,7 +294,8 @@ export function createRunTerminals(deps) {
         const commandLine = [spec.command, ...spec.args].join(" ");
         const explicitName = spec.name?.trim();
         const name = explicitName || (spec.mux ? undefined : defaultRunName(spec.agent, commandLine, workspace));
-        const notifiable = !spec.mux;
+        // A mux attach or an app's own program is not a session of its own.
+        const isSession = !spec.mux && !spec.background;
         const createdAt = Date.now();
         // The agent inside gets the same session env a chat session's agent does, so
         // `bivy notify`/`ask`/`app` reach this run: under its pinned session id, else
@@ -312,7 +313,7 @@ export function createRunTerminals(deps) {
                 cols: spec.cols,
                 rows: spec.rows,
                 clientId: spec.clientId,
-                meta: { kind: "run", agent: spec.agent, model: spec.model, label, name, autoName: !explicitName && !spec.mux, command: commandLine, mux: spec.mux, sessionId: spec.sessionId },
+                meta: { kind: "run", agent: spec.agent, model: spec.model, label, name, autoName: !explicitName && !spec.mux, command: commandLine, mux: spec.mux, sessionId: spec.sessionId, background: spec.background },
                 onData: (data) => {
                     emitRunOutput(id, data);
                     const at = Date.now();
@@ -320,7 +321,7 @@ export function createRunTerminals(deps) {
                         lastActivityPing.set(id, at);
                         deps.broadcast({ type: "terminal.activity", termId: id, at });
                     }
-                    if (notifiable)
+                    if (isSession)
                         armRunIdleNotify(id, name);
                 },
                 onExit: (code, _signal, scrollback) => {
@@ -341,7 +342,7 @@ export function createRunTerminals(deps) {
                         catch { /* best-effort */ }
                         return;
                     }
-                    if (!spec.mux) {
+                    if (isSession) {
                         // The durable record of this run, in order of fidelity: the agent's
                         // own session (pinned at launch), the session discovered in the
                         // agent's store, else — for any agent at all — the terminal
@@ -383,7 +384,7 @@ export function createRunTerminals(deps) {
                             catch { /* best-effort */ }
                         })();
                     }
-                    if (!spec.mux) {
+                    if (isSession) {
                         void ingestAgentCredentials(spec.agent, deps.credsDir, deps.piDir)
                             .then(async (imported) => {
                             if (imported > 0) {
@@ -406,7 +407,8 @@ export function createRunTerminals(deps) {
                 catch { /* best-effort: a metadata write must never block the run launch */ }
             }
             emit({ type: "terminal.opened", termId: id, workspace, mode: "run", agent: spec.agent, label, name });
-            deps.broadcast({ type: "terminal.created", terminal: { termId: id, workspace, createdAt, lastActivityAt: createdAt, kind: "run", agent: spec.agent, model: spec.model, label, name, command: commandLine, mux: spec.mux, sessionId: spec.sessionId, pid: terminals.pid(id) } });
+            if (!spec.background)
+                deps.broadcast({ type: "terminal.created", terminal: { termId: id, workspace, createdAt, lastActivityAt: createdAt, kind: "run", agent: spec.agent, model: spec.model, label, name, command: commandLine, mux: spec.mux, sessionId: spec.sessionId, pid: terminals.pid(id) } });
             // A pinned run is now a durable session too: push the authoritative list
             // (status "working" while this PTY lives) and re-advertise, so clients on
             // other nodes — which never see this node's terminal.created — still get