@backburner/cli 0.1.0

package/dist/src/agents/codex-launch.js

@@ -0,0 +1,82 @@
+export function resolveCodexLaunchConfig(input) {
+    return {
+        executionPermission: input.executionPermission,
+        sandboxMode: mapExecutionPermissionToSandboxMode(input.executionPermission),
+        expectsPushableHandoff: input.handoffPolicy.expectsPushableHandoff,
+        orchestratorOwnsPush: input.handoffPolicy.orchestratorOwnsPush,
+        remotePublishOwner: input.handoffPolicy.remotePublishOwner
+    };
+}
+export function mapExecutionPermissionToSandboxMode(executionPermission) {
+    switch (executionPermission) {
+        case "read-only":
+            return "read-only";
+        case "workspace-write":
+            return "workspace-write";
+    }
+}
+export function buildCodexCliArgs(input) {
+    const args = ["exec", "--json", "--sandbox", input.sandboxMode, "--skip-git-repo-check", "--color", "never"];
+    if (input.sandboxMode === "workspace-write") {
+        args.push("-c", "sandbox_workspace_write.network_access=true");
+    }
+    if (input.githubBroker) {
+        const safeServerName = toCodexCliSafeServerName(input.githubBroker.serverName);
+        args.push("-c", `mcp_servers.${safeServerName}.url=${quoteTomlString(input.githubBroker.serverUrl)}`, "-c", `mcp_servers.${safeServerName}.default_tools_approval_mode="approve"`);
+    }
+    if (input.model) {
+        args.push("--model", input.model);
+    }
+    if (input.resumeThreadId) {
+        args.push("resume", input.resumeThreadId);
+    }
+    args.push("-");
+    return args;
+}
+export function buildGlobalCodexLaunchInstructions(input) {
+    return [
+        "# Global Codex Instructions",
+        "",
+        "These instructions apply across repositories for this orchestrated run.",
+        "",
+        "## MCP Server",
+        `Use the local MCP server \`${input.githubBroker.serverName}\` for normal GitHub reads and writes.`,
+        "- Do not call `gh` directly for normal GitHub issue, pull request, comment, or code-search work.",
+        "",
+        "## When To Use It",
+        "- Use the broker for normal GitHub context gathering and GitHub write actions.",
+        "- Repo-local `AGENTS.md` files still apply for repository-specific build, test, and style rules.",
+        "",
+        "Enabled broker tools for this run:",
+        ...input.githubBroker.toolAllowList.map((tool) => `- \`${tool}\``),
+        "",
+        "## Fallback",
+        "- If a needed GitHub capability is missing from the broker, report the gap clearly instead of silently bypassing it.",
+        "- Continue with local repository work where possible while making the missing broker capability explicit.",
+        "- Any GitHub-authored message you post must begin with `🤖` when the task requires writing back to GitHub.",
+        ""
+    ].join("\n");
+}
+export function prependGlobalLaunchInstructions(promptText, input) {
+    if (!input.githubBroker) {
+        return promptText;
+    }
+    return `${buildGlobalCodexLaunchInstructions({ githubBroker: input.githubBroker })}\n\n${promptText}`;
+}
+export function toCodexCliSafeServerName(value) {
+    const segments = value
+        .split(/[^a-zA-Z0-9]+/)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return "githubBroker";
+    }
+    return segments
+        .map((segment, index) => index === 0
+        ? segment[0].toLowerCase() + segment.slice(1)
+        : segment[0].toUpperCase() + segment.slice(1))
+        .join("");
+}
+function quoteTomlString(value) {
+    return JSON.stringify(value);
+}

package/dist/src/agents/codex.js

