@roamcode.ai/server 1.0.0

package/dist/config.d.ts

@@ -0,0 +1,78 @@
+export interface ServerConfig {
+    claudeBin: string;
+}
+export declare function loadConfig(env: NodeJS.ProcessEnv): ServerConfig;
+/**
+ * Wiring for the mcp-send server (Claude → user attachments). When present, the spawn layer writes a
+ * per-session 0600 MCP config FILE (carrying the loopback base URL, this session's id, and the access
+ * token via env) and passes its PATH to the terminal spawn as `--mcp-config <path>`. The token therefore
+ * NEVER lands in any process's argv (where `ps`/`/proc` would expose it to other local users) — it
+ * lives only in the mode-0600 file. ABSENT → spawn exactly as before (the feature is additive).
+ */
+export interface AttachSpawnOptions {
+    /** Loopback base URL of roamcode (e.g. http://127.0.0.1:4280) the tool POSTs back to. */
+    baseUrl: string;
+    /** The access token the mcp-send tool sends as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Absolute path to the built dist/mcp-send.js node script. */
+    mcpScriptPath: string;
+    /** Host data dir (mode 0700) the per-session 0600 mcp-config-<id>.json is written into. */
+    dataDir: string;
+}
+/** The `{ mcpServers: { ... } }` document written to the per-session 0600 config file. */
+export interface McpConfigDocument {
+    mcpServers: {
+        roamcode: {
+            command: string;
+            args: string[];
+            env: {
+                RC_BASE_URL: string;
+                RC_SESSION_ID: string;
+                RC_TOKEN: string;
+            };
+        };
+    };
+}
+/**
+ * Build the MCP config document for a session. PURE: no fs, no token leakage — the caller writes the
+ * returned object to a 0600 file and passes its path to the terminal spawn as `--mcp-config`.
+ */
+export declare function buildMcpConfigDocument(sessionId: string, attach: AttachSpawnOptions): McpConfigDocument;
+/** Absolute path of the per-session MCP config file inside the data dir. */
+export declare function mcpConfigPathFor(dataDir: string, sessionId: string): string;
+/** Reserved filename prefix for per-session Codex MCP token artifacts. */
+export declare const CODEX_MCP_TOKEN_PREFIX = "codex-mcp-token-";
+/** Absolute path of the per-session 0600 bare token file forwarded only to Codex's MCP subprocess. */
+export declare function codexMcpTokenPathFor(dataDir: string, sessionId: string): string;
+/**
+ * Per-session Claude Code settings document (written 0600, passed as `--settings <path>`). Its HOOKS let
+ * claude signal turn boundaries DIRECTLY instead of us scraping the terminal (which can't tell "generating /
+ * running a background agent" from "waiting for you" — the source of the false "needs you"):
+ *   - `Stop`             → claude finished its turn and is now waiting on YOU (mark awaiting).
+ *   - `UserPromptSubmit` → you submitted a prompt → clear it.
+ * Each hook curls a loopback endpoint, reading the access token from a 0600 file via `-H '@authFile'` so the
+ * token never lands in the hook's argv (ps/proc), and ends in `|| true` so a hook can NEVER block/fail claude.
+ * Hooks fire in an interactive tmux pane, including under `--dangerously-skip-permissions` (verified).
+ */
+export interface HookCommand {
+    type: "command";
+    command: string;
+}
+export interface HooksSettingsDocument {
+    hooks: {
+        Stop: Array<{
+            hooks: HookCommand[];
+        }>;
+        UserPromptSubmit: Array<{
+            hooks: HookCommand[];
+        }>;
+    };
+}
+/** Build the per-session hooks settings. PURE: the caller writes it to a 0600 file + the 0600 `authFilePath`. */
+export declare function buildHooksSettingsDocument(sessionId: string, attach: Pick<AttachSpawnOptions, "baseUrl">, authFilePath: string): HooksSettingsDocument;
+/** Absolute path of the per-session hooks settings file inside the data dir. */
+export declare function hooksSettingsPathFor(dataDir: string, sessionId: string): string;
+/** Absolute path of the per-session 0600 auth-header file the hook curls read via `-H '@file'`. */
+export declare function hookAuthPathFor(dataDir: string, sessionId: string): string;
+/** The exact bytes of that auth-header file (a single curl `-H` line). Keeps the token out of hook argv. */
+export declare function hookAuthFileContent(token: string): string;

