excaliagent 0.2.0 → 0.4.0

package/dist/server/http.js

@@ -3,7 +3,12 @@ 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";
+import { validFile } from "./scene-store.js";
+import { StatusError } from "./characters.js";
+/** Cookies ignore the port, so the name carries it: two boards never clobber each other. */
+export const cookieName = (port) => `excaliagent_token_${port}`;
+/** The token is stable per state dir (token.ts), so the cookie may outlive a restart. */
+const COOKIE_MAX_AGE = 365 * 24 * 3600;
 const MAX_BODY = 50 * 1024 * 1024;
 const TYPES = {
     ".html": "text/html; charset=utf-8",
@@ -33,10 +38,10 @@ function sameToken(a, b) {
     const y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
 }
-function cookieToken(req) {
+function cookieToken(req, port) {
     for (const part of (req.headers.cookie ?? "").split(";")) {
         const [k, ...v] = part.trim().split("=");
-        if (k === COOKIE)
+        if (k === cookieName(port))
             return v.join("=");
     }
     return undefined;
@@ -49,15 +54,21 @@ function text(res, status, body) {
     res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
     res.end(body);
 }
-async function readJson(req) {
+/** Body limits of the character and pack routes: an image upload, everything else. */
+export const IMAGE_BODY_LIMIT = 1536 * 1024;
+export const SMALL_BODY_LIMIT = 64 * 1024;
+async function readJson(req, limit = MAX_BODY) {
     if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
         throw new HttpError(415, "expected application/json");
     }
+    // Refuse a declared oversize body before reading any of it.
+    if (Number(req.headers["content-length"] ?? 0) > limit)
+        throw new HttpError(413, "body too large");
     const chunks = [];
     let size = 0;
     for await (const chunk of req) {
         size += chunk.length;
-        if (size > MAX_BODY)
+        if (size > limit)
             throw new HttpError(413, "body too large");
         chunks.push(chunk);
     }
@@ -118,9 +129,77 @@ export function createAppServer(opts) {
             unsubscribe();
         });
     }
-    async function api(req, res, pathname) {
+    /** GET /api/packs/<pack>/<file>: a custom pack's image, only if that pack lists it. */
+    async function packImage(res, rest, version) {
+        const parts = rest.split("/");
+        if (parts.length !== 2)
+            return json(res, 404, { error: "not found" });
+        let pack, file;
+        try {
+            [pack, file] = parts.map((p) => decodeURIComponent(p));
+        }
+        catch {
+            throw new HttpError(400, "bad path");
+        }
+        const img = await opts.characters.readImage(pack, file);
+        if (!img)
+            return json(res, 404, { error: "not found" });
+        res.writeHead(200, {
+            "content-type": img.mimeType,
+            // `?v=<content hash>` (from the pack listing) names these exact bytes.
+            "cache-control": version === img.hash ? "private, max-age=31536000, immutable" : "no-store",
+            "x-content-type-options": "nosniff",
+            // An SVG opened directly must not run scripts on our origin.
+            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+        });
+        res.end(img.bytes);
+    }
+    async function api(req, res, pathname, search) {
         const route = `${req.method} ${pathname}`;
+        if (req.method === "GET" && pathname.startsWith("/api/packs/"))
+            return packImage(res, pathname.slice("/api/packs/".length), search.get("v"));
+        const chars = opts.characters;
+        const body = async () => {
+            const b = await readJson(req, pathname === "/api/packs/image" ? IMAGE_BODY_LIMIT : SMALL_BODY_LIMIT);
+            if (!b || typeof b !== "object")
+                throw new HttpError(400, "expected a JSON object");
+            return b;
+        };
         switch (route) {
+            case "GET /api/characters":
+                return json(res, 200, await chars.load());
+            case "POST /api/characters/assign": {
+                const b = await body();
+                return json(res, 200, await chars.assign(b.pack, b.assign));
+            }
+            case "POST /api/characters/override": {
+                const b = await body();
+                return json(res, 200, await chars.override(b.sessionId, (b.character ?? null)));
+            }
+            case "POST /api/characters/active":
+                return json(res, 200, await chars.setActive((await body()).pack));
+            case "POST /api/packs": {
+                const b = await body();
+                return json(res, 200, await chars.createPack(b.name, (b.from ?? undefined)));
+            }
+            case "POST /api/packs/rename": {
+                const b = await body();
+                return json(res, 200, await chars.renamePack(b.pack, b.name));
+            }
+            case "POST /api/packs/delete":
+                return json(res, 200, await chars.deletePack((await body()).pack));
+            case "POST /api/packs/emoji": {
+                const b = await body();
+                return json(res, 200, await chars.addEmoji(b.pack, b.emoji));
+            }
+            case "POST /api/packs/image": {
+                const b = await body();
+                return json(res, 200, await chars.addImage(b.pack, b.name, b.dataURL));
+            }
+            case "POST /api/packs/remove": {
+                const b = await body();
+                return json(res, 200, await chars.removeCharacter(b.pack, b.id));
+            }
             case "GET /api/sessions":
                 return json(res, 200, opts.hub.sessions());
             case "GET /api/events":
@@ -145,6 +224,38 @@ export function createAppServer(opts) {
                 res.writeHead(204).end();
                 return;
             }
+            case "PUT /api/files": {
+                const body = (await readJson(req));
+                if (!Array.isArray(body?.files))
+                    throw new HttpError(400, "files must be an array");
+                const bad = body.files.map(validFile).find((f) => f instanceof Error);
+                if (bad)
+                    throw new HttpError(400, bad.message);
+                await opts.scenes.saveFiles(body.files);
+                res.writeHead(204).end();
+                return;
+            }
+            case "POST /api/files/get": {
+                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.scenes.loadFiles(body.ids));
+            }
+            case "POST /api/end": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string" || !SESSION_ID.test(body.sessionId)) {
+                    throw new HttpError(400, "sessionId must be a session id");
+                }
+                const result = await opts.hub.end(body.sessionId);
+                if (result === "ended") {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (result === "unsupported")
+                    return json(res, 501, { error: "unsupported" });
+                return json(res, 409, { error: "not running" });
+            }
             case "POST /api/focus": {
                 const body = (await readJson(req));
                 if (typeof body?.sessionId !== "string")
@@ -158,7 +269,7 @@ export function createAppServer(opts) {
             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");
+                    throw new HttpError(400, "sessionId must be a session id");
                 }
                 const result = await opts.hub.resume(body.sessionId);
                 if (result === "resumed") {
@@ -189,23 +300,23 @@ export function createAppServer(opts) {
                 return text(res, 401, "bad token");
             res.writeHead(302, {
                 location: "/",
-                "set-cookie": `${COOKIE}=${opts.token}; HttpOnly; SameSite=Strict; Path=/`,
+                "set-cookie": `${cookieName(port)}=${opts.token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${COOKIE_MAX_AGE}`,
             });
             res.end();
             return;
         }
-        if (!sameToken(cookieToken(req), opts.token)) {
+        if (!sameToken(cookieToken(req, port), 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);
+            return api(req, res, url.pathname, url.searchParams);
         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;
+            const status = err instanceof HttpError || err instanceof StatusError ? err.status : 500;
             if (status === 500)
                 console.error("excaliagent:", err);
             if (!res.headersSent)

package/dist/server/hub.js

@@ -1,5 +1,10 @@
-/** Claude session ids are UUIDs; anything else is never put into a command. */
-export const SESSION_ID = /^[0-9a-f-]{36}$/i;
+/**
+ * The id formats of every supported harness (Claude and Codex: UUIDs;
+ * OpenCode: `ses_` + 26 alphanumerics).
+ * Anything else is refused before it reaches a source or the characters store;
+ * each source also checks its own exact format before an id goes into a command.
+ */
+export const SESSION_ID = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|ses_[0-9a-zA-Z]{26})$/i;
 const LABEL_MAX = 40;
 function resumeLabel(s) {
     const title = s.title?.trim();
@@ -80,16 +85,25 @@ export function createHub({ source, panes }) {
                 return "unknown";
             if (s.live)
                 return "live";
+            if (!s.resumeCommand)
+                return "unknown";
             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}`,
+                command: s.resumeCommand,
                 label: resumeLabel(s),
             });
             return "resumed";
         },
+        async end(sessionId) {
+            if (!SESSION_ID.test(sessionId))
+                return "unknown";
+            if (!source.end)
+                return "unsupported";
+            return source.end(sessionId);
+        },
         async focus(sessionId) {
             const pane = current.find((s) => s.id === sessionId)?.pane;
             if (!pane)

package/dist/server/instance.js

@@ -0,0 +1,52 @@
+// One board per state dir: two servers saving the same scene.json would
+// overwrite each other's edits. A running server records its port and pid in
+// <stateDir>/server.json; a second start finds it (pid alive, and it answers to
+// this state dir's token) and opens that board instead of starting another.
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cookieName } from "./http.js";
+const recordPath = (stateDir) => join(stateDir, "server.json");
+export async function recordRunning(stateDir, port, pid = process.pid) {
+    await writeFile(recordPath(stateDir), JSON.stringify({ port, pid }), { mode: 0o600 });
+}
+/** Removes the record if it is `pid`'s (a newer server may have replaced it). */
+export async function clearRunning(stateDir, pid = process.pid) {
+    const r = await readRecord(stateDir);
+    if (r?.pid === pid)
+        await rm(recordPath(stateDir), { force: true });
+}
+async function readRecord(stateDir) {
+    try {
+        const r = JSON.parse(await readFile(recordPath(stateDir), "utf8"));
+        return Number.isInteger(r.port) && Number.isInteger(r.pid) ? r : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** The port of a live board serving this state dir, if any. */
+export async function findRunning(stateDir, token) {
+    const r = await readRecord(stateDir);
+    if (!r || !alive(r.pid))
+        return undefined;
+    try {
+        const res = await fetch(`http://127.0.0.1:${r.port}/api/sessions`, {
+            headers: { cookie: `${cookieName(r.port)}=${token}` },
+            signal: AbortSignal.timeout(1500),
+        });
+        await res.body?.cancel();
+        return res.ok ? r.port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/panes/herdr.js

@@ -50,15 +50,40 @@ 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()) {
+/**
+ * pid → pane for every foreground process of every pane; `panes` supplies ids
+ * and labels. With `procs` (the process table), every descendant of a pane's
+ * shell maps to that pane too: a session is not always in the foreground (a
+ * command it runs can take the terminal, or it is suspended). Foreground wins.
+ */
+export function parsePaneMap(infos, panes = new Map(), procs = []) {
     const map = new Map();
+    const byShell = 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);
         }
+        if (typeof info.shell_pid === "number")
+            byShell.set(info.shell_pid, pane);
+    }
+    if (!byShell.size)
+        return map;
+    const children = new Map();
+    for (const p of procs)
+        children.set(p.ppid, [...(children.get(p.ppid) ?? []), p.pid]);
+    const seen = new Set(); // a pid is walked once, even if the table has a cycle
+    for (const [shell, pane] of byShell) {
+        const todo = [...(children.get(shell) ?? [])];
+        for (let pid = todo.pop(); pid !== undefined; pid = todo.pop()) {
+            if (seen.has(pid))
+                continue;
+            seen.add(pid);
+            if (!map.has(pid))
+                map.set(pid, pane);
+            todo.push(...(children.get(pid) ?? []));
+        }
     }
     return map;
 }
@@ -150,6 +175,7 @@ export function createHerdrLink(opts = {}) {
             panes.set(p.pane_id, pane);
         }
         const panesList = list;
+        const procs = table.list().catch(() => []);
         const infos = await Promise.all(panesList.map(async (p) => {
             try {
                 const res = (await client.request("pane.process_info", { pane_id: p.pane_id }));
@@ -161,7 +187,7 @@ export function createHerdrLink(opts = {}) {
         }));
         if (closed || !client.connected())
             return;
-        setMap(parsePaneMap(infos.filter((i) => !!i), panes));
+        setMap(parsePaneMap(infos.filter((i) => !!i), panes, await procs));
     }
     // Coalesce: at most one build running, plus one queued behind it.
     let running;

package/dist/server/scene-store.js

@@ -1,28 +1,50 @@
-import { mkdir, open, readFile, rename } from "node:fs/promises";
+import { mkdir, open, readFile, rename, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+/** Excalidraw file ids: hex hashes or nanoids. Also keeps paths inside files/. */
+export const FILE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const IMAGE_MIME = /^image\/[a-z0-9.+-]+$/;
+/** A clean StoredFile, or an Error naming the bad field. */
+export function validFile(f) {
+    const x = f;
+    if (typeof x?.id !== "string" || !FILE_ID.test(x.id))
+        return new Error("file id must match " + FILE_ID);
+    if (typeof x.mimeType !== "string" || !IMAGE_MIME.test(x.mimeType))
+        return new Error("file mimeType must be image/*");
+    if (typeof x.dataURL !== "string" || !x.dataURL.startsWith(`data:${x.mimeType}`)) {
+        return new Error("file dataURL must be a data: URL of its mimeType");
+    }
+    return { id: x.id, mimeType: x.mimeType, dataURL: x.dataURL, created: typeof x.created === "number" ? x.created : 0 };
+}
 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. */
+/**
+ * scene.json in stateDir, written atomically (temp file + fsync + rename), saves
+ * serialized. Image files live apart, one files/<id>.json each, written once.
+ */
 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 filesDir = join(stateDir, "files");
+    async function writeAtomic(target, data) {
+        const tmp = `${target}.tmp-${process.pid}-${seq++}`;
         const fh = await open(tmp, "w", 0o600);
         try {
-            await fh.writeFile(JSON.stringify(scene));
+            await fh.writeFile(JSON.stringify(data));
             await fh.sync();
         }
         finally {
             await fh.close();
         }
-        await rename(tmp, path);
+        await rename(tmp, target);
+    }
+    async function write(scene) {
+        await mkdir(stateDir, { recursive: true });
+        await writeAtomic(path, scene);
     }
     return {
         path,
@@ -57,5 +79,34 @@ export function createSceneStore(stateDir, log = console) {
             queue = run.catch(() => { });
             return run;
         },
+        async saveFiles(files) {
+            const valid = files.map(validFile);
+            const bad = valid.find((f) => f instanceof Error);
+            if (bad)
+                throw bad;
+            await mkdir(filesDir, { recursive: true });
+            for (const f of valid) {
+                const target = join(filesDir, `${f.id}.json`);
+                if (await stat(target).catch(() => undefined))
+                    continue;
+                await writeAtomic(target, f);
+            }
+        },
+        async loadFiles(ids) {
+            const out = [];
+            for (const id of ids) {
+                if (!FILE_ID.test(id))
+                    continue;
+                try {
+                    const f = validFile(JSON.parse(await readFile(join(filesDir, `${id}.json`), "utf8")));
+                    if (!(f instanceof Error) && f.id === id)
+                        out.push(f);
+                }
+                catch {
+                    // missing or unreadable: the image shows as a placeholder
+                }
+            }
+            return out;
+        },
     };
 }

package/dist/server/sources/claude.js

@@ -5,10 +5,23 @@ 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 { createProcessTable } from "../desktop/process-table.js";
 import { GitReader } from "./git.js";
 import { onceLogger } from "./log.js";
 import { defaultIsAlive, isLive, readRegistry } from "./registry.js";
 import { TranscriptScanner } from "./transcript.js";
+/** A Claude Code process: its executable, argv[0], or script (node cli.js) names claude. */
+export function looksLikeClaude(argv, exe) {
+    const names = [argv?.[0] && basename(argv[0]), exe && basename(exe)];
+    return names.some((n) => !!n && /claude/i.test(n)) || /claude/i.test(argv?.[1] ?? "");
+}
+function defaultIsClaudeProcess() {
+    const table = createProcessTable();
+    return async (pid) => looksLikeClaude(await table.argv(pid), await table.exe(pid));
+}
+/** Claude session ids are UUIDs; anything else is never put into a command. */
+export const CLAUDE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const claudeResumeCommand = (id) => `claude --resume ${id}`;
 const LIVE_STATUSES = new Set([
     "busy", "idle", "waiting", "needs_user", "needs_trust", "blocked",
 ]);
@@ -26,6 +39,8 @@ export function liveSession(e, t, git) {
         live: true,
         pid: e.pid,
         prLinks: t?.prLinks ?? [],
+        resumeCommand: claudeResumeCommand(e.sessionId),
+        canEnd: true,
     };
     return withGit(withTranscriptExtras(s, t, e.name, e.waitingFor), git);
 }
@@ -42,6 +57,7 @@ export function dormantSession(f, t, fallbackCwd, git) {
         cacheExpiresAt: t.cacheExpiresAt,
         live: false,
         prLinks: t.prLinks,
+        resumeCommand: claudeResumeCommand(f.id),
     };
     // A parked session keeps the branch it was on; only the useless "HEAD" stamp
     // is replaced by the repo's current branch.
@@ -97,6 +113,8 @@ export function createClaudeSource(opts = {}) {
     const warn = onceLogger(opts.log ?? console.warn);
     const scanner = new TranscriptScanner({ warn });
     const git = new GitReader({ ttlMs: opts.gitTtlMs ?? 2000 });
+    const isClaudeProcess = opts.isClaudeProcess ?? defaultIsClaudeProcess();
+    const kill = opts.kill ?? ((pid, signal) => process.kill(pid, signal));
     const pathById = new Map();
     /** A cwd seen in any transcript of a project dir, for transcripts without one. */
     const cwdBySlug = new Map();
@@ -197,6 +215,8 @@ export function createClaudeSource(opts = {}) {
         return toDormant(files, maxDormant);
     }
     async function get(id) {
+        if (!CLAUDE_ID.test(id))
+            return undefined;
         const live = (await list()).find((s) => s.id === id);
         if (live)
             return live;
@@ -288,5 +308,20 @@ export function createClaudeSource(opts = {}) {
             watcher = undefined;
         };
     }
-    return { list, listDormant, get, watch };
+    /** SIGTERM, as when its terminal closes: Claude Code exits and keeps the transcript. */
+    async function end(id) {
+        if (!CLAUDE_ID.test(id))
+            return "not-live";
+        const e = (await liveEntries()).find((x) => x.sessionId === id);
+        if (!e || !(await isClaudeProcess(e.pid).catch(() => false)))
+            return "not-live";
+        try {
+            kill(e.pid, "SIGTERM");
+        }
+        catch {
+            return "not-live"; // exited in the meantime
+        }
+        return "ended";
+    }
+    return { list, listDormant, get, watch, end };
 }