@@ -0,0 +1,261 @@
+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 { buildCodexCliArgs, prependGlobalLaunchInstructions, resolveCodexLaunchConfig, toCodexCliSafeServerName } from "./codex-launch.js";
+import { buildExecutionId, extractExitCode, extractAndExportPlanBreakdownResult, extractAndExportWaveAssessmentResult, extractReviewResult, extractStderr, extractStdout, extractTriageResult, detectProviderLimit } from "./extraction.js";
+import { buildPromptPacket, renderPrompt } from "./prompt.js";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+export class CodexCliAgent {
+    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 launchConfig = resolveCodexLaunchConfig({
+            executionPermission: task.executionPermission,
+            handoffPolicy: task.handoffPolicy
+        });
+        const githubBroker = this.options.githubBroker
+            ? {
+                ...this.options.githubBroker,
+                serverName: toCodexCliSafeServerName(this.options.githubBroker.serverName)
+            }
+            : undefined;
+        const promptPacket = buildPromptPacket(task, context);
+        const promptText = prependGlobalLaunchInstructions(renderPrompt(task, promptPacket, {
+            customConstraints: promptContent?.content,
+            learningOverlays: promptContent?.learningOverlays
+        }), githubBroker ? { 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 resumeThreadId = sessionDecision?.mode === "native_resume_candidate"
+            ? sessionDecision.record.providerSessionId
+            : undefined;
+        const args = buildCodexCliArgs({
+            sandboxMode: launchConfig.sandboxMode,
+            resumeThreadId,
+            ...(githubBroker ? { githubBroker } : {}),
+            ...(agentConfig.model ? { model: agentConfig.model } : {})
+        });
+        const cwd = context.localRepoPath ?? process.cwd();
+        await mkdir(artifactDir, { recursive: true });
+        await Promise.all([
+            writeJsonFileAtomic(promptPacketPath, promptPacket),
+            writeFile(promptArtifactPath, promptText, "utf8")
+        ]);
+        if (githubBroker) {
+            this.logger?.info(JSON.stringify({
+                component: "codex-launch",
+                taskKind: task.kind,
+                targetRepoPath: cwd,
+                executionPermission: launchConfig.executionPermission,
+                sandboxMode: launchConfig.sandboxMode,
+                expectsPushableHandoff: launchConfig.expectsPushableHandoff,
+                orchestratorOwnsPush: launchConfig.orchestratorOwnsPush,
+                remotePublishOwner: launchConfig.remotePublishOwner,
+                mcpServerName: githubBroker.serverName,
+                mcpServerUrl: githubBroker.serverUrl,
+                enabledToolAllowList: githubBroker.toolAllowList,
+                configOverrides: args.filter((_, index) => args[index - 1] === "-c")
+            }));
+        }
+        else {
+            this.logger?.info(JSON.stringify({
+                component: "codex-launch",
+                taskKind: task.kind,
+                targetRepoPath: cwd,
+                executionPermission: launchConfig.executionPermission,
+                sandboxMode: launchConfig.sandboxMode,
+                expectsPushableHandoff: launchConfig.expectsPushableHandoff,
+                orchestratorOwnsPush: launchConfig.orchestratorOwnsPush,
+                remotePublishOwner: launchConfig.remotePublishOwner
+            }));
+        }
+        let exitCode = 0;
+        let stdout = "";
+        let stderr = "";
+        let endedAt = startedAt;
+        let stdoutStreamFd;
+        try {
+            stdoutStreamFd = openSync(streamArtifactPath, "w");
+            const result = await this.options.commandRunner.run(agentConfig.command, args, {
+                cwd,
+                input: promptText,
+                timeoutMs: this.timeoutMs,
+                onOutputChunk: (stream, chunk) => {
+                    if (stream === "stdout" && stdoutStreamFd !== undefined) {
+                        writeSync(stdoutStreamFd, chunk);
+                    }
+                }
+            });
+            exitCode = result.exitCode;
+            stdout = result.stdout;
+            stderr = result.stderr;
+            endedAt = this.now();
+        }
+        catch (error) {
+            exitCode = extractExitCode(error);
+            stdout = extractStdout(error);
+            stderr = extractStderr(error);
+            endedAt = this.now();
+        }
+        finally {
+            if (stdoutStreamFd !== undefined) {
+                closeSync(stdoutStreamFd);
+            }
+        }
+        const derivedStdout = exitCode === 0
+            ? extractCodexStreamJsonAssistantText(stdout) ?? stdout
+            : stdout;
+        await Promise.all([
+            writeFile(stdoutArtifactPath, derivedStdout, "utf8"),
+            writeFile(stderrArtifactPath, stderr, "utf8")
+        ]);
+        const triageResult = extractTriageResult(task, derivedStdout);
+        const reviewResult = extractReviewResult(task, derivedStdout);
+        const planBreakdownExtraction = extractAndExportPlanBreakdownResult(task, derivedStdout, this.options.planBreakdownSessionStore);
+        const waveAssessmentExtraction = extractAndExportWaveAssessmentResult(task, derivedStdout, this.options.waveAssessmentSessionStore);
+        let taskStatus = exitCode === 0 ? "completed" : "failed";
+        let errorMessage = exitCode === 0 ? undefined : stderr.trim() || "Codex CLI exited with a non-zero status.";
+        if (task.kind === "review_pr" && 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") && exitCode === 0) {
+            if (!planBreakdownExtraction.ok) {
+                taskStatus = "failed";
+                errorMessage = planBreakdownExtraction.message;
+            }
+        }
+        if (task.kind === "wave_plan_assessment" && 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: "codex",
+            ...(agentConfig.model ? { agentModel: agentConfig.model } : {}),
+            command: {
+                executable: agentConfig.command,
+                args,
+                cwd,
+                timeoutMs: this.timeoutMs
+            },
+            promptArtifactPath,
+            stdoutArtifactPath,
+            stderrArtifactPath,
+            streamArtifactPath,
+            promptPacketPath,
+            startedAt,
+            endedAt,
+            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 parsedThreadId = extractThreadIdFromCodexOutput(stdout);
+        const providerLimitSignal = detectProviderLimit("codex", exitCode, stdout, stderr);
+        return {
+            taskStatus: execution.taskStatus,
+            execution,
+            ...(providerLimitSignal ? { providerLimitSignal } : {}),
+            ...(parsedThreadId ? { providerSession: { providerSessionId: parsedThreadId, status: "active" } } : {})
+        };
+    }
+}
+function extractThreadIdFromCodexOutput(streamText) {
+    if (!streamText.trim()) {
+        return undefined;
+    }
+    const plainTextMatch = /\bsession id:\s*([0-9a-f-]{36})\b/i.exec(streamText);
+    if (plainTextMatch?.[1]) {
+        return plainTextMatch[1];
+    }
+    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 === "thread.started" && typeof event.thread_id === "string") {
+                return event.thread_id;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+function extractCodexStreamJsonAssistantText(streamText) {
+    if (!streamText.trim()) {
+        return undefined;
+    }
+    let assistantText = "";
+    let sawAssistantMessage = false;
+    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 === "item.completed" &&
+                event.item &&
+                typeof event.item === "object" &&
+                event.item.type === "agent_message" &&
+                typeof event.item.text === "string") {
+                assistantText += event.item.text;
+                sawAssistantMessage = true;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    if (sawAssistantMessage) {
+        return assistantText;
+    }
+    return undefined;
+}

package/dist/src/agents/composite-runner.js

@@ -0,0 +1,13 @@
+export class CompositeAgentRunner {
+    runners = new Map();
+    register(provider, runner) {
+        this.runners.set(provider, runner);
+    }
+    async dispatch(task, context, agentConfig, sessionDecision, promptContent) {
+        const runner = this.runners.get(agentConfig.provider);
+        if (!runner) {
+            throw new Error(`No runner registered for agent provider "${agentConfig.provider}" (agent: ${agentConfig.id})`);
+        }
+        return runner.dispatch(task, context, agentConfig, sessionDecision, promptContent);
+    }
+}