excaliagent 0.0.0-stage → 0.2.0

package/dist/server/panes/herdr.js

@@ -0,0 +1,248 @@
+/**
+ * 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 { createProcessTable } from "../desktop/process-table.js";
+import { findHerdrClientPids, herdrSocketPath } 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 herdrSocketPath(process.env, homedir()) ?? 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 table = opts.processTable ?? createProcessTable();
+    const clientPids = () => findHerdrClientPids({ socketPath, table });
+    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 {};

package/dist/server/scene-store.js

@@ -0,0 +1,61 @@
+import { mkdir, open, readFile, rename } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function defaultStateDir(env = process.env, home = homedir()) {
+    const base = env.XDG_STATE_HOME || join(home, ".local", "state");
+    return join(base, "excaliagent");
+}
+const empty = () => ({ elements: [], appState: {} });
+/** scene.json in stateDir, written atomically (temp file + fsync + rename), saves serialized. */
+export function createSceneStore(stateDir, log = console) {
+    const path = join(stateDir, "scene.json");
+    let queue = Promise.resolve();
+    let seq = 0;
+    async function write(scene) {
+        await mkdir(stateDir, { recursive: true });
+        const tmp = `${path}.tmp-${process.pid}-${seq++}`;
+        const fh = await open(tmp, "w", 0o600);
+        try {
+            await fh.writeFile(JSON.stringify(scene));
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        await rename(tmp, path);
+    }
+    return {
+        path,
+        async load() {
+            let raw;
+            try {
+                raw = await readFile(path, "utf8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return empty();
+                throw err;
+            }
+            try {
+                const scene = JSON.parse(raw);
+                if (!Array.isArray(scene.elements))
+                    throw new Error("no elements array");
+                return { ...scene, appState: scene.appState ?? {} };
+            }
+            catch (err) {
+                const aside = `${path}.corrupt-${Date.now()}`;
+                await rename(path, aside).catch(() => { });
+                log.warn(`excaliagent: ${path} was unreadable (${err.message}); moved to ${aside}`);
+                return empty();
+            }
+        },
+        save(scene) {
+            if (!scene || !Array.isArray(scene.elements)) {
+                return Promise.reject(new Error("scene must have an elements array"));
+            }
+            const run = queue.then(() => write(scene));
+            queue = run.catch(() => { });
+            return run;
+        },
+    };
+}

package/dist/server/sources/claude.js

@@ -0,0 +1,292 @@
+// Claude Code source: live sessions from the registry (<claudeDir>/sessions),
+// enriched from transcripts (<claudeDir>/projects/<slug>/<id>.jsonl), plus
+// dormant sessions from the transcript store.
+import { watch as fsWatch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { GitReader } from "./git.js";
+import { onceLogger } from "./log.js";
+import { defaultIsAlive, isLive, readRegistry } from "./registry.js";
+import { TranscriptScanner } from "./transcript.js";
+const LIVE_STATUSES = new Set([
+    "busy", "idle", "waiting", "needs_user", "needs_trust", "blocked",
+]);
+export function liveSession(e, t, git) {
+    const cwd = e.cwd || t?.cwd || "";
+    const s = {
+        id: e.sessionId,
+        source: "claude",
+        cwd,
+        repo: basename(cwd),
+        status: LIVE_STATUSES.has(e.status) ? e.status : "idle",
+        lastActivityAt: Math.max(e.statusUpdatedAt ?? e.updatedAt ?? 0, t?.lastTimestamp ?? 0),
+        cacheTtlMs: t?.cacheTtlMs ?? 0,
+        cacheExpiresAt: t?.cacheExpiresAt ?? 0,
+        live: true,
+        pid: e.pid,
+        prLinks: t?.prLinks ?? [],
+    };
+    return withGit(withTranscriptExtras(s, t, e.name, e.waitingFor), git);
+}
+export function dormantSession(f, t, fallbackCwd, git) {
+    const cwd = t.cwd ?? fallbackCwd ?? "";
+    const s = {
+        id: f.id,
+        source: "claude",
+        cwd,
+        repo: cwd ? basename(cwd) : f.slug,
+        status: "dormant",
+        lastActivityAt: t.lastTimestamp || Math.floor(f.mtimeMs),
+        cacheTtlMs: t.cacheTtlMs,
+        cacheExpiresAt: t.cacheExpiresAt,
+        live: false,
+        prLinks: t.prLinks,
+    };
+    // A parked session keeps the branch it was on; only the useless "HEAD" stamp
+    // is replaced by the repo's current branch.
+    const out = withTranscriptExtras(s, t, undefined, undefined);
+    const recorded = out.branch && out.branch !== "HEAD" ? out.branch : undefined;
+    withGit(out, git);
+    if (recorded)
+        out.branch = recorded;
+    return out;
+}
+/** The repo on disk beats the transcript: its gitBranch is stamped once and goes stale. */
+function withGit(s, git) {
+    if (!git)
+        return s;
+    s.repo = basename(git.root);
+    s.repoRoot = git.root;
+    s.branch = git.branch;
+    return s;
+}
+function withTranscriptExtras(s, t, name, waitingFor) {
+    const title = t?.aiTitle ?? t?.agentName;
+    if (t?.gitBranch !== undefined)
+        s.branch = t.gitBranch;
+    if (title !== undefined)
+        s.title = title;
+    if (name !== undefined)
+        s.name = name;
+    if (waitingFor !== undefined)
+        s.waitingFor = waitingFor;
+    if (t?.continuedIn !== undefined)
+        s.continuedIn = t.continuedIn;
+    return s;
+}
+/** One entry per session id: the most recently updated live registry file wins. */
+function dedupe(entries) {
+    const best = new Map();
+    const at = (e) => e.updatedAt ?? e.statusUpdatedAt ?? 0;
+    for (const e of entries) {
+        const cur = best.get(e.sessionId);
+        if (!cur || at(e) > at(cur) || (at(e) === at(cur) && e.pid > cur.pid))
+            best.set(e.sessionId, e);
+    }
+    return [...best.values()];
+}
+export function createClaudeSource(opts = {}) {
+    const claudeDir = opts.claudeDir ?? join(homedir(), ".claude");
+    const sessionsDir = join(claudeDir, "sessions");
+    const projectsDir = join(claudeDir, "projects");
+    const isAlive = opts.isAlive ?? defaultIsAlive;
+    const pollMs = opts.pollMs ?? 5000;
+    const debounceMs = opts.debounceMs ?? 200;
+    const maxDormant = opts.maxDormant ?? 200;
+    const warn = onceLogger(opts.log ?? console.warn);
+    const scanner = new TranscriptScanner({ warn });
+    const git = new GitReader({ ttlMs: opts.gitTtlMs ?? 2000 });
+    const pathById = new Map();
+    /** A cwd seen in any transcript of a project dir, for transcripts without one. */
+    const cwdBySlug = new Map();
+    async function scan(path, slug) {
+        const t = await scanner.scan(path);
+        if (t?.cwd)
+            cwdBySlug.set(slug, t.cwd);
+        return t;
+    }
+    async function slugs() {
+        try {
+            return (await readdir(projectsDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    async function findTranscript(id) {
+        const cached = pathById.get(id);
+        if (cached && (await stat(cached).catch(() => undefined)))
+            return cached;
+        pathById.delete(id);
+        for (const slug of await slugs()) {
+            const p = join(projectsDir, slug, `${id}.jsonl`);
+            if (await stat(p).catch(() => undefined)) {
+                pathById.set(id, p);
+                return p;
+            }
+        }
+        return undefined;
+    }
+    async function liveEntries() {
+        const all = await readRegistry(sessionsDir, warn);
+        return dedupe(all.filter((e) => isLive(e, isAlive)));
+    }
+    async function list() {
+        const out = [];
+        for (const e of await liveEntries()) {
+            const path = await findTranscript(e.sessionId);
+            const t = path ? await scan(path, basename(join(path, ".."))) : undefined;
+            const cwd = e.cwd || t?.cwd || "";
+            out.push(liveSession(e, t, await git.get(cwd)));
+        }
+        return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    async function transcriptFiles() {
+        const out = [];
+        for (const slug of await slugs()) {
+            let entries;
+            try {
+                entries = await readdir(join(projectsDir, slug), { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const d of entries) {
+                if (!d.isFile() || !d.name.endsWith(".jsonl"))
+                    continue;
+                const path = join(projectsDir, slug, d.name);
+                const st = await stat(path).catch(() => undefined);
+                if (!st)
+                    continue;
+                const id = d.name.slice(0, -".jsonl".length);
+                pathById.set(id, path);
+                out.push({ id, slug, path, mtimeMs: st.mtimeMs });
+            }
+        }
+        return out;
+    }
+    /** Scans and maps files in order; with `limit`, skips superseded transcripts and stops after `limit`. */
+    async function toDormant(files, limit) {
+        const scanned = [];
+        for (const f of files) {
+            if (limit !== undefined && scanned.length >= limit)
+                break;
+            const t = await scan(f.path, f.slug);
+            if (!t)
+                continue;
+            // A continued-in line means the conversation moved to a background
+            // session; Claude Code hides these from /resume, so the picker does too.
+            if (limit !== undefined && t.continuedIn)
+                continue;
+            scanned.push([f, t]);
+        }
+        // Map after scanning all, so sibling cwds are known.
+        const out = [];
+        for (const [f, t] of scanned) {
+            const cwd = t.cwd ?? cwdBySlug.get(f.slug);
+            out.push(dormantSession(f, t, cwdBySlug.get(f.slug), cwd ? await git.get(cwd) : undefined));
+        }
+        return out;
+    }
+    async function listDormant() {
+        const live = new Set((await liveEntries()).map((e) => e.sessionId));
+        const files = (await transcriptFiles())
+            .filter((f) => !live.has(f.id))
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+        return toDormant(files, maxDormant);
+    }
+    async function get(id) {
+        const live = (await list()).find((s) => s.id === id);
+        if (live)
+            return live;
+        const path = await findTranscript(id);
+        if (!path)
+            return undefined;
+        const st = await stat(path).catch(() => undefined);
+        if (!st)
+            return undefined;
+        const slug = basename(join(path, ".."));
+        if (!cwdBySlug.has(slug)) {
+            // Learn a fallback cwd from a sibling transcript when this one has none.
+            const t = await scan(path, slug);
+            if (!t?.cwd)
+                await toDormant((await transcriptFiles()).filter((f) => f.slug === slug && f.id !== id).slice(0, 5));
+        }
+        const [s] = await toDormant([{ id, slug, path, mtimeMs: st.mtimeMs }]);
+        return s;
+    }
+    function watch(cb) {
+        let closed = false;
+        let running = false;
+        let again = false;
+        let last;
+        let debounce;
+        let watcher;
+        const refresh = async () => {
+            if (running) {
+                again = true;
+                return;
+            }
+            running = true;
+            try {
+                do {
+                    again = false;
+                    const sessions = await list();
+                    if (closed)
+                        return;
+                    const key = JSON.stringify(sessions);
+                    if (key !== last) {
+                        last = key;
+                        try {
+                            cb(sessions);
+                        }
+                        catch (e) {
+                            warn(`excaliagent: session watcher callback threw: ${e.message}`, "watch-callback");
+                        }
+                    }
+                } while (again && !closed);
+            }
+            catch (e) {
+                warn(`excaliagent: refreshing Claude sessions failed: ${e.message}`, "refresh");
+            }
+            finally {
+                running = false;
+            }
+        };
+        const kick = () => {
+            if (closed)
+                return;
+            clearTimeout(debounce);
+            debounce = setTimeout(() => void refresh(), debounceMs);
+        };
+        const ensureWatcher = () => {
+            if (watcher || closed)
+                return;
+            try {
+                watcher = fsWatch(sessionsDir, kick);
+                watcher.on("error", () => {
+                    watcher?.close();
+                    watcher = undefined;
+                });
+            }
+            catch {
+                watcher = undefined; // dir missing; the poll retries
+            }
+        };
+        ensureWatcher();
+        const poll = setInterval(() => {
+            ensureWatcher();
+            void refresh();
+        }, pollMs);
+        void refresh();
+        return () => {
+            closed = true;
+            clearInterval(poll);
+            clearTimeout(debounce);
+            watcher?.close();
+            watcher = undefined;
+        };
+    }
+    return { list, listDormant, get, watch };
+}

package/dist/server/sources/git.js

@@ -0,0 +1,65 @@
+// Reads the current branch straight from a repo's HEAD (no git subprocess).
+// Claude Code stamps gitBranch once per session, so the transcript goes stale.
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+async function gitDirAt(dir) {
+    const dotGit = join(dir, ".git");
+    const st = await stat(dotGit).catch(() => undefined);
+    if (!st)
+        return undefined;
+    if (st.isDirectory())
+        return dotGit;
+    if (!st.isFile())
+        return undefined;
+    const text = await readFile(dotGit, "utf8").catch(() => "");
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(text);
+    if (!m)
+        return undefined;
+    return isAbsolute(m[1]) ? m[1] : resolve(dir, m[1]);
+}
+export function parseHead(text) {
+    const t = text.trim();
+    const ref = /^ref:\s*(\S+)$/.exec(t);
+    if (ref)
+        return ref[1].replace(/^refs\/heads\//, "");
+    if (/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(t))
+        return t.slice(0, 7);
+    return undefined;
+}
+/** Walks up from cwd to the nearest `.git`; undefined if none or HEAD is unreadable. */
+export async function readGitInfo(cwd) {
+    if (!cwd || !isAbsolute(cwd))
+        return undefined;
+    let dir = resolve(cwd);
+    for (;;) {
+        const gitDir = await gitDirAt(dir);
+        if (gitDir) {
+            const head = await readFile(join(gitDir, "HEAD"), "utf8").catch(() => undefined);
+            const branch = head === undefined ? undefined : parseHead(head);
+            return branch ? { root: dir, branch } : undefined;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Per-cwd cache: each cwd is re-read at most every ttlMs. */
+export class GitReader {
+    cache = new Map();
+    ttlMs;
+    now;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? 2000;
+        this.now = opts.now ?? Date.now;
+    }
+    get(cwd) {
+        const hit = this.cache.get(cwd);
+        const now = this.now();
+        if (hit && now - hit.at < this.ttlMs)
+            return hit.value;
+        const value = readGitInfo(cwd).catch(() => undefined);
+        this.cache.set(cwd, { at: now, value });
+        return value;
+    }
+}

package/dist/server/sources/log.js

@@ -0,0 +1,10 @@
+/** Wraps a logger so each key is reported at most once. */
+export function onceLogger(log) {
+    const seen = new Set();
+    return (message, key) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        log(message);
+    };
+}