@bridge4dev/runner 0.11.0

package/dist/adapters/types.d.ts

@@ -0,0 +1,183 @@
+import type { TrustMode } from '../policy.js';
+export interface McpConfig {
+    url: string;
+    token: string;
+}
+/**
+ * Agent-agnostic interaction mode (session-5 plan §2).
+ *  ask  — ask before acting               (Claude `default`,  Codex `on-request`)
+ *  plan — plan first, act after approval  (Claude `plan`,     Codex on-request + plan)
+ *  auto — apply edits silently            (Claude `acceptEdits`, Codex `on-failure`)
+ *  full — never ask                       (Claude `bypassPermissions`, Codex `never`)
+ */
+export type AgentMode = 'ask' | 'plan' | 'auto' | 'full';
+export declare const AGENT_MODES: readonly AgentMode[];
+export declare function isAgentMode(value: unknown): value is AgentMode;
+/**
+ * A reasoning-effort level a model supports. Codex advertises these per model
+ * (`supportedReasoningEfforts`) and the set differs between models — the new
+ * Sol/Terra/Luna line adds `max`/`ultra` on top of low/medium/high/xhigh — so
+ * the list is never hard-coded, it always comes from the agent.
+ */
+export interface EffortOption {
+    /** Identifier passed back to setEffort/startSession (e.g. `high`). */
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface ModelOption {
+    /** Identifier passed back to setModel/startSession. */
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    /** Empty/absent when the model has no reasoning-effort dial. */
+    efforts?: EffortOption[];
+    /** The level the agent uses when none is chosen. */
+    defaultEffort?: string;
+}
+export interface CommandOption {
+    /** Without the leading slash. */
+    name: string;
+    description?: string;
+    argumentHint?: string;
+}
+export interface AgentAccountInfo {
+    email?: string;
+    organization?: string;
+    plan?: string;
+}
+export interface McpServerStatusInfo {
+    name: string;
+    status: string;
+}
+/** Everything the dashboard needs to render agent controls, live from the agent. */
+export interface AgentCapabilities {
+    models: ModelOption[];
+    modes: AgentMode[];
+    commands: CommandOption[];
+    currentModel?: string;
+    /** Reasoning effort in force, when the agent has that dial. */
+    currentEffort?: string;
+    currentMode: AgentMode;
+    account?: AgentAccountInfo;
+    mcpServers?: McpServerStatusInfo[];
+    /** Interrupting a running turn is supported. */
+    interrupt: boolean;
+}
+export interface SessionSpec {
+    sessionId: string;
+    /** Working directory for the agent — the session worktree. */
+    cwd: string;
+    /**
+     * Fully composed initial prompt (ticket context included by the supervisor).
+     * Empty/undefined for free CHAT sessions: the agent boots and waits for the
+     * first message instead of starting a turn.
+     */
+    prompt?: string;
+    trustMode: TrustMode;
+    mode?: AgentMode;
+    model?: string;
+    effort?: string;
+    resumeProviderSessionId?: string;
+    mcp?: McpConfig;
+    maxBudgetUsd?: number;
+}
+export type AgentEvent = {
+    type: 'message';
+    role: 'assistant' | 'user';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+}
+/** The agent needs a decision from the user before it can continue. */
+ | {
+    type: 'question';
+    text: string;
+    options?: string[];
+} | {
+    type: 'tool';
+    phase: 'use' | 'result';
+    name: string;
+    toolUseId?: string;
+    detail?: Record<string, unknown>;
+    text?: string;
+} | {
+    type: 'permission';
+    requestId: string;
+    toolName: string;
+    title: string;
+    description?: string;
+    input: Record<string, unknown>;
+    /** Plan approval (Claude ExitPlanMode / Codex plan item) — rendered as a plan card. */
+    plan?: string;
+} | {
+    type: 'permission_resolved';
+    requestId: string;
+    allow: boolean;
+    source: 'user' | 'policy' | 'abort';
+    reason?: string;
+} | {
+    type: 'provider_session';
+    providerSessionId: string;
+    model?: string;
+} | {
+    type: 'capabilities';
+    capabilities: AgentCapabilities;
+} | {
+    type: 'settings';
+    model?: string;
+    mode?: AgentMode;
+    effort?: string | null;
+} | {
+    type: 'context_usage';
+    usedTokens: number;
+    maxTokens: number;
+} | {
+    type: 'notice';
+    level: 'info' | 'warn';
+    text: string;
+} | {
+    type: 'cost';
+    costUsd: number;
+    numTurns?: number;
+    durationMs?: number;
+} | {
+    type: 'turn_end';
+    ok: boolean;
+    errorMessage?: string;
+} | {
+    type: 'error';
+    message: string;
+    /**
+     * `auth_missing` — no login on this server at all.
+     * `auth_expired` — a login exists but the provider rejected it.
+     * Kept apart because the remedies differ, and calling a server that was
+     * never signed in "expired" sent people looking for a problem that did
+     * not exist.
+     */
+    code?: 'resume_failed' | 'auth_expired' | 'auth_missing';
+};
+export interface AgentSession {
+    /** Ends when the underlying agent process is gone. */
+    events: AsyncIterable<AgentEvent>;
+    answerPermission(requestId: string, allow: boolean, note?: string): void;
+    /** Follow-up user input into the live session. */
+    send(text: string): void;
+    /** Switch model mid-session (VS-Code-extension parity). */
+    setModel(model: string): Promise<void>;
+    /** Switch reasoning effort mid-session; null = the model's own default. */
+    setEffort(effort: string | null): Promise<void>;
+    /** Switch interaction mode mid-session. */
+    setMode(mode: AgentMode): Promise<void>;
+    /** Interrupt the current turn (session stays resumable). */
+    interrupt(): Promise<void>;
+    /** Tear the session down (kills the agent process). */
+    stop(): void;
+}
+export interface AgentAdapter {
+    readonly id: 'claude' | 'codex';
+    startSession(spec: SessionSpec): AgentSession;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.js

@@ -0,0 +1,5 @@
+export const AGENT_MODES = ['ask', 'plan', 'auto', 'full'];
+export function isAgentMode(value) {
+    return typeof value === 'string' && AGENT_MODES.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/async-queue.d.ts

@@ -0,0 +1,11 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private readonly values;
+    private readonly waiters;
+    private ended;
+    /** Returns false when the queue has ended and the value was dropped. */
+    push(value: T): boolean;
+    end(): void;
+    get isEnded(): boolean;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=async-queue.d.ts.map

package/dist/async-queue.js

@@ -0,0 +1,50 @@
+// Minimal push-based async queue — bridges callback-style producers (WS
+// frames, SDK messages) into AsyncIterable consumers.
+export class AsyncQueue {
+    values = [];
+    waiters = [];
+    ended = false;
+    /** Returns false when the queue has ended and the value was dropped. */
+    push(value) {
+        if (this.ended)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value, done: false });
+        }
+        else {
+            this.values.push(value);
+        }
+        return true;
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    get isEnded() {
+        return this.ended;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const value = this.values.shift();
+                if (value !== undefined) {
+                    return Promise.resolve({ value, done: false });
+                }
+                if (this.ended) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+            return: () => {
+                this.end();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}
+//# sourceMappingURL=async-queue.js.map

package/dist/attachments.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Files the user attached to a message, brought onto their own machine
+ * (session 10).
+ *
+ * Why they land INSIDE the session worktree: layer-1 policy lets the agent read
+ * only within its worktree (policy.ts `isInsideWorktree`), and Claude Code and
+ * Codex both sandbox to their working directory. A file in `<state>/…` would
+ * cost a permission card on every single read — or be refused outright.
+ *
+ * Why that does not pollute the git panel: `.devbridge/` is added once to the
+ * repository's `info/exclude`, so `git status` and the diff never see it.
+ */
+/** Directory inside the worktree; also the line written to info/exclude. */
+export declare const ATTACHMENT_DIR = ".devbridge/attachments";
+export interface RemoteAttachment {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+}
+export interface SavedAttachment {
+    /** Path relative to the worktree — what the agent is told to open. */
+    relativePath: string;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+}
+/**
+ * A file name that is safe to write and unambiguous to read.
+ *
+ * The name comes from the user's own machine and travels through our API, so it
+ * is treated as hostile: no directory separators, no leading dots, no control
+ * characters, bounded length. The attachment id prefix keeps two files called
+ * `screenshot.png` apart without inventing a counter.
+ */
+export declare function safeAttachmentName(id: string, fileName: string): string;
+/**
+ * Keep `.devbridge/` out of git for this repository.
+ *
+ * Uses `info/exclude` rather than `.gitignore`: it is local-only, so we never
+ * add a line to a file the user commits. `--git-common-dir` matters because a
+ * linked worktree's `.git` is a file, and the shared exclude list is what both
+ * the worktree and the main checkout consult.
+ */
+export declare function ensureGitExclude(worktreePath: string): Promise<void>;
+/**
+ * Download one message's attachments into the session worktree.
+ *
+ * Returns what actually landed — a file that could not be fetched is reported
+ * and skipped rather than failing the whole message, because the text the user
+ * typed is usually still worth delivering.
+ */
+export declare function saveAttachments(input: {
+    worktreePath: string;
+    apiUrl: string;
+    token: string;
+    attachments: RemoteAttachment[];
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    saved: SavedAttachment[];
+    failed: string[];
+}>;
+/**
+ * Turn the user's message plus the files into one prompt.
+ *
+ * Plain paths and an explicit instruction, deliberately: both agents read local
+ * files with their own tools, and an agent-specific encoding (image blocks for
+ * Claude, `localImage` items for Codex) would be two code paths that drift.
+ * The user's own words stay first — the files are context, not the request.
+ */
+export declare function composeMessageWithAttachments(text: string, saved: SavedAttachment[]): string;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.js

@@ -0,0 +1,149 @@
+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';
+const execFileAsync = promisify(execFile);
+/**
+ * Files the user attached to a message, brought onto their own machine
+ * (session 10).
+ *
+ * Why they land INSIDE the session worktree: layer-1 policy lets the agent read
+ * only within its worktree (policy.ts `isInsideWorktree`), and Claude Code and
+ * Codex both sandbox to their working directory. A file in `<state>/…` would
+ * cost a permission card on every single read — or be refused outright.
+ *
+ * Why that does not pollute the git panel: `.devbridge/` is added once to the
+ * repository's `info/exclude`, so `git status` and the diff never see it.
+ */
+/** Directory inside the worktree; also the line written to info/exclude. */
+export const ATTACHMENT_DIR = '.devbridge/attachments';
+/** Hard ceiling per file; the API allows 5 MB for images and 25 MB for documents. */
+const MAX_ATTACHMENT_BYTES = 26 * 1024 * 1024;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * A file name that is safe to write and unambiguous to read.
+ *
+ * The name comes from the user's own machine and travels through our API, so it
+ * is treated as hostile: no directory separators, no leading dots, no control
+ * characters, bounded length. The attachment id prefix keeps two files called
+ * `screenshot.png` apart without inventing a counter.
+ */
+export function safeAttachmentName(id, fileName) {
+    const base = path
+        .basename(fileName)
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^\.+/, '');
+    const trimmed = base.slice(-80) || 'file';
+    return `${id.slice(0, 8)}-${trimmed}`;
+}
+/**
+ * Keep `.devbridge/` out of git for this repository.
+ *
+ * Uses `info/exclude` rather than `.gitignore`: it is local-only, so we never
+ * add a line to a file the user commits. `--git-common-dir` matters because a
+ * linked worktree's `.git` is a file, and the shared exclude list is what both
+ * the worktree and the main checkout consult.
+ */
+export async function ensureGitExclude(worktreePath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--git-common-dir'], {
+            cwd: worktreePath,
+            timeout: 10_000,
+        });
+        const commonDir = path.resolve(worktreePath, stdout.trim());
+        const infoDir = path.join(commonDir, 'info');
+        const excludeFile = path.join(infoDir, 'exclude');
+        const line = '/.devbridge/';
+        let current = '';
+        try {
+            current = fs.readFileSync(excludeFile, 'utf8');
+        }
+        catch {
+            /* no exclude file yet */
+        }
+        if (current.split('\n').some((entry) => entry.trim() === line))
+            return;
+        fs.mkdirSync(infoDir, { recursive: true });
+        const prefix = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+        fs.appendFileSync(excludeFile, `${prefix}# DevBridge: files you attach to a session live here\n${line}\n`);
+    }
+    catch (error) {
+        // Not fatal: the worst case is that attachments show up as untracked files.
+        log.warn('attachments: could not update info/exclude', { error: String(error) });
+    }
+}
+/**
+ * Download one message's attachments into the session worktree.
+ *
+ * Returns what actually landed — a file that could not be fetched is reported
+ * and skipped rather than failing the whole message, because the text the user
+ * typed is usually still worth delivering.
+ */
+export async function saveAttachments(input) {
+    const doFetch = input.fetchImpl ?? fetch;
+    const dir = path.join(input.worktreePath, ATTACHMENT_DIR);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    await ensureGitExclude(input.worktreePath);
+    const saved = [];
+    const failed = [];
+    const base = input.apiUrl.replace(/\/$/, '');
+    for (const attachment of input.attachments) {
+        try {
+            const response = await doFetch(`${base}/api/v1/dev/runner/attachments/${encodeURIComponent(attachment.id)}`, {
+                headers: { Authorization: `Bearer ${input.token}` },
+                signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const buffer = Buffer.from(await response.arrayBuffer());
+            if (buffer.length > MAX_ATTACHMENT_BYTES) {
+                throw new Error(`file is larger than ${Math.round(MAX_ATTACHMENT_BYTES / 1024 / 1024)}MB`);
+            }
+            const name = safeAttachmentName(attachment.id, attachment.fileName);
+            fs.writeFileSync(path.join(dir, name), buffer, { mode: 0o600 });
+            saved.push({
+                relativePath: `${ATTACHMENT_DIR}/${name}`,
+                fileName: attachment.fileName,
+                mimeType: attachment.mimeType,
+                fileSize: buffer.length,
+            });
+        }
+        catch (error) {
+            log.warn('attachments: download failed', {
+                attachmentId: attachment.id,
+                error: String(error),
+            });
+            failed.push(attachment.fileName);
+        }
+    }
+    return { saved, failed };
+}
+/**
+ * Turn the user's message plus the files into one prompt.
+ *
+ * Plain paths and an explicit instruction, deliberately: both agents read local
+ * files with their own tools, and an agent-specific encoding (image blocks for
+ * Claude, `localImage` items for Codex) would be two code paths that drift.
+ * The user's own words stay first — the files are context, not the request.
+ */
+export function composeMessageWithAttachments(text, saved) {
+    if (saved.length === 0)
+        return text;
+    const lines = saved.map((file) => `- ${file.relativePath} — ${file.fileName} (${file.mimeType}, ${sizeLabel(file.fileSize)})`);
+    const header = saved.length === 1
+        ? 'The user attached a file. It is already saved in this workspace:'
+        : 'The user attached files. They are already saved in this workspace:';
+    return [text.trim(), '', header, ...lines, '', 'Open them before answering — images included.']
+        .join('\n')
+        .trim();
+}
+function sizeLabel(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+//# sourceMappingURL=attachments.js.map

package/dist/auth-relay.d.ts

@@ -0,0 +1,57 @@
+export type RelayAgent = 'claude' | 'codex';
+export interface LoginStartResult {
+    url: string;
+    /** Device-auth style user code to enter on the provider page (Codex). */
+    code?: string;
+    /** true → the flow finishes by pasting a confirmation code back (Claude). */
+    expectsCode: boolean;
+}
+export interface LoginCodeResult {
+    ok: boolean;
+    detail?: string;
+}
+export interface AgentAuthStatus {
+    /**
+     * `missing` — never signed in here (or the CLI is not installed).
+     * `expired` — we hold a credential and it is past its expiry.
+     * `unknown` — the probe itself failed; say so instead of guessing.
+     *
+     * `expired` used to be the catch-all, which is how a server that had simply
+     * never signed in — and one whose probe merely timed out — both ended up
+     * telling the user their login had expired.
+     */
+    status: 'ok' | 'expired' | 'missing' | 'unknown';
+    expiresAt?: string;
+    detail?: string;
+}
+/** Strip ANSI/OSC control sequences so text matching sees plain output. */
+export declare function stripControl(raw: string): string;
+export declare function extractLoginUrl(agent: RelayAgent, raw: string): string | null;
+export declare function extractDeviceCode(raw: string): string | null;
+export declare class AuthRelay {
+    private readonly commands;
+    private active;
+    constructor(commands?: Record<RelayAgent, string>);
+    /** Start (or restart) a login flow and wait until the sign-in URL appears. */
+    start(agent: RelayAgent): Promise<LoginStartResult>;
+    /** Paste the confirmation code back into the waiting CLI (Claude flow). */
+    submitCode(agent: RelayAgent, code: string): Promise<LoginCodeResult>;
+    cancel(): void;
+}
+/**
+ * Claude: the subscription token's expiry is recorded in the CLI's own
+ * credentials file. The RUNNER reads it (its own host user's file) — the
+ * agent itself is still denied this path by layer-1 policy.
+ */
+export declare function claudeAuthStatus(homedir?: string): Promise<AgentAuthStatus>;
+/**
+ * Codex reports its own login state via an exit code (0 signed in / 1 not).
+ * Probed against the RUNNER's home: the host user can be signed in while our
+ * isolated home is not, and it is ours that sessions use.
+ */
+export declare function codexAuthStatus(): Promise<AgentAuthStatus>;
+export declare function agentAuthStatuses(): Promise<{
+    claude: AgentAuthStatus;
+    codex: AgentAuthStatus;
+}>;
+//# sourceMappingURL=auth-relay.d.ts.map