@bridge4dev/runner 0.11.0

package/dist/protocol.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+// Wire protocol with the DevBridge API (mirror of
+// packages/api/src/modules/dev-orchestration/dev-orchestration.schema.ts —
+// the API side is the source of truth).
+export const SessionDescriptorSchema = z.object({
+    id: z.string().uuid(),
+    kind: z.enum(['TICKET', 'CHAT']),
+    agent: z.enum(['CLAUDE', 'CODEX']),
+    status: z.enum([
+        'STARTING',
+        'RUNNING',
+        'WAITING_INPUT',
+        'WAITING_PERMISSION',
+        'REVIEW',
+        'DONE',
+        'FAILED',
+        'STOPPED',
+    ]),
+    // Empty for free CHAT sessions: the agent boots and waits for the first message.
+    prompt: z.string(),
+    providerSessionId: z.string().nullable(),
+    // Interaction settings (session-5): normalized across agents.
+    mode: z.enum(['ask', 'plan', 'auto', 'full']).optional().default('ask'),
+    model: z.string().nullable().optional().default(null),
+    // Reasoning effort for agents that advertise levels (Codex Sol line adds
+    // max/ultra) — null when the agent has no such dial or none was picked.
+    effort: z.string().nullable().optional().default(null),
+    // Highest event seq the API already stored for this session — the journal
+    // never reuses it after a runner state wipe (QA-99 MAJOR-3).
+    lastSeq: z.number().int().min(0).optional().default(0),
+    // Cost already accumulated (base for a restarted runner). Optional for
+    // compatibility with older API versions.
+    costUsd: z.number().min(0).optional().default(0),
+    // Bumped by the API every time the session is resumed from a terminal state.
+    // The journal stamps it on status lines so an older life's terminal status
+    // cannot be replayed over a session that has since been picked back up.
+    epoch: z.number().int().min(0).optional().default(0),
+    // Agent-active milliseconds already spent (session 7). The time budget spends
+    // THIS, not wall clock — waiting on a human must not burn the limit.
+    activeMsBase: z.number().int().min(0).optional().default(0),
+    // Extra minutes granted by «Продолжить», on top of the workspace budget.
+    extraBudgetMinutes: z.number().int().min(0).nullable().optional().default(null),
+    workspace: z.object({
+        id: z.string().uuid(),
+        path: z.string(),
+        projectId: z.string().uuid(),
+        trustMode: z.enum(['STRICT', 'NORMAL', 'AUTO']),
+        budgetUsd: z.number().nullable(),
+        budgetMinutes: z.number().nullable(),
+    }),
+    tickets: z.array(z.object({ id: z.string().uuid(), number: z.number(), title: z.string() })),
+    // Branch the API would like this session to use (derived from its ticket
+    // group). Optional: an older API omits it and the runner keeps its
+    // id-derived name. Validated here because it becomes a git ref.
+    // A malformed hint must never cost us the descriptor: the frame carries the
+    // whole session (and hello_ack carries every session of the server), so a
+    // strict failure here used to drop them all (QA-100 MAJOR-1). Bad hint =>
+    // no hint, and the runner falls back to its id-derived branch name.
+    branchHint: z
+        .string()
+        .max(120)
+        .regex(/^[A-Za-z0-9][A-Za-z0-9._\-/]*$/)
+        .optional()
+        .catch(undefined),
+    // Auto-provisioned DevBridge MCP access (dbk_ key scoped to the workspace
+    // project). Preferred over the [mcp] section of config.toml when present.
+    mcp: z.object({ url: z.string().url(), token: z.string().min(1) }).optional(),
+});
+export const GatewayFrameSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('hello_ack'),
+        serverId: z.string(),
+        serverName: z.string(),
+        // How many sessions this server may run at once (session 8). Absent from an
+        // older API — the runner then keeps its historical single-slot behaviour.
+        // Deliberately NOT bounded to the runner's own hard cap here: an
+        // out-of-range number is clamped by the supervisor, while `undefined` means
+        // "this API never told us" and collapses the server to one agent. Rejecting
+        // 999 into `undefined` would confuse the two (QA-102 MINOR-5). `.catch`
+        // still covers genuinely malformed values, because a nonsense field must
+        // not cost us the frame that carries every session of the server.
+        maxSessions: z.number().int().positive().optional().catch(undefined),
+        sessions: z.array(SessionDescriptorSchema),
+    }),
+    z.object({ type: z.literal('event_ack'), sessionId: z.string().uuid(), seq: z.number().int() }),
+    z.object({
+        type: z.literal('event_nack'),
+        sessionId: z.string().uuid(),
+        seq: z.number().int(),
+        reason: z.string(),
+    }),
+    z.object({ type: z.literal('session_start'), session: SessionDescriptorSchema }),
+    z.object({
+        type: z.literal('session_message'),
+        sessionId: z.string().uuid(),
+        text: z.string(),
+        // Files the user attached (session 10) — metadata only; the bytes are
+        // fetched with the runner's own token. `.catch` so a malformed entry costs
+        // the attachments, never the message the user typed.
+        attachments: z
+            .array(z.object({
+            id: z.string().uuid(),
+            fileName: z.string().max(500),
+            mimeType: z.string().max(200),
+            fileSize: z.number().int().min(0),
+        }))
+            .max(10)
+            .optional()
+            .catch(undefined),
+    }),
+    z.object({
+        type: z.literal('permission_answer'),
+        sessionId: z.string().uuid(),
+        requestId: z.string(),
+        allow: z.boolean(),
+        note: z.string().optional(),
+    }),
+    z.object({ type: z.literal('session_stop'), sessionId: z.string().uuid() }),
+    z.object({ type: z.literal('session_interrupt'), sessionId: z.string().uuid() }),
+    // Server-wide settings changed mid-connection (session 8) — today just the
+    // parallel-session ceiling.
+    z.object({
+        type: z.literal('server_settings'),
+        maxSessions: z.number().int().positive().optional().catch(undefined),
+    }),
+    z.object({
+        type: z.literal('session_settings'),
+        sessionId: z.string().uuid(),
+        model: z.string().min(1).max(120).optional(),
+        mode: z.enum(['ask', 'plan', 'auto', 'full']).optional(),
+        // null = clear the pin and fall back to the model's own default.
+        effort: z.string().min(1).max(40).nullable().optional(),
+    }),
+    z.object({
+        type: z.literal('command'),
+        requestId: z.string(),
+        // Deliberately a free string and NOT an enum, so every future command is
+        // additive. An unrecognised frame is dropped whole by ws-client with no
+        // reply, which means a newer API calling a command an older runner does not
+        // know would just hang until the gateway timeout — with a string the frame
+        // parses, reaches `default:` and answers "Unknown command" immediately.
+        // The strict `RunnerCommandName` union on the API side stays the authority.
+        // Known names: validate_path, clean, purge_session, reset_workspace,
+        // git_status, git_diff, git_commit, apply_session, revert_apply, fs_view,
+        // auth_status, login_start, login_code, self_update.
+        name: z.string().min(1).max(64),
+        workspaceId: z.string().optional(),
+        sessionId: z.string().optional(),
+        args: z.record(z.unknown()).optional(),
+    }),
+    z.object({ type: z.literal('revoked'), reason: z.string() }),
+    z.object({ type: z.literal('error'), message: z.string() }),
+]);
+//# sourceMappingURL=protocol.js.map

