excaliagent 0.0.0-stage → 0.2.0

package/dist/server/http.js

@@ -0,0 +1,240 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { timingSafeEqual } from "node:crypto";
+import { SESSION_ID } from "./hub.js";
+const COOKIE = "excaliagent_token";
+const MAX_BODY = 50 * 1024 * 1024;
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".ttf": "font/ttf",
+    ".wasm": "application/wasm",
+};
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function sameToken(a, b) {
+    if (!a)
+        return false;
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+function cookieToken(req) {
+    for (const part of (req.headers.cookie ?? "").split(";")) {
+        const [k, ...v] = part.trim().split("=");
+        if (k === COOKIE)
+            return v.join("=");
+    }
+    return undefined;
+}
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+function text(res, status, body) {
+    res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+    res.end(body);
+}
+async function readJson(req) {
+    if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
+        throw new HttpError(415, "expected application/json");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, "body too large");
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new HttpError(400, "invalid JSON");
+    }
+}
+export function createAppServer(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    let port = 0;
+    const allowedHosts = () => new Set([`${host}:${port}`, `127.0.0.1:${port}`, `localhost:${port}`]);
+    const allowedOrigins = () => new Set([...allowedHosts()].map((h) => `http://${h}`));
+    async function serveStatic(req, res, pathname) {
+        const root = opts.webRoot;
+        if (!root)
+            return text(res, 404, "not found");
+        let rel;
+        try {
+            rel = decodeURIComponent(pathname);
+        }
+        catch {
+            return text(res, 400, "bad path");
+        }
+        if (rel === "/" || rel === "")
+            rel = "/index.html";
+        const file = normalize(join(root, rel));
+        if (!file.startsWith(normalize(root) + sep))
+            return text(res, 404, "not found");
+        try {
+            if (!(await stat(file)).isFile())
+                return text(res, 404, "not found");
+            const body = await readFile(file);
+            res.writeHead(200, {
+                "content-type": TYPES[extname(file)] ?? "application/octet-stream",
+                "cache-control": rel.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-store",
+            });
+            res.end(req.method === "HEAD" ? undefined : body);
+        }
+        catch {
+            text(res, 404, "not found");
+        }
+    }
+    function events(req, res) {
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-store",
+            connection: "keep-alive",
+        });
+        const send = (sessions) => res.write(`event: sessions\ndata: ${JSON.stringify(sessions)}\n\n`);
+        send(opts.hub.sessions());
+        const unsubscribe = opts.hub.subscribe(send);
+        const heartbeat = setInterval(() => res.write(": ping\n\n"), 25_000);
+        req.on("close", () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+        });
+    }
+    async function api(req, res, pathname) {
+        const route = `${req.method} ${pathname}`;
+        switch (route) {
+            case "GET /api/sessions":
+                return json(res, 200, opts.hub.sessions());
+            case "GET /api/events":
+                return events(req, res);
+            case "GET /api/picker":
+                return json(res, 200, await opts.hub.picker());
+            case "POST /api/lookup": {
+                const body = (await readJson(req));
+                if (!Array.isArray(body?.ids) || !body.ids.every((i) => typeof i === "string")) {
+                    throw new HttpError(400, "ids must be a string array");
+                }
+                return json(res, 200, await opts.hub.lookup(body.ids));
+            }
+            case "GET /api/scene":
+                return json(res, 200, await opts.scenes.load());
+            case "PUT /api/scene": {
+                const body = (await readJson(req));
+                if (!body || !Array.isArray(body.elements))
+                    throw new HttpError(400, "elements must be an array");
+                const appState = body.appState && typeof body.appState === "object" ? body.appState : {};
+                await opts.scenes.save({ elements: body.elements, appState: appState });
+                res.writeHead(204).end();
+                return;
+            }
+            case "POST /api/focus": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string")
+                    throw new HttpError(400, "sessionId required");
+                if (await opts.hub.focus(body.sessionId)) {
+                    res.writeHead(204).end();
+                    return;
+                }
+                return json(res, 409, { error: "no pane" });
+            }
+            case "POST /api/resume": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string" || !SESSION_ID.test(body.sessionId)) {
+                    throw new HttpError(400, "sessionId must be a session UUID");
+                }
+                const result = await opts.hub.resume(body.sessionId);
+                if (result === "resumed") {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (result === "unknown")
+                    return json(res, 404, { error: "unknown session" });
+                return json(res, 409, { error: result === "live" ? "live" : "no herdr" });
+            }
+            default:
+                return json(res, 404, { error: "not found" });
+        }
+    }
+    async function handle(req, res) {
+        if (!allowedHosts().has(req.headers.host ?? ""))
+            return text(res, 421, "unexpected Host header");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const method = req.method ?? "GET";
+        if (method !== "GET" && method !== "HEAD") {
+            const origin = req.headers.origin;
+            if (origin !== undefined && !allowedOrigins().has(origin))
+                return text(res, 403, "cross-origin request");
+        }
+        const queryToken = url.searchParams.get("token");
+        if (queryToken !== null && method === "GET" && !url.pathname.startsWith("/api/")) {
+            if (!sameToken(queryToken, opts.token))
+                return text(res, 401, "bad token");
+            res.writeHead(302, {
+                location: "/",
+                "set-cookie": `${COOKIE}=${opts.token}; HttpOnly; SameSite=Strict; Path=/`,
+            });
+            res.end();
+            return;
+        }
+        if (!sameToken(cookieToken(req), opts.token)) {
+            return text(res, 401, "excaliagent: open the URL printed in the terminal (it carries the access token).");
+        }
+        if (url.pathname.startsWith("/api/"))
+            return api(req, res, url.pathname);
+        if (opts.middleware)
+            return opts.middleware(req, res, () => text(res, 404, "not found"));
+        return serveStatic(req, res, url.pathname);
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const status = err instanceof HttpError ? err.status : 500;
+            if (status === 500)
+                console.error("excaliagent:", err);
+            if (!res.headersSent)
+                json(res, status, { error: err.message });
+            else
+                res.end();
+        });
+    });
+    return {
+        server,
+        get port() {
+            return port;
+        },
+        listen(p) {
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(p, host, () => {
+                    server.off("error", reject);
+                    const addr = server.address();
+                    port = typeof addr === "object" && addr ? addr.port : p;
+                    resolve();
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections();
+            });
+        },
+    };
+}

