chamba 0.3.1 → 0.4.0

package/dist/lib/webterm.js

@@ -0,0 +1,490 @@
+// =========================================================================================================================================
+// src/lib/webterm.ts - Host-side logic for the web agent interface (webterm)
+// Sticky per-workspace host-port assignment from the global web_range, plus the container hooks that
+// plant the resume marker and start the baked webterm server once per container start.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { AGENT_RESUME_COMMAND, AGENTS_DIR, CONTAINER_USER, CONTAINER_WEBPANE_DIR, CONTAINER_WEBTERM_STATE_DIR, CONTAINER_WORKSPACE, DEFAULT_WEB_AGENT, RESUME_MARKER_PATH, WEB_AGENTS, WEB_KEY_FILE_PATH, WEBPANE_DIR, WEBTERM_AGENT_FILE, WEBTERM_STATE_DIR, } from "./constants.js";
+import { canBind, containerPublishedPorts, dockerPublishedPorts, PORT_LOOPBACK_HOST } from "./ports.js";
+import { listWorkspaceIds, readWebPort, writeWebPort } from "./workspace-identity.js";
+// --- Port assignment (pure over the .lock files) -----------------------------------------------------------------------------------------
+/** Every web port currently assigned to a workspace, optionally excluding one workspace's own assignment. */
+export function collectAssignedWebPorts(excludeWorkspaceId) {
+    const taken = new Set();
+    for (const id of listWorkspaceIds()) {
+        if (id === excludeWorkspaceId)
+            continue;
+        const port = readWebPort(id);
+        if (port !== null)
+            taken.add(port);
+    }
+    return taken;
+}
+/** Lowest port in the range not already taken, or null when the range is exhausted. */
+export function nextFreeWebPort(range, taken) {
+    for (let port = range.start; port <= range.end; port++) {
+        if (!taken.has(port))
+            return port;
+    }
+    return null;
+}
+/**
+ * Return a workspace's sticky web port, assigning the lowest free port in the range when it has none.
+ * An already-assigned port is returned as-is even when it falls outside the range - stickiness wins;
+ * out-of-range ports move only when the user changes the range (reassignOutOfRangeWebPorts).
+ * This is pure over the .lock files: it never probes the host, so it can say a port is assigned but not
+ * that it can be published. resolveWebPort adds that.
+ */
+export function ensureWebPort(workspaceId, range) {
+    const existing = readWebPort(workspaceId);
+    if (existing !== null)
+        return { ok: true, port: existing };
+    const port = nextFreeWebPort(range, collectAssignedWebPorts(workspaceId));
+    if (port === null)
+        return { ok: false, reason: "exhausted" };
+    // A port that could not be recorded must not be used: it would be invisible to the next
+    // workspace's scan and handed out twice.
+    if (!writeWebPort(workspaceId, port))
+        return { ok: false, reason: "unrecorded" };
+    return { ok: true, port };
+}
+/**
+ * The host port this workspace's web interface should publish this session.
+ *
+ * `usable(port)` is the caller's test for "can this port carry the interface right now" - it covers both
+ * the host-side probe and any host port the workspace already declares in chamba.yaml. When the sticky
+ * assignment fails that test the port MOVES and the new one is persisted: sticky means it stays where it
+ * was last put, not that it stays somewhere unusable and warns about the same conflict at every start.
+ * When nothing in the range qualifies the old assignment is left alone rather than cleared, so the
+ * workspace keeps its identity and picks the port back up once the conflict clears.
+ */
+export async function resolveWebPort(workspaceId, range, usable) {
+    const assigned = ensureWebPort(workspaceId, range);
+    if (!assigned.ok)
+        return { ok: false, reason: assigned.reason, keptPort: readWebPort(workspaceId) };
+    if (await usable(assigned.port))
+        return { ok: true, port: assigned.port };
+    const taken = collectAssignedWebPorts(workspaceId);
+    for (let port = range.start; port <= range.end; port++) {
+        if (port === assigned.port || taken.has(port))
+            continue;
+        if (!(await usable(port)))
+            continue;
+        // Same rule as the first assignment: a port that could not be recorded must not be handed out.
+        if (!writeWebPort(workspaceId, port))
+            return { ok: false, reason: "unrecorded", keptPort: assigned.port };
+        return { ok: true, port, movedFrom: assigned.port };
+    }
+    return { ok: false, reason: "exhausted", keptPort: assigned.port };
+}
+/**
+ * Range-change walk: move only the sticky ports that fall outside the new range to the lowest free
+ * in-range port. In-range assignments are never touched. Returns the moves that were made.
+ */
+export function reassignOutOfRangeWebPorts(range) {
+    const moves = [];
+    for (const workspaceId of listWorkspaceIds()) {
+        const current = readWebPort(workspaceId);
+        if (current === null || (current >= range.start && current <= range.end))
+            continue;
+        const port = nextFreeWebPort(range, collectAssignedWebPorts(workspaceId));
+        if (port === null)
+            continue; // Range exhausted; leave the old assignment rather than dropping it.
+        if (!writeWebPort(workspaceId, port))
+            continue; // Not recorded - keep the old port rather than report a move that did not happen.
+        moves.push({ workspaceId, from: current, to: port });
+    }
+    return moves;
+}
+// --- Default agent (per workspace, kept on the host side of a mount) ---------------------------------------------------------------------
+/** This workspace's webterm state dir on the host - the directory the container sees as its state mount. */
+export function webtermStateDir(cacheDir) {
+    return join(cacheDir, WEBTERM_STATE_DIR);
+}
+/**
+ * The `docker run -v` args for the webterm state dir, creating it on the host first (docker would otherwise
+ * create it as root). Small on purpose: the only thing in it is the agent file the server writes.
+ */
+export function buildWebtermStateMountArgs(cacheDir) {
+    const host = webtermStateDir(cacheDir);
+    mkdirSync(host, { recursive: true });
+    return ["-v", `${host}:${CONTAINER_WEBTERM_STATE_DIR}`];
+}
+/**
+ * This workspace's web pane artifacts dir on the host: one directory per conversation, each holding that
+ * conversation's published pages and the feedback submitted on them. Under `agents/` on purpose - the pages
+ * are the agent's own output, and clearing agent memory is what clears them.
+ */
+export function webpaneDir(cacheDir) {
+    return join(cacheDir, AGENTS_DIR, WEBPANE_DIR);
+}
+/**
+ * The `docker run -v` args for the web pane artifacts dir, creating it on the host first (docker would
+ * otherwise create it as root). Mounted rather than kept in the container so a published page outlives the
+ * container it was written in, which is what lets a resumed conversation open its own pages again.
+ */
+export function buildWebpaneMountArgs(cacheDir) {
+    const host = webpaneDir(cacheDir);
+    mkdirSync(host, { recursive: true });
+    return ["-v", `${host}:${CONTAINER_WEBPANE_DIR}`];
+}
+/**
+ * Which agent this workspace's web sessions start with. The server writes the file whenever `webterm <agent>`
+ * moves the default, and it sits in the mounted state dir rather than the container's /tmp, so the choice
+ * outlives a container recreate. Falls back to the default agent when nothing has been chosen yet, and when
+ * the file holds something this chamba does not run - a value from a newer version, or a stray edit.
+ * It is also the agent the resume marker is written for, so a wrong answer here would resume nothing.
+ */
+export function readWebAgent(cacheDir) {
+    let value;
+    try {
+        value = readFileSync(join(webtermStateDir(cacheDir), WEBTERM_AGENT_FILE), "utf8").trim();
+    }
+    catch {
+        return DEFAULT_WEB_AGENT; // Never chosen, or the dir is not there yet.
+    }
+    return WEB_AGENTS.includes(value) ? value : DEFAULT_WEB_AGENT;
+}
+// --- Host-port and live-session probing ---------------------------------------------------------------------------------------------------
+/**
+ * True when this workspace can publish its sticky web port right now: either the port is free on the
+ * host, or this workspace's own running container is the one already publishing it (the normal case on
+ * the connect path). Anything else holding it - another container, an unrelated host process - means
+ * the mapping has to be dropped for this session, because chamba's own port mapping must never fail a
+ * session the way a chamba.yaml port does.
+ */
+export async function webPortUsable(webPort, containerName) {
+    if (containerPublishedPorts(containerName).has(webPort))
+        return true;
+    return !dockerPublishedPorts().has(webPort) && (await canBind(webPort));
+}
+/**
+ * The key this container's web interface is currently demanding, read from the file its server publishes
+ * before binding the port. A new key is minted at every server start and nothing on the host stores one,
+ * so it is always read fresh, right before it is used.
+ * Returns null when there is nothing to read: no container, no interface running, or a container built
+ * before the key existed. Callers then probe without a key, which is exactly what such an older server
+ * (which ignores the query parameter) expects.
+ */
+export function readWebKey(containerName) {
+    const result = spawnSync("docker", ["exec", "-u", CONTAINER_USER, containerName, "cat", WEB_KEY_FILE_PATH], { stdio: "pipe" });
+    if (result.status !== 0)
+        return null;
+    const key = result.stdout?.toString().trim();
+    return key ? key : null;
+}
+// The shape the server mints: 16 random bytes, hex. The key file is writable by every process in the
+// container, so anything read back from it is checked against this before the host builds a URL out of it
+// and hands that URL to a program. Argv-style spawning already keeps a strange value from being a command;
+// this keeps it from being a URL at all.
+const WEB_KEY_PATTERN = /^[0-9a-f]{32}$/;
+/** Whether a key read back from the container has the shape the server mints. */
+export function isWebKey(key) {
+    return key !== null && WEB_KEY_PATTERN.test(key);
+}
+/**
+ * The URL that opens this workspace's interface. The key is what the server demands of every caller, so a
+ * URL without one lands on a 403 - callers pass the key whenever they have a valid one, and the keyless
+ * form is only for showing a person where the interface lives.
+ */
+export function webInterfaceUrl(webPort, key) {
+    const base = `http://${PORT_LOOPBACK_HOST}:${webPort}`;
+    return isWebKey(key) ? `${base}/?k=${key}` : base;
+}
+/**
+ * Ask this workspace's web interface what it is running, over the published loopback port. `sessions` is
+ * how many agents are alive in the container - they outlive every browser connection and only end with
+ * the container - and `attached` how many of them a browser window is watching right now.
+ * `key` is what the interface demands of every caller (readWebKey); a wrong or missing one is answered
+ * with 403, which reads here like any other non-answer.
+ * Returns null when the interface did not answer at all, so callers can tell "running, nothing open"
+ * from "not running": the connect path relaunches the server on null, and the stop prompt warns only
+ * when sessions would be lost.
+ */
+export async function webSessionInfo(webPort, key) {
+    const query = key === null ? "" : `?k=${encodeURIComponent(key)}`;
+    try {
+        const response = await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/status${query}`, {
+            signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (typeof body.sessions !== "number" || typeof body.attached !== "number")
+            return null;
+        return { sessions: body.sessions, attached: body.attached };
+    }
+    catch {
+        return null; // Not listening, wrong thing listening, or too slow to matter.
+    }
+}
+/**
+ * Point an already-running interface at the directory this session was started from, so its new sessions open
+ * where a terminal session would. The interface takes that directory from the launcher, which only runs once
+ * per container start - so on a container that has been up since yesterday the default is yesterday's
+ * directory, and this is what moves it.
+ * `key` is what the interface demands of every caller (readWebKey); without one it answers 403, which reads
+ * here like any other refusal. Best-effort: a false only means the browser's "+ New session" still opens
+ * where it did, and the picker can be used instead.
+ */
+export async function setWebDefaultCwd(webPort, key, workdir) {
+    const query = key === null ? "" : `?k=${encodeURIComponent(key)}`;
+    try {
+        const response = await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/cwd${query}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ cwd: workdir }),
+            signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS),
+        });
+        return response.ok;
+    }
+    catch {
+        return false; // Not listening, an interface too old to know the route, or too slow to matter.
+    }
+}
+// The interface is on loopback in the same machine, so a slow answer means something is wrong, not far.
+const WEB_STATUS_TIMEOUT_MS = 1500;
+/**
+ * Whether the interface is serving at all. Any HTTP answer counts, including the 403 a keyless probe gets:
+ * refusing a caller without a key is still proof that the server is up. Used where only liveness matters
+ * (did the launch work, is the interface still there), so those paths need no key and no docker exec.
+ */
+export async function webInterfaceAnswers(webPort) {
+    try {
+        await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/status`, { signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS) });
+        return true;
+    }
+    catch {
+        return false; // Not listening, or too slow to matter.
+    }
+}
+// --- Resume command selection (host-side, over the mounted agent dirs) -------------------------------------------------------------------
+const SESSION_FILE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/;
+/**
+ * Claude Code files its transcripts per directory, in a dir named after the directory it ran in with every
+ * character that is not a letter or a digit turned into "-": /workspace -> -workspace, /workspace/apps/api ->
+ * -workspace-apps-api. So a session in a sub-directory reads and writes a different dir from one at the root,
+ * and a resume command built from the wrong one names an id that claude cannot find.
+ * Only the fallback below relies on this naming; the main path reads what a transcript says about itself.
+ */
+export function claudeProjectKey(containerPath) {
+    return containerPath.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/**
+ * The resume command planted in the marker for a given agent, for a session that will run in `workdir`, or
+ * null when this workspace has no conversation for that agent to reopen.
+ *
+ * Null is the important half. A resume command with nothing behind it is not harmless: every one of these
+ * CLIs treats "resume, but there is nothing there" as an error and exits, so the browser would open on a
+ * session that died the moment it started. With null the marker is never planted and the first session
+ * starts the agent fresh, which is what a workspace with no history should give.
+ *
+ * For claude the session is picked explicitly: `claude --continue` takes the newest transcript by mtime and
+ * silently starts FRESH when that transcript has no real messages (e.g. a session that only ran a slash
+ * command), so relying on it makes auto-resume fail quietly whenever such a session happens to be the newest.
+ * Resuming by id sidesteps the picker entirely, and having no id is also the honest answer to "is there
+ * anything to resume". The other two are asked the same question of their own session stores.
+ */
+export function resumeCommandFor(agent, workspaceCacheDir, workdir = CONTAINER_WORKSPACE) {
+    if (agent === "claude") {
+        const sessionId = latestClaudeSessionId(workspaceCacheDir, workdir);
+        return sessionId === null ? null : `claude --resume ${sessionId}`;
+    }
+    return hasStoredConversation(agent, workspaceCacheDir) ? AGENT_RESUME_COMMAND[agent] : null;
+}
+// Where opencode and codex keep their conversations, under this workspace's mounted agent dirs. These are
+// the host side of the directories the container sees at ~/.local/share/opencode/storage/session and
+// ~/.codex/sessions (templates/webterm/config.js holds the container-side pair).
+const AGENT_SESSION_STORE = {
+    opencode: ["opencode", "data", "storage", "session"],
+    codex: ["codex", "sessions"],
+};
+/**
+ * Whether this agent has anything to resume: any file at all in the store it writes conversations to.
+ * Deliberately shallow as a judgement - a file in there means the agent has run and kept something, which is
+ * all the resume flag needs to not fail. Reading each store's own format to find out whether the newest
+ * conversation is really resumable would tie chamba to two more internal layouts for no gain.
+ */
+function hasStoredConversation(agent, workspaceCacheDir) {
+    return containsFile(join(workspaceCacheDir, AGENTS_DIR, ...AGENT_SESSION_STORE[agent]));
+}
+/**
+ * True when `dir` holds a file anywhere below it. Recursive because both stores nest (by project, by date),
+ * depth-bounded so an unexpected directory can never turn this into a walk of the disk, and it stops at the
+ * first file it finds.
+ */
+function containsFile(dir, depth = 4) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false; // Never run, so never created.
+    }
+    for (const entry of entries) {
+        if (entry.isFile())
+            return true;
+        if (entry.isDirectory() && depth > 0 && containsFile(join(dir, entry.name), depth - 1))
+            return true;
+    }
+    return false;
+}
+/**
+ * The most recent Claude Code conversation that can be resumed in `workdir`, read from the host-side mounted
+ * agent dir: the newest transcript with a real (non-sidechain) user message that ran in that directory.
+ *
+ * The directory is matched on what the transcript records, not on which dir it sits in, so however claude
+ * names those dirs we never hand back a conversation from somewhere else - resuming it would either fail or
+ * drop the user into another directory's history. Transcripts old enough to record no directory at all are
+ * the fallback, and for those the dir name is the only evidence there is.
+ * Returns null when nothing qualifies.
+ */
+export function latestClaudeSessionId(workspaceCacheDir, workdir = CONTAINER_WORKSPACE) {
+    const projectsDir = join(workspaceCacheDir, AGENTS_DIR, "claude", "projects");
+    const byRecordedDir = newestResumableSessionId(transcriptsNewestFirst(projectsDir, projectDirNames(projectsDir)), workdir);
+    if (byRecordedDir !== null)
+        return byRecordedDir;
+    return newestResumableSessionId(transcriptsNewestFirst(projectsDir, [claudeProjectKey(workdir)]), null);
+}
+// Every project dir claude has written under this workspace's cache. Read rather than derived: the point of
+// the walk is to find the transcript that says it ran where we are about to run.
+function projectDirNames(projectsDir) {
+    try {
+        return readdirSync(projectsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+// Transcript paths from the given project dirs, newest first. Session files only - anything else in there
+// (subagent dirs, stray notes) is not a conversation. A missing or unreadable dir contributes nothing.
+function transcriptsNewestFirst(projectsDir, dirNames) {
+    const found = [];
+    for (const dirName of dirNames) {
+        const dir = join(projectsDir, dirName);
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!SESSION_FILE_PATTERN.test(name))
+                continue;
+            const path = join(dir, name);
+            try {
+                found.push({ path, mtime: statSync(path).mtimeMs });
+            }
+            catch {
+                // Vanished between the listing and the stat.
+            }
+        }
+    }
+    return found.sort((a, b) => b.mtime - a.mtime).map((entry) => entry.path);
+}
+// The first of these transcripts that can be resumed, in the order given. `requiredCwd` of null asks only
+// that the conversation has messages; a directory asks that it recorded that one too. Transcripts are read
+// in order and the walk stops at the first hit, so the usual case reads a single file.
+function newestResumableSessionId(transcriptPaths, requiredCwd) {
+    for (const path of transcriptPaths) {
+        const facts = transcriptFacts(path);
+        if (!facts.resumable)
+            continue;
+        if (requiredCwd !== null && facts.cwd !== requiredCwd)
+            continue;
+        return basename(path).slice(0, -".jsonl".length);
+    }
+    return null;
+}
+// What a transcript says about itself, in one pass: whether it holds a real user message, and the directory
+// that message was typed in. Sessions that only recorded UI state (mode changes, slash commands) have
+// nothing to resume; sidechain records belong to subagents. isSidechain is a field we do not own, so only an
+// explicit true excludes a record: a record that stopped carrying the field still counts as resumable, which
+// fails on the safe side. `cwd` is null for transcripts written before claude recorded it.
+function transcriptFacts(transcriptPath) {
+    let content;
+    try {
+        content = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return { resumable: false, cwd: null };
+    }
+    // Walked by index rather than split("\n") so a multi-MB transcript is not copied into an array of lines.
+    let start = 0;
+    while (start <= content.length) {
+        const end = content.indexOf("\n", start);
+        const line = content.slice(start, end === -1 ? content.length : end);
+        start = (end === -1 ? content.length : end) + 1;
+        // Cheap pre-filter so multi-MB transcripts are not JSON.parsed line by line.
+        if (!line.includes('"type":"user"'))
+            continue;
+        try {
+            const record = JSON.parse(line);
+            if (record.type === "user" && record.isSidechain !== true) {
+                return { resumable: true, cwd: typeof record.cwd === "string" ? record.cwd : null };
+            }
+        }
+        catch {
+            // Skip malformed lines.
+        }
+    }
+    return { resumable: false, cwd: null };
+}
+// --- Container hooks (docker I/O, best-effort) --------------------------------------------------------------------------------------------
+/**
+ * Plant the resume marker in the container: a devuser-owned file whose content is the full command that
+ * resumes the most recent conversation. Called on every container create/start; the first web session
+ * to come up consumes it atomically and runs the command, and every later one starts fresh.
+ * Best-effort - a failure only means the session starts fresh. The command is always one of the
+ * AGENT_RESUME_COMMAND constants, so interpolating it into the shell string is safe.
+ */
+export function plantResumeMarker(containerName, resumeCommand) {
+    spawnSync("docker", ["exec", "-u", CONTAINER_USER, containerName, "bash", "-c", `printf %s "${resumeCommand}" > "${RESUME_MARKER_PATH}"`], { stdio: "pipe" });
+}
+/**
+ * The `docker exec` argv that starts the baked webterm server, with the given agent as the one its new
+ * sessions start with, opening them in `workdir`. The server runs every agent it knows, one per session, so
+ * this is a default rather than the only agent it will run. It is always passed explicitly - `webterm` on its
+ * own only prints usage.
+ *
+ * The directory travels as an env var rather than as `docker exec -w`: `-w` on a path docker cannot use
+ * fails the whole exec, which would cost the user the interface over something the server itself can just
+ * refuse and fall back to the workspace root.
+ */
+export function webtermExecArgs(containerName, agent, workdir) {
+    return ["exec", "-d", "-u", CONTAINER_USER, "-e", `WEBTERM_CWD=${workdir}`, containerName, "webterm", agent];
+}
+/**
+ * Start the baked webterm server detached, once per container start, defaulting to the given agent.
+ * The launcher is idempotent (exits quietly when the port is already bound).
+ * Best-effort - the user can always run `webterm <agent>` by hand.
+ */
+function startWebtermDetached(containerName, agent, workdir) {
+    spawnSync("docker", webtermExecArgs(containerName, agent, workdir), { stdio: "pipe" });
+}
+// How long to wait for a just-launched interface to answer, and how often to ask. `docker exec -d` returns
+// as soon as the process is detached, so these cover node starting up and binding the port.
+const WEB_START_TIMEOUT_MS = 8000;
+const WEB_START_POLL_MS = 250;
+/**
+ * Start the interface and wait until it actually answers on its port. `docker exec -d` reports success the
+ * moment the process detaches, which says nothing about whether the server came up, so without this a
+ * crashed launch would leave the greeting advertising a URL that never responds. Returns false when the
+ * interface never answered - the caller reports that and starts nothing in its place, leaving the user to
+ * retry `webterm <agent>` or run the agent in the terminal.
+ */
+export async function startWebtermAndVerify(containerName, agent, webPort, workdir) {
+    startWebtermDetached(containerName, agent, workdir);
+    const deadline = Date.now() + WEB_START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await webInterfaceAnswers(webPort))
+            return true;
+        await new Promise((r) => setTimeout(r, WEB_START_POLL_MS));
+    }
+    return false;
+}