package/dist/self-update.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Updating the runner from the dashboard (session 9, plan A1).
+ *
+ * This installs and runs code on someone else's machine, so the whole module is
+ * written around four refusals rather than around the happy path:
+ *
+ *  1. **Only our own tarball.** The URL must live on the same origin the runner
+ *     is paired with. The API is trusted — it already tells us what to run — but
+ *     "trusted" and "may name any URL on the internet" are different things.
+ *  2. **Only a real installation.** Running from a source checkout means npm
+ *     would install a *second* copy elsewhere and the update would silently do
+ *     nothing; we say so instead.
+ *  3. **Only under a supervisor.** The last step of an update is exiting, and
+ *     something has to bring the process back. Without systemd the runner would
+ *     simply disappear.
+ *  4. **Only if the new build actually starts.** The freshly installed binary is
+ *     executed (`--version`, which loads the whole module graph) BEFORE we agree
+ *     to restart. If it does not come up, the previous version is reinstalled
+ *     from a tarball packed a moment earlier and nothing restarts.
+ */
+export interface SelfUpdateOutcome {
+    ok: boolean;
+    fromVersion: string;
+    toVersion?: string;
+    /** True only when the caller should now exit and let the supervisor restart. */
+    restart: boolean;
+    detail?: string;
+    /** Where the previous version was saved, for a manual `npm i -g <file>`. */
+    rollbackTarball?: string;
+}
+export interface SelfUpdateOptions {
+    /** Tarball to install, e.g. `https://api…/api/v1/dev-setup/runner.tgz`. */
+    tarballUrl: string;
+    /** The API this runner is paired with — the only origin we install from. */
+    apiUrl: string;
+    /** Test seam. */
+    exec?: (file: string, args: string[], options: {
+        timeout: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Test seam: the installed package directory (defaults to autodetect). */
+    packageDir?: string | null;
+    /** Test seam: is this process supervised (defaults to autodetect). */
+    supervised?: boolean;
+}
+/**
+ * Directory of the installed runner package, or null when it is running from a
+ * source checkout.
+ *
+ * The `node_modules` segment is the signal: a global npm install lives in
+ * `<prefix>/lib/node_modules/@bridge4dev/runner`, while a monorepo checkout never
+ * has one above `packages/runner`.
+ */
+export declare function resolveInstalledPackageDir(entry?: string): string | null;
+/**
+ * Is something going to restart us?
+ *
+ * `INVOCATION_ID` is set by systemd for every service process since v232 and is
+ * the cheapest honest answer. Anything else (a terminal, tmux, a Docker
+ * entrypoint without a restart policy) is treated as "no" — refusing an update
+ * that would work is recoverable, disappearing from the user's server is not.
+ */
+export declare function isSupervisedProcess(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Same origin as the API we are paired with, and it really is a tarball.
+ *
+ * `URL.origin` covers the protocol as well, so a paired-over-https runner can
+ * never be talked into fetching its own replacement over http.
+ */
+export declare function isTrustedTarballUrl(tarballUrl: string, apiUrl: string): boolean;
+export declare function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdateOutcome>;
+//# sourceMappingURL=self-update.d.ts.map

package/dist/self-update.js

@@ -0,0 +1,221 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { log } from './log.js';
+import { stateDir } from './paths.js';
+import { RUNNER_VERSION } from './version.js';
+const execFileAsync = promisify(execFile);
+const NPM_TIMEOUT_MS = 180_000;
+const VERIFY_TIMEOUT_MS = 30_000;
+/**
+ * Every name this package has shipped under. `@devbridge/runner` was the name
+ * used by the tarball installs that predate the npm publish, and those runners
+ * are the ones that will download and install the renamed package — so a build
+ * that only recognised the new name would fail to find itself mid-update and
+ * refuse to continue. Keep the old name here as long as any server might still
+ * be running it.
+ */
+const PACKAGE_NAMES = ['@bridge4dev/runner', '@devbridge/runner'];
+/**
+ * Directory of the installed runner package, or null when it is running from a
+ * source checkout.
+ *
+ * The `node_modules` segment is the signal: a global npm install lives in
+ * `<prefix>/lib/node_modules/@bridge4dev/runner`, while a monorepo checkout never
+ * has one above `packages/runner`.
+ */
+export function resolveInstalledPackageDir(entry = process.argv[1] ?? '') {
+    let dir;
+    try {
+        dir = path.dirname(fs.realpathSync(entry));
+    }
+    catch {
+        return null;
+    }
+    for (let i = 0; i < 8; i++) {
+        const manifest = path.join(dir, 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+                if (typeof parsed.name === 'string' && PACKAGE_NAMES.includes(parsed.name)) {
+                    return dir.split(path.sep).includes('node_modules') ? dir : null;
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Is something going to restart us?
+ *
+ * `INVOCATION_ID` is set by systemd for every service process since v232 and is
+ * the cheapest honest answer. Anything else (a terminal, tmux, a Docker
+ * entrypoint without a restart policy) is treated as "no" — refusing an update
+ * that would work is recoverable, disappearing from the user's server is not.
+ */
+export function isSupervisedProcess(env = process.env) {
+    return typeof env['INVOCATION_ID'] === 'string' && env['INVOCATION_ID'].length > 0;
+}
+/**
+ * Same origin as the API we are paired with, and it really is a tarball.
+ *
+ * `URL.origin` covers the protocol as well, so a paired-over-https runner can
+ * never be talked into fetching its own replacement over http.
+ */
+export function isTrustedTarballUrl(tarballUrl, apiUrl) {
+    let target;
+    let api;
+    try {
+        target = new URL(tarballUrl);
+        api = new URL(apiUrl);
+    }
+    catch {
+        return false;
+    }
+    return target.origin === api.origin && target.pathname.endsWith('.tgz');
+}
+function readVersion(packageDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The CLI entry point of an installed package, used to smoke-test the update. */
+function binPath(packageDir) {
+    return path.join(packageDir, 'dist', 'index.js');
+}
+/**
+ * npm needs PATH/HOME and a writable cache; everything else is stripped, both to
+ * keep provider credentials out of a child process that touches the network and
+ * to stop a stray `npm_config_*` from redirecting the install.
+ */
+function npmEnv() {
+    const env = {
+        PATH: process.env['PATH'] ?? '/usr/local/bin:/usr/bin:/bin',
+        HOME: process.env['HOME'] ?? '',
+        // npm writes progress to a TTY-shaped stream otherwise.
+        npm_config_progress: 'false',
+        npm_config_fund: 'false',
+        npm_config_audit: 'false',
+    };
+    if (process.env['XDG_CACHE_HOME'])
+        env['XDG_CACHE_HOME'] = process.env['XDG_CACHE_HOME'];
+    return env;
+}
+export async function selfUpdate(options) {
+    const exec = options.exec ??
+        ((file, args, opts) => execFileAsync(file, args, { timeout: opts.timeout, env: opts.env, maxBuffer: 4_000_000 }));
+    const fromVersion = RUNNER_VERSION;
+    const fail = (detail, extra = {}) => ({
+        ok: false,
+        fromVersion,
+        restart: false,
+        detail,
+        ...extra,
+    });
+    if (!isTrustedTarballUrl(options.tarballUrl, options.apiUrl)) {
+        return fail('The update package must be served by the DevBridge API this runner is paired with');
+    }
+    const supervised = options.supervised ?? isSupervisedProcess();
+    if (!supervised) {
+        return fail('The runner is not running as a service, so nothing would start it again after the update. ' +
+            'Install it with `devbridge-runner install-service`, or update it by hand.');
+    }
+    const packageDir = options.packageDir === undefined ? resolveInstalledPackageDir() : options.packageDir;
+    if (!packageDir) {
+        return fail('This runner runs from a source checkout, not from an installed package — update it with git instead.');
+    }
+    // Pack the current version FIRST: without a rollback artefact there is no
+    // honest way back if the new build turns out to be broken.
+    const rollbackDir = path.join(stateDir(), 'rollback');
+    let rollbackTarball;
+    try {
+        fs.mkdirSync(rollbackDir, { recursive: true, mode: 0o700 });
+        const packed = await exec('npm', ['pack', packageDir, '--pack-destination', rollbackDir], {
+            timeout: NPM_TIMEOUT_MS,
+            env: npmEnv(),
+        });
+        const name = packed.stdout.trim().split('\n').pop()?.trim();
+        if (name) {
+            const candidate = path.join(rollbackDir, path.basename(name));
+            if (fs.existsSync(candidate))
+                rollbackTarball = candidate;
+        }
+    }
+    catch (error) {
+        log.warn('self-update: could not pack a rollback copy', { error: String(error) });
+    }
+    if (!rollbackTarball) {
+        return fail('Could not prepare a rollback copy of the current version — update aborted');
+    }
+    try {
+        // `--ignore-scripts` matches the documented install: this package and its
+        // whole tree have no install/postinstall scripts, so nothing legitimate is
+        // skipped — and an update pulled over the network gets no chance to run
+        // anything at install time.
+        await exec('npm', ['install', '-g', '--ignore-scripts', options.tarballUrl], {
+            timeout: NPM_TIMEOUT_MS,
+            env: npmEnv(),
+        });
+    }
+    catch (error) {
+        return fail(`Install failed: ${describe(error)}`, { rollbackTarball });
+    }
+    const toVersion = readVersion(packageDir) ?? undefined;
+    // The real test: does the newly installed build start? `--version` loads the
+    // whole module graph, so a half-downloaded package or a missing dependency
+    // fails here rather than after the restart, when nobody could see it.
+    try {
+        const probe = await exec(process.execPath, [binPath(packageDir), '--version'], {
+            timeout: VERIFY_TIMEOUT_MS,
+            env: npmEnv(),
+        });
+        const printed = probe.stdout.trim();
+        if (!/^\d+\.\d+\.\d+/.test(printed)) {
+            throw new Error(`unexpected version output: ${printed.slice(0, 120)}`);
+        }
+    }
+    catch (error) {
+        const detail = describe(error);
+        log.error('self-update: the new build did not start — rolling back', { error: detail });
+        try {
+            await exec('npm', ['install', '-g', '--ignore-scripts', rollbackTarball], {
+                timeout: NPM_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            return fail(`The new version did not start (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+        catch (rollbackError) {
+            return fail(`The new version did not start (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
+                `Restore it on the server with: npm install -g ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+    }
+    log.info('self-update: installed', { fromVersion, toVersion });
+    return {
+        ok: true,
+        fromVersion,
+        ...(toVersion ? { toVersion } : {}),
+        restart: true,
+        rollbackTarball,
+    };
+}
+function describe(error) {
+    if (error instanceof Error) {
+        const withStderr = error;
+        const stderr = typeof withStderr.stderr === 'string' ? withStderr.stderr.trim() : '';
+        return (stderr || error.message).slice(0, 400);
+    }
+    return String(error).slice(0, 400);
+}
+//# sourceMappingURL=self-update.js.map

package/dist/status-file.d.ts

@@ -0,0 +1,14 @@
+export interface DaemonStatus {
+    pid: number;
+    connected: boolean;
+    serverId: string;
+    serverName: string;
+    apiUrl: string;
+    activeSessionIds: string[];
+    updatedAt: string;
+}
+export declare const STATUS_FRESH_MS = 90000;
+export declare function writeStatusFile(status: DaemonStatus): void;
+export declare function readStatusFile(): DaemonStatus | null;
+export declare function isPidAlive(pid: number): boolean;
+//# sourceMappingURL=status-file.d.ts.map

package/dist/status-file.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir, statusFilePath } from './paths.js';
+export const STATUS_FRESH_MS = 90_000;
+export function writeStatusFile(status) {
+    const dir = stateDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.status.json.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(status, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, statusFilePath());
+}
+export function readStatusFile() {
+    try {
+        return JSON.parse(fs.readFileSync(statusFilePath(), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=status-file.js.map