excaliagent 0.0.0-stage → 0.1.0

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,58 @@
+/**
+ * Find herdr client processes (the TUI attached to a herdr server) by
+ * scanning /proc: comm "herdr" and no "server" argument. Clients whose socket
+ * (HERDR_SOCKET_PATH, else ~/.config/herdr/herdr.sock under their HOME) is
+ * ours are returned. Clients whose socket cannot be read are a fallback only
+ * when none match; a client known to be on another server is never returned.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+async function read(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function findHerdrClientPids(opts) {
+    const procRoot = opts.procRoot ?? "/proc";
+    let entries;
+    try {
+        entries = await readdir(procRoot);
+    }
+    catch {
+        return [];
+    }
+    const unknown = [];
+    const ours = [];
+    await Promise.all(entries
+        .filter((e) => /^\d+$/.test(e))
+        .map(async (e) => {
+        const dir = join(procRoot, e);
+        if ((await read(join(dir, "comm")))?.trim() !== "herdr")
+            return;
+        const argv = (await read(join(dir, "cmdline")))?.split("\0").filter(Boolean) ?? [];
+        if (argv.slice(1).includes("server"))
+            return;
+        const pid = Number(e);
+        const environ = await read(join(dir, "environ"));
+        if (environ === undefined) {
+            unknown.push(pid);
+            return;
+        }
+        const env = new Map();
+        for (const kv of environ.split("\0")) {
+            const i = kv.indexOf("=");
+            if (i > 0)
+                env.set(kv.slice(0, i), kv.slice(i + 1));
+        }
+        const home = env.get("HOME");
+        const sock = env.get("HERDR_SOCKET_PATH") || (home ? join(home, ".config/herdr/herdr.sock") : undefined);
+        if (sock === undefined)
+            unknown.push(pid);
+        else if (sock === opts.socketPath)
+            ours.push(pid);
+    }));
+    return (ours.length > 0 ? ours : unknown).sort((a, b) => a - b);
+}

package/dist/server/panes/herdr.js

@@ -0,0 +1,246 @@
+/**
+ * herdr pane link: pid → pane map built from pane.list + pane.process_info.
+ * Rebuilt on pane events, on (re)connect, on events_lost (herdr 0.9.2+), every
+ * `resyncMs` (0.9.0 has no events_lost), and on refresh(). Never throws when
+ * herdr is absent: available() is false and the socket is retried.
+ */
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { createHerdrClient, HerdrError } from "./herdr-client.js";
+import { findHerdrClientPids } from "./herdr-clients.js";
+export { createNoPaneLink } from "./none.js";
+export const HERDR_SUBSCRIPTIONS = [
+    { type: "pane.created" },
+    { type: "pane.closed" },
+    { type: "pane.exited" },
+    { type: "pane.agent_detected" },
+    // Labels shown on cards: rebuild when they appear, change or go away.
+    { type: "workspace.created" },
+    { type: "workspace.renamed" },
+    { type: "workspace.closed" },
+    { type: "tab.created" },
+    { type: "tab.renamed" },
+    { type: "tab.closed" },
+];
+/** Every method this link sends (tests check them against the schema). */
+export const HERDR_METHODS = [
+    "events.subscribe",
+    "pane.list",
+    "pane.process_info",
+    "pane.focus",
+    "workspace.list",
+    "tab.list",
+    "tab.create",
+    "workspace.create",
+    "pane.send_text",
+];
+/** True when path is dir or inside it (separator boundary: /a/b is not inside /a/bc). */
+export function isInside(path, dir) {
+    const d = dir.length > 1 ? dir.replace(/\/+$/, "") : dir;
+    return path === d || path.startsWith(d === "/" ? "/" : d + "/");
+}
+/** Workspace showing root: the focused pane's workspace if it matches, else the first match. */
+export function pickWorkspace(panes, root) {
+    const matches = panes.filter((p) => [p.cwd, p.foreground_cwd].some((c) => typeof c === "string" && isInside(c, root)));
+    const pick = matches.find((p) => p.focused) ?? matches[0];
+    return pick ? (pick.workspace_id ?? workspaceOf(pick.pane_id)) : undefined;
+}
+export function defaultHerdrSocketPath() {
+    return process.env.HERDR_SOCKET_PATH || join(homedir(), ".config/herdr/herdr.sock");
+}
+const workspaceOf = (paneId) => paneId.split(":")[0] ?? paneId;
+/** pid → pane for every foreground process of every pane; `panes` supplies ids and labels. */
+export function parsePaneMap(infos, panes = new Map()) {
+    const map = new Map();
+    for (const info of infos) {
+        const pane = panes.get(info.pane_id) ?? { paneId: info.pane_id, workspaceId: workspaceOf(info.pane_id) };
+        for (const p of info.foreground_processes ?? []) {
+            if (typeof p.pid === "number")
+                map.set(p.pid, pane);
+        }
+    }
+    return map;
+}
+function sameMap(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [pid, pane] of a) {
+        const other = b.get(pid);
+        if (!other ||
+            other.paneId !== pane.paneId ||
+            other.workspaceId !== pane.workspaceId ||
+            other.workspaceLabel !== pane.workspaceLabel ||
+            other.tabLabel !== pane.tabLabel) {
+            return false;
+        }
+    }
+    return true;
+}
+export function createHerdrLink(opts = {}) {
+    const { resyncMs = 30_000 } = opts;
+    const socketPath = opts.socketPath ?? defaultHerdrSocketPath();
+    const clientPids = () => findHerdrClientPids({ socketPath, procRoot: opts.procRoot });
+    let map = new Map();
+    const listeners = new Set();
+    let closed = false;
+    const setMap = (next) => {
+        if (sameMap(map, next))
+            return;
+        map = next;
+        for (const cb of [...listeners]) {
+            try {
+                cb();
+            }
+            catch {
+                // a listener's failure must not break the link
+            }
+        }
+    };
+    const client = createHerdrClient({
+        socketPath,
+        subscriptions: HERDR_SUBSCRIPTIONS,
+        requestTimeoutMs: opts.requestTimeoutMs,
+        retryMinMs: opts.retryMinMs,
+        retryMaxMs: opts.retryMaxMs,
+        connect: opts.connect,
+        onConnect: () => void rebuild(),
+        onEvent: () => void rebuild(),
+        onEventsLost: () => void rebuild(),
+        onDisconnect: () => setMap(new Map()),
+    });
+    /** id → label from workspace.list / tab.list; empty when the call fails (labels are optional). */
+    async function labels(method, key, id) {
+        try {
+            const res = (await client.request(method, {}));
+            const out = new Map();
+            for (const item of res[key] ?? []) {
+                const k = item[id];
+                if (typeof k === "string" && typeof item.label === "string")
+                    out.set(k, item.label);
+            }
+            return out;
+        }
+        catch {
+            return new Map();
+        }
+    }
+    async function build() {
+        let list;
+        const wsLabels = labels("workspace.list", "workspaces", "workspace_id");
+        const tabLabels = labels("tab.list", "tabs", "tab_id");
+        try {
+            const res = (await client.request("pane.list", {}));
+            list = res.panes ?? [];
+        }
+        catch {
+            return; // keep the current map; the next event/timer/reconnect retries
+        }
+        const [ws, tabs] = await Promise.all([wsLabels, tabLabels]);
+        const panes = new Map();
+        for (const p of list) {
+            const pane = { paneId: p.pane_id, workspaceId: p.workspace_id ?? workspaceOf(p.pane_id) };
+            const wl = ws.get(pane.workspaceId);
+            const tl = p.tab_id !== undefined ? tabs.get(p.tab_id) : undefined;
+            if (wl !== undefined)
+                pane.workspaceLabel = wl;
+            if (tl !== undefined)
+                pane.tabLabel = tl;
+            panes.set(p.pane_id, pane);
+        }
+        const panesList = list;
+        const infos = await Promise.all(panesList.map(async (p) => {
+            try {
+                const res = (await client.request("pane.process_info", { pane_id: p.pane_id }));
+                return res.process_info;
+            }
+            catch {
+                return undefined; // pane vanished or herdr hiccuped: skip it
+            }
+        }));
+        if (closed || !client.connected())
+            return;
+        setMap(parsePaneMap(infos.filter((i) => !!i), panes));
+    }
+    // Coalesce: at most one build running, plus one queued behind it.
+    let running;
+    let queued;
+    function rebuild() {
+        if (closed || !client.connected())
+            return Promise.resolve();
+        if (!running) {
+            running = build().finally(() => {
+                running = undefined;
+            });
+            return running;
+        }
+        queued ??= running.then(() => {
+            queued = undefined;
+            return rebuild();
+        });
+        return queued;
+    }
+    const timer = setInterval(() => void rebuild(), resyncMs);
+    timer.unref?.();
+    const pending = new Set();
+    async function raise() {
+        if (!opts.desktop)
+            return;
+        try {
+            await opts.desktop.raise(await clientPids());
+        }
+        catch {
+            // raising the window is best effort
+        }
+    }
+    return {
+        available: () => !closed && client.connected(),
+        match: (pid) => map.get(pid),
+        async focus(paneId) {
+            if (closed || !client.connected())
+                return;
+            await client.request("pane.focus", { pane_id: paneId });
+            await raise();
+        },
+        async resume(req) {
+            if (closed || !client.connected())
+                throw new HerdrError("unavailable", "herdr is not connected");
+            const root = req.repoRoot ?? req.cwd;
+            const { panes = [] } = (await client.request("pane.list", {}));
+            const workspaceId = pickWorkspace(panes, root);
+            const created = (workspaceId !== undefined
+                ? await client.request("tab.create", { workspace_id: workspaceId, cwd: req.cwd, label: req.label, focus: true })
+                : await client.request("workspace.create", { cwd: req.cwd, label: basename(root) || root, focus: true }));
+            const paneId = created.root_pane?.pane_id;
+            if (typeof paneId !== "string")
+                throw new HerdrError("bad_response", "herdr did not return the new pane");
+            // A fresh shell buffers typed input until it is ready (checked on herdr 0.9.0 with sh and a slow zsh).
+            await client.request("pane.send_text", { pane_id: paneId, text: req.command + "\n" });
+            await raise();
+            const t = setTimeout(() => {
+                pending.delete(t);
+                void rebuild();
+            }, opts.resumeRefreshMs ?? 1500);
+            t.unref?.();
+            pending.add(t);
+            return { paneId };
+        },
+        clientPids,
+        onChange(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        refresh: rebuild,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            for (const t of pending)
+                clearTimeout(t);
+            pending.clear();
+            client.close();
+            listeners.clear();
+            map = new Map();
+        },
+    };
+}

package/dist/server/panes/none.js

@@ -0,0 +1,10 @@
+/** PaneLink for when herdr is disabled: never available, does nothing. */
+export function createNoPaneLink() {
+    return {
+        available: () => false,
+        match: () => undefined,
+        focus: async () => { },
+        onChange: () => () => { },
+        close: () => { },
+    };
+}

package/dist/server/panes/types.js

@@ -0,0 +1 @@
+export {};