@firefunc-agent/runner 0.5.0

package/dist/job.js

@@ -0,0 +1,391 @@
+import { mkdtempSync, rmSync, existsSync, mkdirSync, writeFileSync, copyFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, basename, dirname } from 'node:path';
+import { exec, execOut, spawnBackground, killProcessTree } from './exec.js';
+import { configPath } from './config.js';
+import { createKeyedMutex } from './locks.js';
+import { getAdapter, stripForeignEngineCreds } from './engines/index.js';
+function log(msg) {
+    console.log(`[firefunc-runner] ${new Date().toISOString()} ${msg}`);
+}
+const gitMutex = createKeyedMutex();
+function saveSessionLog(runId, stdout, stderr) {
+    try {
+        const dir = join(dirname(configPath()), 'logs');
+        mkdirSync(dir, { recursive: true });
+        const p = join(dir, `${runId}.log`);
+        writeFileSync(p, `=== agent stdout ===\n${stdout}\n\n=== agent stderr ===\n${stderr}\n`);
+        return p;
+    }
+    catch {
+        return null;
+    }
+}
+const EXT_FOR_MIME = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/bmp': '.bmp',
+};
+function safeAttachmentName(filename, i, mime) {
+    const base = basename(filename ?? '').replace(/[^a-zA-Z0-9._-]/g, '_');
+    if (base && /\.[a-zA-Z0-9]+$/.test(base))
+        return base;
+    const ext = (mime && EXT_FOR_MIME[mime]) || '.png';
+    return `${base || `attachment-${i + 1}`}${ext}`;
+}
+export function resolveRepoPath(repo, cfg) {
+    if (!repo)
+        return null;
+    const want = repo.toLowerCase();
+    if (cfg.repos) {
+        for (const [k, v] of Object.entries(cfg.repos)) {
+            if (k.toLowerCase() === want && existsSync(v))
+                return v;
+        }
+    }
+    if (cfg.reposDir) {
+        const guess = join(cfg.reposDir, basename(repo));
+        if (existsSync(guess))
+            return guess;
+    }
+    return null;
+}
+function installCmdFor(dir) {
+    if (existsSync(join(dir, 'pnpm-lock.yaml')))
+        return 'pnpm install --frozen-lockfile';
+    if (existsSync(join(dir, 'yarn.lock')))
+        return 'yarn install --frozen-lockfile';
+    if (existsSync(join(dir, 'package-lock.json')))
+        return 'npm ci';
+    return 'npm install';
+}
+async function autoInstallDeps(worktree, env, timeoutMs) {
+    const dirs = existsSync(join(worktree, 'package.json'))
+        ? ['']
+        : ['backend', 'web', 'frontend', 'server', 'client', 'api'];
+    let installed = 0;
+    for (const d of dirs) {
+        const dir = d ? join(worktree, d) : worktree;
+        if (!existsSync(join(dir, 'package.json')))
+            continue;
+        const cmd = installCmdFor(dir);
+        log(`auto-install: ${cmd} (in ${d || '.'})`);
+        const r = await exec(cmd, [], { cwd: dir, env, timeoutMs, shell: true });
+        if (r.code !== 0) {
+            log(`auto-install failed (exit ${r.code}) in ${d || '.'} — continuing without deps: ${r.stderr.slice(0, 200)}`);
+        }
+        else {
+            installed++;
+        }
+    }
+    if (!installed && dirs[0] !== '')
+        log('auto-install: no package.json found — skipping');
+}
+export async function runJob(job, cfg, api, viewer, opts) {
+    const report = async (payload) => {
+        try {
+            await api.result(job.runId, payload);
+        }
+        catch (err) {
+            log(`failed to report result for ${job.runId}: ${err.message}`);
+        }
+    };
+    const fail = (error) => {
+        log(`job ${job.runId} FAILED — ${error.replace(/\s+/g, ' ').slice(0, 300)}`);
+        return report({ status: 'failed', error });
+    };
+    const repoPath = resolveRepoPath(job.repo, cfg);
+    if (!repoPath) {
+        log(`no local checkout for ${job.repo} — set it in config.repos or reposDir`);
+        return report({
+            status: 'failed',
+            error: `Runner has no local checkout configured for ${job.repo}.`,
+        });
+    }
+    const adapter = getAdapter(job.engine ?? cfg.engine);
+    const branch = job.branch ?? `${adapter.branchPrefix}/firefunc-${job.runId.slice(0, 8)}`;
+    const timeoutMs = (cfg.jobTimeoutMinutes ?? 20) * 60_000;
+    let worktree = null;
+    let attachDir = null;
+    const bgProcs = [];
+    viewer?.begin(job.runId, {
+        title: job.title ?? job.externalId ?? undefined,
+        repo: job.repo ?? undefined,
+    });
+    try {
+        await api.event(job.runId, 'cloning', { repo: job.repo, branch });
+        const prep = await gitMutex.run(repoPath, async () => {
+            await exec('git', ['-C', repoPath, 'fetch', 'origin', '--quiet'], { timeoutMs: 120_000 });
+            let b = cfg.baseBranch ?? '';
+            if (!b) {
+                const head = await execOut('git', ['-C', repoPath, 'symbolic-ref', 'refs/remotes/origin/HEAD'], repoPath);
+                b = head ? head.replace('refs/remotes/origin/', '') : 'main';
+            }
+            await exec('git', ['-C', repoPath, 'worktree', 'prune']).catch(() => { });
+            const wt = mkdtempSync(join(tmpdir(), 'firefunc-'));
+            const result = await exec('git', ['-C', repoPath, 'worktree', 'add', '--force', '-B', branch, wt, `origin/${b}`], { timeoutMs: 120_000 });
+            return { base: b, wt, add: result };
+        });
+        const base = prep.base;
+        worktree = prep.wt;
+        if (prep.add.code !== 0) {
+            return fail(`git worktree add failed: ${prep.add.stderr.slice(0, 400)}`);
+        }
+        const attachPaths = [];
+        if (job.attachments?.length) {
+            attachDir = mkdtempSync(join(tmpdir(), 'firefunc-attach-'));
+            mkdirSync(attachDir, { recursive: true });
+            job.attachments.forEach((att, i) => {
+                if (!att?.dataB64)
+                    return;
+                try {
+                    const p = join(attachDir, safeAttachmentName(att.filename, i, att.contentType));
+                    writeFileSync(p, Buffer.from(att.dataB64, 'base64'));
+                    attachPaths.push(p);
+                }
+                catch {
+                }
+            });
+            if (attachPaths.length)
+                log(`wrote ${attachPaths.length} attachment(s) for ${job.runId}`);
+        }
+        const attachNote = attachPaths.length
+            ? `The reporter attached ${attachPaths.length} file(s). Read EACH one with the Read tool before forming your fix — they may be screenshots, designs, logs, stack traces, or repro data that show the bug or the intended result:\n${attachPaths
+                .map((p) => `- ${p}`)
+                .join('\n')}\n\n`
+            : '';
+        const runEnv = {
+            ...cfg.claudeEnv,
+            ...(cfg.claudeCodeOAuthToken ? { CLAUDE_CODE_OAUTH_TOKEN: cfg.claudeCodeOAuthToken } : {}),
+            ...(opts?.devServerPort ? { PORT: String(opts.devServerPort) } : {}),
+        };
+        if (opts?.devServerPort && cfg.backgroundCommands?.length) {
+            log(`session dev-server PORT=${opts.devServerPort} (parallel-safe)`);
+        }
+        if (cfg.envFile) {
+            try {
+                copyFileSync(cfg.envFile, join(worktree, '.env'));
+                log(`copied ${cfg.envFile} → worktree/.env`);
+            }
+            catch (e) {
+                log(`envFile copy failed (${cfg.envFile}): ${e.message}`);
+            }
+        }
+        const setupMs = (cfg.setupTimeoutMinutes ?? cfg.jobTimeoutMinutes ?? 20) * 60_000;
+        if (cfg.setupCommands?.length) {
+            for (const cmd of cfg.setupCommands) {
+                log(`setup: ${cmd}`);
+                const r = await exec(cmd, [], {
+                    cwd: worktree,
+                    env: runEnv,
+                    timeoutMs: setupMs,
+                    shell: true,
+                });
+                if (r.code !== 0) {
+                    return fail(`Setup command failed (exit ${r.code}): ${cmd}\n${r.stderr.slice(0, 400)}`);
+                }
+            }
+        }
+        else if (cfg.autoInstall ?? true) {
+            await autoInstallDeps(worktree, runEnv, setupMs);
+        }
+        for (const cmd of cfg.backgroundCommands ?? []) {
+            log(`starting background: ${cmd}`);
+            bgProcs.push(spawnBackground(cmd, { cwd: worktree, env: runEnv }));
+        }
+        await api.event(job.runId, 'fixing', { title: job.title });
+        const mode = job.permissionMode ?? cfg.permissionMode ?? 'bypassPermissions';
+        const model = job.model ?? cfg.model ?? null;
+        const effort = job.effort ?? cfg.effort ?? null;
+        const ultracode = effort === 'ultracode';
+        const observeNote = 'Dev/observation tooling MAY be available here: the app may be runnable (setup ran), a dev server may be up, and AWS read creds / a staging URL / a test account may be in your environment. PREFER reproducing the reported symptom LIVE (run the app, curl the API, drive the UI) before reasoning statically, and re-observe after your change to confirm the fix. Treat any cloud/staging access as READ-ONLY.\n\n';
+        const prompt = observeNote + attachNote + (ultracode ? `ultracode\n\n${job.prompt}` : job.prompt);
+        const tools = cfg.allowedTools ??
+            'Read Edit Write Bash Glob Grep WebFetch WebSearch Task TodoWrite NotebookEdit';
+        const isWin = process.platform === 'win32';
+        let inv;
+        try {
+            inv = adapter.buildInvocation({
+                prompt,
+                model,
+                effort,
+                ultracode,
+                permissionMode: mode,
+                allowedTools: tools,
+                maxBudgetUsd: cfg.maxBudgetUsd,
+                attachDir: attachDir ?? undefined,
+                attachPaths,
+                isWin,
+                runEnv: stripForeignEngineCreds(runEnv, adapter.id),
+                cfg,
+            });
+        }
+        catch (e) {
+            return fail(`${adapter.displayName} cannot run on this machine: ${e.message}`);
+        }
+        const engineName = adapter.displayName;
+        log(`running ${inv.bin} (${engineName}) on ${job.repo} (${branch}) — model=${model ?? 'default'} effort=${effort ?? 'default'} mode=${mode}`);
+        log(`${engineName} auth: ${inv.authLogLine}`);
+        const printer = cfg.quiet ? undefined : adapter.makeStreamPrinter();
+        const onStdout = printer || viewer
+            ? (chunk) => {
+                printer?.(chunk);
+                viewer?.push(job.runId, chunk);
+            }
+            : undefined;
+        if (printer) {
+            log(`── live ${engineName} session (shown here only — never sent to FireFunc) ──`);
+        }
+        const heartbeat = setInterval(() => void api.event(job.runId, 'heartbeat'), 5 * 60_000);
+        const engineRun = await exec(inv.bin, inv.args, {
+            cwd: worktree,
+            timeoutMs,
+            env: inv.env,
+            input: inv.stdinInput,
+            shell: inv.shell,
+            onStdout,
+        }).finally(() => clearInterval(heartbeat));
+        viewer?.end(job.runId, engineRun.code === 0 ? 'done' : 'failed');
+        if (printer)
+            log(`── end ${engineName} session ──`);
+        const sessionLogPath = saveSessionLog(job.runId, engineRun.stdout, engineRun.stderr);
+        const summary = adapter.summarize(engineRun.stdout);
+        if (sessionLogPath)
+            log(`${engineName} session saved → ${sessionLogPath}`);
+        if (summary)
+            log(`${engineName} said: ${summary.replace(/\s+/g, ' ').slice(0, 500)}`);
+        if (engineRun.code === 124) {
+            return fail(`${engineName} timed out after ${cfg.jobTimeoutMinutes ?? 20} min.`);
+        }
+        const scanHints = () => {
+            const authMsg = adapter.authFailureHint(`${summary}\n${engineRun.stderr}`);
+            if (authMsg) {
+                log(`auth/billing failure for ${job.runId}: ${authMsg}`);
+                return { status: 'failed', error: authMsg };
+            }
+            const rateMsg = adapter.rateLimitHint(`${summary}\n${engineRun.stderr}`);
+            if (rateMsg) {
+                log(`rate limit for ${job.runId}: ${rateMsg}`);
+                return { status: 'failed', error: rateMsg };
+            }
+            return null;
+        };
+        if (engineRun.code !== 0) {
+            const hinted = scanHints();
+            if (hinted)
+                return report(hinted);
+            return fail(summary
+                ? `${engineName} exited abnormally (code ${engineRun.code}). Last message: ${summary.replace(/\s+/g, ' ').slice(0, 500)}`
+                : `${engineName} exited abnormally (code ${engineRun.code}). ${engineRun.stderr.slice(0, 300)}`);
+        }
+        const title = job.title ? `fix: ${job.title}` : `fix: ${job.externalId ?? 'FireFunc auto-fix'}`;
+        await exec('git', ['-C', worktree, 'add', '-A']);
+        const vsBase = await exec('git', [
+            '-C',
+            worktree,
+            'diff',
+            '--cached',
+            '--quiet',
+            `origin/${base}`,
+        ]);
+        if (vsBase.code === 0) {
+            const hinted = scanHints();
+            if (hinted)
+                return report(hinted);
+            log(`no changes produced for ${job.runId} — reporting no_pr`);
+            return report({
+                status: 'no_pr',
+                error: summary
+                    ? `No code change made. ${engineName}: ${summary.replace(/\s+/g, ' ').slice(0, 800)}`
+                    : `${engineName} made no changes (could not reproduce or fix).`,
+            });
+        }
+        const uncommitted = await exec('git', ['-C', worktree, 'diff', '--cached', '--quiet', 'HEAD']);
+        if (uncommitted.code !== 0) {
+            await exec('git', ['-C', worktree, 'commit', '-m', title, '--quiet']);
+        }
+        else {
+            log(`agent already committed its changes for ${job.runId} — reconciling to a PR`);
+        }
+        await api.event(job.runId, 'pushing', { branch });
+        const push = await exec('git', ['-C', worktree, 'push', '--force-with-lease', 'origin', `${branch}:${branch}`], { timeoutMs: 120_000 });
+        if (push.code !== 0) {
+            return fail(`git push failed: ${push.stderr.slice(0, 400)}`);
+        }
+        const body = `Automated fix by FireFunc (self-hosted ${engineName} runner) for ${job.externalId ?? 'a reported bug'}.\n\nReview before merging.`;
+        const create = await exec('gh', [
+            'pr',
+            'create',
+            '--draft',
+            '--head',
+            branch,
+            '--base',
+            base,
+            '--title',
+            title,
+            '--body',
+            body,
+        ], { cwd: worktree, timeoutMs: 60_000 });
+        const wt = worktree;
+        const viewPr = async (b) => {
+            const out = await execOut('gh', ['pr', 'view', b, '--json', 'url,number'], wt);
+            try {
+                const j = JSON.parse(out);
+                if (typeof j.url === 'string' && /\/pull\/\d+/.test(j.url) && Number.isFinite(j.number)) {
+                    return { url: j.url, number: Number(j.number) };
+                }
+            }
+            catch {
+            }
+            return null;
+        };
+        const headBranch = (await execOut('git', ['rev-parse', '--abbrev-ref', 'HEAD'], wt)) || branch;
+        let resolved = null;
+        for (const b of [...new Set([headBranch, branch].filter(Boolean))]) {
+            resolved = await viewPr(b);
+            if (resolved)
+                break;
+        }
+        if (!resolved) {
+            const m = `${create.stdout}\n${create.stderr}`.match(/https?:\/\/\S*\/pull\/(\d+)/);
+            if (m)
+                resolved = { url: m[0], number: Number(m[1]) };
+        }
+        const url = resolved?.url ?? '';
+        const number = resolved?.number;
+        await api.event(job.runId, 'pr_opened', { url, branch });
+        log(`opened PR for ${job.runId}: ${url || '(url unknown)'}`);
+        return report({
+            status: 'pr_opened',
+            pr: { repo: job.repo ?? undefined, number, url: url || undefined, branch, summary: title },
+        });
+    }
+    catch (err) {
+        log(`job ${job.runId} errored: ${err.message}`);
+        return report({ status: 'failed', error: err.message.slice(0, 400) });
+    }
+    finally {
+        viewer?.end(job.runId, 'failed');
+        await Promise.all(bgProcs.map((p) => killProcessTree(p).catch(() => { })));
+        if (worktree) {
+            await gitMutex
+                .run(repoPath, () => exec('git', ['-C', repoPath, 'worktree', 'remove', '--force', worktree]))
+                .catch(() => { });
+            try {
+                rmSync(worktree, { recursive: true, force: true });
+            }
+            catch {
+            }
+        }
+        if (attachDir) {
+            try {
+                rmSync(attachDir, { recursive: true, force: true });
+            }
+            catch {
+            }
+        }
+    }
+}
+//# sourceMappingURL=job.js.map

