@starlove/orbit 1.4.1 → 2.0.0

package/lib/client/http.js

@@ -0,0 +1,334 @@
+/**
+ * The OrbitClient over HTTP: `createHttpClient({ baseUrl })` calls an Orbit's
+ * JSON API with any `fetch` (remote agents, the CLI in remote mode, the web
+ * app, the Suite). Each method is one route; a refusal comes back as the
+ * OrbitError the server answered with.
+ *
+ * A command session's board lives here, on the caller's side: the server
+ * forgets between requests, so each command sends the board this client
+ * chose last, and the caller's orbit.json as it reads it.
+ */
+import { ERROR_CODES, OrbitError } from "../core/errors.js";
+import { DOWNLOAD_TYPE, isShownImage } from "../core/image-types.js";
+import { objectUrl } from "./object-url.js";
+function repoFields(repo) {
+    if (!repo)
+        return {};
+    const fields = {};
+    if (repo.board)
+        fields.repo_board = repo.board;
+    if (repo.problem)
+        fields.repo_board_problem = repo.problem;
+    if (repo.problem === "not_slug" && typeof repo.value === "string")
+        fields.repo_board = repo.value;
+    return fields;
+}
+const hintQuery = (hint = {}) => ({ board_id: hint.board_id, board: hint.board });
+export function createHttpClient(options) {
+    const base = options.baseUrl.replace(/\/+$/, "");
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    let sessionBoard = options.board ?? null;
+    async function send(method, path, call = {}) {
+        const url = new URL(`${base}${path}`);
+        for (const [key, value] of Object.entries(call.query ?? {})) {
+            if (value !== undefined && value !== null && value !== "" && value !== false)
+                url.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
+        }
+        const headers = { ...options.headers };
+        let body;
+        if (call.raw) {
+            headers["Content-Type"] = call.raw.type;
+            if (call.raw.name)
+                headers["X-File-Name"] = call.raw.name;
+            body = call.raw.bytes;
+        }
+        else if (call.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(call.body);
+        }
+        const response = await doFetch(url, { method, headers, body });
+        if (!(call.ok ?? [200, 201, 202]).includes(response.status)) {
+            const text = await response.text();
+            let payload = {};
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = { message: text };
+            }
+            const code = typeof payload.error === "string" ? payload.error : "";
+            const message = typeof payload.message === "string" && payload.message ? payload.message : code || `Orbit API ${method} ${url.pathname} failed with HTTP ${response.status}`;
+            if (code in ERROR_CODES)
+                throw new OrbitError(code, { message });
+            throw new Error(message);
+        }
+        return response;
+    }
+    async function request(method, path, call = {}) {
+        const response = await send(method, path, call);
+        const text = await response.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    const id = encodeURIComponent;
+    const get = (path, query) => request("GET", path, query ? { query } : {});
+    const ticket = (ticketId, rest = "") => `/api/tickets/${id(ticketId)}${rest}`;
+    const contextQuery = (opts = {}, hint) => ({
+        ...hintQuery(hint),
+        max_chars_per_field: opts.max_chars_per_field,
+        comment_limit: opts.comment_limit,
+        include_parent_full: opts.include_parent_full ? "true" : undefined,
+        include_related_full: opts.include_related_full ? "true" : undefined
+    });
+    const contentPath = (ticketId, attachmentId) => ticket(ticketId, `/attachments/${id(attachmentId)}/content`);
+    return {
+        health: () => get("/api/health"),
+        version: (opts = {}) => get("/api/version", { refresh: opts.refresh ? "1" : undefined }),
+        update: () => request("POST", "/api/update"),
+        bootstrap: (hint) => get("/api/bootstrap", hintQuery(hint)),
+        sessions: (opts = {}) => get("/api/sessions", { since: opts.since }),
+        async command(input) {
+            const body = {
+                command: input.command,
+                argv: input.argv,
+                text: input.text,
+                json: Boolean(input.json),
+                read_only: Boolean(input.readOnly),
+                board: sessionBoard,
+                transport: input.transport ?? "mcp",
+                ...repoFields(options.repo?.() ?? null)
+            };
+            const reply = await request("POST", "/api/cmd", { body, ok: [200, 422] });
+            if (reply.board)
+                sessionBoard = reply.board;
+            return reply;
+        },
+        search: (hint, q) => get("/api/search", {
+            ...hintQuery(hint),
+            q: q.q,
+            limit: q.limit,
+            mode: q.mode,
+            include_full: q.include_full ? "true" : undefined,
+            fields: Array.isArray(q.fields) ? q.fields.join(",") : q.fields,
+            max_chars_per_field: q.max_chars_per_field
+        }),
+        boards: {
+            list: () => get("/api/boards"),
+            create: (input) => request("POST", "/api/boards", { body: input }),
+            update: (board, patch) => request("PATCH", `/api/boards/${id(board)}`, { body: patch }),
+            remove: (board, input) => request("DELETE", `/api/boards/${id(board)}`, { body: input }),
+            context: (board, opts = {}) => get(`/api/boards/${id(board)}/context`, { include_struck: opts.include_struck ? "true" : undefined }),
+            archive: (board) => get(`/api/boards/${id(board)}/archive`),
+            export: (board, opts = {}) => get(`/api/boards/${id(board)}/export`, { include_attachments: opts.include_attachments ? "true" : undefined }),
+            import: (input) => request("POST", "/api/admin/import", { body: input })
+        },
+        states: {
+            create: (board, input) => request("POST", `/api/boards/${id(board)}/states`, { body: input }),
+            update: (stateId, patch, hint) => request("PATCH", `/api/states/${id(stateId)}`, { body: patch, query: hintQuery(hint) }),
+            reorder: (board, input) => request("PATCH", `/api/boards/${id(board)}/states`, { body: input }),
+            remove: (stateId, hint) => request("DELETE", `/api/states/${id(stateId)}`, { query: hintQuery(hint) })
+        },
+        tickets: {
+            create: (input) => request("POST", "/api/tickets", { body: input }),
+            lookup: (hint, by) => get("/api/tickets/lookup", { ...hintQuery(hint), number: by.number, title: by.title }),
+            read: (ticketId, hint) => get(ticket(ticketId), hintQuery(hint)),
+            update: (ticketId, patch, hint) => request("PATCH", ticket(ticketId), { body: patch, query: hintQuery(hint) }),
+            archive: (ticketId, hint) => request("POST", ticket(ticketId, "/archive"), { query: hintQuery(hint) }),
+            restore: (ticketId, hint) => request("POST", ticket(ticketId, "/restore"), { query: hintQuery(hint) }),
+            remove: (ticketId, hint) => request("DELETE", ticket(ticketId), { query: hintQuery(hint) }),
+            context: (ticketId, opts, hint) => get(ticket(ticketId, "/context"), contextQuery(opts, hint)),
+            contextFull: (ticketId, opts, hint) => get(ticket(ticketId, "/context/full"), contextQuery(opts, hint)),
+            dispatchPacket: (ticketId, opts, hint) => get(ticket(ticketId, "/dispatch-packet"), contextQuery(opts, hint)),
+            history: (ticketId, hint) => get(ticket(ticketId, "/history"), hintQuery(hint)),
+            relations: (ticketId, hint) => get(ticket(ticketId, "/relations"), hintQuery(hint)),
+            blockers: (ticketId, hint) => get(ticket(ticketId, "/blockers"), hintQuery(hint))
+        },
+        comments: {
+            list: (ticketId, hint) => get(ticket(ticketId, "/comments"), hintQuery(hint)),
+            create: (ticketId, input, hint) => request("POST", ticket(ticketId, "/comments"), { body: input, query: hintQuery(hint) }),
+            update: (ticketId, commentId, patch, hint) => request("PATCH", ticket(ticketId, `/comments/${id(commentId)}`), { body: patch, query: hintQuery(hint) })
+        },
+        attachments: {
+            list: (ticketId, hint) => get(ticket(ticketId, "/attachments"), hintQuery(hint)),
+            create: (ticketId, bytes, meta, hint) => {
+                const raw = { bytes, type: meta.mime_type };
+                if (meta.original_name)
+                    raw.name = meta.original_name;
+                return request("POST", ticket(ticketId, "/attachments"), { raw, query: hintQuery(hint) });
+            },
+            async content(ticketId, attachmentId, hint) {
+                const response = await send("GET", contentPath(ticketId, attachmentId), { query: hintQuery(hint) });
+                const mime = response.headers.get("content-type") ?? DOWNLOAD_TYPE;
+                return { bytes: new Uint8Array(await response.arrayBuffer()), mime_type: mime, download_only: !isShownImage(mime), original_name: dispositionName(response.headers.get("content-disposition")) };
+            },
+            async url(ticketId, attachmentId, hint) {
+                if (options.images === "object") {
+                    const response = await send("GET", contentPath(ticketId, attachmentId), { query: hintQuery(hint) });
+                    return objectUrl(new Uint8Array(await response.arrayBuffer()), response.headers.get("content-type") ?? "application/octet-stream");
+                }
+                const url = new URL(`${base}${contentPath(ticketId, attachmentId)}`);
+                for (const [key, value] of Object.entries(hintQuery(hint)))
+                    if (typeof value === "string" && value)
+                        url.searchParams.set(key, value);
+                return { url: url.href, release: () => undefined };
+            },
+            remove: (ticketId, attachmentId, hint) => request("DELETE", ticket(ticketId, `/attachments/${id(attachmentId)}`), { query: hintQuery(hint) })
+        },
+        artifacts: {
+            read: (ticketId, path, hint) => get(ticket(ticketId, "/artifacts/markdown"), { ...hintQuery(hint), path }),
+            write: (ticketId, input, hint) => request("POST", ticket(ticketId, "/artifacts/markdown"), { body: input, query: hintQuery(hint) })
+        },
+        verdicts: {
+            list: (ticketId, opts = {}, hint) => get(ticket(ticketId, "/review-verdicts"), { ...hintQuery(hint), limit: opts.limit }),
+            create: (ticketId, input, hint) => request("POST", ticket(ticketId, "/review-verdicts"), { body: input, query: hintQuery(hint) }),
+            get: (reviewId, hint) => get(`/api/review-verdicts/${id(reviewId)}`, hintQuery(hint))
+        },
+        entries: {
+            create: (board, input) => request("POST", `/api/boards/${id(board)}/entries`, { body: input }),
+            update: (entryId, patch, hint) => request("PATCH", `/api/board-entries/${id(entryId)}`, { body: patch, query: hintQuery(hint) }),
+            remove: (entryId, hint) => request("DELETE", `/api/board-entries/${id(entryId)}`, { query: hintQuery(hint) })
+        },
+        relations: {
+            create: (input) => request("POST", "/api/relations", { body: input }),
+            remove: (relationId, hint) => request("DELETE", `/api/relations/${id(relationId)}`, { query: hintQuery(hint) })
+        },
+        agent: {
+            claimNext: (hint, filters = {}) => request("POST", "/api/agent/claim-next", { body: { ...filters, ...hintQuery(hint) } }),
+            claim: (input) => request("POST", "/api/agent/claim", { body: input }),
+            checkpoint: (input) => request("POST", "/api/agent/checkpoint", { body: input }),
+            complete: (input) => request("POST", "/api/agent/complete", { body: input })
+        },
+        changes(boardId, listener, opts = {}) {
+            const controller = new AbortController();
+            void followChanges({
+                doFetch,
+                url: `${base}/api/events/stream?board_id=${id(boardId)}`,
+                headers: options.headers ?? {},
+                signal: controller.signal,
+                listener,
+                onState: opts.onState ?? (() => undefined),
+                firstMs: options.reconnect?.firstMs ?? 1000,
+                maxMs: options.reconnect?.maxMs ?? 30_000,
+                staleMs: options.staleMs ?? 75_000
+            });
+            return () => {
+                controller.abort();
+            };
+        }
+    };
+}
+/** Resolves after `ms`, or at once when `signal` aborts. */
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        signal.addEventListener("abort", done);
+    });
+}
+/**
+ * Follows a board's server-sent event stream until aborted: each change to
+ * `listener`, in order. When the stream drops it waits (1 s, doubling to
+ * 30 s) and reconnects with `Last-Event-ID`, so the server replays what was
+ * missed. Its state goes to `onState`: connecting, then live, then down
+ * while it is lost (and retrying), live again once back. A board that is
+ * gone (404) ends it, down.
+ */
+async function followChanges(f) {
+    let lastId = null;
+    let delay = f.firstMs;
+    let state = null;
+    const report = (next) => {
+        if (next === state || f.signal.aborted)
+            return;
+        state = next;
+        f.onState(next);
+    };
+    const aborted = () => f.signal.aborted;
+    report("connecting");
+    while (!aborted()) {
+        const attempt = new AbortController();
+        const stop = () => {
+            attempt.abort();
+        };
+        f.signal.addEventListener("abort", stop);
+        const quiet = { timer: null };
+        const watchdog = () => {
+            if (quiet.timer)
+                clearTimeout(quiet.timer);
+            quiet.timer = setTimeout(stop, f.staleMs);
+        };
+        try {
+            const headers = { ...f.headers, Accept: "text/event-stream" };
+            if (lastId)
+                headers["Last-Event-ID"] = lastId;
+            watchdog();
+            const response = await f.doFetch(f.url, { headers, signal: attempt.signal });
+            if (response.status === 404) {
+                report("down");
+                return;
+            }
+            if (!response.ok || !response.body)
+                throw new Error(`event stream answered ${response.status}`);
+            report("live");
+            delay = f.firstMs;
+            const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+            let buffer = "";
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                watchdog();
+                buffer += value;
+                let end;
+                while ((end = buffer.indexOf("\n\n")) >= 0) {
+                    const frame = buffer.slice(0, end);
+                    buffer = buffer.slice(end + 2);
+                    let data = "";
+                    let frameId = null;
+                    for (const line of frame.split("\n")) {
+                        if (line.startsWith("data: "))
+                            data += (data ? "\n" : "") + line.slice(6);
+                        else if (line.startsWith("id: "))
+                            frameId = line.slice(4);
+                    }
+                    if (!data)
+                        continue;
+                    if (frameId)
+                        lastId = frameId;
+                    f.listener(JSON.parse(data));
+                }
+            }
+        }
+        catch {
+            // Dropped, refused or gone quiet: wait, then reconnect.
+        }
+        finally {
+            if (quiet.timer)
+                clearTimeout(quiet.timer);
+            f.signal.removeEventListener("abort", stop);
+        }
+        if (aborted())
+            return;
+        report("down");
+        await pause(delay, f.signal);
+        delay = Math.min(delay * 2, f.maxMs);
+    }
+}
+/** The file name a `Content-Disposition` gives (its UTF-8 form first), or "". */
+function dispositionName(value) {
+    if (!value)
+        return "";
+    const utf8 = /filename\*=UTF-8''([^;]+)/i.exec(value);
+    if (utf8?.[1]) {
+        try {
+            return decodeURIComponent(utf8[1]);
+        }
+        catch {
+            // Fall back to the plain name.
+        }
+    }
+    return /filename="([^"]*)"/i.exec(value)?.[1] ?? "";
+}

