chamba 0.3.0 → 0.4.0

package/templates/webterm/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "webterm",
+    "version": "0.1.0",
+    "private": true,
+    "description": "Browser front-end for the interactive agent CLIs (claude, opencode, codex) inside a chamba container (PTY relay + rich composer).",
+    "type": "module",
+    "scripts": {
+        "start": "node server.js"
+    },
+    "dependencies": {
+        "@xterm/addon-fit": "^0.10.0",
+        "@xterm/xterm": "^5.5.0",
+        "express": "^4.21.2",
+        "node-pty": "^1.0.0",
+        "ws": "^8.18.0"
+    }
+}

package/templates/webterm/pane.js

@@ -0,0 +1,156 @@
+// pane.js - Which conversation's pages a session is looking at.
+//
+// The store (artifacts.js) knows about directories and the discovery (conversation.js) knows about agents.
+// This is the piece between them: every live session gets a key, the key becomes the agent's own conversation
+// id as soon as the agent has written one down, and the pages follow.
+//
+// A session that has just started has no id yet - the agent writes its first record a moment later - so it
+// gets a provisional key and can publish immediately. When the id turns up, the provisional directory is
+// adopted into the id's own, and from then on the conversation carries its pages wherever it is resumed.
+//
+// Two sessions never share a directory. If a conversation is resumed while another live session already holds
+// its key, the second session is refused the adoption and keeps its provisional key for the rest of its life,
+// with a notice the pane can show - two writers on one directory would interleave the page numbering, and the
+// user would be reading two conversations as if they were one.
+
+import { randomBytes } from "node:crypto";
+import { isPaneKey } from "./artifacts.js";
+import { conversationId } from "./conversation.js";
+
+// The shape a key has before an agent has told us its real one. Distinguishable on disk at a glance, and
+// narrow enough to pass the store's own name check.
+const PROVISIONAL_PREFIX = "pending-";
+
+// How many sessions the key map remembers. Entries outlive their session on purpose: feedback submitted after
+// an agent exited still has to land in the right directory. The cap only keeps a container that has been up
+// for weeks from growing the map without end.
+const MAX_REMEMBERED = 64;
+
+/** True for a key this server invented rather than one an agent owns. */
+export function isProvisional(key) {
+    return typeof key === "string" && key.startsWith(PROVISIONAL_PREFIX);
+}
+
+/**
+ * The pane's session bookkeeping.
+ *
+ * - `store` is the artifacts store.
+ * - `stores` is where each agent writes its conversation id (config's AGENT_STORES).
+ * - `sessions()` returns the live sessions as `{ sid, agent, cwd, pid, since }` - everything the discovery
+ *   needs, handed in rather than reached for, so this file needs no registry and no PTYs to be tested.
+ * - `onChange(sid)` is called whenever that session's page list moved, for whatever reason.
+ */
+export function createPane({ store, stores, sessions, onChange }) {
+    // sid -> { key, adopted, refused }. `adopted` means the key is the agent's own conversation id, so the
+    // discovery is done with this session; `refused` means it found one and could not have it.
+    const bySession = new Map();
+
+    function forget() {
+        if (bySession.size <= MAX_REMEMBERED) return;
+        const live = new Set(sessions().map((session) => session.sid));
+        for (const sid of bySession.keys()) {
+            if (bySession.size <= MAX_REMEMBERED) return;
+            if (!live.has(sid)) bySession.delete(sid);
+        }
+    }
+
+    /** The key this session's pages are filed under, assigning a provisional one the first time it is asked. */
+    function keyFor(sid) {
+        const known = bySession.get(sid);
+        if (known) return known.key;
+        const entry = { key: `${PROVISIONAL_PREFIX}${randomBytes(4).toString("hex")}`, adopted: false, refused: false };
+        bySession.set(sid, entry);
+        forget();
+        return entry.key;
+    }
+
+    /** Why this session's pane is not the conversation's own, when it is not: "shared", else null. */
+    function noticeFor(sid) {
+        return bySession.get(sid)?.refused === true ? "shared" : null;
+    }
+
+    /** Every key a live session currently holds, so an adoption can tell a free conversation from a taken one. */
+    function liveKeys(exceptSid) {
+        const taken = new Set();
+        for (const session of sessions()) {
+            if (session.sid === exceptSid) continue;
+            const entry = bySession.get(session.sid);
+            if (entry) taken.add(entry.key);
+        }
+        return taken;
+    }
+
+    /**
+     * Ask the agent, once more, which conversation this session is having, and move its pages under that id
+     * when the answer arrives. Returns true when the session's pane changed.
+     */
+    function discover(session) {
+        const entry = bySession.get(session.sid);
+        if (!entry || entry.adopted || entry.refused) return false;
+        const id = conversationId(session, stores);
+        if (id === null || id === entry.key) return false;
+        // An id that cannot be a directory name is not one we can file under. The name only: creating the
+        // directory here would leave the adoption nothing to rename into, and it makes its own directory.
+        if (!isPaneKey(id)) return false;
+        if (liveKeys(session.sid).has(id)) {
+            // Someone else is already having this conversation in another tab. Say so once and stop asking.
+            entry.refused = true;
+            console.log(
+                `[webterm] pane: ${session.sid} resumed a conversation another session already holds - keeping its own pages apart`,
+            );
+            return true;
+        }
+        if (!store.adopt(entry.key, id)) return false;
+        entry.key = id;
+        entry.adopted = true;
+        return true;
+    }
+
+    /**
+     * One pass over the live sessions: find the conversation ids that have appeared, and look at the
+     * directories again for pages written by hand. Called on a timer by the server; every session whose pane
+     * moved is reported through `onChange`.
+     */
+    function sweep() {
+        for (const session of sessions()) {
+            // A session that has never published has no key yet, and the discovery works on keys - so this is
+            // also where a session started a moment ago joins the pane at all.
+            keyFor(session.sid);
+            const changed = discover(session);
+            const rescanned = store.refresh(keyFor(session.sid));
+            if (changed || rescanned) onChange?.(session.sid);
+        }
+    }
+
+    /** The pages of the session's pane, and the notice that goes with it. */
+    function pages(sid) {
+        return { pages: store.list(keyFor(sid)), notice: noticeFor(sid) };
+    }
+
+    /** Publish into this session's pane. The page is new, so whoever is watching hears about it at once. */
+    function publish(sid, page) {
+        const result = store.publish(keyFor(sid), page);
+        if (result.ok) onChange?.(sid);
+        return result;
+    }
+
+    /** Read one page of this session's pane, and count it as read. */
+    function read(sid, id) {
+        const key = keyFor(sid);
+        const result = store.read(key, id);
+        if (result.ok && store.markRead(key, id)) onChange?.(sid);
+        return result;
+    }
+
+    /** File a submission from one of this session's pages. The caller has already checked the page exists. */
+    function feedback(sid, id, submission) {
+        return store.writeFeedback(keyFor(sid), id, submission);
+    }
+
+    /** Whether this session has a pane at all. A sid nobody has seen gets no directory made for it. */
+    function knows(sid) {
+        return bySession.has(sid);
+    }
+
+    return { discover, feedback, keyFor, knows, noticeFor, pages, publish, read, sweep };
+}