package/dist/locks.d.ts

@@ -0,0 +1,4 @@
+export type KeyedMutex = {
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+};
+export declare function createKeyedMutex(): KeyedMutex;

package/dist/locks.js

@@ -0,0 +1,13 @@
+const noop = () => { };
+export function createKeyedMutex() {
+    const tails = new Map();
+    return {
+        run(key, fn) {
+            const prev = tails.get(key) ?? Promise.resolve();
+            const result = prev.then(fn, fn);
+            tails.set(key, result.then(noop, noop));
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=locks.js.map

package/dist/pool.d.ts

@@ -0,0 +1,12 @@
+export type JobPoolDeps<J> = {
+    maxParallel: number | (() => number);
+    stopping: () => boolean;
+    claim: () => Promise<J | null>;
+    run: (job: J) => Promise<void>;
+    onClaimError?: (err: unknown) => Promise<'fatal' | 'retry'>;
+    onStart?: (job: J, inFlight: number) => void;
+    idleDelayMs?: number;
+    maxIdleDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function runJobPool<J>(deps: JobPoolDeps<J>): Promise<void>;

package/dist/pool.js

@@ -0,0 +1,47 @@
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function runJobPool(deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const baseIdleMs = deps.idleDelayMs ?? 800;
+    const maxIdleMs = Math.max(baseIdleMs, deps.maxIdleDelayMs ?? 8_000);
+    let emptyClaims = 0;
+    const idleDelay = () => Math.min(maxIdleMs, baseIdleMs * 2 ** Math.min(emptyClaims, 10));
+    const cap = () => Math.max(1, Math.floor(typeof deps.maxParallel === 'function' ? deps.maxParallel() : deps.maxParallel));
+    const active = new Set();
+    while (!deps.stopping()) {
+        if (active.size >= cap()) {
+            await Promise.race(active);
+            continue;
+        }
+        let job;
+        try {
+            job = await deps.claim();
+        }
+        catch (err) {
+            if (!deps.onClaimError)
+                throw err;
+            if ((await deps.onClaimError(err)) === 'fatal')
+                break;
+            continue;
+        }
+        if (job == null) {
+            const delay = idleDelay();
+            emptyClaims += 1;
+            if (active.size > 0)
+                await Promise.race([...active, sleep(delay)]);
+            else
+                await sleep(delay);
+            continue;
+        }
+        emptyClaims = 0;
+        if (deps.stopping())
+            break;
+        deps.onStart?.(job, active.size + 1);
+        const p = deps.run(job).finally(() => {
+            active.delete(p);
+        });
+        active.add(p);
+    }
+    if (active.size > 0)
+        await Promise.allSettled(active);
+}
+//# sourceMappingURL=pool.js.map

package/dist/session-stream.d.ts

@@ -0,0 +1,12 @@
+export type SessionEvent = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool';
+    name: string;
+    arg?: string;
+} | {
+    kind: 'result';
+    text: string;
+};
+export declare function makeStreamJsonParser(onEvent: (ev: SessionEvent) => void): (chunk: string) => void;

package/dist/session-stream.js

@@ -0,0 +1,42 @@
+export function makeStreamJsonParser(onEvent) {
+    let buf = '';
+    return (chunk) => {
+        buf += chunk;
+        let nl = buf.indexOf('\n');
+        while (nl >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            nl = buf.indexOf('\n');
+            if (!line)
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (ev.type === 'assistant' && ev.message?.content) {
+                for (const c of ev.message.content) {
+                    if (c.type === 'text' && c.text?.trim()) {
+                        onEvent({ kind: 'text', text: c.text });
+                    }
+                    else if (c.type === 'tool_use' && c.name) {
+                        const inp = c.input ?? {};
+                        const arg = (inp.file_path ??
+                            inp.command ??
+                            inp.pattern ??
+                            inp.path ??
+                            inp.url ??
+                            '');
+                        onEvent(arg ? { kind: 'tool', name: c.name, arg } : { kind: 'tool', name: c.name });
+                    }
+                }
+            }
+            else if (ev.type === 'result' && typeof ev.result === 'string' && ev.result.trim()) {
+                onEvent({ kind: 'result', text: ev.result });
+            }
+        }
+    };
+}
+//# sourceMappingURL=session-stream.js.map

package/dist/viewer.d.ts

@@ -0,0 +1,16 @@
+export type SessionStatus = 'running' | 'done' | 'failed';
+export type SessionViewer = {
+    url: string | null;
+    begin: (runId: string, meta: {
+        title?: string;
+        repo?: string;
+    }) => void;
+    push: (runId: string, chunk: string) => void;
+    end: (runId: string, status: Exclude<SessionStatus, 'running'>) => void;
+    close: () => void;
+};
+export declare function createSessionViewer(opts: {
+    port?: number;
+    onListen?: (url: string) => void;
+    onError?: (msg: string) => void;
+}): SessionViewer;