package/dist/config.js

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+export function loadConfig(env) {
+    return { claudeBin: env.CLAUDE_BIN ?? "claude" };
+}
+/**
+ * Build the MCP config document for a session. PURE: no fs, no token leakage — the caller writes the
+ * returned object to a 0600 file and passes its path to the terminal spawn as `--mcp-config`.
+ */
+export function buildMcpConfigDocument(sessionId, attach) {
+    return {
+        mcpServers: {
+            roamcode: {
+                command: process.execPath,
+                args: [attach.mcpScriptPath],
+                env: {
+                    RC_BASE_URL: attach.baseUrl,
+                    RC_SESSION_ID: sessionId,
+                    RC_TOKEN: attach.token,
+                },
+            },
+        },
+    };
+}
+/** Absolute path of the per-session MCP config file inside the data dir. */
+export function mcpConfigPathFor(dataDir, sessionId) {
+    return join(dataDir, `mcp-config-${sessionId}.json`);
+}
+/** Reserved filename prefix for per-session Codex MCP token artifacts. */
+export const CODEX_MCP_TOKEN_PREFIX = "codex-mcp-token-";
+/** Absolute path of the per-session 0600 bare token file forwarded only to Codex's MCP subprocess. */
+export function codexMcpTokenPathFor(dataDir, sessionId) {
+    return join(dataDir, `${CODEX_MCP_TOKEN_PREFIX}${sessionId}`);
+}
+/** Build the per-session hooks settings. PURE: the caller writes it to a 0600 file + the 0600 `authFilePath`. */
+export function buildHooksSettingsDocument(sessionId, attach, authFilePath) {
+    const post = (event) => ({
+        type: "command",
+        command: `curl -sS -m 4 -X POST -H '@${authFilePath}' ` +
+            `'${attach.baseUrl}/sessions/${sessionId}/hook?event=${event}' >/dev/null 2>&1 || true`,
+    });
+    return {
+        hooks: {
+            Stop: [{ hooks: [post("stop")] }],
+            UserPromptSubmit: [{ hooks: [post("submit")] }],
+        },
+    };
+}
+/** Absolute path of the per-session hooks settings file inside the data dir. */
+export function hooksSettingsPathFor(dataDir, sessionId) {
+    return join(dataDir, `hooks-${sessionId}.json`);
+}
+/** Absolute path of the per-session 0600 auth-header file the hook curls read via `-H '@file'`. */
+export function hookAuthPathFor(dataDir, sessionId) {
+    return join(dataDir, `hook-auth-${sessionId}`);
+}
+/** The exact bytes of that auth-header file (a single curl `-H` line). Keeps the token out of hook argv. */
+export function hookAuthFileContent(token) {
+    return `Authorization: Bearer ${token}\n`;
+}

