@firefunc-agent/runner 0.5.0

package/dist/engines/cursor.js

@@ -0,0 +1,120 @@
+function cursorSummary(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.type === 'result' && typeof ev.result === 'string' && ev.result.trim()) {
+                return ev.result.trim();
+            }
+            if (typeof ev.message === 'string' && ev.message.trim())
+                return ev.message.trim();
+            if (typeof ev.message === 'object' && ev.message?.content) {
+                const t = ev.message.content
+                    .filter((c) => c.type === 'text' && c.text)
+                    .map((c) => c.text)
+                    .join('')
+                    .trim();
+                if (t)
+                    return t;
+            }
+            if (typeof ev.text === 'string' && ev.text.trim())
+                return ev.text.trim();
+        }
+        catch {
+        }
+    }
+    return '';
+}
+export const cursorAdapter = {
+    id: 'cursor_cli',
+    displayName: 'Cursor',
+    branchPrefix: 'cursor',
+    bin(cfg) {
+        return cfg.cursorAgentBin ?? 'cursor-agent';
+    },
+    buildInvocation(ctx) {
+        const { cfg } = ctx;
+        if (ctx.isWin) {
+            throw new Error('The Cursor CLI engine is not supported on native Windows runners (Cursor supports Windows via WSL only). Run the firefunc-runner inside WSL, or pick another engine for this project.');
+        }
+        const args = ['-p', ctx.prompt, '--force', '--output-format', 'stream-json', '--trust'];
+        if (ctx.model)
+            args.push('--model', ctx.model);
+        args.push(...(cfg.cursorArgs ?? []));
+        const env = cfg.cursorApiKey
+            ? { ...ctx.runEnv, CURSOR_API_KEY: cfg.cursorApiKey }
+            : ctx.runEnv;
+        const authLogLine = cfg.cursorApiKey
+            ? 'CURSOR_API_KEY from runner config (bills your Cursor plan)'
+            : ctx.runEnv.CURSOR_API_KEY
+                ? 'CURSOR_API_KEY from the environment (bills your Cursor plan)'
+                : 'NO Cursor API key configured — the run will fail with a setup hint';
+        return {
+            bin: this.bin(cfg),
+            args,
+            env,
+            stdinInput: undefined,
+            shell: false,
+            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.type === 'result' && ev.result) {
+                        process.stdout.write(`  └ ${short(ev.result, 240)}\n`);
+                    }
+                    else if (ev.message?.content) {
+                        const t = ev.message.content
+                            .filter((c) => c.type === 'text' && c.text)
+                            .map((c) => c.text)
+                            .join('');
+                        if (t.trim())
+                            process.stdout.write(`  │ ${short(t)}\n`);
+                    }
+                    else if (ev.text) {
+                        process.stdout.write(`  │ ${short(ev.text)}\n`);
+                    }
+                }
+                catch {
+                }
+            }
+        };
+    },
+    summarize(stdout) {
+        return cursorSummary(stdout);
+    },
+    authFailureHint(text) {
+        const t = text.toLowerCase();
+        if (t.includes('no cursor api key') ||
+            t.includes('not authenticated') ||
+            /\bunauthorized\b/.test(t) ||
+            t.includes('invalid api key') ||
+            /\b401\b/.test(t) ||
+            t.includes('please login') ||
+            t.includes('agent login')) {
+            return 'Cursor could not authenticate. Create a User API Key in the Cursor dashboard and set it on the runner (`--cursor-api-key` / CURSOR_API_KEY), then retry. Note: Cursor headless runs bill your Cursor plan via the API key.';
+        }
+        return null;
+    },
+    rateLimitHint(text) {
+        const t = text.toLowerCase();
+        if (/rate limit|rate_limit|too many requests|\b429\b|usage limit/.test(t)) {
+            return 'Cursor hit a rate / usage limit on your plan. This run was throttled, not failed: retry shortly, or lower "max parallel".';
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=cursor.js.map

package/dist/engines/gemini.d.ts

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

package/dist/engines/gemini.js

@@ -0,0 +1,94 @@
+function geminiSummary(stdout) {
+    const trimmed = stdout.trim();
+    try {
+        const j = JSON.parse(trimmed);
+        if (typeof j.response === 'string' && j.response.trim())
+            return j.response.trim();
+        if (j.error?.message)
+            return j.error.message.trim();
+    }
+    catch {
+    }
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const ev = JSON.parse(lines[i]);
+            if (typeof ev.response === 'string' && ev.response.trim())
+                return ev.response.trim();
+            if (typeof ev.message === 'string' && ev.message.trim())
+                return ev.message.trim();
+            if (typeof ev.message === 'object' && ev.message?.content)
+                return String(ev.message.content).trim();
+            if (ev.error?.message)
+                return ev.error.message.trim();
+        }
+        catch {
+        }
+    }
+    return trimmed.split('\n').slice(-8).join(' ').replace(/\s+/g, ' ').trim().slice(0, 800);
+}
+export const geminiAdapter = {
+    id: 'gemini_cli',
+    displayName: 'Gemini CLI',
+    branchPrefix: 'gemini',
+    bin(cfg) {
+        return cfg.geminiBin ?? 'gemini';
+    },
+    buildInvocation(ctx) {
+        const { cfg } = ctx;
+        const args = [
+            ...(ctx.isWin ? [] : ['-p', ctx.prompt]),
+            '--approval-mode',
+            'yolo',
+            '--output-format',
+            'json',
+            '--skip-trust',
+        ];
+        if (ctx.model)
+            args.push('--model', ctx.model);
+        args.push(...(cfg.geminiArgs ?? []));
+        const env = cfg.geminiApiKey
+            ? { ...ctx.runEnv, GEMINI_API_KEY: cfg.geminiApiKey }
+            : ctx.runEnv;
+        const authLogLine = cfg.geminiApiKey
+            ? 'GEMINI_API_KEY from runner config (free tier 250/day, or paid)'
+            : ctx.runEnv.GEMINI_API_KEY
+                ? 'GEMINI_API_KEY from the environment'
+                : 'Gemini auth from the environment (GEMINI_API_KEY / Vertex / enterprise Code Assist)';
+        return {
+            bin: this.bin(cfg),
+            args,
+            env,
+            stdinInput: ctx.isWin ? ctx.prompt : undefined,
+            shell: ctx.isWin,
+            authLogLine,
+        };
+    },
+    makeStreamPrinter() {
+        return undefined;
+    },
+    summarize(stdout) {
+        return geminiSummary(stdout);
+    },
+    authFailureHint(text) {
+        const t = text.toLowerCase();
+        if (t.includes('please set an auth method') ||
+            t.includes('fatalauthenticationerror') ||
+            t.includes('not eligible') ||
+            t.includes('invalid api key') ||
+            t.includes('api key not valid') ||
+            t.includes('exit code 41') ||
+            /\b401\b/.test(t)) {
+            return 'Gemini CLI could not authenticate. Consumer "Login with Google" was retired for Gemini CLI in June 2026 — set a GEMINI_API_KEY (Google AI Studio; free 250 req/day) on the runner (`--gemini-api-key` / GEMINI_API_KEY) or use Vertex/enterprise Code Assist, then retry.';
+        }
+        return null;
+    },
+    rateLimitHint(text) {
+        const t = text.toLowerCase();
+        if (/rate limit|resource_exhausted|too many requests|\b429\b|quota exceeded|quota_exceeded/.test(t)) {
+            return 'Gemini CLI hit a rate / quota limit (the API-key free tier allows ~250 req/day). This run was throttled, not failed: retry shortly, lower "max parallel", or use a paid key.';
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=gemini.js.map

package/dist/engines/index.d.ts

@@ -0,0 +1,12 @@
+import type { AgentAdapter, EngineId } from './types.js';
+import type { RunnerConfig } from '../config.js';
+export type { AgentAdapter, EngineId, Invocation, InvocationContext } from './types.js';
+export { claudeAdapter } from './claude.js';
+export { codexAdapter } from './codex.js';
+export { geminiAdapter } from './gemini.js';
+export { cursorAdapter } from './cursor.js';
+export declare function getAdapter(engine: string | null | undefined): AgentAdapter;
+export declare function supportedEngines(): EngineId[];
+export declare function binaryOnPath(bin: string): boolean;
+export declare function availableEngines(cfg: RunnerConfig): EngineId[];
+export declare function stripForeignEngineCreds(env: NodeJS.ProcessEnv, engine: EngineId): NodeJS.ProcessEnv;

package/dist/engines/index.js

@@ -0,0 +1,68 @@
+import { existsSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { claudeAdapter } from './claude.js';
+import { codexAdapter } from './codex.js';
+import { geminiAdapter } from './gemini.js';
+import { cursorAdapter } from './cursor.js';
+export { claudeAdapter } from './claude.js';
+export { codexAdapter } from './codex.js';
+export { geminiAdapter } from './gemini.js';
+export { cursorAdapter } from './cursor.js';
+const REGISTRY = {
+    claude_code: claudeAdapter,
+    codex_cli: codexAdapter,
+    gemini_cli: geminiAdapter,
+    cursor_cli: cursorAdapter,
+};
+export function getAdapter(engine) {
+    if (engine && engine in REGISTRY)
+        return REGISTRY[engine];
+    return claudeAdapter;
+}
+export function supportedEngines() {
+    return Object.keys(REGISTRY);
+}
+export function binaryOnPath(bin) {
+    if (!bin)
+        return false;
+    const isWin = process.platform === 'win32';
+    const exts = isWin ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+    const bases = isAbsolute(bin) || bin.includes('/') || (isWin && bin.includes('\\'))
+        ? [bin]
+        : (process.env.PATH ?? '')
+            .split(delimiter)
+            .filter(Boolean)
+            .map((d) => join(d, bin));
+    for (const base of bases) {
+        for (const ext of exts) {
+            const p = base + ext;
+            try {
+                if (existsSync(p) && statSync(p).isFile())
+                    return true;
+            }
+            catch {
+            }
+        }
+    }
+    return false;
+}
+export function availableEngines(cfg) {
+    return supportedEngines().filter((id) => binaryOnPath(REGISTRY[id].bin(cfg)));
+}
+const ENGINE_CRED_VARS = {
+    claude_code: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'],
+    codex_cli: ['OPENAI_API_KEY', 'CODEX_API_KEY'],
+    gemini_cli: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+    cursor_cli: ['CURSOR_API_KEY'],
+};
+export function stripForeignEngineCreds(env, engine) {
+    const out = { ...env };
+    for (const [id, vars] of Object.entries(ENGINE_CRED_VARS)) {
+        if (id === engine)
+            continue;
+        for (const v of vars)
+            delete out[v];
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/engines/types.d.ts

@@ -0,0 +1,47 @@
+import type { RunnerConfig } from '../config.js';
+export type EngineId = 'claude_code' | 'codex_cli' | 'gemini_cli' | 'cursor_cli';
+export type InvocationContext = {
+    prompt: string;
+    model: string | null;
+    effort: string | null;
+    ultracode: boolean;
+    permissionMode: string;
+    allowedTools?: string;
+    maxBudgetUsd?: number;
+    attachDir?: string;
+    attachPaths: string[];
+    isWin: boolean;
+    runEnv: NodeJS.ProcessEnv;
+    cfg: RunnerConfig;
+};
+export type Invocation = {
+    bin: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    stdinInput?: string;
+    shell: boolean;
+    authLogLine: string;
+};
+export type EngineBudgetWindow = {
+    window: string;
+    label: string;
+    pctUsed: number;
+    resetsAt: string | null;
+};
+export type EngineBudgetReport = {
+    engine: EngineId;
+    planLabel?: string;
+    windows: EngineBudgetWindow[];
+};
+export interface AgentAdapter {
+    readonly id: EngineId;
+    readonly displayName: string;
+    readonly branchPrefix: string;
+    bin(cfg: RunnerConfig): string;
+    buildInvocation(ctx: InvocationContext): Invocation;
+    makeStreamPrinter(): ((chunk: string) => void) | undefined;
+    summarize(stdout: string): string;
+    authFailureHint(text: string): string | null;
+    rateLimitHint(text: string): string | null;
+    readBudget?(cfg: RunnerConfig): Promise<EngineBudgetReport | null>;
+}

package/dist/engines/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/exec.d.ts

@@ -0,0 +1,20 @@
+import { type ChildProcess } from 'node:child_process';
+export type ExecResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function spawnBackground(cmd: string, opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): ChildProcess;
+export declare function killProcessTree(child: ChildProcess): Promise<void>;
+export declare function exec(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    shell?: boolean;
+    onStdout?: (chunk: string) => void;
+}): Promise<ExecResult>;
+export declare function execOut(cmd: string, args: string[], cwd?: string): Promise<string>;

package/dist/exec.js

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+function mergeEnv(extra) {
+    const env = { ...process.env, ...extra };
+    for (const k of Object.keys(env))
+        if (env[k] === undefined)
+            delete env[k];
+    return env;
+}
+export function spawnBackground(cmd, opts = {}) {
+    const child = spawn(cmd, [], {
+        cwd: opts.cwd,
+        env: mergeEnv(opts.env),
+        stdio: 'ignore',
+        shell: true,
+        detached: process.platform !== 'win32',
+    });
+    child.on('error', () => { });
+    return child;
+}
+export async function killProcessTree(child) {
+    if (!child.pid)
+        return;
+    if (process.platform === 'win32') {
+        try {
+            spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        catch {
+        }
+        return;
+    }
+    const groupKill = (sig) => {
+        try {
+            process.kill(-child.pid, sig);
+        }
+        catch {
+            try {
+                child.kill(sig);
+            }
+            catch {
+            }
+        }
+    };
+    groupKill('SIGTERM');
+    await new Promise((r) => setTimeout(r, 1500));
+    groupKill('SIGKILL');
+}
+export function exec(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            env: mergeEnv(opts.env),
+            stdio: [opts.input != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+            shell: opts.shell,
+        });
+        if (opts.input != null) {
+            child.stdin?.on('error', () => { });
+            child.stdin?.write(opts.input);
+            child.stdin?.end();
+        }
+        let stdout = '';
+        let stderr = '';
+        let timer = null;
+        let timedOut = false;
+        if (opts.timeoutMs) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                setTimeout(() => child.kill('SIGKILL'), 5_000);
+            }, opts.timeoutMs);
+        }
+        child.stdout?.on('data', (d) => {
+            const s = d.toString();
+            stdout += s;
+            opts.onStdout?.(s);
+        });
+        child.stderr?.on('data', (d) => (stderr += d.toString()));
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                code: timedOut ? 124 : (code ?? 1),
+                stdout,
+                stderr: timedOut ? `${stderr}\n[firefunc-runner] timed out` : stderr,
+            });
+        });
+    });
+}
+export async function execOut(cmd, args, cwd) {
+    const r = await exec(cmd, args, { cwd });
+    return r.code === 0 ? r.stdout.trim() : '';
+}
+//# sourceMappingURL=exec.js.map

package/dist/job.d.ts

@@ -0,0 +1,7 @@
+import type { RunnerApi, ClaimedJob } from './api.js';
+import { type RunnerConfig } from './config.js';
+import type { SessionViewer } from './viewer.js';
+export declare function resolveRepoPath(repo: string | null | undefined, cfg: RunnerConfig): string | null;
+export declare function runJob(job: ClaimedJob, cfg: RunnerConfig, api: RunnerApi, viewer?: SessionViewer, opts?: {
+    devServerPort?: number;
+}): Promise<void>;