@firefunc-agent/runner 0.5.0

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+export type RunnerConfig = {
+    apiUrl: string;
+    token: string;
+    name?: string;
+    repos?: Record<string, string>;
+    reposDir?: string;
+    claudeBin?: string;
+    engine?: string;
+    codexBin?: string;
+    codexUseApiKey?: boolean;
+    codexArgs?: string[];
+    geminiBin?: string;
+    geminiApiKey?: string;
+    geminiArgs?: string[];
+    cursorAgentBin?: string;
+    cursorApiKey?: string;
+    cursorArgs?: string[];
+    quiet?: boolean;
+    viewerPort?: number;
+    viewerEnabled?: boolean;
+    maxParallel?: number;
+    devServerBasePort?: number;
+    model?: string;
+    effort?: string;
+    permissionMode?: string;
+    allowedTools?: string;
+    maxBudgetUsd?: number;
+    claudeCodeOAuthToken?: string;
+    claudeUseApiKey?: boolean;
+    claudeArgs?: string[];
+    jobTimeoutMinutes?: number;
+    baseBranch?: string;
+    claudeEnv?: Record<string, string>;
+    setupCommands?: string[];
+    autoInstall?: boolean;
+    setupTimeoutMinutes?: number;
+    envFile?: string;
+    backgroundCommands?: string[];
+};
+export declare function configPath(): string;
+export declare function loadConfig(): RunnerConfig | null;
+export declare function saveConfig(cfg: RunnerConfig): void;

package/dist/config.js