package/dist/data-dir.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Host data dir for the SQLite DB + access token. Never inside the project tree by default.
+ *
+ * Rename compat (Remote Coder → RoamCode): installs that predate the rename keep their data where it
+ * already lives — the legacy `REMOTE_CODER_DATA_DIR` env still wins over defaults, and an existing
+ * `…/remote-coder` dir is preferred over creating a fresh `…/roamcode` (their token / service.json /
+ * session index MUST survive an OTA update). Only brand-new installs get the new directory name.
+ */
+export declare function resolveDataDir(env: NodeJS.ProcessEnv, exists?: (p: string) => boolean): string;
+export declare function ensureDataDir(dir: string): void;
+/**
+ * Strong default token: 32 bytes of CSPRNG entropy (>= spec §9 baseline),
+ * base64url-encoded (43 chars, no padding). Never Math.random / randomUUID.
+ */
+export declare function generateAccessToken(): string;
+/**
+ * Persist a token to `<dataDir>/token` with mode 0600 (overwriting any prior file). Used by both first-run
+ * generation and POST /token/rotate. `writeFileSync`'s `mode` is honored only when CREATING a file, so we
+ * chmod unconditionally afterwards — a rotated secret can never land in a too-permissive (e.g. world-
+ * readable) file left behind by an earlier write.
+ */
+export declare function persistAccessToken(dataDir: string, token: string): void;
+export interface ResolveAccessTokenOptions {
+    /** From ACCESS_TOKEN; when set it wins and is not persisted. */
+    configured?: string;
+    dataDir: string;
+    /** Injectable generator for tests. Defaults to a 32-byte base64url CSPRNG token. */
+    generate?: () => string;
+}
+/**
+ * Spec §9: a long random secret generated on first run (printed once, stored).
+ * Precedence: explicit ACCESS_TOKEN > persisted token file > freshly generated.
+ *
+ * A configured (env) token is used verbatim and never written to disk. A
+ * generated token is persisted to `<dataDir>/token` with mode 0600 so other
+ * users on the host cannot read it; `generated: true` lets the caller print it
+ * once with the access URL.
+ */
+export declare function resolveAccessToken(opts: ResolveAccessTokenOptions): {
+    token: string;
+    generated: boolean;
+};

package/dist/data-dir.js

@@ -0,0 +1,70 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+/**
+ * Host data dir for the SQLite DB + access token. Never inside the project tree by default.
+ *
+ * Rename compat (Remote Coder → RoamCode): installs that predate the rename keep their data where it
+ * already lives — the legacy `REMOTE_CODER_DATA_DIR` env still wins over defaults, and an existing
+ * `…/remote-coder` dir is preferred over creating a fresh `…/roamcode` (their token / service.json /
+ * session index MUST survive an OTA update). Only brand-new installs get the new directory name.
+ */
+export function resolveDataDir(env, exists = existsSync) {
+    if (env.ROAMCODE_DATA_DIR)
+        return env.ROAMCODE_DATA_DIR;
+    if (env.REMOTE_CODER_DATA_DIR)
+        return env.REMOTE_CODER_DATA_DIR; // legacy (pre-rename services set this)
+    const pick = (next, legacy) => (!exists(next) && exists(legacy) ? legacy : next);
+    if (env.XDG_CONFIG_HOME)
+        return pick(join(env.XDG_CONFIG_HOME, "roamcode"), join(env.XDG_CONFIG_HOME, "remote-coder"));
+    if (env.HOME)
+        return pick(join(env.HOME, ".config", "roamcode"), join(env.HOME, ".config", "remote-coder"));
+    return pick(join(process.cwd(), ".roamcode"), join(process.cwd(), ".remote-coder"));
+}
+export function ensureDataDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * Strong default token: 32 bytes of CSPRNG entropy (>= spec §9 baseline),
+ * base64url-encoded (43 chars, no padding). Never Math.random / randomUUID.
+ */
+export function generateAccessToken() {
+    return randomBytes(32).toString("base64url");
+}
+/**
+ * Persist a token to `<dataDir>/token` with mode 0600 (overwriting any prior file). Used by both first-run
+ * generation and POST /token/rotate. `writeFileSync`'s `mode` is honored only when CREATING a file, so we
+ * chmod unconditionally afterwards — a rotated secret can never land in a too-permissive (e.g. world-
+ * readable) file left behind by an earlier write.
+ */
+export function persistAccessToken(dataDir, token) {
+    ensureDataDir(dataDir);
+    const tokenPath = join(dataDir, "token");
+    writeFileSync(tokenPath, token + "\n", { mode: 0o600 });
+    chmodSync(tokenPath, 0o600);
+}
+/**
+ * Spec §9: a long random secret generated on first run (printed once, stored).
+ * Precedence: explicit ACCESS_TOKEN > persisted token file > freshly generated.
+ *
+ * A configured (env) token is used verbatim and never written to disk. A
+ * generated token is persisted to `<dataDir>/token` with mode 0600 so other
+ * users on the host cannot read it; `generated: true` lets the caller print it
+ * once with the access URL.
+ */
+export function resolveAccessToken(opts) {
+    if (opts.configured)
+        return { token: opts.configured, generated: false };
+    const tokenPath = join(opts.dataDir, "token");
+    try {
+        const existing = readFileSync(tokenPath, "utf8").trim();
+        if (existing)
+            return { token: existing, generated: false };
+    }
+    catch {
+        // no token file yet — fall through to generation
+    }
+    const token = (opts.generate ?? generateAccessToken)();
+    persistAccessToken(opts.dataDir, token);
+    return { token, generated: true };
+}

