@bridge4dev/runner 0.11.0

package/dist/adapters/codex-home.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stateDir } from '../paths.js';
+import { log } from '../log.js';
+// A dedicated CODEX_HOME for the runner. This is a security control, not tidiness.
+//
+// The host user's ~/.codex/config.toml is theirs to write, and in the wild it
+// contains exactly the settings we must never inherit — the owner's own file on
+// our dogfood server has `approval_policy = "never"`,
+// `sandbox_mode = "danger-full-access"` and a live DevBridge MCP key in
+// plaintext inside a URL. Inheriting it would give every client session full
+// disk access with zero approval prompts, using someone else's key.
+//
+// Verified live: with CODEX_HOME pointed here, `config/read` reports exactly two
+// layers (ours + the always-present system file) and the user's config is not
+// among them.
+const CONFIG_FILENAME = 'config.toml';
+const AUTH_FILENAME = 'auth.json';
+/**
+ * Records how this home is meant to be authenticated. Without it a plain
+ * auth.json is ambiguous — it could be our own device login, or codex having
+ * replaced our symlink. A MISSING marker always reads as `own`: treating an
+ * unknown file as a link would let us move somebody's real credential around.
+ */
+const MODE_FILENAME = '.devbridge-auth-mode';
+/**
+ * Minimal config. Deliberately has NO `[mcp_servers]` section: a per-thread
+ * config overlay MERGES with the home config at the map-key level (verified
+ * live), so anything declared here would leak into every session's thread and
+ * could not be removed by the overlay.
+ */
+const CONFIG_BODY = [
+    '# Managed by @bridge4dev/runner — do not edit.',
+    '# Sessions get their approval policy, sandbox and MCP servers per thread;',
+    '# these are only the fallbacks for a thread that sets nothing.',
+    'approval_policy = "on-request"',
+    'sandbox_mode = "workspace-write"',
+    '',
+].join('\n');
+export function codexHomePath() {
+    return path.join(stateDir(), 'codex-home');
+}
+/**
+ * Throwaway home for a device-code login. The flow runs here and is promoted
+ * into the real home only on success, so an abandoned or timed-out sign-in
+ * cannot destroy a credential that was working.
+ */
+export function stagingCodexHomePath() {
+    return path.join(stateDir(), 'codex-login');
+}
+function readMode(dir) {
+    try {
+        const value = fs.readFileSync(path.join(dir, MODE_FILENAME), 'utf8').trim();
+        return value === 'link' || value === 'own' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMode(dir, mode) {
+    try {
+        fs.writeFileSync(path.join(dir, MODE_FILENAME), mode, { mode: 0o600 });
+    }
+    catch (error) {
+        log.warn('codex: could not record the auth mode', { error: String(error) });
+    }
+}
+/**
+ * Create (or refresh) the runner's CODEX_HOME and return it.
+ *
+ * `auth: 'link'` (default) symlinks the host user's `~/.codex/auth.json` so the
+ * runner uses their ChatGPT subscription and — importantly — shares one
+ * credential store with their own CLI, so a token refresh on either side keeps
+ * both working. `auth: 'own'` leaves the home unauthenticated until a
+ * device-code login writes into it, which is the choice for full isolation.
+ *
+ * A home under the OS temp dir still works, but codex then refuses to install
+ * its helper binaries ("Refusing to create helper binaries under temporary
+ * dir") — which can quietly break the agent's shell tooling, so it is worth a
+ * warning rather than a failure.
+ */
+export function ensureCodexHome(options = {}) {
+    const dir = codexHomePath();
+    if (isUnderTempDir(dir)) {
+        log.warn('codex: CODEX_HOME is under the temp dir — codex will skip its helper binaries', {
+            path: dir,
+        });
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // The directory carries secrets: the per-thread config overlay (MCP key
+    // included) is persisted inside codex's own sqlite logs.
+    fs.chmodSync(dir, 0o700);
+    const configFile = path.join(dir, CONFIG_FILENAME);
+    const current = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : null;
+    if (current !== CONFIG_BODY) {
+        fs.writeFileSync(configFile, CONFIG_BODY, { mode: 0o600 });
+        // `mode` only applies when the file is CREATED — an existing file keeps its
+        // old, possibly wider permissions (QA-100 MINOR-8).
+        fs.chmodSync(configFile, 0o600);
+    }
+    return { path: dir, auth: ensureAuth(dir, options) };
+}
+function ensureAuth(dir, options) {
+    const target = path.join(dir, AUTH_FILENAME);
+    const userAuth = path.join(options.homedir ?? os.homedir(), '.codex', AUTH_FILENAME);
+    const recorded = readMode(dir);
+    // The marker is the persisted decision. Callers that do not name a mode —
+    // the per-session repair, the health probe — must inherit it, or an
+    // isolated home would be re-linked to the host credential by the next probe
+    // that happens to run.
+    const mode = options.auth ?? recorded ?? 'link';
+    const existing = lstatOrNull(target);
+    // A real file is a usable credential, full stop. We do NOT try to be clever
+    // and push it back into the host user's ~/.codex: that file is theirs, we
+    // cannot know which copy is newer, and getting it wrong costs them their
+    // login. If codex replaced our symlink with its own atomic write, the
+    // credential it wrote is right here — keep using it, and record that this
+    // home now owns its login so we never overwrite it later.
+    if (existing?.isFile()) {
+        if (recorded === 'link') {
+            log.warn("codex: auth.json is no longer a shared link — keeping it as this runner's own", {
+                path: target,
+            });
+        }
+        writeMode(dir, 'own');
+        return 'own';
+    }
+    if (mode === 'own') {
+        if (existing?.isSymbolicLink())
+            fs.rmSync(target, { force: true });
+        writeMode(dir, 'own');
+        return 'missing';
+    }
+    if (existing?.isSymbolicLink()) {
+        // Repoint if the user's file moved or the link went stale.
+        const resolved = fs.readlinkSync(target);
+        if (resolved === userAuth && fs.existsSync(userAuth)) {
+            writeMode(dir, 'link');
+            return 'linked';
+        }
+        fs.rmSync(target, { force: true });
+    }
+    if (!fs.existsSync(userAuth))
+        return 'missing';
+    try {
+        fs.symlinkSync(userAuth, target);
+        writeMode(dir, 'link');
+        // Loud on purpose: the link going missing under a live daemon is exactly
+        // the failure that made the panel report "login expired" about a perfectly
+        // valid credential, and nothing recorded it. Now it does.
+        if (!existing) {
+            log.info('codex: linked the host auth.json into the isolated home', { path: target });
+        }
+        return 'linked';
+    }
+    catch (error) {
+        log.warn('codex: could not link the host auth.json', { error: String(error) });
+        return 'missing';
+    }
+}
+/**
+ * Cheap re-assert of the home's credential, safe to call on every session start
+ * and before every probe. Does NOT rewrite the config or touch codex's caches —
+ * it only answers "is the credential still where we left it, and if not, can we
+ * put it back". This is what makes a credential disappearing under a running
+ * daemon self-healing instead of permanent.
+ */
+export function repairCodexAuth(options = {}) {
+    const dir = codexHomePath();
+    if (!fs.existsSync(dir))
+        return ensureCodexHome(options);
+    return { path: dir, auth: ensureAuth(dir, options) };
+}
+function isUnderTempDir(dir) {
+    try {
+        const tmp = fs.realpathSync(os.tmpdir());
+        return path.resolve(dir).startsWith(tmp + path.sep);
+    }
+    catch {
+        return false;
+    }
+}
+function lstatOrNull(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Drop a linked auth.json so a device-code login writes our own file instead.
+ *
+ * Only ever called AFTER a login has actually succeeded in the staging home —
+ * never as a pre-step. Detaching first meant an abandoned or timed-out sign-in
+ * left the server permanently "not signed in", recoverable only by restarting
+ * the daemon.
+ */
+export function detachLinkedAuth(dir = codexHomePath()) {
+    const target = path.join(dir, AUTH_FILENAME);
+    if (lstatOrNull(target)?.isSymbolicLink())
+        fs.rmSync(target, { force: true });
+}
+/**
+ * Promote a credential produced by a staging login into the real home, and
+ * record that this home now owns its own login.
+ */
+export function adoptLoginResult(stagingDir, dir = codexHomePath()) {
+    const source = path.join(stagingDir, AUTH_FILENAME);
+    if (!lstatOrNull(source)?.isFile())
+        return false;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    detachLinkedAuth(dir);
+    const target = path.join(dir, AUTH_FILENAME);
+    fs.copyFileSync(source, target);
+    fs.chmodSync(target, 0o600);
+    writeMode(dir, 'own');
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    return true;
+}
+/** Seed a throwaway home for the device-code flow (config only, no credential). */
+export function prepareStagingHome() {
+    const dir = stagingCodexHomePath();
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(dir, CONFIG_FILENAME), CONFIG_BODY, { mode: 0o600 });
+    return dir;
+}
+/** Remove the staging home whatever the outcome — it may hold a credential. */
+export function discardStagingHome() {
+    fs.rmSync(stagingCodexHomePath(), { recursive: true, force: true });
+}
+//# sourceMappingURL=codex-home.js.map

package/dist/adapters/codex-protocol.d.ts

@@ -0,0 +1,59 @@
+export interface RpcErrorBody {
+    code: number;
+    message: string;
+}
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly method: string;
+    constructor(code: number, message: string, method: string);
+}
+export interface ServerRequest {
+    id: number | string;
+    method: string;
+    params: Record<string, unknown>;
+}
+export interface AppServerOptions {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env: Record<string, string>;
+    onNotification: (method: string, params: Record<string, unknown>) => void;
+    onServerRequest: (request: ServerRequest) => void;
+    /** Fired once when the child is gone — the session's end-of-stream signal. */
+    onExit: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void;
+    onStderr?: (text: string) => void;
+    requestTimeoutMs?: number;
+}
+export declare class AppServerClient {
+    private readonly opts;
+    private readonly child;
+    private readonly pending;
+    private nextId;
+    private stdoutBuffer;
+    private exited;
+    constructor(opts: AppServerOptions);
+    get pid(): number | undefined;
+    get alive(): boolean;
+    private finish;
+    private failAll;
+    private onStdout;
+    private onLine;
+    private writeLine;
+    request<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    notify(method: string, params?: Record<string, unknown>): void;
+    respond(id: number | string, result: Record<string, unknown>): void;
+    respondError(id: number | string, code: number, message: string): void;
+    /**
+     * Graceful stop: closing stdin is a clean shutdown path (exit 0 within a few
+     * seconds, verified live), with SIGTERM as the follow-up and SIGKILL as the
+     * backstop. The child does NOT die just because we go away.
+     */
+    kill(): void;
+}
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function str(value: unknown): string | undefined;
+export declare function num(value: unknown): number | undefined;
+//# sourceMappingURL=codex-protocol.d.ts.map

package/dist/adapters/codex-protocol.js

@@ -0,0 +1,204 @@
+import { spawn } from 'node:child_process';
+import { log } from '../log.js';
+export class RpcError extends Error {
+    code;
+    method;
+    constructor(code, message, method) {
+        super(message);
+        this.code = code;
+        this.method = method;
+        this.name = 'RpcError';
+    }
+}
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+/** A line longer than this means the far end is misbehaving — drop the buffer. */
+const MAX_LINE_BYTES = 8 * 1024 * 1024;
+export class AppServerClient {
+    opts;
+    child;
+    pending = new Map();
+    nextId = 1;
+    stdoutBuffer = '';
+    exited = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.child = spawn(opts.command, opts.args, {
+            ...(opts.cwd ? { cwd: opts.cwd } : {}),
+            env: opts.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child.stdout.setEncoding('utf8');
+        this.child.stdout.on('data', (chunk) => this.onStdout(chunk));
+        this.child.stderr.setEncoding('utf8');
+        this.child.stderr.on('data', (chunk) => opts.onStderr?.(chunk));
+        this.child.on('error', (error) => {
+            // Spawn failure (binary missing) surfaces here, not as a JSON-RPC error.
+            this.failAll(error);
+            this.finish({ code: null, signal: null });
+        });
+        this.child.on('exit', (code, signal) => {
+            this.failAll(new Error(`codex app-server exited (code ${code ?? 'null'})`));
+            this.finish({ code, signal });
+        });
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    get alive() {
+        return !this.exited;
+    }
+    finish(info) {
+        if (this.exited)
+            return;
+        this.exited = true;
+        this.opts.onExit(info);
+    }
+    failAll(error) {
+        for (const [id, entry] of [...this.pending]) {
+            this.pending.delete(id);
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+    }
+    onStdout(chunk) {
+        this.stdoutBuffer += chunk;
+        if (this.stdoutBuffer.length > MAX_LINE_BYTES) {
+            log.warn('codex: stdout line over cap, dropping buffer');
+            this.stdoutBuffer = '';
+            return;
+        }
+        let newline = this.stdoutBuffer.indexOf('\n');
+        while (newline !== -1) {
+            const line = this.stdoutBuffer.slice(0, newline).trim();
+            this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+            if (line)
+                this.onLine(line);
+            newline = this.stdoutBuffer.indexOf('\n');
+        }
+    }
+    onLine(line) {
+        let message;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return;
+            message = parsed;
+        }
+        catch {
+            // Non-JSON chatter on stdout (banners, warnings) is not fatal.
+            return;
+        }
+        const hasId = message['id'] !== undefined && message['id'] !== null;
+        const method = typeof message['method'] === 'string' ? message['method'] : null;
+        const params = asRecord(message['params']);
+        if (method && hasId) {
+            this.opts.onServerRequest({
+                id: message['id'],
+                method,
+                params,
+            });
+            return;
+        }
+        if (method) {
+            this.opts.onNotification(method, params);
+            return;
+        }
+        if (!hasId)
+            return;
+        const entry = this.pending.get(message['id']);
+        if (!entry)
+            return; // late reply to a timed-out request
+        this.pending.delete(message['id']);
+        clearTimeout(entry.timer);
+        const error = asRecord(message['error']);
+        if (message['error'] !== undefined && message['error'] !== null) {
+            entry.reject(new RpcError(typeof error['code'] === 'number' ? error['code'] : -1, typeof error['message'] === 'string' ? error['message'] : 'unknown error', entry.method));
+            return;
+        }
+        entry.resolve(message['result']);
+    }
+    writeLine(payload) {
+        if (this.exited)
+            return;
+        try {
+            this.child.stdin.write(JSON.stringify(payload) + '\n');
+        }
+        catch (error) {
+            log.warn('codex: write failed', { error: String(error) });
+        }
+    }
+    request(method, params, timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS) {
+        if (this.exited)
+            return Promise.reject(new Error('codex app-server is gone'));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new RpcError(-32000, `${method} timed out after ${timeoutMs}ms`, method));
+            }, timeoutMs);
+            timer.unref();
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                method,
+                timer,
+            });
+            // `jsonrpc` is sent for correctness on our side even though the server
+            // does not echo it back.
+            this.writeLine({ jsonrpc: '2.0', id, method, ...(params ? { params } : {}) });
+        });
+    }
+    notify(method, params) {
+        this.writeLine({ jsonrpc: '2.0', method, ...(params ? { params } : {}) });
+    }
+    respond(id, result) {
+        this.writeLine({ jsonrpc: '2.0', id, result });
+    }
+    respondError(id, code, message) {
+        this.writeLine({ jsonrpc: '2.0', id, error: { code, message } });
+    }
+    /**
+     * Graceful stop: closing stdin is a clean shutdown path (exit 0 within a few
+     * seconds, verified live), with SIGTERM as the follow-up and SIGKILL as the
+     * backstop. The child does NOT die just because we go away.
+     */
+    kill() {
+        if (this.exited)
+            return;
+        try {
+            this.child.stdin.end();
+        }
+        catch {
+            // already closed
+        }
+        try {
+            this.child.kill('SIGTERM');
+        }
+        catch {
+            // already gone
+        }
+        const hard = setTimeout(() => {
+            if (!this.exited) {
+                try {
+                    this.child.kill('SIGKILL');
+                }
+                catch {
+                    // already gone
+                }
+            }
+        }, 5_000);
+        hard.unref();
+    }
+}
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function str(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+export function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=codex-protocol.js.map

package/dist/adapters/codex.d.ts

@@ -0,0 +1,61 @@
+import { type CodexHome } from './codex-home.js';
+import { AppServerClient, type ServerRequest } from './codex-protocol.js';
+import { type AgentAdapter, type AgentSession, type EffortOption, type SessionSpec } from './types.js';
+export interface CodexAdapterDeps {
+    /** Injected in tests to drive a scripted app-server. */
+    spawnClient?: (options: {
+        env: Record<string, string>;
+        onNotification: (method: string, params: Record<string, unknown>) => void;
+        onServerRequest: (request: ServerRequest) => void;
+        onExit: (info: {
+            code: number | null;
+            signal: string | null;
+        }) => void;
+        onStderr: (text: string) => void;
+    }) => AppServerClient;
+    /**
+     * Injected in tests. Production leaves it unset on purpose: the home has to
+     * be re-evaluated on EVERY session, not frozen at daemon boot. A boot-time
+     * snapshot is how a credential that vanished mid-day kept being reported as
+     * "linked" while every session failed with "login expired".
+     */
+    codexHome?: CodexHome;
+    /**
+     * Re-assert the credential. Defaults to the real filesystem repair; tests
+     * that inject `codexHome` get no repair at all, so the injected value stays
+     * authoritative and nothing touches the host's ~/.codex.
+     */
+    repairHome?: () => CodexHome;
+    /**
+     * How this runner's CODEX_HOME is authenticated (`[codex] auth` in
+     * config.toml). Carried here because every repair has to honour it — a
+     * repair that defaults to `link` would undo an owner's decision to keep the
+     * runner's credential separate.
+     */
+    authMode?: 'link' | 'own';
+}
+/**
+ * Codex's own wording for "the sign-in did not work".
+ *
+ * A bare `401`/`unauthorized` is deliberately NOT here: those appear in MCP
+ * server errors and proxy failures too, and matching them turned unrelated
+ * problems into "your Codex login expired". A 401 only counts when the same
+ * message also talks about tokens or signing in — and never when it names MCP.
+ */
+export declare function isAuthError(message: string): boolean;
+/** The dashboard shows "label — description"; the wire wants the label. */
+export declare function stripOptionHint(text: string): string;
+/**
+ * `supportedReasoningEfforts` from `model/list`: a list of
+ * `{reasoningEffort, description}`. Codex 0.145 ships six levels on the Sol
+ * line (low…ultra) and four on the older models, so the labels are derived,
+ * never enumerated on our side.
+ */
+export declare function readEfforts(value: unknown): EffortOption[];
+export declare class CodexAdapter implements AgentAdapter {
+    private readonly deps;
+    readonly id: "codex";
+    constructor(deps?: CodexAdapterDeps);
+    startSession(spec: SessionSpec): AgentSession;
+}
+//# sourceMappingURL=codex.d.ts.map