@starlove/orbit 1.4.1 → 2.0.0

package/lib/http/app.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Orbit's JSON API and its pages as one `fetch` handler, Hono inside:
+ * `createOrbitApp(orbit, { resolveActor, assets })`. `orbit run` serves it
+ * through @hono/node-server; a host can mount it anywhere `fetch` runs.
+ *
+ * Every request finds its own actor and board from the request itself; no
+ * "active board" is shared between requests. The API has no accounts, so
+ * whoever reaches it acts as the owner unless the headers say an agent: the
+ * guard refuses what a browser marks as coming from another site, and a page
+ * is never framed by another.
+ */
+import type { Actor } from "../core/model.ts";
+import type { Orbit } from "../orbit.ts";
+export declare const MAX_JSON_BODY_BYTES: number;
+export interface OrbitAppOptions {
+    /** Who a request acts as. Default: the owner, or the agent its headers name. */
+    resolveActor?: (request: Request) => Actor;
+    /** The app's files: a response for a page or asset, or null for none. */
+    assets?: (request: Request, pathname: string) => Promise<Response | null>;
+    /** The package's version, for /llms.txt. */
+    version?: string;
+    /** One line per expected refusal (a 4xx) and per fault. */
+    log?: (line: string) => void;
+    /** How often a stream says it's alive, in ms. */
+    heartbeatMs?: number;
+}
+/**
+ * True for a request a browser marks as coming from another site: a
+ * Sec-Fetch-Site other than same-origin or none (same-site too: on a
+ * tailnet, other services share the site), or an Origin naming another host.
+ * Non-browser clients send neither, so they keep working.
+ */
+export declare function isCrossSiteRequest(headers: Headers): boolean;
+/** A Web-standard handler: Request in, Response out, so any host can mount it. */
+export interface OrbitApp {
+    fetch: (request: Request) => Promise<Response>;
+}
+export declare function createOrbitApp(orbit: Orbit, options?: OrbitAppOptions): OrbitApp;
+/**
+ * An attachment's content may be anything a person or an import put on a
+ * card, so it is never a page of Orbit's origin: the browser may not sniff
+ * it into another type, and opened as a document it runs nothing (`sandbox`
+ * gives it an origin of its own). An `<img>` ignores both, so images still
+ * show. A type Orbit won't show (an SVG) comes as a download.
+ */
+export declare const ATTACHMENT_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";

package/lib/http/app.js