package/dist/diag.d.ts

@@ -0,0 +1,43 @@
+import type { ProviderAvailability } from "./providers/types.js";
+/** Merge host and provider capability probes while replacing all provider/child detail with stable text. */
+export declare function normalizeProviderAvailability(hostTerminalAvailable: boolean, probed: ProviderAvailability, metadataAvailable?: boolean): ProviderAvailability;
+/**
+ * Best-effort, CACHED `claude --version` probe for the authed GET /diag (fleet observability). It must
+ * NOT block the request long, so the spawn is timeout-guarded (short) and the result is cached for
+ * CLAUDE_VERSION_CACHE_MS — a /diag poll then never re-spawns within the window. A missing/erroring
+ * claude resolves to {available:false} (never throws), so /diag degrades instead of 500ing.
+ *
+ * The spawn is injectable (a function returning {stdout} or rejecting) so tests assert the caching +
+ * the available/unavailable shaping without spawning a real binary.
+ */
+/** How long a probe result (success OR failure) is reused before re-spawning. Long enough that the
+ *  /diag poll is cheap; short enough that a claude install/upgrade is reflected within a few minutes. */
+export declare const CLAUDE_VERSION_CACHE_MS: number;
+/** Short hard timeout on the spawn so a hung claude never makes /diag hang. */
+export declare const CLAUDE_VERSION_TIMEOUT_MS = 3000;
+export interface ClaudeAvailability {
+    available: boolean;
+    /** The parsed version string (e.g. "1.2.3") when available; absent otherwise. */
+    version?: string;
+}
+/** Run `<bin> --version` (timeout-guarded), resolving its stdout. Rejects on spawn error / non-zero. */
+export type RunClaudeVersion = () => Promise<{
+    stdout: string;
+}>;
+export interface ClaudeVersionProbe {
+    /** Resolve the (cached) availability. Never rejects. */
+    get(): Promise<ClaudeAvailability>;
+}
+/** The real runner: `<claudeBin> --version` with the server env + a short timeout. */
+export declare function defaultRunClaudeVersion(claudeBin: string, env: NodeJS.ProcessEnv): RunClaudeVersion;
+/**
+ * Extract a version-looking token from `claude --version` output (e.g. "1.2.3 (Claude Code)" → "1.2.3").
+ * Returns the trimmed raw string when no dotted-number token is found (still useful), or undefined for
+ * empty output.
+ */
+export declare function parseClaudeVersion(raw: string): string | undefined;
+/** Build a cached probe over an injected runner + clock. */
+export declare function createClaudeVersionProbe(deps: {
+    run: RunClaudeVersion;
+    now?: () => number;
+}): ClaudeVersionProbe;

package/dist/diag.js