package/templates/webterm/proc.js

@@ -0,0 +1,89 @@
+// proc.js - The few things the server needs to know about processes, read from /proc.
+//
+// Two questions come up, and both are about identity rather than about process control. "Did this publish
+// come from inside a session?" - a helper hands over its own pid and the server checks whether one of the
+// pids it already knows is above it in the tree, because a caller naming a session directly would be a value
+// the server has to trust. "Is this snapshot this session's?" - the same walk, plus the start time, which is
+// what tells a live pid from a recycled one on a bind-mounted directory that outlived the container that
+// wrote it.
+//
+// Everything here fails towards "no": an unreadable /proc entry, a pid that is gone, a tree that is deeper
+// than any real one - all of them answer null or false rather than throwing, because the caller's next move
+// is always to refuse.
+
+import { readFileSync } from "node:fs";
+
+// A process tree in a container is a handful of levels deep. The cap is what keeps a malformed /proc, or a
+// cycle that should not exist, from spinning here.
+const MAX_ANCESTRY_DEPTH = 64;
+
+// Where the process table is read from. Always /proc in the container; a fixture tree in the tests, which is
+// the only way to exercise a tree shape the test host does not happen to have.
+const PROC_ROOT = process.env.WEBTERM_PROC_ROOT || "/proc";
+
+/**
+ * The fields of /proc/<pid>/stat after the command name, or null when the process is gone.
+ *
+ * The command name is the reason this is not a plain split: it is wrapped in parentheses and may itself hold
+ * spaces and parentheses ("(node (deleted))"), so everything up to the LAST ") " is skipped. What is left
+ * starts at the state field, which makes the parent pid field 2 and the start time field 20 - the same
+ * offsets the shell helpers use, counted the same way.
+ */
+function statFields(pid) {
+    let line;
+    try {
+        line = readFileSync(`${PROC_ROOT}/${pid}/stat`, "utf8");
+    } catch {
+        return null;
+    }
+    const end = line.lastIndexOf(") ");
+    if (end === -1) return null;
+    return line
+        .slice(end + 2)
+        .trim()
+        .split(/\s+/);
+}
+
+/** The pid that started this one, or null when it is gone or unreadable. */
+export function parentPid(pid) {
+    const fields = statFields(pid);
+    const parent = Number(fields?.[1]);
+    return Number.isInteger(parent) && parent > 0 ? parent : null;
+}
+
+/**
+ * When a process started, in jiffies since boot (/proc/<pid>/stat field 22), or null when it is gone.
+ * Pids are recycled; a pid plus its start time is not, which is what makes this worth reading.
+ */
+export function processStart(pid) {
+    const fields = statFields(pid);
+    const started = Number(fields?.[19]);
+    return Number.isInteger(started) ? started : null;
+}
+
+/** True when `pid` is `ancestor` itself or anything it started, however many levels down. */
+export function isSelfOrDescendant(pid, ancestor) {
+    if (!Number.isInteger(pid) || !Number.isInteger(ancestor) || pid < 1 || ancestor < 1) return false;
+    let current = pid;
+    for (let depth = 0; depth < MAX_ANCESTRY_DEPTH; depth++) {
+        if (current === ancestor) return true;
+        if (current <= 1) return false;
+        const parent = parentPid(current);
+        if (parent === null) return false;
+        current = parent;
+    }
+    return false;
+}
+
+/**
+ * Whether a process that recorded itself as `pid` started at `start` is still that same process. A snapshot
+ * written before a container restart can name a pid that something else holds now, and the start time is
+ * what tells the two apart. A record with no start time is taken at face value: it is older than the field,
+ * not suspect.
+ */
+export function isSameProcess(pid, start) {
+    if (!Number.isInteger(pid) || pid < 1) return false;
+    if (start === null || start === undefined) return processStart(pid) !== null;
+    const live = processStart(pid);
+    return live !== null && live === Number(start);
+}