@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/question.js

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { randomUUID } from "node:crypto";
+// Bivy owns the AskUserQuestion → interactive-question-card feature at the
+// governance layer, NOT inside any single runtime adapter. A `user_question`
+// is a blocking, multiple-choice clarifying question an agent raises mid-turn
+// (Claude Code's AskUserQuestion tool, and any future agent that emits the same
+// tool). It is intercepted in the guardian tool-interceptor — the one seam every
+// runtime with capabilities.toolInterception already implements — so pi and the
+// Claude Agent SDK both light up with zero per-runtime question code. This is
+// the deliberate sibling of ApprovalManager: same block-and-wait shape, but it
+// returns the user's structured answers instead of a yes/no.
+/** How long a pending question waits for an answer before auto-cancelling.
+ *  Without this a client that never renders/answers the card (a stale client,
+ *  a UI bug, nobody looking) would park the agent's tool call — and the turn —
+ *  indefinitely. Mirrors the old runtime-side QUESTION_TIMEOUT_MS. */
+const QUESTION_TIMEOUT_MS = 10 * 60 * 1000;
+export class QuestionManager {
+    pending = new Map();
+    requestListeners = new Set();
+    resolvedListeners = new Set();
+    /** Notified when a new question is raised — the server broadcasts
+     *  `session.question` from here (mirrors approvals.onRequest). */
+    onRequest(listener) {
+        this.requestListeners.add(listener);
+        return () => this.requestListeners.delete(listener);
+    }
+    /** Notified every time a question settles — answered, cancelled, timed out,
+     *  or aborted — exactly once. The server broadcasts `session.question.resolved`
+     *  from here, so it fires precisely when the card should close. */
+    onResolved(listener) {
+        this.resolvedListeners.add(listener);
+        return () => this.resolvedListeners.delete(listener);
+    }
+    list() {
+        return [...this.pending.values()].map((p) => p.request);
+    }
+    hasPendingForSession(sessionId) {
+        for (const p of this.pending.values())
+            if (p.request.sessionId === sessionId)
+                return true;
+        return false;
+    }
+    /**
+     * Raise a blocking question and resolve once the user answers/skips (or it
+     * times out / the turn aborts). Called from the guardian interceptor; the
+     * returned answer is formatted back to the agent as the tool result.
+     */
+    request(input) {
+        const request = {
+            id: randomUUID(),
+            sessionId: input.sessionId,
+            questions: input.questions,
+            createdAt: Date.now(),
+            status: "pending",
+        };
+        return new Promise((resolve) => {
+            // Already-aborted turn: settle immediately, never register.
+            if (input.signal?.aborted) {
+                request.status = "cancelled";
+                resolve({ behavior: "cancelled" });
+                for (const l of this.resolvedListeners)
+                    l(request);
+                return;
+            }
+            const timeout = setTimeout(() => this.settle(request.id, { behavior: "cancelled" }, "expired"), input.timeoutMs ?? QUESTION_TIMEOUT_MS);
+            const onAbort = () => this.settle(request.id, { behavior: "cancelled" }, "cancelled");
+            input.signal?.addEventListener("abort", onAbort, { once: true });
+            this.pending.set(request.id, { request, resolve, timeout, onAbort, signal: input.signal });
+            for (const l of this.requestListeners)
+                l(request);
+        });
+    }
+    /** Deliver the user's answer (or a skip/cancel) to a pending question. A
+     *  stale/unknown id is a silent no-op — same tolerance as ApprovalManager. */
+    resolve(id, answer) {
+        return this.settle(id, answer, answer.behavior === "completed" ? "answered" : "cancelled");
+    }
+    /** Cancel every question outstanding for a session — called when the session
+     *  is disposed/killed so cards close and the awaiting guardian promise (and
+     *  the turn behind it) doesn't hang until timeout. */
+    cancelForSession(sessionId) {
+        for (const id of [...this.pending.keys()]) {
+            if (this.pending.get(id)?.request.sessionId === sessionId)
+                this.settle(id, { behavior: "cancelled" }, "cancelled");
+        }
+    }
+    settle(id, answer, status) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return false;
+        clearTimeout(pending.timeout);
+        if (pending.onAbort)
+            pending.signal?.removeEventListener("abort", pending.onAbort);
+        pending.request.status = status;
+        this.pending.delete(id);
+        pending.resolve(answer);
+        for (const l of this.resolvedListeners)
+            l(pending.request);
+        return true;
+    }
+}
+/**
+ * Defensive shape-check for an AskUserQuestion tool input's `questions` array.
+ * Returns null (rather than throwing or forwarding a partial item) on anything
+ * that doesn't look like a real UserQuestionItem[], so a malformed call degrades
+ * to "let the tool run un-intercepted" instead of reaching QuestionCard (which
+ * has no ErrorBoundary above it) with e.g. a missing `options` array.
+ */
+export function validQuestions(value) {
+    if (!Array.isArray(value) || !value.length)
+        return null;
+    for (const q of value) {
+        if (typeof q?.question !== "string" || typeof q?.header !== "string")
+            return null;
+        if (!Array.isArray(q.options) || q.options.length < 2)
+            return null;
+        for (const opt of q.options) {
+            if (typeof opt?.label !== "string")
+                return null;
+        }
+    }
+    return value;
+}
+/** Case-insensitive match for the AskUserQuestion tool across runtimes. Pi's
+ *  "stealth" naming mirrors Claude Code exactly ("AskUserQuestion"); other
+ *  agents may vary case, so normalize. */
+export function isAskUserQuestionTool(toolName) {
+    return toolName.toLowerCase() === "askuserquestion";
+}
+/**
+ * Format the user's answer into the tool result text handed back to the agent.
+ * The interceptor delivers this through each runtime's block/deny channel (the
+ * only host-supplied-result mechanism both pi and the Claude SDK expose), so it
+ * reads as a plain statement of what the user chose rather than an error.
+ */
+export function formatQuestionResult(questions, answer) {
+    if (answer.behavior === "cancelled") {
+        return "The user dismissed the question(s) without answering. Proceed using your best judgment, or ask again if you truly cannot continue.";
+    }
+    const lines = questions.map((q) => {
+        const a = answer.answers[q.question];
+        return `- ${q.header}: ${a && a.trim() ? a : "(no answer)"}`;
+    });
+    return `The user answered your question(s):\n${lines.join("\n")}`;
+}