package/lib/client/local.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The in-process OrbitClient: every use case, acting as one actor, in this
+ * process (the CLI, `orbit mcp` on a computer, the HTTP app's routes). Each
+ * method finds its board the way the JSON API always has: a route naming a
+ * board uses it; a record named by id is looked for on the hinted board
+ * first, then on the others; a route that needs a board and gets no hint is
+ * refused with `board_id_required`.
+ */
+import type { Ctx } from "../core/context.ts";
+import type { Id } from "../core/model.ts";
+import type { RepoSource, Transport } from "../commands/index.ts";
+import type { HostServices, OrbitClient } from "./types.ts";
+export interface LocalClientOptions {
+    transport?: Transport;
+    /** A command over HTTP to an Orbit others use. */
+    shared?: boolean;
+    /** The board the command session starts on (ORBIT_BOARD). */
+    board?: string | null;
+    /** Where the caller's orbit.json comes from. */
+    repo?: RepoSource | null;
+    /** Every board's committed changes, from any process. */
+    watch: (boardId: Id, listener: Parameters<OrbitClient["changes"]>[1]) => () => void;
+    /** What the computer can do: the version check, self-update. */
+    host?: HostServices;
+}
+export declare function createLocalClient(c: Ctx, options: LocalClientOptions): OrbitClient;

package/lib/client/local.js

@@ -0,0 +1,190 @@
+/**
+ * The in-process OrbitClient: every use case, acting as one actor, in this
+ * process (the CLI, `orbit mcp` on a computer, the HTTP app's routes). Each
+ * method finds its board the way the JSON API always has: a route naming a
+ * board uses it; a record named by id is looked for on the hinted board
+ * first, then on the others; a route that needs a board and gets no hint is
+ * refused with `board_id_required`.
+ */
+import { checkpointTicket, claimNext, claimTicket, completeTicket, contextPack, dispatchPacket, readComments, readTicket } from "../core/agent.js";
+import { archivedTickets, boardManual, createBoard, createEntry, deleteBoard, deleteEntry, listBoards, strikeEntry, updateBoard } from "../core/boards.js";
+import { bootstrap } from "../core/bootstrap.js";
+import { boardFromHints, boardHolding, onBoard } from "../core/context.js";
+import { OrbitError } from "../core/errors.js";
+import { attachmentContent, createAttachment, deleteAttachment, listAttachments, readArtifact, writeArtifact } from "../core/files.js";
+import { createRelation, deleteRelation, ticketBlockers, ticketRelations } from "../core/relations.js";
+import { boardHoldingCrossLink, linkAcrossBoards, unlinkAcrossBoards } from "../core/cross-board.js";
+import { searchTickets } from "../core/search.js";
+import { listSessions } from "../core/sessions.js";
+import { importAsNewBoard, importReplacing, exportBoard, refuseAgentReplace } from "../core/snapshots.js";
+import { createState, deleteState, reorderStates, updateState } from "../core/states.js";
+import { asText } from "../core/text.js";
+import { archiveTicket, createComment, createTicket, deleteTicket, restoreTicket, setCommentHidden, ticketHistory, updateTicket } from "../core/tickets.js";
+import { createVerdict, getVerdict, listVerdicts } from "../core/verdicts.js";
+import { objectUrl } from "./object-url.js";
+export function createLocalClient(c, options) {
+    // The command language loads with the first command, so a host that never runs one (the browser edition) never loads it.
+    const commands = () => import("../commands/index.js");
+    let session = null;
+    const commandSession = () => (session ??= commands().then(({ createSession }) => createSession(c, { transport: options.transport ?? "mcp", shared: options.shared ?? false, board: options.board ?? null, repo: options.repo ?? null })));
+    const hinted = (hint) => boardFromHints(c, hint?.board_id, hint?.board);
+    /** The board a route needs: the hinted one, else `board_id_required`. */
+    async function required(hint) {
+        const row = await hinted(hint);
+        if (!row)
+            throw new OrbitError("board_id_required");
+        return onBoard(c, row);
+    }
+    /** The board a path names by id or slug, marked as used (the app opens it). */
+    /** A board as the list has it, by id or slug, without opening its data. */
+    async function listed(ident) {
+        const row = (await c.store.boards.get(ident)) ?? (await c.store.boards.bySlug(ident));
+        if (!row)
+            throw new OrbitError("board_not_found");
+        return row;
+    }
+    async function named(ident, touch = true) {
+        const row = await listed(ident);
+        if (touch)
+            await c.store.boards.touch(row.id, c.clock.now());
+        return onBoard(c, row);
+    }
+    const ticketBoard = async (id, hint) => boardHolding(c, "ticket", id, await hinted(hint), "ticket_not_found");
+    /** The hinted board, else the board holding `ticketId`, else `board_id_required`. */
+    async function hintedOrHolding(hint, ticketId) {
+        const row = await hinted(hint);
+        if (row)
+            return onBoard(c, row);
+        const id = asText(ticketId);
+        if (id)
+            return boardHolding(c, "ticket", id, null, "ticket_not_found");
+        throw new OrbitError("board_id_required");
+    }
+    const hintOf = (input) => ({ board: input.board ?? null, board_id: input.board_id ?? null });
+    return {
+        health: () => Promise.resolve({ ok: true }),
+        async version(opts = {}) {
+            const check = options.host?.version;
+            if (!check)
+                throw new OrbitError("not_found");
+            return check({ force: Boolean(opts.refresh) });
+        },
+        update() {
+            const started = options.host?.selfUpdate?.() ?? null;
+            return started ? Promise.resolve(started) : Promise.reject(new OrbitError("not_found"));
+        },
+        bootstrap: (hint = {}) => bootstrap(c, { board_id: hint.board_id ?? null, board: hint.board ?? null }),
+        sessions: (opts = {}) => listSessions(c, opts),
+        command: async (input) => {
+            const [s, { runCommand }] = await Promise.all([commandSession(), commands()]);
+            if (input.transport)
+                s.transport = input.transport;
+            return runCommand(input, s);
+        },
+        search: async (hint, query) => searchTickets(await required(hint), query),
+        boards: {
+            list: () => listBoards(c),
+            create: (input) => createBoard(c, input),
+            update: async (board, patch) => updateBoard(await named(board), patch),
+            // Without opening its data: a board whose file is gone can still be deleted.
+            remove: async (board, input) => deleteBoard(c, await listed(board), input),
+            context: async (board, opts = {}) => boardManual(await named(board), { includeStruck: Boolean(opts.include_struck) }),
+            archive: async (board) => ({ tickets: await archivedTickets(await named(board)) }),
+            export: async (board, opts = {}) => exportBoard(await named(board), { includeAttachments: Boolean(opts.include_attachments) }),
+            import: async (input) => {
+                // First, so an agent asking to replace is told so before its board is looked up, whatever else it asks.
+                refuseAgentReplace(c, input);
+                if (input.create_new)
+                    return importAsNewBoard(c, input);
+                return importReplacing(await required(hintOf(input)), input);
+            }
+        },
+        states: {
+            create: async (board, input) => createState(await named(board), input),
+            update: async (id, patch, hint) => updateState(await boardHolding(c, "state", id, await hinted(hint), "state_not_found"), id, patch),
+            reorder: async (board, input) => reorderStates(await named(board), input),
+            remove: async (id, hint) => deleteState(await boardHolding(c, "state", id, await hinted(hint), "state_not_found"), id)
+        },
+        tickets: {
+            create: async (input) => createTicket(await required(hintOf(input)), input),
+            lookup: async (hint, by) => {
+                const lookup = {};
+                if (by.number !== undefined && by.number !== null)
+                    lookup.number = by.number;
+                if (by.title !== undefined && by.title !== null)
+                    lookup.title = by.title;
+                return readTicket(await required(hint), lookup);
+            },
+            read: async (id, hint) => readTicket(await ticketBoard(id, hint), { ticket_id: id }),
+            update: async (id, patch, hint) => updateTicket(await ticketBoard(id, hint), id, patch),
+            archive: async (id, hint) => archiveTicket(await ticketBoard(id, hint), id),
+            restore: async (id, hint) => restoreTicket(await ticketBoard(id, hint), id),
+            remove: async (id, hint) => deleteTicket(await ticketBoard(id, hint), id),
+            context: async (id, opts = {}, hint) => contextPack(await ticketBoard(id, hint), id, opts),
+            contextFull: async (id, opts = {}, hint) => contextPack(await ticketBoard(id, hint), id, opts, true),
+            dispatchPacket: async (id, opts = {}, hint) => dispatchPacket(await ticketBoard(id, hint), id, opts),
+            history: async (id, hint) => ticketHistory(await ticketBoard(id, hint), id),
+            relations: async (id, hint) => ticketRelations(await ticketBoard(id, hint), id),
+            blockers: async (id, hint) => ticketBlockers(await ticketBoard(id, hint), id)
+        },
+        comments: {
+            list: async (ticketId, hint) => readComments(await ticketBoard(ticketId, hint), { ticket_id: ticketId }),
+            create: async (ticketId, input, hint) => createComment(await ticketBoard(ticketId, hint), ticketId, input),
+            update: async (ticketId, commentId, patch, hint) => setCommentHidden(await ticketBoard(ticketId, hint), ticketId, commentId, patch)
+        },
+        attachments: {
+            list: async (ticketId, hint) => listAttachments(await ticketBoard(ticketId, hint), ticketId),
+            create: async (ticketId, bytes, meta, hint) => createAttachment(await ticketBoard(ticketId, hint), ticketId, { bytes, mime_type: meta.mime_type, original_name: meta.original_name }),
+            content: async (ticketId, attachmentId, hint) => attachmentContent(await ticketBoard(ticketId, hint), ticketId, attachmentId),
+            url: async (ticketId, attachmentId, hint) => {
+                const file = await attachmentContent(await ticketBoard(ticketId, hint), ticketId, attachmentId);
+                return objectUrl(file.bytes, file.mime_type);
+            },
+            remove: async (ticketId, attachmentId, hint) => deleteAttachment(await ticketBoard(ticketId, hint), ticketId, attachmentId)
+        },
+        artifacts: {
+            read: async (ticketId, path, hint) => readArtifact(await ticketBoard(ticketId, hint), ticketId, path),
+            write: async (ticketId, input, hint) => writeArtifact(await ticketBoard(ticketId, hint), ticketId, input)
+        },
+        verdicts: {
+            list: async (ticketId, opts = {}, hint) => ({ review_verdicts: await listVerdicts(await ticketBoard(ticketId, hint), ticketId, opts) }),
+            create: async (ticketId, input, hint) => createVerdict(await ticketBoard(ticketId, hint), ticketId, input),
+            get: async (id, hint) => getVerdict(await required(hint), id)
+        },
+        entries: {
+            create: async (board, input) => createEntry(await named(board), input),
+            update: async (id, patch, hint) => strikeEntry(await boardHolding(c, "entry", id, await hinted(hint), "board_entry_not_found"), id, patch),
+            remove: async (id, hint) => deleteEntry(await boardHolding(c, "entry", id, await hinted(hint), "board_entry_not_found"), id)
+        },
+        relations: {
+            create: async (input) => {
+                const from = await hintedOrHolding(hintOf(input), input.source_ticket_id);
+                const other = typeof input.target_board === "string" && input.target_board ? await listed(input.target_board) : null;
+                if (!other || other.id === from.board.id)
+                    return createRelation(from, input);
+                return linkAcrossBoards(c, from, asText(input.source_ticket_id), await onBoard(c, other), asText(input.target_ticket_id), input.type);
+            },
+            remove: async (id, hint) => {
+                const board = await hinted(hint);
+                // A link on one board, else one across boards (each lives on one board).
+                const holder = (await c.store.locate("relation", id, board?.id)) ?? null;
+                if (holder)
+                    return deleteRelation(await onBoard(c, holder), id);
+                const crossHolder = await boardHoldingCrossLink(c, id, board);
+                if (!crossHolder)
+                    throw new OrbitError("relation_not_found");
+                return unlinkAcrossBoards(await onBoard(c, crossHolder), id);
+            }
+        },
+        agent: {
+            claimNext: async (hint, filters = {}) => claimNext(await required(hint), filters),
+            claim: async (input) => claimTicket(await hintedOrHolding(hintOf(input), input.ticket_id), input),
+            checkpoint: async (input) => checkpointTicket(await hintedOrHolding(hintOf(input), input.ticket_id), input),
+            complete: async (input) => completeTicket(await hintedOrHolding(hintOf(input), input.ticket_id), input)
+        },
+        changes: (boardId, listener, opts = {}) => {
+            opts.onState?.("live");
+            return options.watch(boardId, listener);
+        }
+    };
+}

package/lib/client/object-url.d.ts

@@ -0,0 +1,8 @@
+import type { ImageUrl } from "./types.ts";
+/**
+ * Bytes as an object URL, which `release()` revokes (once). A `blob:` URL
+ * runs in the page's own origin, so only a type Orbit shows as an image keeps
+ * its type; anything else (an SVG, which can carry script) becomes bytes to
+ * download, which a browser never renders as a page.
+ */
+export declare function objectUrl(bytes: Uint8Array, type: string): ImageUrl;

package/lib/client/object-url.js

@@ -0,0 +1,21 @@
+import { DOWNLOAD_TYPE, isShownImage } from "../core/image-types.js";
+/**
+ * Bytes as an object URL, which `release()` revokes (once). A `blob:` URL
+ * runs in the page's own origin, so only a type Orbit shows as an image keeps
+ * its type; anything else (an SVG, which can carry script) becomes bytes to
+ * download, which a browser never renders as a page.
+ */
+export function objectUrl(bytes, type) {
+    const safe = isShownImage((type.split(";")[0] ?? "").trim().toLowerCase()) ? type : DOWNLOAD_TYPE;
+    const url = URL.createObjectURL(new Blob([bytes], { type: safe }));
+    let released = false;
+    return {
+        url,
+        release() {
+            if (released)
+                return;
+            released = true;
+            URL.revokeObjectURL(url);
+        }
+    };
+}