@@ -0,0 +1,23 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+export function configPath() {
+    return process.env.FIREFUNC_RUNNER_CONFIG ?? join(homedir(), '.firefunc-runner', 'config.json');
+}
+export function loadConfig() {
+    const p = configPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(cfg) {
+    const p = configPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+//# sourceMappingURL=config.js.map

package/dist/daemon.d.ts

@@ -0,0 +1,2 @@
+import type { RunnerConfig } from './config.js';
+export declare function startDaemon(cfg: RunnerConfig): Promise<void>;

package/dist/daemon.js

@@ -0,0 +1,152 @@
+import { hostname, platform } from 'node:os';
+import { RunnerApi } from './api.js';
+import { availableEngines, getAdapter, supportedEngines } from './engines/index.js';
+import { runJob, resolveRepoPath } from './job.js';
+import { createSessionViewer } from './viewer.js';
+import { runJobPool } from './pool.js';
+const VERSION = '0.6.0';
+function log(msg) {
+    console.log(`[firefunc-runner] ${new Date().toISOString()} ${msg}`);
+}
+export async function startDaemon(cfg) {
+    const api = new RunnerApi(cfg.apiUrl, cfg.token);
+    const viewerPort = cfg.viewerEnabled === false ? null : (cfg.viewerPort ?? 8787);
+    const declaredEngines = availableEngines(cfg);
+    const skipped = supportedEngines().filter((e) => !declaredEngines.includes(e));
+    if (declaredEngines.length > 0) {
+        log(`engines available on this machine: ${declaredEngines.join(', ')}`);
+    }
+    else {
+        log('WARNING: no engine CLI found on PATH — this runner cannot run jobs. Install "claude" (or set --claude-bin).');
+    }
+    if (skipped.length > 0) {
+        log(`engines not installed (skipped): ${skipped.join(', ')} — install the CLI to enable them`);
+    }
+    const meta = {
+        version: VERSION,
+        hostname: hostname(),
+        platform: platform(),
+        viewerPort,
+        engines: declaredEngines,
+    };
+    let stopping = false;
+    const viewer = cfg.viewerEnabled === false
+        ? undefined
+        : createSessionViewer({
+            port: cfg.viewerPort,
+            onListen: (u) => log(`live session viewer → ${u} (local only — watch Claude work in a browser)`),
+            onError: (m) => log(`${m} — set "viewerPort" or pass --no-viewer`),
+        });
+    const stop = (sig) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log(`${sig} received — finishing in-flight job(s) then exiting…`);
+    };
+    process.on('SIGINT', () => stop('SIGINT'));
+    process.on('SIGTERM', () => stop('SIGTERM'));
+    let serverMax = 1;
+    const refreshConfig = async () => {
+        const c = await api.config();
+        if (c)
+            serverMax = Math.max(1, Math.floor(c.maxParallel));
+    };
+    await refreshConfig().catch(() => { });
+    const cfgTimer = setInterval(() => void refreshConfig().catch(() => { }), 60_000);
+    let budgets = [];
+    const refreshBudgets = async () => {
+        const reports = [];
+        for (const id of supportedEngines()) {
+            const read = getAdapter(id).readBudget;
+            if (!read)
+                continue;
+            try {
+                const r = await read(cfg);
+                if (r)
+                    reports.push(r);
+            }
+            catch {
+            }
+        }
+        budgets = reports;
+    };
+    await refreshBudgets().catch(() => { });
+    const budgetTimer = setInterval(() => void refreshBudgets().catch(() => { }), 5 * 60_000);
+    const effectiveMax = () => Math.max(1, Math.floor(cfg.maxParallel ?? serverMax));
+    log(`connected to ${cfg.apiUrl} as "${cfg.name ?? meta.hostname}" — watching for work` +
+        (effectiveMax() > 1 ? ` (up to ${effectiveMax()} parallel sessions).` : '.'));
+    try {
+        const routed = await api.repos();
+        const unmapped = routed.filter((r) => !resolveRepoPath(r, cfg));
+        if (unmapped.length) {
+            log(`${unmapped.length} routed repo(s) need a local checkout — run one of:`);
+            for (const r of unmapped) {
+                log(`  firefunc-runner repo ${r} <path-to-your-${r.split('/').pop()}-checkout>`);
+            }
+        }
+        else if (routed.length) {
+            log(`all ${routed.length} routed repo(s) are mapped to a local checkout. ✓`);
+        }
+    }
+    catch {
+    }
+    const portBase = cfg.devServerBasePort ?? 3100;
+    const usedPorts = new Set();
+    const takePort = () => {
+        if (effectiveMax() <= 1)
+            return undefined;
+        for (let p = portBase; p < portBase + 500; p++) {
+            if (!usedPorts.has(p)) {
+                usedPorts.add(p);
+                return p;
+            }
+        }
+        return undefined;
+    };
+    let backoffMs = 2_000;
+    await runJobPool({
+        maxParallel: effectiveMax,
+        stopping: () => stopping,
+        claim: async () => {
+            const job = await api.claim({ ...meta, budget: budgets });
+            backoffMs = 2_000;
+            return job;
+        },
+        onClaimError: async (err) => {
+            const msg = err.message;
+            if (/token rejected/.test(msg)) {
+                log(`FATAL: ${msg}. Re-run "firefunc-runner connect <token>".`);
+                process.exitCode = 1;
+                return 'fatal';
+            }
+            log(`poll error: ${msg} — retrying in ${Math.round(backoffMs / 1000)}s`);
+            await new Promise((r) => setTimeout(r, backoffMs));
+            backoffMs = Math.min(backoffMs * 2, 60_000);
+            return 'retry';
+        },
+        onStart: (job, inFlight) => {
+            log(`[${inFlight}/${effectiveMax()}] claimed ${job.runId} — ${job.title ?? job.externalId ?? 'a bug'} (${job.repo ?? '?'})`);
+            if (viewer?.url)
+                log(`  watch live → ${viewer.url}/s/${job.runId}`);
+        },
+        run: async (job) => {
+            const devServerPort = takePort();
+            try {
+                await runJob(job, cfg, api, viewer, { devServerPort });
+            }
+            catch (e) {
+                log(`job ${job.runId} errored: ${e.message}`);
+            }
+            finally {
+                if (devServerPort != null)
+                    usedPorts.delete(devServerPort);
+                log(`done ${job.runId}`);
+            }
+        },
+    });
+    clearInterval(cfgTimer);
+    clearInterval(budgetTimer);
+    viewer?.close();
+    log('stopped.');
+}
+//# sourceMappingURL=daemon.js.map

package/dist/engines/claude-budget.d.ts

@@ -0,0 +1,4 @@
+import type { RunnerConfig } from '../config.js';
+import type { EngineBudgetReport, EngineBudgetWindow } from './types.js';
+export declare function parseClaudeUsage(json: unknown): EngineBudgetWindow[];
+export declare function readClaudeBudget(cfg: RunnerConfig): Promise<EngineBudgetReport | null>;

package/dist/engines/claude-budget.js

@@ -0,0 +1,122 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+const USAGE_BETA = 'oauth-2025-04-20';
+const FETCH_TIMEOUT_MS = 5_000;
+function toPct(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return null;
+    const p = v <= 1 ? v * 100 : v;
+    return Math.max(0, Math.min(100, Math.round(p)));
+}
+export function parseClaudeUsage(json) {
+    if (!json || typeof json !== 'object')
+        return [];
+    const o = json;
+    if (Array.isArray(o.limits)) {
+        const out = [];
+        for (const lim of o.limits) {
+            const pct = toPct(lim?.percent ?? lim?.utilization ?? lim?.used_pct);
+            if (pct === null)
+                continue;
+            const resetsAt = typeof lim?.resets_at === 'string' ? lim.resets_at : null;
+            const kind = String(lim?.kind ?? '');
+            if (kind === 'session' || kind === 'five_hour') {
+                out.push({ window: 'rolling_5h', label: '5-hour limit', pctUsed: pct, resetsAt });
+            }
+            else if (kind === 'weekly_all' || kind === 'seven_day' || kind === 'weekly') {
+                out.push({ window: 'weekly', label: 'Weekly · all models', pctUsed: pct, resetsAt });
+            }
+            else if (kind === 'weekly_scoped') {
+                const scope = lim?.scope;
+                const name = typeof scope?.model?.display_name === 'string' ? scope.model.display_name : 'scoped';
+                out.push({ window: 'weekly_scoped', label: `Weekly · ${name}`, pctUsed: pct, resetsAt });
+            }
+        }
+        if (out.length > 0)
+            return out;
+    }
+    const out = [];
+    const push = (window, label, node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const pct = toPct(n.utilization ?? n.percent ?? n.used_pct);
+        if (pct === null)
+            return;
+        const resetsAt = typeof n.resets_at === 'string' ? n.resets_at : null;
+        out.push({ window, label, pctUsed: pct, resetsAt });
+    };
+    push('rolling_5h', '5-hour limit', o.five_hour);
+    push('weekly', 'Weekly · all models', o.seven_day ?? o.weekly);
+    return out;
+}
+function accessTokenFromBlob(raw) {
+    try {
+        const j = JSON.parse(raw);
+        const tok = j?.claudeAiOauth?.accessToken;
+        return typeof tok === 'string' && tok.length > 0 ? tok : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readMacKeychainToken() {
+    if (process.platform !== 'darwin')
+        return null;
+    try {
+        const { stdout } = await execFileAsync('security', ['find-generic-password', '-s', 'Claude Code-credentials', '-w'], { timeout: 5_000 });
+        return accessTokenFromBlob(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveOAuthToken(cfg) {
+    if (cfg.claudeCodeOAuthToken)
+        return cfg.claudeCodeOAuthToken;
+    try {
+        const raw = await readFile(join(homedir(), '.claude', '.credentials.json'), 'utf8');
+        const tok = accessTokenFromBlob(raw);
+        if (tok)
+            return tok;
+    }
+    catch {
+    }
+    return readMacKeychainToken();
+}
+export async function readClaudeBudget(cfg) {
+    if (cfg.claudeUseApiKey)
+        return null;
+    const token = await resolveOAuthToken(cfg);
+    if (!token)
+        return null;
+    try {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), FETCH_TIMEOUT_MS);
+        let res;
+        try {
+            res = await fetch(USAGE_URL, {
+                headers: { authorization: `Bearer ${token}`, 'anthropic-beta': USAGE_BETA },
+                signal: ctl.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return null;
+        const windows = parseClaudeUsage(await res.json());
+        if (windows.length === 0)
+            return null;
+        return { engine: 'claude_code', planLabel: 'Claude subscription', windows };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=claude-budget.js.map

package/dist/engines/claude.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAdapter } from './types.js';
+export declare const claudeAdapter: AgentAdapter;

package/dist/engines/claude.js

@@ -0,0 +1,119 @@
+import { makeStreamJsonParser } from '../session-stream.js';
+import { readClaudeBudget } from './claude-budget.js';
+function claudeSummary(streamJson) {
+    const lines = streamJson.trim().split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const ev = JSON.parse(lines[i]);
+            if (ev.type === 'result' && typeof ev.result === 'string' && ev.result.trim()) {
+                return ev.result.trim();
+            }
+            if (ev.type === 'assistant' && ev.message?.content) {
+                const text = ev.message.content
+                    .filter((c) => c.type === 'text' && c.text)
+                    .map((c) => c.text)
+                    .join('')
+                    .trim();
+                if (text)
+                    return text;
+            }
+        }
+        catch {
+        }
+    }
+    return '';
+}
+export const claudeAdapter = {
+    id: 'claude_code',
+    displayName: 'Claude Code',
+    branchPrefix: 'claude',
+    bin(cfg) {
+        return cfg.claudeBin ?? 'claude';
+    },
+    buildInvocation(ctx) {
+        const { cfg } = ctx;
+        const model = ctx.model ?? 'opus';
+        const effortFlag = ctx.ultracode ? 'xhigh' : ctx.effort;
+        const tools = ctx.allowedTools ??
+            'Read Edit Write Bash Glob Grep WebFetch WebSearch Task TodoWrite NotebookEdit';
+        const args = [
+            '-p',
+            ...(ctx.isWin ? [] : [ctx.prompt]),
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--permission-mode',
+            ctx.permissionMode,
+            '--allowedTools',
+            tools,
+        ];
+        if (model)
+            args.push('--model', model);
+        if (effortFlag)
+            args.push('--effort', effortFlag);
+        if (ctx.attachDir && ctx.attachPaths.length)
+            args.push('--add-dir', ctx.attachDir);
+        if (ctx.maxBudgetUsd)
+            args.push('--max-budget-usd', String(ctx.maxBudgetUsd));
+        args.push(...(cfg.claudeArgs ?? []));
+        const env = cfg.claudeUseApiKey
+            ? ctx.runEnv
+            : { ...ctx.runEnv, ANTHROPIC_API_KEY: undefined };
+        const authLogLine = cfg.claudeUseApiKey
+            ? 'ANTHROPIC_API_KEY (API billing — opted in)'
+            : cfg.claudeCodeOAuthToken
+                ? 'subscription token'
+                : 'your machine Claude login (API key hidden — subscription billing)';
+        return {
+            bin: this.bin(cfg),
+            args,
+            env,
+            stdinInput: ctx.isWin ? ctx.prompt : undefined,
+            shell: ctx.isWin,
+            authLogLine,
+        };
+    },
+    makeStreamPrinter() {
+        const short = (s, n = 160) => {
+            const one = s.replace(/\s+/g, ' ').trim();
+            return one.length > n ? `${one.slice(0, n)}…` : one;
+        };
+        return makeStreamJsonParser((ev) => {
+            if (ev.kind === 'text')
+                process.stdout.write(`  │ ${short(ev.text)}\n`);
+            else if (ev.kind === 'tool')
+                process.stdout.write(`  │ ⚒ ${ev.name}${ev.arg ? ` ${short(ev.arg, 90)}` : ''}\n`);
+            else
+                process.stdout.write(`  └ ${short(ev.text, 240)}\n`);
+        });
+    },
+    summarize(stdout) {
+        return claudeSummary(stdout);
+    },
+    authFailureHint(text) {
+        const t = text.toLowerCase();
+        if (t.includes('credit balance is too low')) {
+            return 'Claude Code billed pay-as-you-go API credits (balance $0), not your subscription. On the runner machine run `claude setup-token` and set it via `--claude-oauth-token` (or clear ANTHROPIC_API_KEY before starting), then retry.';
+        }
+        if (t.includes('invalid x-api-key') ||
+            t.includes('invalid api key') ||
+            t.includes('authentication_error') ||
+            t.includes('oauth token has expired') ||
+            t.includes('oauth token expired') ||
+            t.includes('please run /login')) {
+            return 'Claude Code could not authenticate. Fix the runner’s Claude auth — run `claude setup-token` and pass `--claude-oauth-token`, or clear a stale/invalid ANTHROPIC_API_KEY — then retry.';
+        }
+        return null;
+    },
+    rateLimitHint(text) {
+        const t = text.toLowerCase();
+        if (/rate limit|rate_limit|too many requests|\b429\b|max concurrent|usage limit|usage_limit|overloaded_error/.test(t)) {
+            return 'Claude Code hit a rate / usage limit — likely too many parallel sessions on your subscription. This run was throttled, not failed: retry shortly, or lower "max parallel".';
+        }
+        return null;
+    },
+    readBudget(cfg) {
+        return readClaudeBudget(cfg);
+    },
+};
+//# sourceMappingURL=claude.js.map

package/dist/engines/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAdapter } from './types.js';
+export declare const codexAdapter: AgentAdapter;

package/dist/engines/codex.js

@@ -0,0 +1,117 @@
+function codexSummary(stdout) {
+    const lines = stdout.trim().split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const ev = JSON.parse(lines[i]);
+            if (ev.item && (ev.item.type === 'agent_message' || ev.item.type === 'assistant_message')) {
+                const t = (ev.item.text ?? ev.item.content ?? '').trim();
+                if (t)
+                    return t;
+            }
+            if (ev.type === 'turn.failed' && typeof ev.message === 'string' && ev.message.trim()) {
+                return ev.message.trim();
+            }
+            if (ev.type === 'error' && typeof ev.message === 'string' && ev.message.trim()) {
+                return ev.message.trim();
+            }
+        }
+        catch {
+        }
+    }
+    return '';
+}
+export const codexAdapter = {
+    id: 'codex_cli',
+    displayName: 'OpenAI Codex',
+    branchPrefix: 'codex',
+    bin(cfg) {
+        return cfg.codexBin ?? 'codex';
+    },
+    buildInvocation(ctx) {
+        const { cfg } = ctx;
+        const args = ['exec', ...(ctx.isWin ? ['-'] : [ctx.prompt]), '--json'];
+        args.push('--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true');
+        if (ctx.model)
+            args.push('--model', ctx.model);
+        const rawEffort = ctx.ultracode ? 'xhigh' : ctx.effort;
+        const effort = rawEffort === 'max' || rawEffort === 'ultracode' ? 'xhigh' : rawEffort;
+        if (effort && ['minimal', 'low', 'medium', 'high', 'xhigh'].includes(effort)) {
+            args.push('-c', `model_reasoning_effort="${effort}"`);
+        }
+        args.push(...(cfg.codexArgs ?? []));
+        const env = cfg.codexUseApiKey
+            ? ctx.runEnv
+            : { ...ctx.runEnv, OPENAI_API_KEY: undefined, CODEX_API_KEY: undefined };
+        const authLogLine = cfg.codexUseApiKey
+            ? 'OPENAI_API_KEY / CODEX_API_KEY (API billing — opted in)'
+            : 'your machine `codex login` (API keys hidden — ChatGPT-plan billing)';
+        return {
+            bin: this.bin(cfg),
+            args,
+            env,
+            stdinInput: ctx.isWin ? ctx.prompt : undefined,
+            shell: ctx.isWin,
+            authLogLine,
+        };
+    },
+    makeStreamPrinter() {
+        const short = (s, n = 160) => {
+            const one = s.replace(/\s+/g, ' ').trim();
+            return one.length > n ? `${one.slice(0, n)}…` : one;
+        };
+        let buf = '';
+        return (chunk) => {
+            buf += chunk;
+            const lines = buf.split('\n');
+            buf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const ev = JSON.parse(line);
+                    if (ev.item?.type === 'agent_message' && ev.item.text) {
+                        process.stdout.write(`  │ ${short(ev.item.text)}\n`);
+                    }
+                    else if (ev.item?.type === 'command_execution' && ev.item.command) {
+                        process.stdout.write(`  │ ⚒ bash ${short(ev.item.command, 90)}\n`);
+                    }
+                    else if (ev.type === 'turn.failed' || ev.type === 'error') {
+                        process.stdout.write(`  └ ✗ ${short(ev.message ?? 'turn failed', 240)}\n`);
+                    }
+                    else if (ev.type === 'turn.completed') {
+                        process.stdout.write(`  └ turn completed\n`);
+                    }
+                }
+                catch {
+                }
+            }
+        };
+    },
+    summarize(stdout) {
+        return codexSummary(stdout);
+    },
+    authFailureHint(text) {
+        const t = text.toLowerCase();
+        if (t.includes('not logged in') ||
+            t.includes('login required') ||
+            t.includes('please run codex login') ||
+            t.includes('`codex login`') ||
+            /\bunauthorized\b/.test(t) ||
+            t.includes('invalid api key') ||
+            /\b401\b/.test(t)) {
+            return 'OpenAI Codex could not authenticate. On the runner machine run `codex login` (signs into your ChatGPT plan) — or set an API key and enable `codexUseApiKey` — then retry.';
+        }
+        if (t.includes('insufficient_quota') || t.includes('billing hard limit')) {
+            return 'OpenAI Codex hit a billing/quota wall on this account. Check your ChatGPT plan’s agentic usage (or API billing if opted in), then retry.';
+        }
+        return null;
+    },
+    rateLimitHint(text) {
+        const t = text.toLowerCase();
+        if (/rate limit|rate_limit|too many requests|\b429\b|usage limit|usage_limit/.test(t)) {
+            return 'OpenAI Codex hit a rate / usage limit — ChatGPT-plan agentic usage is a shared 5-hour window. This run was throttled, not failed: retry shortly, or lower "max parallel".';
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=codex.js.map

package/dist/engines/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAdapter } from './types.js';
+export declare const cursorAdapter: AgentAdapter;