package/dist/redact.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Redact credentials from text before it is persisted to disk. Bivy stores
+// session transcripts and tool-activity sidecars as JSON under `.bivy/`, and
+// those files sync to the web/PWA — so any secret an agent happens to print
+// (e.g. a tool running `git remote -v`, which surfaces the token baked into a
+// clone's origin URL) would otherwise land in cleartext in a synced log.
+//
+// Applied at the single persistence choke point (EventLog.flush), so every
+// base-transcript / tool-activity / intermediate-message write is scrubbed. Pattern-
+// based and structure-preserving: it only ever shortens string *values*, so the
+// surrounding JSON stays valid.
+const REDACTED = "***REDACTED***";
+// GitHub tokens in all current shapes:
+//   ghp_ (classic PAT), gho_ (OAuth), ghu_/ghs_ (GitHub App user/installation),
+//   ghr_ (refresh), and github_pat_ (fine-grained PAT).
+const GH_TOKEN = /\bgh[posur]_[A-Za-z0-9]{16,255}\b/g;
+const GH_FINE_PAT = /\bgithub_pat_[A-Za-z0-9_]{20,255}\b/g;
+// The password half of any URL userinfo — `scheme://user:SECRET@host`. Covers
+// the `https://x-access-token:<token>@github.com/...` form Bivy writes into a
+// clone's remote, plus any other basic-auth URL. Keeps the user, masks the rest.
+const URL_CREDENTIAL = /([a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+// Model/provider and common SaaS API keys with distinctive, high-entropy
+// prefixes — the shapes an agent most often prints via `env`/`cat .env`. These
+// prefixes are specific enough that the minimum-length suffix guards keep false
+// positives (redacting innocuous transcript text) negligible.
+//   sk-… / sk-ant-… / sk-proj-…  OpenAI + Anthropic
+//   sk_live_… / sk_test_… / rk_live_… / rk_test_…  Stripe secret + restricted
+//   gsk_…  Groq
+//   xai-…  xAI
+//   AIza…  Google API keys
+//   AKIA…  AWS access key id
+//   xox[baprs]-…  Slack tokens
+const PROVIDER_KEYS = [
+    /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}\b/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+    /\bgsk_[A-Za-z0-9]{20,}\b/g,
+    /\bxai-[A-Za-z0-9]{20,}\b/g,
+    /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+];
+// Bivy's own bearer tokens — all minted as `<prefix>_` + `randomBytes(...).
+// toString("base64url")` (see identity.ts's `mesh_` device tokens and the
+// control-plane's `postgres-store.ts`):
+//   mesh_…  device access token (identity.ts, `.bivy/node.json` creation flow)
+//   enr_…   node enrollment token (relay-setup.ts, written to `.bivy/relay.json`)
+//   sess_…  account session token (the bearer used while enrolling/pairing)
+//   mlt_…   magic-link sign-in token
+//   lnk_…   remote-device link grant
+//   tkt_…   single-use relay ticket
+const BIVY_TOKEN = /\b(?:mesh|enr|sess|mlt|lnk|tkt)_[A-Za-z0-9_-]{20,}\b/g;
+// JWTs (three dot-separated base64url segments, header always decodes to `{"`
+// so it always starts `eyJ`). Covers GitHub App JWTs (server.ts's
+// `createAppJwt`) and any other JWT an agent might print.
+const JWT = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g;
+// Generic `Authorization: Bearer <token>` — catches bearer credentials that
+// don't match one of the specific shapes above (e.g. a third-party bearer an
+// agent echoes while debugging a request). Case-insensitive on the scheme
+// name; keeps "Bearer"/"bearer" as written and only masks the credential.
+const BEARER_HEADER = /\b(bearer\s+)[A-Za-z0-9._-]{16,}\b/gi;
+// Pairing secrets / room keys / private keys: high-entropy string *values*
+// serialized right next to one of Bivy's own known secret-bearing field
+// names (device-registry.ts, pairing-crypto.ts, server.ts's GitHub App vault).
+// These are raw random bytes with no distinctive prefix of their own, so we
+// key off the surrounding JSON field name instead — e.g.
+// `"roomKeyB64":"<...>"` in a synced device-registry / vault write, or the
+// account session forwarded as `"sessionToken":"<...>"` during pairing.
+const KNOWN_SECRET_FIELDS = [
+    "roomKeyB64",
+    "privateKeyB64",
+    "pairSecretB64",
+    "pairSecret",
+    "vaultKeyB64",
+    "deviceSecret",
+    "webhookSecret",
+    "sessionToken",
+    "enrollmentToken",
+    "privateKeyPem",
+];
+const KNOWN_SECRET_FIELD_VALUE = new RegExp(`("(?:${KNOWN_SECRET_FIELDS.join("|")})"\\s*:\\s*")[^"\\\\]*(?:\\\\.[^"\\\\]*)*(")`, "g");
+/** Mask credentials in `text`. Safe on non-string / empty input. */
+export function redactSecrets(text) {
+    if (!text)
+        return text;
+    let out = text
+        .replace(URL_CREDENTIAL, `$1:${REDACTED}@`)
+        .replace(GH_TOKEN, REDACTED)
+        .replace(GH_FINE_PAT, REDACTED)
+        .replace(BIVY_TOKEN, REDACTED)
+        .replace(JWT, REDACTED)
+        .replace(BEARER_HEADER, `$1${REDACTED}`)
+        .replace(KNOWN_SECRET_FIELD_VALUE, `$1${REDACTED}$2`);
+    for (const re of PROVIDER_KEYS)
+        out = out.replace(re, REDACTED);
+    return out;
+}

package/dist/relay-attach.js

@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Relay-tunnelled attach bridge for `bivy run --node <account-node>`.
+//
+// Bivy has no node↔node link; a node reaches a sibling it co-owns exactly the
+// way a phone reaches a node — as a CLIENT in the sibling's relay room. This
+// process is that client. It:
+//
+//   1. Mints a client-scoped grant for the target node from THIS node's
+//      enrollment token   (POST /node/sibling-link-grant),
+//   2. Exchanges it for a single-use relay ticket
+//      (POST /client/relay-ticket),
+//   3. Opens the relay `/client` socket in the target's room, and
+//   4. Pairs with `pair.account` to recover the target's rotating room key.
+//
+// After pairing it stands up a LOOPBACK WebSocket server that speaks the node's
+// plain `/ws` protocol, and spawns the ordinary `attach` client against it. The
+// two ends share ONE identical `terminal.*` message vocabulary — the only
+// difference between a local `/ws` and the relay is the encrypted frame
+// envelope — so the bridge is a pure translation layer and `attach` needs no
+// relay awareness:
+//
+//   attach → local /ws  (bare terminal.* command JSON)
+//          → seal + chunk → relay frames → target node
+//   target node → relay frames → open + reassemble
+//          → bare terminal.* event JSON → local /ws → attach
+//
+// The crypto + framing are the already-unit-tested node core
+// (relay-cli-crypto.ts + relay-chunk.ts); the credential handshake mirrors
+// SiblingClient (src/session/sibling-client.ts).
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { WebSocket, WebSocketServer } from "ws";
+import { newDeviceKeypair, acceptWelcome, RoomCipher } from "./relay-cli-crypto.js";
+import { frameMessages, FrameReassembler } from "./relay-chunk.js";
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[22m`,
+    red: (s) => `\x1b[31m${s}\x1b[39m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[39m`,
+};
+// All progress goes to STDERR: once `attach` binds the PTY it owns stdout in raw
+// mode, so anything we print there would corrupt the terminal.
+const note = (s) => process.stderr.write(s + "\n");
+function parseArgs(argv) {
+    const get = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : undefined;
+    };
+    const nodeId = get("--node-id");
+    const relayConfigPath = get("--relay-config");
+    const attachCmdRaw = get("--attach-cmd");
+    if (!nodeId || !relayConfigPath || !attachCmdRaw) {
+        note("relay-attach: missing --node-id / --relay-config / --attach-cmd");
+        process.exit(2);
+    }
+    let attachCmd;
+    try {
+        attachCmd = JSON.parse(attachCmdRaw);
+        if (!Array.isArray(attachCmd))
+            throw new Error("not an array");
+    }
+    catch {
+        note("relay-attach: --attach-cmd must be a JSON array");
+        process.exit(2);
+    }
+    return {
+        nodeId: nodeId,
+        nodeName: get("--node-name") || nodeId,
+        relayConfigPath: relayConfigPath,
+        attachCmd,
+        run: get("--run"),
+        attachTermId: get("--attach"),
+        label: get("--label") || "Bivy CLI (run --node)",
+    };
+}
+function loadRelay(relayConfigPath) {
+    let raw = {};
+    try {
+        raw = JSON.parse(fs.readFileSync(relayConfigPath, "utf8"));
+    }
+    catch {
+        /* handled below */
+    }
+    const controlPlaneUrl = process.env.BIVY_CONTROL_PLANE_URL || raw.controlPlaneUrl;
+    const enrollmentToken = process.env.BIVY_RELAY_TOKEN || raw.enrollmentToken;
+    if (!controlPlaneUrl || !enrollmentToken) {
+        note(c.red("relay-attach: relay is not configured (missing controlPlaneUrl/enrollmentToken). Run 'bivy relay:setup'."));
+        process.exit(1);
+    }
+    return { controlPlaneUrl, enrollmentToken, url: process.env.BIVY_RELAY_URL || raw.url };
+}
+// Reuse ONE client device identity across runs so we don't spam the target
+// node's device list with a fresh pairing on every `bivy run --node`.
+function loadOrCreateDeviceKeypair(relayConfigPath) {
+    const file = path.join(path.dirname(relayConfigPath), "relay-cli-device.json");
+    try {
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (data?.publicKeyB64 && data?.privateKeyB64)
+            return data;
+    }
+    catch {
+        /* create below */
+    }
+    const kp = newDeviceKeypair();
+    try {
+        fs.writeFileSync(file, JSON.stringify(kp), { mode: 0o600 });
+    }
+    catch {
+        /* non-fatal: fall back to an ephemeral identity */
+    }
+    return kp;
+}
+async function postJson(url, bearer, body) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${bearer}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok)
+        throw new Error(`${url} → ${res.status} ${String(data.error || text).slice(0, 160)}`);
+    return data;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const relay = loadRelay(args.relayConfigPath);
+    const cp = relay.controlPlaneUrl.replace(/\/$/, "");
+    const keypair = loadOrCreateDeviceKeypair(args.relayConfigPath);
+    // 1. grant (enrollment-scoped) → 2. single-use relay ticket.
+    note(c.dim(`Linking to ${c.cyan(args.nodeName)} over the relay…`));
+    const grantRes = await postJson(`${cp}/node/sibling-link-grant`, relay.enrollmentToken, { nodeId: args.nodeId });
+    const grant = String(grantRes.grant ?? "");
+    if (!grant)
+        throw new Error("sibling-link-grant returned no grant");
+    const ticketRes = await postJson(`${cp}/client/relay-ticket`, grant, { nodeId: args.nodeId });
+    const ticket = String(ticketRes.ticket ?? "");
+    if (!ticket)
+        throw new Error("relay-ticket returned no ticket");
+    const relayBase = String((typeof ticketRes.relayUrl === "string" && ticketRes.relayUrl) ||
+        (typeof grantRes.relayUrl === "string" && grantRes.relayUrl) ||
+        relay.url ||
+        "").replace(/\/$/, "");
+    if (!relayBase)
+        throw new Error("no relay URL available for the target node");
+    // 3. open the relay /client socket in the target's room and pair.
+    const rly = new WebSocket(`${relayBase}/client?ticket=${encodeURIComponent(ticket)}&nodeId=${encodeURIComponent(args.nodeId)}`);
+    const reassembler = new FrameReassembler();
+    let cipher = null;
+    let local = null;
+    let paired = false;
+    let pairSent = false;
+    const fail = (message, code = 1) => {
+        note(c.red(`\n${message}`));
+        try {
+            rly.close();
+        }
+        catch {
+            /* ignore */
+        }
+        process.exit(code);
+    };
+    const pairTimer = setTimeout(() => {
+        if (!paired)
+            fail(`Node "${args.nodeName}" did not respond to pairing — it may be offline.`, 1);
+    }, 20_000);
+    pairTimer.unref?.();
+    const sendPair = () => {
+        if (pairSent)
+            return;
+        pairSent = true;
+        rly.send(JSON.stringify({
+            t: "pair",
+            // `ephemeral`: this is a transient CLI bridge, not a user device — the
+            // control plane authorizes it but keeps it out of the account's
+            // "Signed-in devices" list.
+            p: JSON.stringify({ k: "pair.account", sessionToken: grant, devicePublicKeyB64: keypair.publicKeyB64, label: args.label, ephemeral: true }),
+        }));
+    };
+    rly.on("open", () => note(c.dim("Relay connected; pairing…")));
+    rly.on("error", (err) => fail(`Relay connection error: ${err.message}`, 1));
+    rly.on("close", () => {
+        if (!paired)
+            fail("Relay closed before the session was established.", 1);
+        // After pairing, a relay drop ends the remote session bridge; let the child exit.
+        try {
+            local?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    rly.on("message", (data) => {
+        let msg;
+        try {
+            msg = JSON.parse(String(data));
+        }
+        catch {
+            return;
+        }
+        if (msg.t === "ready" || msg.t === "peer.online") {
+            sendPair();
+            return;
+        }
+        if (msg.t === "peer.offline") {
+            if (!paired)
+                fail(`Node "${args.nodeName}" is offline.`, 1);
+            return;
+        }
+        if (msg.t === "error") {
+            fail(`Relay error: ${String(msg.message || msg.p || "unknown")}`, 1);
+            return;
+        }
+        if (msg.t === "pair") {
+            let p;
+            try {
+                p = JSON.parse(String(msg.p));
+            }
+            catch {
+                return;
+            }
+            if (p.k === "pair.welcome") {
+                try {
+                    const roomKey = acceptWelcome(keypair, { nodePublicKeyB64: String(p.nodePublicKeyB64), wrapped: String(p.wrapped) });
+                    cipher = new RoomCipher(roomKey);
+                    paired = true;
+                    clearTimeout(pairTimer);
+                    startBridge();
+                }
+                catch (err) {
+                    fail(`Pairing failed: ${err.message}`, 1);
+                }
+            }
+            else if (p.k === "pair.error") {
+                fail(`Pairing rejected by ${args.nodeName}: ${p.error || "unknown reason"}`, 1);
+            }
+            return;
+        }
+        if (msg.t === "frame" && typeof msg.p === "string" && cipher) {
+            const full = reassembler.accept(msg);
+            if (!full)
+                return;
+            let event;
+            try {
+                event = cipher.open(full).data;
+            }
+            catch {
+                return; // undecryptable frame — ignore
+            }
+            // Forward the bare terminal.* event to the local attach socket verbatim.
+            if (local && local.readyState === WebSocket.OPEN)
+                local.send(JSON.stringify(event));
+        }
+    });
+    // Stand up the loopback /ws server + spawn attach, only once paired.
+    function startBridge() {
+        const wss = new WebSocketServer({ host: "127.0.0.1", port: 0, path: "/ws" });
+        wss.on("connection", (sock) => {
+            // A single attach client owns the bridge. Reject extras.
+            if (local) {
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            local = sock;
+            sock.on("message", (data) => {
+                if (!cipher)
+                    return;
+                let command;
+                try {
+                    command = JSON.parse(String(data));
+                }
+                catch {
+                    return;
+                }
+                try {
+                    for (const frame of frameMessages(cipher.seal(command))) {
+                        if (rly.readyState === WebSocket.OPEN)
+                            rly.send(frame);
+                    }
+                }
+                catch {
+                    /* seal/send failure — the relay close handler will surface it */
+                }
+            });
+            sock.on("close", () => {
+                // attach detached or the remote session ended; tear down.
+                try {
+                    rly.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+        });
+        wss.on("listening", () => {
+            const addr = wss.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            const localUrl = `http://127.0.0.1:${port}`;
+            const childArgs = [
+                ...args.attachCmd,
+                "--url",
+                localUrl,
+                ...(args.run ? ["--run", args.run] : []),
+                ...(args.attachTermId ? ["--attach", args.attachTermId] : []),
+            ];
+            note(c.dim(`Paired ✓  starting session on ${c.cyan(args.nodeName)}\n`));
+            const child = spawn(process.execPath, childArgs, { stdio: "inherit", env: process.env });
+            child.on("exit", (code, signal) => {
+                try {
+                    rly.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                try {
+                    wss.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                process.exit(signal ? 1 : code ?? 0);
+            });
+            child.on("error", (err) => fail(`Could not start the attach client: ${err.message}`, 1));
+        });
+        wss.on("error", (err) => fail(`Local bridge error: ${err.message}`, 1));
+    }
+}
+main().catch((err) => {
+    note(c.red(`relay-attach: ${err?.message || String(err)}`));
+    process.exit(1);
+});

package/dist/relay-chunk.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { randomBytes } from "node:crypto";
+import { FRAME_CHUNK_BYTES, MAX_REASSEMBLY_BYTES, MAX_FRAME_CHUNKS, MAX_REASSEMBLY_GROUPS, } from "./wire-format.js";
+// Re-exported so existing importers keep using `./relay-chunk.js`; the value
+// itself is owned by the shared wire-format spec.
+export { FRAME_CHUNK_BYTES };
+/**
+ * Turn a sealed payload string into one or more wire messages (JSON strings).
+ * Returns a single `{ t: "frame", p }` for small payloads, or an ordered list of
+ * chunk messages for large ones.
+ */
+export function frameMessages(payload) {
+    if (payload.length <= FRAME_CHUNK_BYTES) {
+        return [JSON.stringify({ t: "frame", p: payload })];
+    }
+    const id = randomBytes(8).toString("hex");
+    const total = Math.ceil(payload.length / FRAME_CHUNK_BYTES);
+    const out = [];
+    for (let i = 0; i < total; i++) {
+        const slice = payload.slice(i * FRAME_CHUNK_BYTES, (i + 1) * FRAME_CHUNK_BYTES);
+        out.push(JSON.stringify({ t: "frame", p: slice, fc: id, fi: i, fn: total }));
+    }
+    return out;
+}
+/**
+ * Buffers inbound frame chunks and yields the full payload once a group is
+ * complete. A non-chunked frame passes straight through.
+ */
+export class FrameReassembler {
+    groups = new Map();
+    /**
+     * Feed one inbound frame envelope. Returns the reassembled payload string when
+     * complete (or the payload itself when the frame was not chunked), or null
+     * while more chunks are still outstanding / the frame was invalid.
+     */
+    accept(env) {
+        if (typeof env.p !== "string")
+            return null;
+        if (env.fc === undefined)
+            return env.p; // not chunked
+        const id = String(env.fc);
+        const index = Number(env.fi);
+        const total = Number(env.fn);
+        if (!Number.isInteger(index) || !Number.isInteger(total) || total <= 0 || total > MAX_FRAME_CHUNKS || index < 0 || index >= total) {
+            return null;
+        }
+        let group = this.groups.get(id);
+        if (!group) {
+            // Bound concurrent groups; evict the oldest (insertion order) if needed.
+            if (this.groups.size >= MAX_REASSEMBLY_GROUPS) {
+                const oldest = this.groups.keys().next().value;
+                if (oldest !== undefined)
+                    this.groups.delete(oldest);
+            }
+            group = { total, parts: new Array(total), have: 0, bytes: 0 };
+            this.groups.set(id, group);
+        }
+        if (group.parts[index] !== undefined)
+            return null; // duplicate chunk
+        group.parts[index] = env.p;
+        group.have += 1;
+        group.bytes += env.p.length;
+        if (group.bytes > MAX_REASSEMBLY_BYTES) {
+            this.groups.delete(id);
+            return null;
+        }
+        if (group.have < group.total)
+            return null;
+        this.groups.delete(id);
+        return group.parts.join("");
+    }
+}