@bridge4dev/runner 0.11.0

package/dist/index.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { ClaudeAdapter } from './adapters/claude.js';
+import { CodexAdapter } from './adapters/codex.js';
+import { ensureCodexHome } from './adapters/codex-home.js';
+import { loadConfig, requireConfig, saveConfig } from './config.js';
+import { log } from './log.js';
+import { isSupervisedProcess, resolveInstalledPackageDir } from './self-update.js';
+import { Supervisor } from './supervisor.js';
+import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
+import { RunnerWsClient } from './ws-client.js';
+import { RUNNER_VERSION } from './version.js';
+const execFileAsync = promisify(execFile);
+function print(line) {
+    process.stdout.write(line + '\n');
+}
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    process.exit(1);
+}
+function argValue(args, flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+/**
+ * Which agent CLIs this server actually has. Reported at pairing and in every
+ * `hello`, so the dashboard can grey out an agent instead of letting the user
+ * create a session that immediately fails.
+ */
+function installedAgents() {
+    const agents = [];
+    // Claude is bundled inside the Agent SDK, so it is always available.
+    agents.push('claude');
+    if (hasExecutable('codex'))
+        agents.push('codex');
+    return agents;
+}
+/**
+ * Can this process replace itself? Both halves matter: npm must have a real
+ * installation to upgrade, and something must bring the daemon back after it
+ * exits. Reported in `hello`, so the dashboard shows the copyable command
+ * instead of a button that would fail on tap.
+ */
+function selfUpdatable() {
+    return resolveInstalledPackageDir() !== null && isSupervisedProcess();
+}
+function hasExecutable(name) {
+    const dirs = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
+    return dirs.some((dir) => {
+        try {
+            fs.accessSync(path.join(dir, name), fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * What this runner can do, sent in `hello` and stored on DevServer. The API
+ * checks these instead of parsing a version string — and it MUST, because an
+ * older runner drops a frame it cannot parse without ever replying, so a
+ * command it does not know would just hang until the gateway timeout.
+ */
+function runnerCapabilities() {
+    const localLimit = loadConfig()?.limits?.max_sessions;
+    return {
+        agents: installedAgents(),
+        git: true,
+        /** Session 7: resume a terminal session without replaying its old status. */
+        resumeEpoch: true,
+        /** Session 8: understands `maxSessions` and runs sessions side by side. */
+        parallelSessions: true,
+        /**
+         * Session 9: can update itself on command. Reported as a capability rather
+         * than inferred from the version, because the dashboard must not offer a
+         * button whose frame an older runner would silently drop. Only true for an
+         * installed package under a supervisor — a source checkout or a hand-started
+         * daemon says so here, so the button never appears where it cannot work.
+         */
+        ...(selfUpdatable() ? { selfUpdate: true } : {}),
+        /**
+         * A stricter ceiling set on the machine itself (layer 1). Reported so the
+         * dashboard can explain why raising the number there changed nothing.
+         */
+        ...(localLimit ? { maxSessionsLimit: localLimit } : {}),
+        /**
+         * Session 10: understands `attachments` on a session message and can pull
+         * the files onto this machine. The dashboard hides the paperclip without it.
+         */
+        messageAttachments: true,
+        /**
+         * Session 11: `git_log`/`git_show`. Without it the dashboard hides the
+         * History tab rather than showing a tab that answers "unknown command".
+         */
+        gitHistory: true,
+        /** Commands beyond the stage-A/B set. */
+        commands: ['purge_session', 'git_log', 'git_show'],
+    };
+}
+// ─── pair ────────────────────────────────────────────────────────────
+async function cmdPair(args) {
+    const code = args[0];
+    if (!code || !/^DBR-[A-Z2-9]{8}$/.test(code)) {
+        fail('usage: devbridge-runner pair DBR-XXXXXXXX --api https://api.bridge4.dev');
+    }
+    const apiUrl = (argValue(args, '--api') ?? 'https://api.bridge4.dev').replace(/\/$/, '');
+    const name = argValue(args, '--name') ?? os.hostname();
+    const response = await fetch(`${apiUrl}/api/v1/dev/servers/claim`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            pairingCode: code,
+            name,
+            runnerVersion: RUNNER_VERSION,
+            osInfo: `${os.type()} ${os.release()} ${os.arch()}`.slice(0, 200),
+            capabilities: runnerCapabilities(),
+        }),
+    });
+    const body = (await response.json().catch(() => null));
+    if (!response.ok || !body?.success || !body.data) {
+        fail(`pairing failed (HTTP ${response.status}): ${body?.error?.message ?? 'unknown error'}. ` +
+            'The code is one-time and expires in 10 minutes — generate a fresh one in the dashboard if needed.');
+    }
+    const existing = loadConfig();
+    const config = {
+        api: { url: apiUrl, ws_url: body.data.wsUrl },
+        server: { id: body.data.serverId, name: body.data.serverName, token: body.data.token },
+        ...(existing?.mcp ? { mcp: existing.mcp } : {}),
+        // Carry settings the user wrote by hand — saveConfig re-parses through the
+        // schema, so a section dropped here is a section deleted from disk.
+        ...(existing?.codex ? { codex: existing.codex } : {}),
+    };
+    saveConfig(config);
+    print(`Paired as "${body.data.serverName}" (server ${body.data.serverId}).`);
+    print('Start the daemon with: devbridge-runner install-service   (or: devbridge-runner daemon)');
+}
+// ─── daemon ──────────────────────────────────────────────────────────
+/**
+ * Prepare the runner's own CODEX_HOME once, at startup. It is per-runner, not
+ * per-session: a fresh home clones ~90 MB of plugin marketplace on first use.
+ * A failure here disables Codex rather than the whole daemon.
+ */
+function bootstrapCodex(config) {
+    try {
+        const home = ensureCodexHome({ auth: config.codex?.auth ?? 'link' });
+        log.info('codex: isolated home ready', { path: home.path, auth: home.auth });
+        // Deliberately NOT passing `codexHome`: the adapter re-asserts the home on
+        // every session. Freezing this snapshot is how a credential that went
+        // missing mid-day kept being reported as present while sessions failed.
+        // The mode does travel, so those repairs honour `[codex] auth = "own"`.
+        return new CodexAdapter({ authMode: config.codex?.auth ?? 'link' });
+    }
+    catch (error) {
+        log.error('codex: could not prepare an isolated home — Codex disabled', {
+            error: String(error),
+        });
+        return null;
+    }
+}
+/** Long enough for the `command_result` frame to leave the socket. */
+const RESTART_DELAY_MS = 1_500;
+async function cmdDaemon() {
+    const config = requireConfig();
+    log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
+    const agents = installedAgents();
+    const ws = new RunnerWsClient(config.api.ws_url, config.server.token, runnerCapabilities());
+    const codex = agents.includes('codex') ? bootstrapCodex(config) : null;
+    const supervisor = new Supervisor(ws, {
+        adapters: {
+            CLAUDE: new ClaudeAdapter(),
+            ...(codex ? { CODEX: codex } : {}),
+        },
+        ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
+        ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
+        apiUrl: config.api.url,
+        // Used to fetch the files a user attaches to a message (session 10) — the
+        // same token the WS connection authenticates with, never passed onwards.
+        runnerToken: config.server.token,
+        // A successful update ends with this: exit cleanly and let systemd start
+        // the build that was just installed. The delay is for the WS frame that
+        // carries the answer — closing the socket first would leave the dashboard
+        // showing a timeout for an update that worked.
+        onRestartRequested: (outcome) => {
+            log.info('daemon: restarting into the updated build', {
+                from: outcome.fromVersion,
+                to: outcome.toVersion ?? 'unknown',
+            });
+            const timer = setTimeout(() => {
+                supervisor.shutdown();
+                ws.stop();
+                process.exit(0);
+            }, RESTART_DELAY_MS);
+            timer.unref();
+        },
+    });
+    const updateStatus = () => writeStatusFile({
+        pid: process.pid,
+        connected: ws.connected,
+        serverId: config.server.id,
+        serverName: config.server.name,
+        apiUrl: config.api.url,
+        activeSessionIds: supervisor.activeSessionIds,
+        updatedAt: new Date().toISOString(),
+    });
+    ws.on('open', updateStatus);
+    ws.on('close', updateStatus);
+    ws.on('revoked', (reason) => {
+        log.error(`daemon: access revoked (${reason}) — exiting`);
+        supervisor.shutdown();
+        updateStatus();
+        process.exit(3);
+    });
+    const statusTimer = setInterval(updateStatus, 30_000);
+    statusTimer.unref();
+    // Journal housekeeping also runs on every reconnect; this covers a runner
+    // that stays connected for weeks.
+    const pruneTimer = setInterval(() => supervisor.pruneJournals(), 6 * 3_600_000);
+    pruneTimer.unref();
+    const shutdown = (signal) => {
+        log.info(`daemon: ${signal} received, shutting down`);
+        supervisor.shutdown();
+        ws.stop();
+        updateStatus();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    ws.start();
+    updateStatus();
+    // Keep the process alive forever; ws timers drive everything.
+    await new Promise(() => undefined);
+}
+// ─── status ──────────────────────────────────────────────────────────
+function cmdStatus() {
+    const config = loadConfig();
+    if (!config) {
+        print('NOT PAIRED — run: devbridge-runner pair <code> --api <url>');
+        process.exit(1);
+    }
+    const status = readStatusFile();
+    const fresh = status &&
+        isPidAlive(status.pid) &&
+        Date.now() - new Date(status.updatedAt).getTime() < STATUS_FRESH_MS;
+    if (!fresh) {
+        print(`NOT RUNNING — server "${config.server.name}" (${config.api.url})`);
+        print('Start with: devbridge-runner install-service   (or: devbridge-runner daemon)');
+        process.exit(1);
+    }
+    if (status.connected) {
+        print(`CONNECTED — server "${status.serverName}" → ${status.apiUrl}`);
+        if (status.activeSessionIds.length) {
+            print(`Active sessions: ${status.activeSessionIds.join(', ')}`);
+        }
+        process.exit(0);
+    }
+    print(`DISCONNECTED — daemon is running (pid ${status.pid}) but not connected; check network/logs`);
+    process.exit(1);
+}
+// ─── install-service ─────────────────────────────────────────────────
+function systemdUnit() {
+    const script = fs.realpathSync(process.argv[1] ?? '');
+    return [
+        '[Unit]',
+        'Description=DevBridge Dev Runner',
+        'After=network-online.target',
+        '',
+        '[Service]',
+        `ExecStart=${process.execPath} ${script} daemon`,
+        'Restart=always',
+        'RestartSec=5',
+        'CPUQuota=80%',
+        'MemoryMax=2G',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n');
+}
+async function cmdInstallService() {
+    requireConfig(); // fail early if not paired
+    if (process.platform !== 'linux')
+        fail('install-service supports Linux/systemd only');
+    const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    fs.mkdirSync(unitDir, { recursive: true });
+    const unitPath = path.join(unitDir, 'devbridge-runner.service');
+    fs.writeFileSync(unitPath, systemdUnit() + '\n');
+    print(`Wrote ${unitPath}`);
+    try {
+        await execFileAsync('systemctl', ['--user', 'daemon-reload']);
+        await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner']);
+        print('Service enabled and started (systemctl --user).');
+    }
+    catch (error) {
+        fail(`systemctl failed: ${String(error instanceof Error ? error.message : error)}. ` +
+            'Start manually with `systemctl --user enable --now devbridge-runner` or run `devbridge-runner daemon` under your supervisor.');
+    }
+    try {
+        await execFileAsync('loginctl', ['enable-linger', os.userInfo().username]);
+        print('Linger enabled — the runner survives logout.');
+    }
+    catch {
+        print('warning: could not enable linger; run `loginctl enable-linger $USER` manually.');
+    }
+    print('Verify with: devbridge-runner status');
+}
+// ─── set-token ───────────────────────────────────────────────────────
+function cmdSetToken(args) {
+    const token = args[0];
+    if (!token || !token.startsWith('dbr_'))
+        fail('usage: devbridge-runner set-token dbr_…');
+    const config = requireConfig();
+    saveConfig({ ...config, server: { ...config.server, token } });
+    print('Token updated. Restart the daemon: systemctl --user restart devbridge-runner');
+}
+// ─── main ────────────────────────────────────────────────────────────
+const HELP = `devbridge-runner ${RUNNER_VERSION}
+
+Usage:
+  devbridge-runner pair <DBR-code> [--api <url>] [--name <name>]   pair this server with DevBridge
+  devbridge-runner daemon                                          run the runner (foreground)
+  devbridge-runner install-service                                 install + start systemd user service
+  devbridge-runner status                                          connection status (exit 0 = connected)
+  devbridge-runner set-token <dbr_token>                           store a rotated runner token
+`;
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    switch (command) {
+        case 'pair':
+            return cmdPair(args);
+        case 'daemon':
+            return cmdDaemon();
+        case 'status':
+            return cmdStatus();
+        case 'install-service':
+            return cmdInstallService();
+        case 'set-token':
+            return cmdSetToken(args);
+        case '--version':
+        case 'version':
+            print(RUNNER_VERSION);
+            return;
+        default:
+            print(HELP);
+            process.exit(command ? 1 : 0);
+    }
+}
+main().catch((error) => fail(String(error instanceof Error ? error.message : error)));
+//# sourceMappingURL=index.js.map

package/dist/journal.d.ts

@@ -0,0 +1,118 @@
+export interface JournalEvent {
+    seq: number;
+    eventType: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * A user message the runner accepted but has not handed to an agent yet —
+ * because the worktree was still being prepared, or every session slot was
+ * taken. It lives in the journal for the same reason events do: the API
+ * considers it delivered the moment it hands it over, so losing it to a daemon
+ * restart means the user sees their own bubble in the feed and never an answer
+ * (QA-102 tail, session 9).
+ */
+export interface PendingMessage {
+    id: string;
+    text: string;
+    /**
+     * Files that came with the message (session 10). Held as metadata, not bytes:
+     * they are downloaded at delivery time, which is also the first moment the
+     * session worktree is guaranteed to exist.
+     */
+    attachments?: PendingAttachment[];
+}
+export interface PendingAttachment {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+}
+export declare class SessionJournal {
+    readonly sessionId: string;
+    private readonly file;
+    private nextSeq;
+    private readonly unackedBySeq;
+    /** Messages accepted from the API but not yet handed to an agent. */
+    private readonly pendingById;
+    private pendingCounter;
+    /** Bytes written since the file was last rewritten from live state. */
+    private bytesOnDisk;
+    /** Last status reported for this session — replayed after a reconnect. */
+    lastStatus: {
+        status: string;
+        extra?: Record<string, unknown>;
+        epoch?: number;
+    } | null;
+    constructor(sessionId: string, dir?: string);
+    private replay;
+    private write;
+    /**
+     * Rewrite the file from live state: the seq counter, the events still waiting
+     * for an ack, and the last reported status. Everything else is history the
+     * runner never reads again.
+     *
+     * Atomic (tmp + rename) so a crash mid-compaction leaves the previous file
+     * intact rather than a truncated one.
+     */
+    compact(): void;
+    private compactIfLarge;
+    /**
+     * Statuses are fire-and-forget on the wire; journaling the latest one lets
+     * the supervisor re-report it after a reconnect (QA-96 F1).
+     */
+    recordStatus(status: string, extra?: Record<string, unknown>, epoch?: number): void;
+    /** Assign the next seq and persist the event before it is sent. */
+    append(eventType: string, payload: Record<string, unknown>): JournalEvent;
+    /**
+     * Never reuse a seq the API already stored: after a runner state-dir wipe the
+     * local counter restarts at 1 and every replayed event would collide with an
+     * existing (sessionId, seq) row and be swallowed as a duplicate — the session
+     * would look mute in the dashboard (QA-99 MAJOR-3).
+     */
+    ensureSeqAbove(lastStoredSeq: number): void;
+    ack(seq: number): void;
+    unacked(): JournalEvent[];
+    /**
+     * Record a message that could not be handed to an agent yet. Persisted before
+     * it is queued in memory, so the ordering is "on disk, then held" — a crash
+     * between the two costs a duplicate delivery at worst, never a lost message.
+     */
+    appendPending(text: string, attachments?: PendingAttachment[]): PendingMessage;
+    /** The message reached an agent — stop replaying it after a restart. */
+    resolvePending(id: string): void;
+    /** Messages still waiting, oldest first (ids are minted in order). */
+    pending(): PendingMessage[];
+    get lastAssignedSeq(): number;
+    /** Delete the journal file — used when a terminal session is fully acked. */
+    destroy(): void;
+}
+export declare class JournalStore {
+    private readonly dir;
+    private readonly journals;
+    constructor(dir?: string);
+    open(sessionId: string): SessionJournal;
+    exists(sessionId: string): boolean;
+    /** Sessions with journal files on disk (used for redelivery on reconnect). */
+    persistedSessionIds(): string[];
+    closeAndDelete(sessionId: string): void;
+    /**
+     * Drop journals of sessions that ended long ago.
+     *
+     * Two ages, on purpose. A journal with unacked events is the *only* copy of
+     * those events, and the recorded terminal status is what gets replayed after
+     * a reconnect (QA-96 F1) — so within `maxAgeMs` a non-empty journal is never
+     * touched. `hardMaxAgeMs` is the backstop for a session whose events the API
+     * will never accept (an org deleted server-side, say), so the directory
+     * cannot grow without bound.
+     *
+     * Returns the ids actually removed.
+     */
+    prune(options: {
+        maxAgeMs: number;
+        hardMaxAgeMs: number;
+        /** Session ids the supervisor still tracks — never pruned. */
+        skip: ReadonlySet<string>;
+        now?: number;
+    }): string[];
+}
+//# sourceMappingURL=journal.d.ts.map