package/dist/server/hub.js

@@ -0,0 +1,101 @@
+/** Claude session ids are UUIDs; anything else is never put into a command. */
+export const SESSION_ID = /^[0-9a-f-]{36}$/i;
+const LABEL_MAX = 40;
+function resumeLabel(s) {
+    const title = s.title?.trim();
+    if (!title)
+        return s.repo;
+    const chars = [...title];
+    return chars.length <= LABEL_MAX ? title : chars.slice(0, LABEL_MAX - 1).join("") + "…";
+}
+/** Joins a Source with a PaneLink and fans the result out to subscribers. */
+export function createHub({ source, panes }) {
+    let raw = [];
+    let current = [];
+    let serialized = "[]";
+    const listeners = new Set();
+    const cleanups = [];
+    const withPane = (s) => {
+        const pane = s.pid !== undefined ? panes.match(s.pid) : undefined;
+        const { pane: _old, ...rest } = s;
+        return pane ? { ...rest, pane } : rest;
+    };
+    function recompute() {
+        const next = raw.map(withPane);
+        const json = JSON.stringify(next);
+        if (json === serialized)
+            return;
+        current = next;
+        serialized = json;
+        for (const cb of listeners)
+            cb(current);
+    }
+    function setRaw(next) {
+        const ids = (l) => l.map((s) => `${s.id}:${s.pid}`).join(",");
+        const membershipChanged = ids(next) !== ids(raw);
+        raw = next;
+        recompute();
+        if (membershipChanged)
+            void panes.refresh?.().catch(() => { });
+    }
+    return {
+        async start() {
+            raw = await source.list();
+            current = raw.map(withPane);
+            serialized = JSON.stringify(current);
+            cleanups.push(source.watch(setRaw));
+            cleanups.push(panes.onChange(recompute));
+        },
+        stop() {
+            for (const c of cleanups.splice(0))
+                c();
+            listeners.clear();
+        },
+        sessions: () => current,
+        subscribe(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        async lookup(ids) {
+            const out = [];
+            for (const id of ids) {
+                const live = current.find((s) => s.id === id);
+                const found = live ?? (await source.get(id));
+                if (found)
+                    out.push(live ? found : withPane(found));
+            }
+            return out;
+        },
+        async picker() {
+            const live = new Set(current.map((s) => s.id));
+            return (await source.listDormant()).filter((s) => !s.live && !live.has(s.id));
+        },
+        async resume(sessionId) {
+            if (!SESSION_ID.test(sessionId))
+                return "unknown";
+            if (current.some((s) => s.id === sessionId))
+                return "live";
+            const s = await source.get(sessionId);
+            if (!s)
+                return "unknown";
+            if (s.live)
+                return "live";
+            if (!panes.resume || !panes.available())
+                return "no-herdr";
+            await panes.resume({
+                cwd: s.cwd,
+                ...(s.repoRoot !== undefined ? { repoRoot: s.repoRoot } : {}),
+                command: `claude --resume ${s.id}`,
+                label: resumeLabel(s),
+            });
+            return "resumed";
+        },
+        async focus(sessionId) {
+            const pane = current.find((s) => s.id === sessionId)?.pane;
+            if (!pane)
+                return false;
+            await panes.focus(pane.paneId);
+            return true;
+        },
+    };
+}

package/dist/server/panes/herdr-client.js

@@ -0,0 +1,220 @@
+/**
+ * Minimal herdr socket client (verified against herdr 0.9.0, protocol 22).
+ *
+ * Wire: newline-delimited JSON over a Unix stream socket.
+ *   request  {"id","method","params"}
+ *   response {"id","result":{"type",...}} | {"id","error":{"code","message"}}
+ *   event    {"event":"pane_created","data":{"type":"pane_created",...}}  (no id)
+ *
+ * herdr serves ONE request per connection: a second line on the same
+ * connection resets it, including on an events.subscribe connection. So this
+ * client keeps one long-lived subscription connection (events, reconnect with
+ * backoff, `connected()`), and opens a short connection per request.
+ * Malformed requests get an error with id "" — on a one-shot connection any
+ * reply is ours, so it is accepted.
+ */
+import { existsSync } from "node:fs";
+import net from "node:net";
+export class HerdrError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HerdrError";
+        this.code = code;
+    }
+}
+/** Parse one wire line; undefined for blank or unrecognised lines. */
+export function parseLine(line) {
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (!msg || typeof msg !== "object")
+        return undefined;
+    const m = msg;
+    if (m.error && typeof m.error === "object") {
+        const e = m.error;
+        return { kind: "error", id: String(m.id ?? ""), code: String(e.code ?? "unknown"), message: String(e.message ?? "") };
+    }
+    if ("result" in m)
+        return { kind: "response", id: String(m.id ?? ""), result: m.result };
+    if (typeof m.event === "string") {
+        const data = m.data && typeof m.data === "object" ? m.data : {};
+        return { kind: "event", event: { event: m.event, data } };
+    }
+    return undefined;
+}
+const defaultConnect = (p) => net.createConnection(p);
+function onLines(sock, cb) {
+    let buf = "";
+    sock.setEncoding("utf8");
+    sock.on("data", (chunk) => {
+        buf += chunk;
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, i);
+            buf = buf.slice(i + 1);
+            if (line.trim())
+                cb(line);
+        }
+    });
+}
+let seq = 0;
+const nextId = (prefix) => `${prefix}-${process.pid}-${++seq}`;
+/** One request on its own connection. Never throws synchronously. */
+export function herdrRequest(socketPath, method, params = {}, opts = {}) {
+    const { timeoutMs = 5000, connect = defaultConnect } = opts;
+    return new Promise((resolve, reject) => {
+        if (!existsSync(socketPath)) {
+            reject(new HerdrError("unavailable", `herdr socket not found: ${socketPath}`));
+            return;
+        }
+        const id = nextId("ea");
+        let sock;
+        try {
+            sock = connect(socketPath);
+        }
+        catch (e) {
+            reject(new HerdrError("unavailable", String(e)));
+            return;
+        }
+        const untrack = opts.track?.(sock);
+        let done = false;
+        const finish = (err, value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            untrack?.();
+            sock.destroy();
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => finish(new HerdrError("timeout", `${method} timed out after ${timeoutMs} ms`)), timeoutMs);
+        sock.on("error", (e) => finish(new HerdrError("unavailable", `${method}: ${e.code ?? e.message}`)));
+        sock.on("close", () => finish(new HerdrError("closed", `${method}: connection closed without a reply`)));
+        onLines(sock, (line) => {
+            const msg = parseLine(line);
+            if (!msg || msg.kind === "event")
+                return;
+            if (msg.id !== id && msg.id !== "")
+                return;
+            if (msg.kind === "error")
+                finish(new HerdrError(msg.code, msg.message));
+            else
+                finish(undefined, msg.result);
+        });
+        sock.write(JSON.stringify({ id, method, params }) + "\n");
+    });
+}
+export function createHerdrClient(opts) {
+    const { socketPath, requestTimeoutMs = 5000, retryMinMs = 250, retryMaxMs = 5000 } = opts;
+    const connect = opts.connect ?? defaultConnect;
+    let closed = false;
+    let isConnected = false;
+    let sub;
+    let retryTimer;
+    let delay = retryMinMs;
+    const inflight = new Set();
+    const scheduleRetry = () => {
+        if (closed || retryTimer)
+            return;
+        retryTimer = setTimeout(() => {
+            retryTimer = undefined;
+            start();
+        }, delay);
+        retryTimer.unref?.();
+        delay = Math.min(delay * 2, retryMaxMs);
+    };
+    const start = () => {
+        if (closed)
+            return;
+        if (!existsSync(socketPath)) {
+            scheduleRetry();
+            return;
+        }
+        let sock;
+        try {
+            sock = connect(socketPath);
+        }
+        catch {
+            scheduleRetry();
+            return;
+        }
+        sub = sock;
+        const subId = nextId("ea-sub");
+        let acked = false;
+        sock.on("error", () => { });
+        sock.on("close", () => {
+            if (sub === sock)
+                sub = undefined;
+            const was = isConnected && acked;
+            if (acked)
+                isConnected = false;
+            if (was)
+                opts.onDisconnect?.();
+            scheduleRetry();
+        });
+        onLines(sock, (line) => {
+            const msg = parseLine(line);
+            if (!msg)
+                return;
+            if (msg.kind === "event") {
+                if (msg.event.event === "events_lost")
+                    opts.onEventsLost?.();
+                else
+                    opts.onEvent?.(msg.event);
+                return;
+            }
+            if (msg.kind === "error") {
+                if (msg.code === "events_lost")
+                    opts.onEventsLost?.();
+                else if (!acked)
+                    sock.destroy(); // subscribe rejected: retry later
+                return;
+            }
+            if (!acked && (msg.id === subId || msg.id === "")) {
+                acked = true;
+                isConnected = true;
+                delay = retryMinMs;
+                opts.onConnect?.();
+            }
+        });
+        sock.write(JSON.stringify({ id: subId, method: "events.subscribe", params: { subscriptions: opts.subscriptions } }) + "\n");
+    };
+    start();
+    return {
+        request(method, params = {}) {
+            if (closed)
+                return Promise.reject(new HerdrError("closed", "herdr client closed"));
+            return herdrRequest(socketPath, method, params, {
+                timeoutMs: requestTimeoutMs,
+                connect,
+                track: (s) => {
+                    inflight.add(s);
+                    return () => inflight.delete(s);
+                },
+            });
+        },
+        connected: () => isConnected && !closed,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            isConnected = false;
+            if (retryTimer)
+                clearTimeout(retryTimer);
+            retryTimer = undefined;
+            sub?.destroy();
+            sub = undefined;
+            for (const s of inflight)
+                s.destroy();
+            inflight.clear();
+        },
+    };
+}

