@backburner/cli 0.1.0

package/dist/src/agents/gemini.js

@@ -0,0 +1,392 @@
+import { closeSync, openSync, writeSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import { writeJsonFileAtomic } from "../utils/json.js";
+import { buildGeminiCliArgs, GEMINI_MODEL_FALLBACKS, getGeminiEnvOverrides, mapPermissionToApprovalMode, prependGlobalGeminiLaunchInstructions, writeGeminiSystemSettings } from "./gemini-launch.js";
+import { buildExecutionId, extractExitCode, extractAndExportPlanBreakdownResult, extractAndExportWaveAssessmentResult, isRecord, extractReviewResult, extractStderr, extractStdout, extractTriageResult, detectProviderLimit } from "./extraction.js";
+import { buildPromptPacket, renderPrompt } from "./prompt.js";
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const GEMINI_RETRYABLE_EXHAUSTION_PATTERN = /\b(?:QUOTA_EXHAUSTED|RESOURCE_EXHAUSTED|MODEL_CAPACITY_EXHAUSTED)\b|no capacity available|model capacity|quota/i;
+export class GeminiCliAgent {
+    options;
+    now;
+    timeoutMs;
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.logger = options.logger;
+    }
+    async dispatch(task, context, agentConfig, sessionDecision, promptContent) {
+        const promptPacket = buildPromptPacket(task, context);
+        const promptText = prependGlobalGeminiLaunchInstructions(renderPrompt(task, promptPacket, {
+            providerIdentity: "Gemini CLI",
+            customConstraints: promptContent?.content,
+            learningOverlays: promptContent?.learningOverlays
+        }), { ...(this.options.githubBroker ? { mcp: this.options.githubBroker } : {}) });
+        const startedAt = this.now();
+        const executionId = buildExecutionId(task.id, startedAt);
+        const artifactDir = path.join(this.options.logDir, "artifacts", executionId);
+        const promptPacketPath = path.join(artifactDir, "prompt-packet.json");
+        const promptArtifactPath = path.join(artifactDir, "prompt.md");
+        const stdoutArtifactPath = path.join(artifactDir, "stdout.txt");
+        const stderrArtifactPath = path.join(artifactDir, "stderr.txt");
+        const streamArtifactPath = path.join(artifactDir, "stdout-stream.jsonl");
+        const settingsArtifactPath = path.join(artifactDir, "gemini-system-settings.json");
+        await mkdir(artifactDir, { recursive: true });
+        await writeGeminiSystemSettings(settingsArtifactPath, {
+            ...(this.options.githubBroker ? { mcp: this.options.githubBroker } : {})
+        });
+        await Promise.all([
+            writeJsonFileAtomic(promptPacketPath, promptPacket),
+            writeFile(promptArtifactPath, promptText, "utf8")
+        ]);
+        const approvalMode = mapPermissionToApprovalMode(task.executionPermission);
+        const envOverrides = getGeminiEnvOverrides(settingsArtifactPath);
+        const cwd = context.localRepoPath ?? process.cwd();
+        this.logger?.info(JSON.stringify({
+            component: "gemini-launch",
+            taskKind: task.kind,
+            targetRepoPath: cwd,
+            systemSettingsPath: settingsArtifactPath,
+            mcpServerUrl: this.options.githubBroker?.serverUrl
+        }));
+        let stdoutStreamFd;
+        let stderrStreamFd;
+        const resumeSessionId = sessionDecision?.mode === "native_resume_candidate"
+            ? sessionDecision.record.providerSessionId
+            : undefined;
+        try {
+            stdoutStreamFd = openSync(streamArtifactPath, "w");
+            stderrStreamFd = openSync(stderrArtifactPath, "w");
+            const result = await this.runWithModelFallbacks({
+                command: agentConfig.command,
+                approvalMode,
+                cwd,
+                env: envOverrides,
+                promptText,
+                resumeSessionId,
+                ...(agentConfig.model ? { model: agentConfig.model } : {}),
+                onOutputChunk: (stream, chunk) => {
+                    if (stream === "stdout" && stdoutStreamFd !== undefined) {
+                        writeSync(stdoutStreamFd, chunk);
+                    }
+                    if (stream === "stderr" && stderrStreamFd !== undefined) {
+                        writeSync(stderrStreamFd, chunk);
+                    }
+                }
+            });
+            const derivedStdout = result.exitCode === 0 ? extractGeminiStreamJsonAssistantText(result.stdout) ?? result.stdout : result.stdout;
+            const stdout = withAttemptNotes(derivedStdout, result.attemptNotes);
+            const stderr = result.stderr;
+            const endedAt = this.now();
+            await Promise.all([
+                writeFile(stdoutArtifactPath, stdout, "utf8"),
+                writeFile(stderrArtifactPath, stderr, "utf8")
+            ]);
+            const triageResult = extractTriageResult(task, stdout);
+            const reviewResult = extractReviewResult(task, stdout);
+            const planBreakdownExtraction = extractAndExportPlanBreakdownResult(task, stdout, this.options.planBreakdownSessionStore);
+            const waveAssessmentExtraction = extractAndExportWaveAssessmentResult(task, stdout, this.options.waveAssessmentSessionStore);
+            let taskStatus = result.exitCode === 0 ? "completed" : "failed";
+            let errorMessage = result.exitCode === 0 ? undefined : stderr.trim() || "Gemini CLI exited with a non-zero status.";
+            if (task.kind === "review_pr" && result.exitCode === 0 && !reviewResult) {
+                taskStatus = "failed";
+                errorMessage = "Agent output did not contain a valid structured review result.";
+            }
+            if ((task.kind === "plan_breakdown" || task.kind === "wave_plan_replanning") && result.exitCode === 0) {
+                if (!planBreakdownExtraction.ok) {
+                    taskStatus = "failed";
+                    errorMessage = planBreakdownExtraction.message;
+                }
+            }
+            if (task.kind === "wave_plan_assessment" && result.exitCode === 0) {
+                if (!waveAssessmentExtraction.ok) {
+                    taskStatus = "failed";
+                    errorMessage = waveAssessmentExtraction.message;
+                }
+            }
+            const execution = {
+                id: executionId,
+                taskId: task.id,
+                taskKind: task.kind,
+                taskStatus,
+                repoId: task.repoId,
+                repoSlug: task.repoSlug,
+                agentId: agentConfig.id,
+                agentProvider: "gemini",
+                ...(agentConfig.model ? { agentModel: agentConfig.model } : {}),
+                command: {
+                    executable: agentConfig.command,
+                    args: result.args,
+                    cwd,
+                    timeoutMs: this.timeoutMs
+                },
+                promptArtifactPath,
+                stdoutArtifactPath,
+                stderrArtifactPath,
+                streamArtifactPath,
+                promptPacketPath,
+                settingsArtifactPath,
+                startedAt,
+                endedAt,
+                exitCode: result.exitCode,
+                ...(errorMessage ? { errorMessage } : {}),
+                ...(triageResult || reviewResult || planBreakdownExtraction.ok || waveAssessmentExtraction.ok
+                    ? {
+                        result: {
+                            ...(triageResult ? { triage: triageResult } : {}),
+                            ...(reviewResult ? { review: reviewResult } : {}),
+                            ...(planBreakdownExtraction.ok
+                                ? {
+                                    planBreakdown: planBreakdownExtraction.planBreakdown,
+                                    planBreakdownSessionId: planBreakdownExtraction.sessionId
+                                }
+                                : {}),
+                            ...(waveAssessmentExtraction.ok
+                                ? {
+                                    waveAssessment: waveAssessmentExtraction.waveAssessment
+                                }
+                                : {})
+                        }
+                    }
+                    : {})
+            };
+            const parsedSessionId = extractSessionIdFromGeminiStream(result.stdout);
+            const providerLimitSignal = detectProviderLimit("gemini", result.exitCode, result.stdout, result.stderr);
+            return {
+                taskStatus: execution.taskStatus,
+                execution,
+                ...(providerLimitSignal ? { providerLimitSignal } : {}),
+                ...(parsedSessionId ? { providerSession: { providerSessionId: parsedSessionId, status: "active" } } : {})
+            };
+        }
+        finally {
+            if (stdoutStreamFd !== undefined) {
+                const fd = stdoutStreamFd;
+                stdoutStreamFd = undefined;
+                closeSync(fd);
+            }
+            if (stderrStreamFd !== undefined) {
+                const fd = stderrStreamFd;
+                stderrStreamFd = undefined;
+                closeSync(fd);
+            }
+        }
+    }
+    async runWithModelFallbacks(input) {
+        let lastResult;
+        const attemptNotes = [];
+        let resumeSessionId = input.resumeSessionId;
+        const models = input.model ? [input.model] : [...GEMINI_MODEL_FALLBACKS];
+        for (const [index, model] of models.entries()) {
+            const args = buildGeminiCliArgs({
+                approvalMode: input.approvalMode,
+                model,
+                outputFormat: "stream-json",
+                resumeSessionId
+            });
+            try {
+                const result = await this.options.commandRunner.run(input.command, args, {
+                    cwd: input.cwd,
+                    env: input.env,
+                    input: input.promptText,
+                    timeoutMs: this.timeoutMs,
+                    ...(input.onOutputChunk ? { onOutputChunk: input.onOutputChunk } : {})
+                });
+                return { args, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, attemptNotes };
+            }
+            catch (error) {
+                const exitCode = extractExitCode(error);
+                const stdout = extractStdout(error);
+                const stderr = extractStderr(error);
+                lastResult = { args, exitCode, stdout, stderr };
+                resumeSessionId = undefined; // Do not attempt to resume on fallback models!
+                if (!isGeminiQuotaExhaustion(stdout, stderr) || index === models.length - 1) {
+                    break;
+                }
+                const nextModel = models[index + 1];
+                attemptNotes.push(`Gemini model ${model} hit quota exhaustion; retrying with ${nextModel}.`);
+                this.logger?.info(JSON.stringify({
+                    component: "gemini-launch",
+                    event: "quota-fallback",
+                    exhaustedModel: model,
+                    nextModel
+                }));
+            }
+        }
+        if (!lastResult) {
+            return {
+                args: buildGeminiCliArgs({
+                    approvalMode: input.approvalMode,
+                    model: GEMINI_MODEL_FALLBACKS[0],
+                    outputFormat: "stream-json"
+                }),
+                exitCode: 1,
+                stdout: "",
+                stderr: "Gemini CLI did not return an execution result.",
+                attemptNotes
+            };
+        }
+        return {
+            ...lastResult,
+            attemptNotes
+        };
+    }
+}
+function extractGeminiStreamJsonAssistantText(streamText) {
+    if (!streamText.trim()) {
+        return undefined;
+    }
+    let assistantText = "";
+    let sawAssistantMessage = false;
+    let resultText;
+    for (const line of streamText.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(event)) {
+            continue;
+        }
+        if (event.type === "message" && getStreamRole(event) === "assistant") {
+            const messageText = extractStreamText(event);
+            if (messageText) {
+                assistantText += messageText;
+                sawAssistantMessage = true;
+            }
+            continue;
+        }
+        if (resultText === undefined && event.type === "result") {
+            const candidate = extractStreamText(event);
+            if (candidate) {
+                resultText = candidate;
+            }
+        }
+    }
+    if (sawAssistantMessage && assistantText.trim()) {
+        return assistantText;
+    }
+    return resultText;
+}
+function extractStreamText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => extractStreamText(item) ?? "").join("");
+    }
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const keys = ["content", "text", "delta", "response", "output", "message", "result"];
+    const parts = [];
+    for (const key of keys) {
+        const candidate = extractStreamText(value[key]);
+        if (candidate) {
+            parts.push(candidate);
+        }
+    }
+    return parts.length > 0 ? parts.join("") : undefined;
+}
+function getStreamRole(value) {
+    if (typeof value.role === "string") {
+        return value.role;
+    }
+    if (isRecord(value.message) && typeof value.message.role === "string") {
+        return value.message.role;
+    }
+    if (isRecord(value.metadata) && typeof value.metadata.role === "string") {
+        return value.metadata.role;
+    }
+    return undefined;
+}
+function isGeminiQuotaExhaustion(stdout, stderr) {
+    const combined = `${stdout}\n${stderr}`;
+    if (GEMINI_RETRYABLE_EXHAUSTION_PATTERN.test(combined)) {
+        return true;
+    }
+    const jsonCandidates = [parseJsonObject(stdout), parseJsonObject(stderr)];
+    for (const json of jsonCandidates) {
+        if (json && hasRetryableValue(json)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasRetryableValue(obj) {
+    if (typeof obj === "string") {
+        return GEMINI_RETRYABLE_EXHAUSTION_PATTERN.test(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.some((val) => hasRetryableValue(val));
+    }
+    if (obj !== null && typeof obj === "object") {
+        return Object.values(obj).some((val) => hasRetryableValue(val));
+    }
+    return false;
+}
+function parseJsonObject(text) {
+    if (!text.trim()) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Attempt substring extraction if full parse failed
+    }
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start !== -1 && end !== -1 && end > start) {
+        try {
+            const substring = text.substring(start, end + 1);
+            const parsed = JSON.parse(substring);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Ignore parse errors for candidates
+        }
+    }
+    return undefined;
+}
+function withAttemptNotes(stdout, attemptNotes) {
+    if (attemptNotes.length === 0) {
+        return stdout;
+    }
+    return `${attemptNotes.map((note) => `[orchestrator] ${note}`).join("\n")}\n${stdout}`;
+}
+function extractSessionIdFromGeminiStream(streamText) {
+    if (!streamText.trim()) {
+        return undefined;
+    }
+    for (const line of streamText.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            const event = JSON.parse(trimmed);
+            if (event && typeof event === "object" && event.type === "init" && typeof event.session_id === "string") {
+                return event.session_id;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}

package/dist/src/agents/job-agent-assignments.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { workflowRegistry } from "../workflows/registry.js";
+import { roleForTask, selectAgentForTask } from "./selection.js";
+export function getJobKey(role, modelClass) {
+    return `${role}-${modelClass}`;
+}
+export function getJobAgentAssignmentId(input) {
+    const base = `job-assignment:${input.repoKey.replaceAll("/", "~")}:${input.workstreamId}:${input.jobKey}`;
+    return input.uniqueSuffix ? `${base}:${input.uniqueSuffix}` : base;
+}
+export function resolveJobAgentAssignment(input) {
+    const providerLimits = input.providerLimits ?? [];
+    const definition = workflowRegistry.getDefinition(input.task.kind);
+    const role = roleForTask(input.task);
+    const modelClass = definition.modelClass;
+    const jobKey = getJobKey(role, modelClass);
+    if (!input.task.workstreamId) {
+        const configuredAgent = selectAgentForTask(input.task, input.agents, providerLimits, {
+            ...(input.replacementForProvider ? { replacementForProvider: input.replacementForProvider } : {}),
+            ...(input.providerBrokerToolAllowLists ? { providerBrokerToolAllowLists: input.providerBrokerToolAllowLists } : {}),
+            ...(input.capabilitiesByProvider ? { capabilitiesByProvider: input.capabilitiesByProvider } : {})
+        });
+        return {
+            mode: "unscoped_fallback",
+            configuredAgent,
+            initialized: false,
+            assignments: input.existingAssignments
+        };
+    }
+    const existingAssignment = input.existingAssignments.find((a) => a.repoKey === input.task.repoSlug &&
+        a.workstreamId === input.task.workstreamId &&
+        a.role === role &&
+        a.modelClass === modelClass &&
+        a.jobKey === jobKey &&
+        a.status === "active");
+    if (existingAssignment) {
+        const agent = input.agents.find((a) => a.id === existingAssignment.configuredAgentId);
+        let staleReason = getPinnedAssignmentStaleReason(existingAssignment, agent, role, modelClass);
+        if (!staleReason && agent) {
+            const providerLimit = providerLimits.find((limit) => limit.provider === agent.provider && limit.status === "limited");
+            if (providerLimit) {
+                staleReason = "Pinned provider limit exceeded";
+            }
+        }
+        if (staleReason) {
+            const staleAssignments = input.existingAssignments.map((assignment) => assignment.id === existingAssignment.id
+                ? {
+                    ...assignment,
+                    status: "stale",
+                    updatedAt: input.now,
+                    notes: staleReason
+                }
+                : assignment);
+            return createNewAssignment({
+                task: input.task,
+                agents: input.agents,
+                existingAssignments: staleAssignments,
+                providerLimits,
+                replacementForProvider: existingAssignment.provider,
+                ...(input.providerBrokerToolAllowLists ? { providerBrokerToolAllowLists: input.providerBrokerToolAllowLists } : {}),
+                ...(input.capabilitiesByProvider ? { capabilitiesByProvider: input.capabilitiesByProvider } : {}),
+                now: input.now,
+                role,
+                modelClass,
+                jobKey
+            });
+        }
+        return {
+            mode: "pinned",
+            configuredAgent: agent,
+            assignment: existingAssignment,
+            initialized: false,
+            assignments: input.existingAssignments
+        };
+    }
+    return createNewAssignment({
+        task: input.task,
+        agents: input.agents,
+        existingAssignments: input.existingAssignments,
+        providerLimits,
+        ...(input.replacementForProvider ? { replacementForProvider: input.replacementForProvider } : {}),
+        ...(input.providerBrokerToolAllowLists ? { providerBrokerToolAllowLists: input.providerBrokerToolAllowLists } : {}),
+        ...(input.capabilitiesByProvider ? { capabilitiesByProvider: input.capabilitiesByProvider } : {}),
+        now: input.now,
+        role,
+        modelClass,
+        jobKey
+    });
+}
+function createNewAssignment(input) {
+    const configuredAgent = selectAgentForTask(input.task, input.agents, input.providerLimits, {
+        ...(input.replacementForProvider ? { replacementForProvider: input.replacementForProvider } : {}),
+        ...(input.providerBrokerToolAllowLists ? { providerBrokerToolAllowLists: input.providerBrokerToolAllowLists } : {}),
+        ...(input.capabilitiesByProvider ? { capabilitiesByProvider: input.capabilitiesByProvider } : {})
+    });
+    if (!input.task.workstreamId) {
+        throw new Error(`Task ${input.task.id} has no workstreamId; scoped job assignment cannot be created.`);
+    }
+    const newAssignment = {
+        id: getJobAgentAssignmentId({
+            repoKey: input.task.repoSlug,
+            workstreamId: input.task.workstreamId,
+            jobKey: input.jobKey,
+            uniqueSuffix: randomUUID().slice(0, 8)
+        }),
+        repoKey: input.task.repoSlug,
+        workstreamId: input.task.workstreamId,
+        role: input.role,
+        modelClass: input.modelClass,
+        jobKey: input.jobKey,
+        configuredAgentId: configuredAgent.id,
+        provider: configuredAgent.provider,
+        status: "active",
+        createdAt: input.now,
+        updatedAt: input.now
+    };
+    return {
+        mode: "pinned",
+        configuredAgent,
+        assignment: newAssignment,
+        initialized: true,
+        assignments: [...input.existingAssignments, newAssignment].sort(compareJobAgentAssignments)
+    };
+}
+function getPinnedAssignmentStaleReason(assignment, agent, role, modelClass) {
+    if (!agent) {
+        return `Pinned agent "${assignment.configuredAgentId}" no longer exists in agents.json.`;
+    }
+    if (!agent.enabled) {
+        return `Pinned agent "${agent.id}" is disabled in agents.json.`;
+    }
+    if (agent.provider !== assignment.provider) {
+        return `Pinned agent "${agent.id}" provider changed from "${assignment.provider}" to "${agent.provider}".`;
+    }
+    if (agent.modelClass !== modelClass) {
+        return `Pinned agent "${agent.id}" modelClass changed from "${modelClass}" to "${agent.modelClass}".`;
+    }
+    if (!agent.roles.includes(role)) {
+        return `Pinned agent "${agent.id}" no longer has required role "${role}".`;
+    }
+    return undefined;
+}
+export function recordJobAgentAssignmentExecution(input) {
+    const index = input.assignments.findIndex((a) => a.id === input.assignmentId);
+    if (index === -1) {
+        throw new Error(`Assignment "${input.assignmentId}" not found for execution update`);
+    }
+    const existing = input.assignments[index];
+    const updated = {
+        ...existing,
+        lastTaskId: input.taskId,
+        lastExecutionId: input.executionId,
+        lastStartedAt: input.startedAt,
+        updatedAt: input.endedAt
+    };
+    if (input.taskStatus === "completed") {
+        updated.lastCompletedAt = input.endedAt;
+    }
+    else if (input.taskStatus === "failed") {
+        updated.lastFailedAt = input.endedAt;
+    }
+    const nextAssignments = [...input.assignments];
+    nextAssignments[index] = updated;
+    return nextAssignments.sort(compareJobAgentAssignments);
+}
+function compareJobAgentAssignments(left, right) {
+    const repoComparison = left.repoKey.localeCompare(right.repoKey);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    const workstreamComparison = left.workstreamId.localeCompare(right.workstreamId);
+    if (workstreamComparison !== 0) {
+        return workstreamComparison;
+    }
+    const jobKeyComparison = left.jobKey.localeCompare(right.jobKey);
+    if (jobKeyComparison !== 0) {
+        return jobKeyComparison;
+    }
+    return left.id.localeCompare(right.id);
+}