@roamcode.ai/server 1.0.0

package/dist/origin-check.js

@@ -0,0 +1,101 @@
+/**
+ * Origin / CSWSH (cross-site WebSocket hijacking) guard for the WS upgrade and state-changing HTTP.
+ *
+ * The token is the only auth boundary, and it can leak into a URL (`?token=` connect link, push deep
+ * link, browser history). The WS handshake (and any browser-driven HTTP) carries an `Origin` header the
+ * page CANNOT forge — so a malicious cross-origin page that somehow holds the token still can't make the
+ * BROWSER attach to our WS / drive our API, because the browser stamps its OWN origin on the request and
+ * we reject it. Without this check, a leaked-in-URL token is enough for a foreign page to puppet the host.
+ *
+ * SAFE DEFAULT (must never reject the real app): a request is allowed when
+ *   - the `Origin` header is ABSENT (native/non-browser clients, same-origin navigations + most
+ *     same-origin GETs omit it — the PWA's own fetches are same-origin), OR
+ *   - the Origin's host:port equals the request `Host` (same-origin — the PWA always is), OR
+ *   - the Origin matches the configured public URL (ROAMCODE_PUBLIC_URL), OR
+ *   - the Origin is a loopback/localhost origin (local dev), OR
+ *   - the Origin is in the explicit ROAMCODE_ALLOWED_ORIGINS allow-list.
+ * Only a PRESENT, cross-origin, non-allow-listed Origin is rejected (403).
+ */
+/** Normalize a URL/origin string to a comparable `scheme://host[:port]` origin (lowercased). Returns
+ *  undefined for anything that isn't a parseable absolute URL (so it can never match by accident). */
+export function normalizeOrigin(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === "null")
+        return undefined; // a sandboxed/opaque origin serializes to "null"
+    try {
+        const u = new URL(trimmed);
+        // `URL.origin` is `scheme://host[:port]` with the default port elided — exactly the comparison we want.
+        return u.origin.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True if a host (no scheme) is a loopback/localhost name. Accepts a bare host or host:port. */
+function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/:\d+$/, ""); // drop a :port suffix
+    if (h === "localhost" || h === "::1" || h === "[::1]")
+        return true;
+    return /^127(?:\.\d{1,3}){3}$/.test(h);
+}
+/** True if a normalized origin (`scheme://host[:port]`) is loopback. */
+function isLoopbackOrigin(origin) {
+    try {
+        return isLoopbackHost(new URL(origin).host);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide whether a request's Origin is allowed. PURE / I/O-free so it is unit-testable; the transport
+ * preHandler passes `origin` (the header) and `host` (the request Host header).
+ *
+ * @param origin the request's `Origin` header (may be undefined)
+ * @param host   the request's `Host` header (e.g. `remotecode.example.com` or `127.0.0.1:4280`)
+ */
+export function isOriginAllowed(origin, host, opts = {}) {
+    // Absent Origin → allow (native clients, same-origin navigations + most same-origin GETs omit it). A
+    // present-but-unparseable / opaque ("null") Origin normalizes to undefined and is treated the same way
+    // (it cannot be a real cross-origin browser page driving us — those send a concrete origin).
+    const reqOrigin = normalizeOrigin(origin);
+    if (reqOrigin === undefined)
+        return true;
+    // Same-origin: the Origin's host:port equals the request Host. The PWA (served same-origin) always is.
+    if (host) {
+        const sameOriginHost = (() => {
+            try {
+                return new URL(reqOrigin).host.toLowerCase() === host.trim().toLowerCase();
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (sameOriginHost)
+            return true;
+    }
+    // Loopback origin (local dev directly against 127.0.0.1/localhost).
+    if (isLoopbackOrigin(reqOrigin))
+        return true;
+    // Configured public URL (the tunnel/user-facing origin the PWA is actually installed under).
+    const publicOrigin = normalizeOrigin(opts.publicUrl);
+    if (publicOrigin !== undefined && reqOrigin === publicOrigin)
+        return true;
+    // Explicit allow-list extension.
+    for (const extra of opts.allowedOrigins ?? []) {
+        if (normalizeOrigin(extra) === reqOrigin)
+            return true;
+    }
+    return false;
+}
+/** Parse a comma-separated ROAMCODE_ALLOWED_ORIGINS value into a trimmed, non-empty list. */
+export function parseAllowedOrigins(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}

package/dist/pane-status.d.ts

@@ -0,0 +1,61 @@
+export type PaneStatus = "working" | "blocked" | "idle";
+/**
+ * The newest Claude Code MAJOR.MINOR the classifier's markers below were VERIFIED against on a live box.
+ * The whole classifier is tied to Claude Code's ENGLISH TUI strings — the load-bearing markers are:
+ *   - "Do you want to proceed" / "Would you like to proceed"   (blocked — permission/plan prompts)
+ *   - the gerund ellipsis "…" + "↓ <n>k tokens" live counter    (working — main spinner + live agents)
+ *   - a "…(<n>s"-style parenthesised spinner timer               (working — pre-token-flow window)
+ *   - "Waiting for … to finish" / "esc to interrupt"             (working)
+ * A NEWER claude may reword any of these and silently degrade every rail status to "idle", so boot logs a
+ * one-time warning (see start.ts) when the installed claude's MAJOR.MINOR exceeds this. Bump it after
+ * re-verifying the markers against a newer claude.
+ */
+export declare const CLASSIFIER_TESTED_UP_TO = "2.1";
+/**
+ * True iff `current`'s MAJOR.MINOR is strictly NEWER than `testedUpTo`'s. Patch versions are ignored — a
+ * patch release doesn't reword the TUI. Unparseable input (either side) → false, so a weird version string
+ * can never produce a spurious warning. Pure.
+ */
+export declare function isNewerMajorMinor(current: string, testedUpTo: string): boolean;
+/**
+ * The one-line boot warning when the RUNNING claude is newer than the classifier was verified against —
+ * or undefined when there is nothing to warn about (older/equal/unknown version). Pure so it's testable;
+ * start.ts logs it once via console.warn and NEVER throws (a version bump must not affect boot).
+ */
+export declare function classifierVersionWarning(claudeVersion: string | undefined): string | undefined;
+/**
+ * Classify a session's live ACTIVITY from its RENDERED tmux pane (`capture-pane -p` — the CURRENT screen, not
+ * scrollback). UNIVERSAL: works for any running session regardless of how claude was spawned (no per-session
+ * hooks needed), and works while the browser is DETACHED (it reads the tmux session directly). Grounded in
+ * Claude Code's real output — see pane-status.test.ts for captured samples.
+ *
+ *   working → something is actively generating. The strongest tell is a LIVE token-flow counter "↓ 216.5k
+ *             tokens" — it appears on the MAIN spinner ("Schlepping… (1m 17s · ↓ 2.1k tokens)") AND on an
+ *             ACTIVE background agent ("⏺ general-purpose  Listing f… 24m 23s · ↓ 216.5k tokens"), and is GONE
+ *             the moment a turn finishes ("Baked for 23m 15s"). So a session whose MAIN loop is at the prompt
+ *             but has agents still developing in the background reads "working" — NOT idle (the user's
+ *             explicit correction). Also: a spinner's parenthesised timer, "Waiting for … to finish", or
+ *             "esc to interrupt".
+ *   blocked → claude is WAITING ON A DECISION FROM YOU: a permission prompt ("Do you want to proceed?"), a
+ *             plan-mode approval ("Would you like to proceed?"). This is the ONLY state that earns the loud
+ *             "needs you" — so it must stay RARE + real; that's why it's just the explicit-prompt phrasings.
+ *   idle    → none of the above: claude finished a turn and is sitting at an empty prompt with nothing running
+ *             and nothing to decide. A calm "your turn whenever" — NOT a loud alert.
+ *
+ * Order matters: blocked is checked first (a decision prompt overrides any stale spinner text), then working,
+ * else idle.
+ */
+export declare function classifyPaneStatus(pane: string): PaneStatus;
+/** How capturePane locates a session's tmux pane. */
+export interface CaptureOptions {
+    tmuxBin?: string;
+    socket: string;
+    sessionName: string;
+    timeoutMs?: number;
+}
+/**
+ * Capture a tmux session's CURRENT pane as plain text (`capture-pane -p`, no escape sequences). READ-ONLY —
+ * it never sends input or resizes, so it can NEVER disturb a live session. Best-effort: resolves "" on any
+ * error/timeout and never throws. Async (non-blocking) so the activity monitor doesn't stall the event loop.
+ */
+export declare function capturePane(opts: CaptureOptions): Promise<string>;

package/dist/pane-status.js

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+/**
+ * The newest Claude Code MAJOR.MINOR the classifier's markers below were VERIFIED against on a live box.
+ * The whole classifier is tied to Claude Code's ENGLISH TUI strings — the load-bearing markers are:
+ *   - "Do you want to proceed" / "Would you like to proceed"   (blocked — permission/plan prompts)
+ *   - the gerund ellipsis "…" + "↓ <n>k tokens" live counter    (working — main spinner + live agents)
+ *   - a "…(<n>s"-style parenthesised spinner timer               (working — pre-token-flow window)
+ *   - "Waiting for … to finish" / "esc to interrupt"             (working)
+ * A NEWER claude may reword any of these and silently degrade every rail status to "idle", so boot logs a
+ * one-time warning (see start.ts) when the installed claude's MAJOR.MINOR exceeds this. Bump it after
+ * re-verifying the markers against a newer claude.
+ */
+export const CLASSIFIER_TESTED_UP_TO = "2.1";
+/**
+ * True iff `current`'s MAJOR.MINOR is strictly NEWER than `testedUpTo`'s. Patch versions are ignored — a
+ * patch release doesn't reword the TUI. Unparseable input (either side) → false, so a weird version string
+ * can never produce a spurious warning. Pure.
+ */
+export function isNewerMajorMinor(current, testedUpTo) {
+    const parse = (v) => {
+        const m = /(\d+)\.(\d+)/.exec(v);
+        return m ? [Number(m[1]), Number(m[2])] : undefined;
+    };
+    const cur = parse(current);
+    const tested = parse(testedUpTo);
+    if (!cur || !tested)
+        return false; // can't decide → never warn spuriously
+    if (cur[0] !== tested[0])
+        return cur[0] > tested[0];
+    return cur[1] > tested[1];
+}
+/**
+ * The one-line boot warning when the RUNNING claude is newer than the classifier was verified against —
+ * or undefined when there is nothing to warn about (older/equal/unknown version). Pure so it's testable;
+ * start.ts logs it once via console.warn and NEVER throws (a version bump must not affect boot).
+ */
+export function classifierVersionWarning(claudeVersion) {
+    if (!claudeVersion || !isNewerMajorMinor(claudeVersion, CLASSIFIER_TESTED_UP_TO))
+        return undefined;
+    return (`pane-status markers were verified against claude <=${CLASSIFIER_TESTED_UP_TO}; ` +
+        `current is ${claudeVersion} — verify rail statuses after this upgrade`);
+}
+/**
+ * Classify a session's live ACTIVITY from its RENDERED tmux pane (`capture-pane -p` — the CURRENT screen, not
+ * scrollback). UNIVERSAL: works for any running session regardless of how claude was spawned (no per-session
+ * hooks needed), and works while the browser is DETACHED (it reads the tmux session directly). Grounded in
+ * Claude Code's real output — see pane-status.test.ts for captured samples.
+ *
+ *   working → something is actively generating. The strongest tell is a LIVE token-flow counter "↓ 216.5k
+ *             tokens" — it appears on the MAIN spinner ("Schlepping… (1m 17s · ↓ 2.1k tokens)") AND on an
+ *             ACTIVE background agent ("⏺ general-purpose  Listing f… 24m 23s · ↓ 216.5k tokens"), and is GONE
+ *             the moment a turn finishes ("Baked for 23m 15s"). So a session whose MAIN loop is at the prompt
+ *             but has agents still developing in the background reads "working" — NOT idle (the user's
+ *             explicit correction). Also: a spinner's parenthesised timer, "Waiting for … to finish", or
+ *             "esc to interrupt".
+ *   blocked → claude is WAITING ON A DECISION FROM YOU: a permission prompt ("Do you want to proceed?"), a
+ *             plan-mode approval ("Would you like to proceed?"). This is the ONLY state that earns the loud
+ *             "needs you" — so it must stay RARE + real; that's why it's just the explicit-prompt phrasings.
+ *   idle    → none of the above: claude finished a turn and is sitting at an empty prompt with nothing running
+ *             and nothing to decide. A calm "your turn whenever" — NOT a loud alert.
+ *
+ * Order matters: blocked is checked first (a decision prompt overrides any stale spinner text), then working,
+ * else idle.
+ */
+export function classifyPaneStatus(pane) {
+    // Only look at the BOTTOM of the pane. Claude Code pins its live chrome — the spinner, the input box, the
+    // status line, and the background-agent block — to the last ~dozen rows; everything above is CONVERSATION
+    // SCROLLBACK. Restricting to the tail means a session whose scrollback happens to show these very marker
+    // strings (e.g. one editing roamcode's own source, or a diff mentioning "↓ … tokens" / "proceed") can't
+    // be misread — only claude's actual status chrome is classified.
+    const tail = pane.split("\n").slice(-22).join("\n");
+    // BLOCKED — an explicit decision prompt. Kept to Claude Code's exact permission/plan phrasings so the loud
+    // "needs you" it drives stays rare + trustworthy.
+    if (/\bDo you want to proceed\b/i.test(tail))
+        return "blocked";
+    if (/\bWould you like to proceed\b/i.test(tail))
+        return "blocked";
+    // WORKING — a LIVE token-flow counter "↓ <n>k tokens" is the reliable "actively generating" signal, present
+    // for BOTH the main spinner ("Schlepping… (1m 17s · ↓ 2.1k tokens)") and an active background agent
+    // ("⏺ general-purpose  Listing f… 24m 23s · ↓ 216.5k tokens"). We require a GERUND ellipsis "…" on the SAME
+    // line so a FINISHED thing's past-tense summary ("Done · ↓ 12k tokens") can't read as working — an active
+    // worker always shows "<Gerund>… <timer> · ↓ tokens".
+    if (/…[^\n]*↓\s*[\d.]+\s*[kKmM]?\s*tokens?\b/.test(tail))
+        return "working";
+    // A spinner's parenthesised elapsed timer (covers the brief window at a turn's start before tokens flow).
+    if (/…\s*\(\s*\d+\s*[ms]\b/.test(tail))
+        return "working";
+    // Main loop blocked on a foreground agent/tool.
+    if (/\bWaiting for\b[\s\S]{0,80}?\bto finish\b/i.test(tail))
+        return "working";
+    // Interruptible generation (may be truncated to "e…" on a narrow phone pane, so it's a bonus, not the only tell).
+    if (/\besc to interrupt\b/i.test(tail))
+        return "working";
+    return "idle";
+}
+/**
+ * Capture a tmux session's CURRENT pane as plain text (`capture-pane -p`, no escape sequences). READ-ONLY —
+ * it never sends input or resizes, so it can NEVER disturb a live session. Best-effort: resolves "" on any
+ * error/timeout and never throws. Async (non-blocking) so the activity monitor doesn't stall the event loop.
+ */
+export function capturePane(opts) {
+    return new Promise((resolve) => {
+        let out = "";
+        let done = false;
+        const finish = (s) => {
+            if (done)
+                return;
+            done = true;
+            resolve(s);
+        };
+        try {
+            const p = spawn(opts.tmuxBin ?? "tmux", ["-L", opts.socket, "capture-pane", "-p", "-t", opts.sessionName], {
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            p.stdout?.on("data", (d) => {
+                out += d.toString("utf8");
+                if (out.length > 65536) {
+                    try {
+                        p.kill();
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                    finish(out);
+                }
+            });
+            p.on("error", () => finish("")); // tmux missing / spawn failed → treat as "no data"
+            p.on("close", () => finish(out));
+            const t = setTimeout(() => {
+                try {
+                    p.kill();
+                }
+                catch {
+                    /* already gone */
+                }
+                finish(out);
+            }, opts.timeoutMs ?? 2000);
+            if (typeof t.unref === "function")
+                t.unref();
+        }
+        catch {
+            finish("");
+        }
+    });
+}

package/dist/providers/claude-metadata-service.d.ts

@@ -0,0 +1,58 @@
+import { type SpawnOptions } from "node:child_process";
+export interface ClaudeModelCatalogItem {
+    value: string;
+    displayName: string;
+    description?: string;
+    supportedEffortLevels: string[];
+    isDefault: boolean;
+}
+export interface ClaudeMetadataRunner {
+    run(): Promise<unknown>;
+    /** Claude 2.1.207+ no longer includes models in initialize; `/model` is the catalog fallback. */
+    runModelList?(): Promise<unknown>;
+    dispose?(): void | Promise<void>;
+}
+interface ClaudeMetadataChildProcess {
+    readonly stdin: {
+        end(chunk: string): unknown;
+        on(event: "error", listener: (error: Error) => void): unknown;
+        off(event: "error", listener: (error: Error) => void): unknown;
+    };
+    readonly stdout: NodeJS.ReadableStream;
+    readonly stderr: NodeJS.ReadableStream;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    off(event: "error", listener: (error: Error) => void): this;
+    off(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+    kill(): boolean;
+}
+type ClaudeMetadataSpawnProcess = (command: string, args: readonly string[], options: SpawnOptions) => ClaudeMetadataChildProcess;
+interface CreateClaudeMetadataRunnerOptions {
+    claudeBin: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    /** Process boundary injected by lifecycle tests. */
+    spawnProcess?: ClaudeMetadataSpawnProcess;
+    /** `/model` process boundary injected by fallback tests. */
+    modelListRun?: () => Promise<unknown>;
+}
+export declare class ClaudeMetadataService {
+    private readonly runner;
+    private readonly now;
+    private readonly ttlMs;
+    private cache?;
+    private inFlight?;
+    private disposed;
+    constructor(runner: ClaudeMetadataRunner, options?: {
+        now?: () => number;
+        ttlMs?: number;
+    });
+    getModels(force?: boolean): Promise<ClaudeModelCatalogItem[]>;
+    validateModelSelection(model: string, effort?: string): Promise<void>;
+    dispose(): void | Promise<void>;
+    private loadModels;
+}
+export declare function createClaudeMetadataRunner(options: CreateClaudeMetadataRunnerOptions): ClaudeMetadataRunner;
+export {};