@@ -0,0 +1,491 @@
+/**
+ * Orbit's JSON API and its pages as one `fetch` handler, Hono inside:
+ * `createOrbitApp(orbit, { resolveActor, assets })`. `orbit run` serves it
+ * through @hono/node-server; a host can mount it anywhere `fetch` runs.
+ *
+ * Every request finds its own actor and board from the request itself; no
+ * "active board" is shared between requests. The API has no accounts, so
+ * whoever reaches it acts as the owner unless the headers say an agent: the
+ * guard refuses what a browser marks as coming from another site, and a page
+ * is never framed by another.
+ */
+import { Hono } from "hono";
+import { actorFromHeaders, localOwnerActor } from "../core/actors.js";
+import { HTTP_STATUS, OrbitError, isOrbitError } from "../core/errors.js";
+import { DOWNLOAD_TYPE, MAX_IMAGE_BYTES } from "../core/files.js";
+import { changeOf } from "../core/model.js";
+import { asText } from "../core/text.js";
+export const MAX_JSON_BODY_BYTES = 100 * 1024 * 1024;
+const JSON_TYPE = "application/json; charset=utf-8";
+/** JSON as Orbit has always written it: two-space indented. */
+function json(status, body, headers = {}) {
+    return new Response(JSON.stringify(body, null, 2), { status, headers: { "Content-Type": JSON_TYPE, ...headers } });
+}
+const OWN_SITES = new Set(["same-origin", "none"]);
+const firstHost = (value) => (value.split(",")[0] ?? "").trim().toLowerCase();
+/**
+ * True for a request a browser marks as coming from another site: a
+ * Sec-Fetch-Site other than same-origin or none (same-site too: on a
+ * tailnet, other services share the site), or an Origin naming another host.
+ * Non-browser clients send neither, so they keep working.
+ */
+export function isCrossSiteRequest(headers) {
+    const site = (headers.get("sec-fetch-site") ?? "").trim().toLowerCase();
+    if (site)
+        return !OWN_SITES.has(site);
+    const origin = (headers.get("origin") ?? "").trim();
+    if (!origin)
+        return false;
+    let host;
+    try {
+        host = new URL(origin).host.toLowerCase();
+    }
+    catch {
+        return true; // "null" (sandboxed frames, file://) or garbage
+    }
+    // Behind a TLS proxy (tailscale serve) the page's origin names the proxy; a cross-site page can't add X-Forwarded-Host without a preflight, which Orbit never grants.
+    return ![headers.get("host"), headers.get("x-forwarded-host")]
+        .map((value) => (value ?? "").trim())
+        .filter(Boolean)
+        .map(firstHost)
+        .includes(host);
+}
+/** The URL a request reached Orbit at, for the commands /llms.txt suggests. A forwarded scheme or host counts only when it looks like one. */
+function requestOrigin(headers) {
+    const first = (value) => (value ?? "").split(",")[0]?.trim() ?? "";
+    const hostLike = (value) => /^[A-Za-z0-9.-]+(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/.test(value);
+    const forwarded = first(headers.get("x-forwarded-proto")).toLowerCase();
+    const proto = forwarded === "https" || forwarded === "http" ? forwarded : "http";
+    const host = [first(headers.get("x-forwarded-host")), first(headers.get("host"))].find(hostLike) ?? "localhost";
+    return `${proto}://${host}`;
+}
+/** The body's bytes, refused past `max` with `payload_too_large` as they arrive. */
+async function readBytes(request, max) {
+    if (!request.body)
+        return new Uint8Array(0);
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel().catch(() => undefined);
+            throw new OrbitError("payload_too_large");
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return bytes;
+}
+/** The request's JSON: {} when empty, `invalid_json` when unreadable. An array or a value passes through, for the routes that check it. */
+async function readJson(request) {
+    const text = new TextDecoder().decode(await readBytes(request, MAX_JSON_BODY_BYTES));
+    if (!text.trim())
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new OrbitError("invalid_json");
+    }
+}
+async function readObject(request) {
+    const body = await readJson(request);
+    return body && typeof body === "object" && !Array.isArray(body) ? body : {};
+}
+const str = (value) => {
+    const text = asText(value);
+    return text === "" ? null : text;
+};
+export function createOrbitApp(orbit, options = {}) {
+    const app = new Hono();
+    const log = options.log ?? (() => undefined);
+    const resolveActor = options.resolveActor ?? ((request) => actorFromHeaders((name) => request.headers.get(name) ?? undefined));
+    const heartbeatMs = options.heartbeatMs ?? 30_000;
+    const clientFor = (c) => orbit.client(resolveActor(c.req.raw), { transport: "http", shared: true });
+    const query = (c, name) => c.req.query(name) ?? null;
+    const queryHint = (c) => ({ board_id: query(c, "board_id"), board: query(c, "board") });
+    /** A body's board, else the query's. */
+    const bodyHint = (c, body) => ({ board_id: str(body.board_id) ?? query(c, "board_id"), board: str(body.board) ?? query(c, "board") });
+    /** The board holding a record (the hinted board first), or the error that says it's missing. */
+    async function located(c, kind, id, missing) {
+        const store = orbit.context(resolveActor(c.req.raw)).store;
+        const hint = queryHint(c);
+        const hinted = hint.board_id ? await store.boards.get(hint.board_id) : hint.board ? await store.boards.bySlug(hint.board) : null;
+        if ((hint.board_id || hint.board) && !hinted)
+            throw new OrbitError("board_not_found");
+        if (!(await store.locate(kind, id, hinted?.id)))
+            throw new OrbitError(missing);
+    }
+    const contextOptions = (c) => ({
+        max_chars_per_field: query(c, "max_chars_per_field") ?? undefined,
+        comment_limit: query(c, "comment_limit") ?? undefined,
+        include_parent_full: query(c, "include_parent_full") === "true",
+        include_related_full: query(c, "include_related_full") === "true"
+    });
+    app.use("*", async (c, next) => {
+        const path = new URL(c.req.url).pathname;
+        if (path.startsWith("/api/") && isCrossSiteRequest(c.req.raw.headers)) {
+            log(`Orbit: 403 cross_site_request on ${c.req.method} ${path}`);
+            return json(403, { error: "cross_site_request", message: "Orbit's API answers only its own pages and non-browser clients." });
+        }
+        if (c.req.method === "OPTIONS")
+            return new Response(null, { status: 204 });
+        await next();
+        return undefined;
+    });
+    app.onError((error, c) => {
+        const path = new URL(c.req.url).pathname;
+        if (isOrbitError(error)) {
+            const status = HTTP_STATUS[error.kind];
+            if (status < 500)
+                log(`Orbit: ${status} ${error.code} on ${c.req.method} ${path}`);
+            else
+                log(`Orbit: ${status} ${error.code} on ${c.req.method} ${path}${error.cause instanceof Error ? `: ${error.cause.message}` : ""}`);
+            // An internal fault never carries a database's own words.
+            return json(status, { error: error.code, message: error.kind === "internal" ? error.code : error.message });
+        }
+        log(`Orbit: 500 on ${c.req.method} ${path}: ${error.stack ?? error.message}`);
+        return json(500, { error: "internal_error", message: "internal_error" });
+    });
+    app.get("/api/health", () => json(200, { ok: true }));
+    // What the computer can do comes from the host given to createOrbit (HostServices); without it, 404.
+    app.get("/api/version", async (c) => json(200, await clientFor(c).version({ refresh: query(c, "refresh") === "1" })));
+    // Replacing Orbit's own code is the person's call, never an agent's, as with the folder picker.
+    app.post("/api/update", async (c) => {
+        if (resolveActor(c.req.raw).type === "agent")
+            throw new OrbitError("forbidden");
+        return json(202, await clientFor(c).update());
+    });
+    app.get("/api/bootstrap", async (c) => json(200, await clientFor(c).bootstrap(queryHint(c))));
+    app.get("/api/boards", async (c) => json(200, await clientFor(c).boards.list()));
+    app.get("/api/sessions", async (c) => json(200, await clientFor(c).sessions({ since: query(c, "since") ?? undefined })));
+    app.post("/api/cmd", async (c) => {
+        const raw = await readJson(c.req.raw);
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new OrbitError("invalid_body", { message: 'Send a JSON object: { "command": "view", "board": "<slug>", "text": "..." }.' });
+        const body = raw;
+        const transport = body.transport === "cli" || body.transport === "mcp" ? body.transport : "http";
+        // A remote client's repo board (its orbit.json), checked again here; callers that send none are untouched.
+        const { repoBoardFromRequest } = await import("../commands/index.js");
+        const repo = repoBoardFromRequest(body.repo_board, body.repo_board_problem);
+        const board = typeof body.board === "string" && body.board.trim() ? body.board.trim() : null;
+        const client = orbit.client(resolveActor(c.req.raw), { transport, shared: true, board, repo: repo ? { read: () => repo } : null });
+        const input = { json: Boolean(body.json), readOnly: Boolean(body.read_only) };
+        if (Array.isArray(body.argv))
+            input.argv = body.argv.map((word) => asText(word));
+        else
+            input.command = asText(body.command);
+        if (typeof body.text === "string")
+            input.text = body.text;
+        const result = await client.command(input);
+        const reply = { ok: result.ok, text: result.text, board: result.board, kind: result.kind };
+        if (body.json && result.ok)
+            reply.data = result.data;
+        return json(result.ok ? 200 : 422, reply);
+    });
+    // Opens Finder or Explorer on the server's machine, so the person can choose a folder there.
+    // Its answer is a path on that machine, so an agent is refused.
+    app.post("/api/system/pick-folder", async (c) => {
+        if (resolveActor(c.req.raw).type === "agent")
+            throw new OrbitError("forbidden");
+        const result = await orbit.host.pickFolder?.();
+        if (!result || result.unsupported)
+            throw new OrbitError("folder_picker_unavailable");
+        return json(200, result);
+    });
+    app.post("/api/boards", async (c) => json(201, await clientFor(c).boards.create(await readObject(c.req.raw))));
+    const boardRoute = async (c) => {
+        const ident = c.req.param("ident") ?? "";
+        const sub = c.req.param("sub") ?? "";
+        const method = c.req.method;
+        const client = clientFor(c);
+        if (sub === "" && method === "DELETE")
+            return json(200, await client.boards.remove(ident, await readObject(c.req.raw)));
+        if (sub === "" && method === "PATCH")
+            return json(200, await client.boards.update(ident, await readObject(c.req.raw)));
+        if (sub === "context" && method === "GET")
+            return json(200, await client.boards.context(ident, { include_struck: query(c, "include_struck") === "true" }));
+        if (sub === "archive" && method === "GET")
+            return json(200, await client.boards.archive(ident));
+        if (sub === "entries" && method === "POST")
+            return json(201, await client.entries.create(ident, await readObject(c.req.raw)));
+        if (sub === "export" && method === "GET")
+            return json(200, await client.boards.export(ident, { include_attachments: query(c, "include_attachments") === "true" || query(c, "include_images") === "true" }));
+        if (sub === "states" && method === "POST")
+            return json(201, await client.states.create(ident, await readObject(c.req.raw)));
+        if (sub === "states" && method === "PATCH")
+            return json(200, await client.states.reorder(ident, await readObject(c.req.raw)));
+        // No such route: the board is named first, as every route here does.
+        await client.boards.context(ident);
+        return json(404, { error: "not_found" });
+    };
+    app.all("/api/boards/:ident", boardRoute);
+    app.all("/api/boards/:ident/:sub{.+}", boardRoute);
+    app.post("/api/tickets", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(201, await clientFor(c).tickets.create({ ...body, ...bodyHint(c, body) }));
+    });
+    app.get("/api/tickets/lookup", async (c) => {
+        const by = {};
+        if (query(c, "number") !== null)
+            by.number = query(c, "number");
+        if (query(c, "title") !== null)
+            by.title = query(c, "title");
+        return json(200, await clientFor(c).tickets.lookup(queryHint(c), by));
+    });
+    const ticketRoute = async (c) => {
+        const id = c.req.param("id") ?? "";
+        const sub = c.req.param("sub") ?? "";
+        const method = c.req.method;
+        const client = clientFor(c);
+        const hint = queryHint(c);
+        const comment = /^comments\/([^/]+)$/.exec(sub);
+        const content = /^attachments\/([^/]+)\/content$/.exec(sub);
+        const attachment = /^attachments\/([^/]+)$/.exec(sub);
+        if (sub === "" && method === "GET")
+            return json(200, await client.tickets.read(id, hint));
+        if (sub === "" && method === "PATCH")
+            return json(200, await client.tickets.update(id, await readObject(c.req.raw), hint));
+        if (sub === "" && method === "DELETE")
+            return json(200, await client.tickets.remove(id, hint));
+        if (sub === "archive" && method === "POST")
+            return json(200, await client.tickets.archive(id, hint));
+        if (sub === "restore" && method === "POST")
+            return json(200, await client.tickets.restore(id, hint));
+        if (sub === "context" && method === "GET")
+            return json(200, await client.tickets.context(id, contextOptions(c), hint));
+        if (sub === "context/full" && method === "GET")
+            return json(200, await client.tickets.contextFull(id, contextOptions(c), hint));
+        if ((sub === "dispatch-packet" || sub === "agent-dispatch-packet") && method === "GET")
+            return json(200, await client.tickets.dispatchPacket(id, contextOptions(c), hint));
+        if (sub === "history" && method === "GET")
+            return json(200, await client.tickets.history(id, hint));
+        if (sub === "relations" && method === "GET")
+            return json(200, await client.tickets.relations(id, hint));
+        if (sub === "blockers" && method === "GET")
+            return json(200, await client.tickets.blockers(id, hint));
+        if (sub === "comments" && method === "GET")
+            return json(200, await client.comments.list(id, hint));
+        if (sub === "artifacts/markdown" && method === "GET")
+            return json(200, await client.artifacts.read(id, query(c, "path") ?? "", hint));
+        if (sub === "artifacts/markdown" && method === "POST")
+            return json(201, await client.artifacts.write(id, await readObject(c.req.raw), hint));
+        if (sub === "comments" && method === "POST")
+            return json(201, await client.comments.create(id, await readObject(c.req.raw), hint));
+        if (comment?.[1] && method === "PATCH")
+            return json(200, await client.comments.update(id, decodeURIComponent(comment[1]), await readObject(c.req.raw), hint));
+        if (sub === "review-verdicts" && method === "GET")
+            return json(200, await client.verdicts.list(id, { limit: query(c, "limit") }, hint));
+        if (sub === "review-verdicts" && method === "POST")
+            return json(201, await client.verdicts.create(id, await readObject(c.req.raw), hint));
+        if (sub === "attachments" && method === "GET")
+            return json(200, await client.attachments.list(id, hint));
+        if (sub === "attachments" && method === "POST") {
+            const bytes = await readBytes(c.req.raw, MAX_IMAGE_BYTES);
+            const name = c.req.header("x-file-name") || query(c, "filename") || "image";
+            return json(201, await client.attachments.create(id, bytes, { mime_type: c.req.header("content-type") ?? "", original_name: name }, hint));
+        }
+        if (content?.[1] && method === "GET") {
+            const file = await client.attachments.content(id, decodeURIComponent(content[1]), hint);
+            return new Response(file.bytes, { status: 200, headers: attachmentHeaders(file) });
+        }
+        if (attachment?.[1] && method === "DELETE")
+            return json(200, await client.attachments.remove(id, decodeURIComponent(attachment[1]), hint));
+        // No such route: the card is found first, as every route here does.
+        await located(c, "ticket", id, "ticket_not_found");
+        return json(404, { error: "not_found" });
+    };
+    app.all("/api/tickets/:id", ticketRoute);
+    app.all("/api/tickets/:id/:sub{.+}", ticketRoute);
+    app.get("/api/review-verdicts/:id", async (c) => json(200, await clientFor(c).verdicts.get(c.req.param("id"), requiredHint(queryHint(c)))));
+    app.all("/api/states/:id", async (c) => {
+        const client = clientFor(c);
+        const id = c.req.param("id");
+        if (c.req.method === "PATCH")
+            return json(200, await client.states.update(id, await readObject(c.req.raw), queryHint(c)));
+        if (c.req.method === "DELETE")
+            return json(200, await client.states.remove(id, queryHint(c)));
+        // The lane must exist before the method is refused.
+        await located(c, "state", id, "state_not_found");
+        return json(405, { error: "method_not_allowed" });
+    });
+    app.patch("/api/board-entries/:id", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(200, await clientFor(c).entries.update(c.req.param("id"), body, queryHint(c)));
+    });
+    app.delete("/api/board-entries/:id", async (c) => json(200, await clientFor(c).entries.remove(c.req.param("id"), queryHint(c))));
+    app.post("/api/relations", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(201, await clientFor(c).relations.create({ ...body, ...bodyHint(c, body) }));
+    });
+    app.delete("/api/relations/:id", async (c) => json(200, await clientFor(c).relations.remove(c.req.param("id"), queryHint(c))));
+    app.get("/api/search", async (c) => json(200, await clientFor(c).search(queryHint(c), {
+        q: query(c, "q") ?? "",
+        limit: query(c, "limit"),
+        mode: query(c, "mode"),
+        include_full: query(c, "include_full") === "true" ? true : undefined,
+        fields: query(c, "fields"),
+        max_chars_per_field: query(c, "max_chars_per_field") ?? undefined
+    })));
+    app.post("/api/agent/claim-next", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(200, await clientFor(c).agent.claimNext(bodyHint(c, body), body));
+    });
+    app.post("/api/agent/claim", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(200, await clientFor(c).agent.claim({ ...body, ...bodyHint(c, body) }));
+    });
+    app.post("/api/agent/checkpoint", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(200, await clientFor(c).agent.checkpoint({ ...body, ...bodyHint(c, body) }));
+    });
+    app.post("/api/agent/complete", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(200, await clientFor(c).agent.complete({ ...body, ...bodyHint(c, body) }));
+    });
+    // By default an import makes a new board; replacing one names it, and never an agent's (the core
+    // refuses it: refuseAgentReplace).
+    app.post("/api/admin/import", async (c) => {
+        const body = await readObject(c.req.raw);
+        return json(201, await clientFor(c).boards.import({ ...body, ...bodyHint(c, body) }));
+    });
+    app.get("/api/events/stream", async (c) => {
+        const boardId = query(c, "board_id");
+        const rows = await orbit.context(resolveActor(c.req.raw)).store.boards.list();
+        if (boardId && !rows.some((row) => row.id === boardId))
+            return json(404, { error: "board_not_found" });
+        const after = c.req.header("last-event-id") || query(c, "last_event_id");
+        return eventStream(orbit, boardId ? [boardId] : rows.map((row) => row.id), after ?? null, heartbeatMs, c.req.raw.signal);
+    });
+    app.all("/api/*", () => json(404, { error: "not_found" }));
+    app.on(["GET", "HEAD"], "/llms.txt", async (c) => {
+        const { instanceLlmsTxt } = await import("../commands/agent-tools.js");
+        const text = instanceLlmsTxt({ origin: requestOrigin(c.req.raw.headers), version: options.version ?? "" });
+        return new Response(c.req.method === "HEAD" ? null : text, { status: 200, headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-cache" } });
+    });
+    app.all("*", async (c) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+            return new Response(null, { status: 405 });
+        const found = await options.assets?.(c.req.raw, new URL(c.req.url).pathname);
+        return found ?? new Response(null, { status: 404 });
+    });
+    return { fetch: (request) => Promise.resolve(app.fetch(request)) };
+}
+/**
+ * An attachment's content may be anything a person or an import put on a
+ * card, so it is never a page of Orbit's origin: the browser may not sniff
+ * it into another type, and opened as a document it runs nothing (`sandbox`
+ * gives it an origin of its own). An `<img>` ignores both, so images still
+ * show. A type Orbit won't show (an SVG) comes as a download.
+ */
+export const ATTACHMENT_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
+function attachmentHeaders(file) {
+    const headers = {
+        "Content-Type": file.download_only ? DOWNLOAD_TYPE : file.mime_type,
+        "Cache-Control": "private, max-age=3600",
+        "X-Content-Type-Options": "nosniff",
+        "Content-Security-Policy": ATTACHMENT_CSP
+    };
+    if (file.download_only)
+        headers["Content-Disposition"] = contentDisposition(file.original_name || "file");
+    return headers;
+}
+/** `attachment`, with the name in ASCII for old readers and in UTF-8 for the rest (RFC 6266). */
+function contentDisposition(name) {
+    const ascii = name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+/** A route that needs a board, given none: `board_id_required` before anything is looked up. */
+function requiredHint(hint) {
+    if (!hint.board_id && !hint.board)
+        throw new OrbitError("board_id_required");
+    return hint;
+}
+const encoder = new TextEncoder();
+const frame = (change) => encoder.encode(`id: ${change.id}\nevent: board\ndata: ${JSON.stringify(change)}\n\n`);
+/**
+ * The live stream: every committed change on these boards, from any writer
+ * (the app, MCP, the CLI), as server-sent events. With an event id to
+ * resume from, the events after it come first (up to 200).
+ */
+function eventStream(orbit, boardIds, after, heartbeatMs, signal) {
+    const stops = [];
+    let timer = null;
+    const stop = () => {
+        if (timer)
+            clearInterval(timer);
+        timer = null;
+        for (const fn of stops.splice(0))
+            fn();
+    };
+    const body = new ReadableStream({
+        start: async (controller) => {
+            const sent = new Set();
+            let live = false;
+            const queued = [];
+            const send = (change) => {
+                if (sent.has(change.id))
+                    return;
+                sent.add(change.id);
+                try {
+                    controller.enqueue(frame(change));
+                }
+                catch {
+                    stop();
+                }
+            };
+            controller.enqueue(encoder.encode(":ok\n\n"));
+            // Listen first, so nothing committed during the replay is missed.
+            for (const id of boardIds)
+                stops.push(orbit.watch(id, (change) => {
+                    if (live)
+                        send(change);
+                    else
+                        queued.push(change);
+                }));
+            if (after && boardIds.length === 1 && boardIds[0]) {
+                const boardId = boardIds[0];
+                try {
+                    const data = await orbit.context(localOwnerActor()).store.board(boardId);
+                    const missed = await data.read((r) => r.events.after(after, 200));
+                    for (const event of missed)
+                        send(changeOf(boardId, event));
+                }
+                catch {
+                    // A board that can't be read now still streams what comes next.
+                }
+            }
+            live = true;
+            for (const change of queued.splice(0))
+                send(change);
+            timer = setInterval(() => {
+                try {
+                    controller.enqueue(encoder.encode(":heartbeat\n\n"));
+                }
+                catch {
+                    stop();
+                }
+            }, heartbeatMs);
+            signal.addEventListener("abort", () => {
+                stop();
+                try {
+                    controller.close();
+                }
+                catch {
+                    // Already closed.
+                }
+            });
+        },
+        cancel: stop
+    });
+    return new Response(body, { status: 200, headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive", "X-Accel-Buffering": "no" } });
+}

package/lib/mcp-server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `orbit mcp`: the board commands for an MCP app over stdio, on the MCP SDK's
+ * low-level Server. Two tools take a command line (orbit_read refuses
+ * anything that writes), and the guide is a resource. Local mode runs Orbit
+ * in this process on the data folder; remote mode (ORBIT_MODE=remote) sends
+ * each command to ORBIT_API_URL. Either way the repo's orbit.json is read
+ * where the server runs, or in the folder `--cwd` names.
+ */
+import "./quiet-sqlite-warning.ts";
+export declare function runMcpServer(): Promise<void>;