@@ -0,0 +1,83 @@
+import { execFile as nodeExecFile } from "node:child_process";
+/** Merge host and provider capability probes while replacing all provider/child detail with stable text. */
+export function normalizeProviderAvailability(hostTerminalAvailable, probed, metadataAvailable = probed.metadataAvailable) {
+    const terminalAvailable = hostTerminalAvailable && probed.terminalAvailable;
+    return {
+        terminalAvailable,
+        metadataAvailable,
+        ...(probed.version ? { version: probed.version } : {}),
+        ...(!terminalAvailable
+            ? { detail: "Provider terminal unavailable" }
+            : !metadataAvailable
+                ? { detail: "Provider metadata protocol unavailable" }
+                : {}),
+    };
+}
+/**
+ * Best-effort, CACHED `claude --version` probe for the authed GET /diag (fleet observability). It must
+ * NOT block the request long, so the spawn is timeout-guarded (short) and the result is cached for
+ * CLAUDE_VERSION_CACHE_MS — a /diag poll then never re-spawns within the window. A missing/erroring
+ * claude resolves to {available:false} (never throws), so /diag degrades instead of 500ing.
+ *
+ * The spawn is injectable (a function returning {stdout} or rejecting) so tests assert the caching +
+ * the available/unavailable shaping without spawning a real binary.
+ */
+/** How long a probe result (success OR failure) is reused before re-spawning. Long enough that the
+ *  /diag poll is cheap; short enough that a claude install/upgrade is reflected within a few minutes. */
+export const CLAUDE_VERSION_CACHE_MS = 5 * 60_000;
+/** Short hard timeout on the spawn so a hung claude never makes /diag hang. */
+export const CLAUDE_VERSION_TIMEOUT_MS = 3_000;
+/** The real runner: `<claudeBin> --version` with the server env + a short timeout. */
+export function defaultRunClaudeVersion(claudeBin, env) {
+    return () => new Promise((resolve, reject) => {
+        nodeExecFile(claudeBin, ["--version"], { env, timeout: CLAUDE_VERSION_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve({ stdout: String(stdout) });
+        });
+    });
+}
+/**
+ * Extract a version-looking token from `claude --version` output (e.g. "1.2.3 (Claude Code)" → "1.2.3").
+ * Returns the trimmed raw string when no dotted-number token is found (still useful), or undefined for
+ * empty output.
+ */
+export function parseClaudeVersion(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const m = /\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.]+)?/.exec(trimmed);
+    return m ? m[0] : trimmed;
+}
+/** Build a cached probe over an injected runner + clock. */
+export function createClaudeVersionProbe(deps) {
+    const now = deps.now ?? (() => Date.now());
+    let cache;
+    let inFlight;
+    return {
+        async get() {
+            const t = now();
+            if (cache && t - cache.at < CLAUDE_VERSION_CACHE_MS)
+                return cache.value;
+            // Collapse concurrent probes into one spawn.
+            if (inFlight)
+                return inFlight;
+            inFlight = (async () => {
+                let value;
+                try {
+                    const { stdout } = await deps.run();
+                    const version = parseClaudeVersion(stdout);
+                    value = version ? { available: true, version } : { available: true };
+                }
+                catch {
+                    value = { available: false };
+                }
+                cache = { at: now(), value };
+                inFlight = undefined;
+                return value;
+            })();
+            return inFlight;
+        },
+    };
+}

package/dist/fs-service.d.ts

