@backburner/cli 0.1.0

package/dist/src/agents/extraction.js

@@ -0,0 +1,442 @@
+import { exportSession } from "../workstreams/plan-breakdown-generator/export.js";
+import { buildPacketPlanFromPlanBreakdown } from "../workstreams/packet-plan.js";
+import { exportWaveAssessmentSession } from "../workstreams/wave-assessment/session.js";
+export function extractAndExportPlanBreakdownResult(task, stdout, sessionStore) {
+    if (!requiresPlanBreakdownResult(task)) {
+        return { ok: false, reason: "not_plan_breakdown", message: "Task does not require a plan breakdown result." };
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: "empty_stdout", message: "Agent output is empty." };
+    }
+    const candidate = extractTrailingJsonObject(trimmed);
+    if (!candidate) {
+        return { ok: false, reason: "missing_json", message: "No JSON object found in agent output." };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(candidate);
+    }
+    catch {
+        return { ok: false, reason: "malformed_json", message: "Malformed JSON object in agent output." };
+    }
+    if (!isRecord(parsed) || typeof parsed.sessionId !== "string") {
+        return {
+            ok: false,
+            reason: "missing_session_id",
+            message: 'Agent response must be a JSON object with a "sessionId" string.'
+        };
+    }
+    const { sessionId } = parsed;
+    const normalizedSessionId = sessionId.trim();
+    if (!normalizedSessionId) {
+        return {
+            ok: false,
+            reason: "missing_session_id",
+            message: 'Agent response "sessionId" must not be empty.'
+        };
+    }
+    if (!sessionStore) {
+        return {
+            ok: false,
+            reason: "session_store_unavailable",
+            message: "Plan breakdown session store is unavailable for this agent."
+        };
+    }
+    const session = sessionStore.getSessionSync(normalizedSessionId);
+    if (!session) {
+        return {
+            ok: false,
+            reason: "unknown_session_id",
+            message: `Unknown session ID: "${normalizedSessionId}"`
+        };
+    }
+    let planBreakdown;
+    try {
+        planBreakdown = exportSession(session);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "export_failed",
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+    const workstreamId = getTaskWorkstreamId(task);
+    if (!workstreamId) {
+        return {
+            ok: false,
+            reason: "missing_workstream_id",
+            message: "Plan breakdown task is missing canonical workstream identity."
+        };
+    }
+    try {
+        buildPacketPlanFromPlanBreakdown({
+            workstreamId,
+            planBreakdown,
+            generatedAt: new Date().toISOString()
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "packet_plan_invalid",
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+    return { ok: true, sessionId: normalizedSessionId, planBreakdown };
+}
+export function extractAndExportWaveAssessmentResult(task, stdout, sessionStore) {
+    if (task.kind !== "wave_plan_assessment") {
+        return {
+            ok: false,
+            reason: "not_wave_plan_assessment",
+            message: "Task is not a wave plan assessment."
+        };
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: "empty_stdout", message: "Agent output is empty." };
+    }
+    const candidate = extractTrailingJsonObject(trimmed);
+    if (!candidate) {
+        return { ok: false, reason: "missing_json", message: "No JSON object found in agent output." };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(candidate);
+    }
+    catch {
+        return { ok: false, reason: "malformed_json", message: "Malformed JSON object in agent output." };
+    }
+    if (!isRecord(parsed) || typeof parsed.sessionId !== "string" || parsed.sessionId.trim() === "") {
+        return {
+            ok: false,
+            reason: "missing_session_id",
+            message: 'Agent response must be a JSON object with a non-empty "sessionId" string.'
+        };
+    }
+    if (!sessionStore) {
+        return {
+            ok: false,
+            reason: "session_store_unavailable",
+            message: "Wave assessment session store is unavailable for this agent."
+        };
+    }
+    const checkpoint = task.context.waveAssessmentCheckpoint;
+    if (!checkpoint) {
+        return {
+            ok: false,
+            reason: "checkpoint_missing",
+            message: "Wave assessment task is missing checkpoint context."
+        };
+    }
+    const sessionId = parsed.sessionId.trim();
+    const session = sessionStore.getSessionSync(sessionId);
+    if (!session) {
+        return {
+            ok: false,
+            reason: "unknown_session_id",
+            message: `Unknown wave assessment session ID: "${sessionId}"`
+        };
+    }
+    let exported;
+    try {
+        exported = exportWaveAssessmentSession(session);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "export_failed",
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+    const mismatch = findWaveAssessmentCheckpointMismatch(exported, checkpoint.identity);
+    if (mismatch) {
+        return {
+            ok: false,
+            reason: "checkpoint_mismatch",
+            message: mismatch
+        };
+    }
+    return {
+        ok: true,
+        sessionId,
+        waveAssessment: {
+            id: `assessment:${checkpoint.id}`,
+            sessionId,
+            checkpoint,
+            decision: exported.decision,
+            summary: exported.summary,
+            findings: exported.findings,
+            status: "finalized",
+            createdAt: exported.timestamps.createdAt,
+            finalizedAt: exported.timestamps.finalizedAt,
+            updatedAt: exported.timestamps.finalizedAt
+        }
+    };
+}
+function findWaveAssessmentCheckpointMismatch(exported, identity) {
+    const checks = [
+        ["workstreamId", exported.workstreamId, identity.workstreamId],
+        ["waveId", exported.waveId, identity.waveId],
+        ["parentPrNumber", exported.parentPrNumber, identity.parentPrNumber],
+        ["parentHeadSha", exported.assessedParentHeadSha, identity.parentHeadSha],
+        ["planRevision", exported.currentPlanRevision, identity.planRevision],
+        ["originalPlanningSessionId", exported.originalPlanningSessionId, identity.originalPlanningSessionId]
+    ];
+    const mismatch = checks.find(([, left, right]) => left !== right);
+    if (mismatch) {
+        return `Wave assessment session ${mismatch[0]} "${mismatch[1]}" does not match checkpoint "${mismatch[2]}".`;
+    }
+    if (!arraysEqual(exported.planNodeIds, identity.planNodeIds)) {
+        return `Wave assessment session planNodeIds "${formatStringArray(exported.planNodeIds)}" do not match checkpoint "${formatStringArray(identity.planNodeIds)}".`;
+    }
+    return undefined;
+}
+function arraysEqual(left, right) {
+    if (!left || !right) {
+        return false;
+    }
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatStringArray(values) {
+    return values?.join(",") ?? "<missing>";
+}
+function getTaskWorkstreamId(task) {
+    return typeof task.workstreamId === "string" && task.workstreamId.trim()
+        ? task.workstreamId
+        : undefined;
+}
+export function extractTriageResult(task, stdout) {
+    if (task.kind !== "triage_issue") {
+        return undefined;
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    const candidate = extractTrailingJsonObject(trimmed);
+    if (!candidate) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed.decision !== "answer_only" && parsed.decision !== "start_implementation") {
+            return undefined;
+        }
+        return {
+            decision: parsed.decision,
+            ...(typeof parsed.summary === "string" ? { summary: parsed.summary } : {}),
+            ...(typeof parsed.reply === "string" ? { reply: parsed.reply } : {})
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractReviewResult(task, stdout) {
+    if (task.kind !== "review_pr") {
+        return undefined;
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    const candidate = extractTrailingJsonObject(trimmed);
+    if (!candidate) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(candidate);
+        // Handle new shape
+        if (typeof parsed.action === "string" && ["COMMENT", "APPROVE", "REQUEST_CHANGES"].includes(parsed.action)) {
+            const action = parsed.action;
+            const summary = typeof parsed.summary === "string" ? parsed.summary.trim() : "";
+            if (!summary) {
+                return undefined;
+            }
+            const inlineComments = Array.isArray(parsed.inlineComments)
+                ? parsed.inlineComments
+                    .map((comment) => {
+                    if (!isRecord(comment)) {
+                        return undefined;
+                    }
+                    const path = typeof comment.path === "string" ? comment.path.trim() : undefined;
+                    const line = typeof comment.line === "number" ? comment.line : undefined;
+                    const body = typeof comment.body === "string" ? comment.body.trim() : undefined;
+                    const side = comment.side === "LEFT" || comment.side === "RIGHT"
+                        ? comment.side
+                        : undefined;
+                    const startLine = typeof comment.startLine === "number" ? comment.startLine : undefined;
+                    const startSide = comment.startSide === "LEFT" || comment.startSide === "RIGHT"
+                        ? comment.startSide
+                        : undefined;
+                    return {
+                        ...(path ? { path } : {}),
+                        ...(line !== undefined ? { line } : {}),
+                        ...(body ? { body } : {}),
+                        ...(side ? { side } : {}),
+                        ...(startLine !== undefined ? { startLine } : {}),
+                        ...(startSide ? { startSide } : {})
+                    };
+                })
+                    .filter((c) => c !== undefined)
+                : undefined;
+            return {
+                action,
+                summary,
+                ...(inlineComments && inlineComments.length > 0 ? { inlineComments } : {})
+            };
+        }
+        // Handle legacy shape
+        if (parsed.decision === "approve" || parsed.decision === "request_changes") {
+            const action = parsed.decision === "approve" ? "APPROVE" : "REQUEST_CHANGES";
+            const summary = typeof parsed.summary === "string" ? parsed.summary.trim() : "Review submitted.";
+            const findings = Array.isArray(parsed.findings)
+                ? parsed.findings
+                    .map((finding) => {
+                    if (!isRecord(finding)) {
+                        return undefined;
+                    }
+                    const path = typeof finding.path === "string" ? finding.path.trim() : undefined;
+                    const line = typeof finding.line === "number" ? finding.line : undefined;
+                    const body = typeof finding.body === "string" ? finding.body.trim() : undefined;
+                    return {
+                        ...(path ? { path } : {}),
+                        ...(line !== undefined ? { line } : {}),
+                        ...(body ? { body } : {})
+                    };
+                })
+                    .filter((finding) => finding !== undefined)
+                : undefined;
+            return {
+                action,
+                summary,
+                decision: parsed.decision,
+                ...(findings && findings.length > 0
+                    ? {
+                        inlineComments: findings.map((f) => ({ ...f, side: "RIGHT" })),
+                        findings
+                    }
+                    : {})
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractPlanBreakdownResult(task, stdout, sessionStore) {
+    if (!requiresPlanBreakdownResult(task)) {
+        return undefined;
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    const candidate = extractTrailingJsonObject(trimmed);
+    if (!candidate) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(candidate);
+        // Support for sessionId format
+        if (isRecord(parsed) && typeof parsed.sessionId === "string" && sessionStore) {
+            const sessionId = parsed.sessionId.trim();
+            if (!sessionId) {
+                return undefined;
+            }
+            const session = sessionStore.getSessionSync(sessionId);
+            if (session) {
+                return exportSession(session);
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function requiresPlanBreakdownResult(task) {
+    return task.kind === "plan_breakdown" || task.kind === "wave_plan_replanning";
+}
+function requiredStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    if (value.some((v) => typeof v !== "string"))
+        return undefined;
+    return value;
+}
+function nonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function extractTrailingJsonObject(value) {
+    const end = value.lastIndexOf("}");
+    if (end === -1) {
+        return undefined;
+    }
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = end; index >= 0; index -= 1) {
+        const character = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (character === "}") {
+            depth += 1;
+            continue;
+        }
+        if (character === "{") {
+            depth -= 1;
+            if (depth === 0) {
+                return value.slice(index, end + 1);
+            }
+        }
+    }
+    return undefined;
+}
+export function buildExecutionId(taskId, startedAt) {
+    const safeTaskId = taskId.replace(/[^a-zA-Z0-9_-]+/g, "_");
+    const safeTimestamp = startedAt.replace(/[:.]/g, "-");
+    return `exec-${safeTaskId}-${safeTimestamp}`;
+}
+export function extractExitCode(error) {
+    if (typeof error === "object" && error !== null && "exitCode" in error && typeof error.exitCode === "number") {
+        return error.exitCode;
+    }
+    return 1;
+}
+export function extractStdout(error) {
+    if (typeof error === "object" && error !== null && "stdout" in error && typeof error.stdout === "string") {
+        return error.stdout;
+    }
+    return "";
+}
+export function extractStderr(error) {
+    if (typeof error === "object" && error !== null && "stderr" in error && typeof error.stderr === "string") {
+        return error.stderr;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+export { detectProviderLimit } from "./limit-detector.js";

package/dist/src/agents/failure-feedback.js

@@ -0,0 +1,132 @@
+import { Task } from "../tasks/task.js";
+export class GitHubTaskFailureNotifier {
+    gitHubGateway;
+    logger;
+    constructor(gitHubGateway, repos, logger) {
+        this.gitHubGateway = gitHubGateway;
+        this.logger = logger;
+        this.reposById = new Map(repos.map((repo) => [repo.id, repo]));
+    }
+    reposById;
+    async notifyFailure(task, execution, customMessage) {
+        const wrappedTask = Task.from(task);
+        const repo = this.reposById.get(task.repoId);
+        if (!repo) {
+            return undefined;
+        }
+        const targetNumber = resolveFailureThreadNumber(wrappedTask);
+        if (targetNumber === undefined) {
+            return undefined;
+        }
+        const body = customMessage ?? buildTechnicalFailureComment(task, execution);
+        const result = await this.gitHubGateway.postIssueComment({
+            owner: repo.owner,
+            name: repo.name,
+            issueNumber: targetNumber,
+            body
+        });
+        this.logger?.warn(JSON.stringify({
+            component: "task-failure-comment",
+            taskId: task.id,
+            taskKind: task.kind,
+            repoSlug: task.repoSlug,
+            threadNumber: targetNumber,
+            executionId: execution.id,
+            commentId: result.id,
+            commentUrl: result.url
+        }));
+        return String(result.id);
+    }
+}
+export function buildTechnicalFailureComment(task, execution) {
+    const detail = summarizeExecutionFailure(execution);
+    return [
+        "🤖 I tried to handle this orchestrator task, but it failed for a technical reason and did not complete.",
+        "",
+        `Task: \`${task.kind}\``,
+        `Execution: \`${execution.id}\``,
+        `Failure: ${detail}`,
+        "",
+        'If you want me to try again after the underlying issue is fixed, reply with `retry: <url-of-this-comment>`.'
+    ].join("\n");
+}
+function resolveFailureThreadNumber(task) {
+    const targetId = task.getOwningThreadId() ?? task.sourceId;
+    const match = targetId.match(/:(\d+)$/);
+    return match ? Number(match[1]) : undefined;
+}
+function summarizeExecutionFailure(execution) {
+    if (isTimeoutExecution(execution)) {
+        return formatTimeoutFailure(execution);
+    }
+    return summarizeExecutionError(execution.errorMessage);
+}
+function summarizeExecutionError(errorMessage) {
+    if (!errorMessage) {
+        return "Unknown technical failure.";
+    }
+    const trimmed = errorMessage.trim();
+    const firstNonEmptyLine = trimmed
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    const summary = firstNonEmptyLine ?? "Unknown technical failure.";
+    return summary.length > 240 ? `${summary.slice(0, 237)}...` : summary;
+}
+function isTimeoutExecution(execution) {
+    return execution.exitCode === 124 || /timed out/i.test(execution.errorMessage ?? "");
+}
+function formatTimeoutFailure(execution) {
+    const timeoutMs = execution.command.timeoutMs;
+    const timeoutLimit = timeoutMs > 0 ? `${timeoutMs}ms` : "the configured timeout";
+    return `Timed out after ${timeoutLimit} (exitCode: ${execution.exitCode}).`;
+}
+export function buildMcpBlockedFailureComment(task, execution, blockers) {
+    const blockerDetails = blockers
+        .map((b) => `- **${b.mcpHandle}**: ${b.safeReason}`)
+        .join("\n");
+    return [
+        "🤖 I tried to handle this orchestrator task, but it is blocked because a required MCP capability requires authorization, configuration, or setup.",
+        "",
+        `Task: \`${task.kind}\``,
+        `Execution: \`${execution.id}\``,
+        "",
+        "### Blocked Capabilities/MCPs",
+        blockerDetails,
+        "",
+        "Please resolve the MCP setup requirement. Once resolved, the task will be resumed automatically."
+    ].join("\n");
+}
+export function buildMcpBlockerNotificationComment(task, blocker, execution) {
+    return [
+        "🤖 **MCP capability blocked**",
+        "",
+        `The task \`${task.id}\` (\`${task.kind}\`) requires MCP-backed capability ${formatCapabilityNames(blocker.affectedCapabilityNames)}, but the \`${blocker.mcpHandle}\` MCP connection needs authorization or configuration.`,
+        ...(execution ? [`Execution: \`${execution.id}\``] : []),
+        "",
+        `Reason: ${sanitizeMcpCommentText(blocker.safeReason)}`,
+        "",
+        "Options:",
+        `1. Complete the required setup for \`${blocker.mcpHandle}\`, then rerun the orchestrator. The task will remain pending until the MCP becomes ready.`,
+        `2. Skip this MCP for this task only by replying exactly: \`mcp-skip: ${task.id} ${blocker.mcpHandle}\``,
+        "",
+        "If skipped, the agent will proceed without these tools and must find a workaround or report that the task cannot be completed correctly."
+    ].join("\n");
+}
+function formatCapabilityNames(names) {
+    if (names.length === 0) {
+        return "the configured capability";
+    }
+    if (names.length === 1) {
+        return `\`${names[0]}\``;
+    }
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+function sanitizeMcpCommentText(value) {
+    const text = value?.trim() || "MCP requires user authorization or configuration.";
+    return text
+        .replace(/https?:\/\/\S+/gi, "[redacted-url]")
+        .replace(/\b(token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+        .replace(/\bBearer\s+\S+/gi, "Bearer [redacted]")
+        .slice(0, 300);
+}

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

@@ -0,0 +1,96 @@
+import { writeJsonFileAtomic } from "../utils/json.js";
+export const DEFAULT_GEMINI_MODEL = "gemini-3-flash-preview";
+export const GEMINI_MODEL_FALLBACKS = [
+    DEFAULT_GEMINI_MODEL,
+    "gemini-3.1-pro-preview",
+    "gemini-3.1-flash-lite-preview"
+];
+const GEMINI_HEADLESS_PROMPT = "";
+/**
+ * Maps orchestrator permissions to Gemini approval modes.
+ * - read-only -> "plan"
+ * - workspace-write -> "yolo"
+ */
+export function mapPermissionToApprovalMode(permission) {
+    switch (permission) {
+        case "read-only":
+            return "plan";
+        case "workspace-write":
+            return "yolo";
+    }
+}
+/**
+ * Builds Gemini CLI arguments while sending the prompt over stdin.
+ */
+export function buildGeminiCliArgs(options) {
+    const args = [
+        "--model",
+        options.model ?? DEFAULT_GEMINI_MODEL,
+        "--approval-mode",
+        options.approvalMode,
+        "--output-format",
+        options.outputFormat ?? "text"
+    ];
+    if (options.resumeSessionId) {
+        args.push("--resume", options.resumeSessionId);
+    }
+    args.push("--prompt", GEMINI_HEADLESS_PROMPT);
+    return args;
+}
+export async function writeGeminiSystemSettings(settingsPath, options) {
+    const settings = options.mcp ? buildMcpSettings(options.mcp) : {};
+    await writeJsonFileAtomic(settingsPath, settings);
+}
+/**
+ * Removes auth-switching env vars and points Gemini at a run-scoped system settings file.
+ */
+export function getGeminiEnvOverrides(systemSettingsPath) {
+    const overrides = {
+        GEMINI_CLI_SYSTEM_SETTINGS_PATH: systemSettingsPath
+    };
+    // We explicitly want to reuse Google-account login and avoid drifting into API-key mode.
+    const toRemove = ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENAI_USE_VERTEXAI"];
+    for (const key of toRemove) {
+        overrides[key] = undefined;
+    }
+    return overrides;
+}
+/**
+ * Builds Gemini MCP system settings for the local broker.
+ * Inspection showed the broker uses streamable HTTP, so we use httpUrl.
+ */
+function buildMcpSettings(mcp) {
+    return {
+        mcp: {
+            allowed: [mcp.serverName]
+        },
+        mcpServers: {
+            [mcp.serverName]: {
+                httpUrl: mcp.serverUrl,
+                includeTools: mcp.toolAllowList
+            }
+        }
+    };
+}
+export function buildGlobalGeminiLaunchInstructions(input) {
+    return [
+        "# Global Gemini Instructions",
+        "",
+        "These instructions apply across repositories for this orchestrated run.",
+        "",
+        "## MCP Server",
+        `Use the local MCP server \`${input.mcp.serverName}\` for managed GitHub operations.`,
+        "- Invoke broker tools instead of using `gh` directly.",
+        "",
+        "Enabled broker tools for this run:",
+        ...input.mcp.toolAllowList.map((tool) => `- \`${tool}\``),
+        "",
+        "Any GitHub-authored message you post must begin with `🤖`."
+    ].join("\n");
+}
+export function prependGlobalGeminiLaunchInstructions(promptText, options) {
+    if (!options.mcp) {
+        return promptText;
+    }
+    return `${buildGlobalGeminiLaunchInstructions({ mcp: options.mcp })}\n\n${promptText}`;
+}