package/dist/server/panes/herdr-clients.js

@@ -0,0 +1,37 @@
+/**
+ * Find herdr client processes (the TUI attached to a herdr server): processes
+ * whose executable name is "herdr" and that have no "server" argument. Clients
+ * whose socket is ours are preferred; if none can be tied to it (environment
+ * unreadable), every client is returned.
+ */
+import { basename, join } from "node:path";
+/**
+ * herdr's API socket for an environment (checked on herdr 0.9.0 / Linux):
+ * HERDR_SOCKET_PATH, else $XDG_CONFIG_HOME/herdr/herdr.sock, else
+ * $HOME/.config/herdr/herdr.sock. The binary has no macOS-specific path
+ * (no ~/Library); assumed the same there (unverified on real hardware).
+ */
+export function herdrSocketPath(env, home) {
+    if (env.HERDR_SOCKET_PATH)
+        return env.HERDR_SOCKET_PATH;
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, "herdr", "herdr.sock");
+    const h = env.HOME || home;
+    return h ? join(h, ".config", "herdr", "herdr.sock") : undefined;
+}
+export async function findHerdrClientPids(opts) {
+    const { table } = opts;
+    const candidates = (await table.list()).filter((p) => basename(p.comm) === "herdr");
+    const all = [];
+    const ours = [];
+    await Promise.all(candidates.map(async ({ pid }) => {
+        const argv = await table.argv(pid);
+        if (argv?.slice(1).includes("server"))
+            return;
+        all.push(pid);
+        const env = await table.env(pid);
+        if (env && herdrSocketPath(env) === opts.socketPath)
+            ours.push(pid);
+    }));
+    return (ours.length > 0 ? ours : all).sort((a, b) => a - b);
+}