@@ -0,0 +1,90 @@
+export type FsErrorCode = "forbidden" | "not-found" | "exists";
+export declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    constructor(code: FsErrorCode, message: string);
+}
+export interface DirEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isGitRepo: boolean;
+    gitBranch?: string;
+}
+export interface DirListing {
+    path: string;
+    parent?: string;
+    entries: DirEntry[];
+}
+export interface FsServiceOptions {
+    root: string;
+}
+/** One GET /fs/search hit — a DIRECTORY whose name matched, shaped for the picker. */
+export interface DirSearchResult {
+    path: string;
+    name: string;
+    isGitRepo: boolean;
+}
+/** GET /fs/search walk bounds. Depth 5 / 400 dirs keeps the worst case (a huge home dir) to a bounded,
+ *  sub-second readdir sweep; 30 results is more than a picker list ever shows. */
+export declare const SEARCH_MAX_DEPTH = 5;
+export declare const SEARCH_MAX_DIRS = 400;
+export declare const SEARCH_MAX_RESULTS = 30;
+export declare class FsService {
+    private readonly root;
+    constructor(opts: FsServiceOptions);
+    /** Resolve a target (absolute or relative to root) and confine it to root. */
+    resolveWithinRoot(target: string): string;
+    /** Resolve real paths so a symlink inside root cannot point outside it. Missing -> not-found. */
+    private realWithinRoot;
+    listDirectory(target: string): Promise<DirListing>;
+    /** Read .git/HEAD cheaply; return the branch name or undefined if not a repo. */
+    private readGitBranch;
+    readFileForDownload(target: string): Promise<{
+        filename: string;
+        data: Buffer;
+    }>;
+    /**
+     * Validate that `target` is a real in-root file and describe it for an attachment frame WITHOUT
+     * reading its bytes. Reuses the same resolveWithinRoot + realpath defense as readFileForDownload so
+     * a traversal/symlink-escape path throws FsError("forbidden") and a missing path FsError("not-found").
+     */
+    describeForAttachment(target: string): Promise<{
+        name: string;
+        isImage: boolean;
+    }>;
+    writeUploadedFile(targetDir: string, filename: string, data: Buffer): Promise<{
+        path: string;
+    }>;
+    /** Ensure a directory (confined to root) exists, creating parents as needed; returns its absolute path. */
+    ensureDirWithinRoot(target: string): Promise<string>;
+    /**
+     * POST /fs/mkdir: create ONE new directory (recursive:false — the picker creates a single folder under
+     * an existing parent; a missing parent is a client bug, not something to silently paper over). Same
+     * confinement as listDirectory: resolveWithinRoot on the target + realpath on the PARENT (the target
+     * itself doesn't exist yet), so a symlinked parent can't smuggle the create outside root.
+     * Errors: "exists" (→409) when the path is already taken, "not-found" (→404) when the parent is
+     * missing, "forbidden" (→403) on any escape.
+     */
+    makeDirectory(target: string): Promise<{
+        path: string;
+    }>;
+    /**
+     * GET /fs/search: case-insensitive SUBSTRING match on DIRECTORY names under `base` (default root),
+     * for the project picker's "type to find your repo" flow. Breadth-first — so results come back
+     * shallowest-first without a sort — bounded by {@link SEARCH_MAX_DEPTH} / {@link SEARCH_MAX_DIRS} /
+     * {@link SEARCH_MAX_RESULTS} so a giant tree can never wedge the request. Dot-entries and node_modules
+     * are skipped (never a project root; node_modules alone would blow the dir budget). Unreadable dirs are
+     * skipped, not fatal. Same fsRoot confinement as every other fs route; entries are reported by their
+     * in-root path (symlinked children are NOT re-resolved — mirroring listDirectory).
+     */
+    searchDirectories(query: string, base?: string): Promise<DirSearchResult[]>;
+    /** Prune expired files inside EACH immediate subdirectory of `base` (confined to root). Used to age out
+     *  the terminal shared-files folders (one per session) in a single sweep — including ORPHANED folders
+     *  whose session no longer exists (the old per-live-session sweep leaked those forever). Best-effort:
+     *  returns the total files removed; a missing base / unreadable entry is skipped, not thrown. */
+    pruneChildDirsOlderThan(base: string, maxAgeMs: number, now?: number): Promise<number>;
+    /** Delete top-level regular files in `target` (confined to root) whose mtime is older than `maxAgeMs`.
+     *  Best-effort — returns how many were removed; a missing dir / unreadable entry is skipped, not thrown.
+     *  Subdirectories are left untouched. Used to give terminal shared-files uploads a bounded lifetime. */
+    pruneOlderThan(target: string, maxAgeMs: number, now?: number): Promise<number>;
+}