@backburner/cli 0.1.0

package/dist/src/agents/provider-sessions.js

@@ -0,0 +1,105 @@
+import { createHash, randomUUID } from "node:crypto";
+import { workflowRegistry } from "../workflows/registry.js";
+import { roleForTask } from "./selection.js";
+export function resolveProviderSessionScope(task, agent) {
+    if (!task.workstreamId) {
+        throw new Error(`Task ${task.id} has no workstreamId; provider session scope requires a workstream identity.`);
+    }
+    const { localRepoPath, branchName } = task.context;
+    if (!localRepoPath || !branchName) {
+        throw new Error(`Task ${task.id} is missing localRepoPath or branchName; provider session scope cannot be resolved.`);
+    }
+    const definition = workflowRegistry.getDefinition(task.kind);
+    if (agent.modelClass !== definition.modelClass) {
+        throw new Error(`Agent model class "${agent.modelClass}" does not match required model class "${definition.modelClass}" for task "${task.kind}".`);
+    }
+    return {
+        repoKey: task.repoSlug,
+        workstreamId: task.workstreamId,
+        job: roleForTask(task),
+        modelClass: agent.modelClass,
+        configuredAgentId: agent.id,
+        provider: agent.provider,
+        localRepoPath,
+        branchName
+    };
+}
+export function getProviderSessionRecordId(scope) {
+    const components = [
+        scope.repoKey,
+        scope.workstreamId,
+        scope.job,
+        scope.modelClass,
+        scope.provider,
+        scope.configuredAgentId,
+        scope.localRepoPath,
+        scope.branchName
+    ];
+    const data = components.join("|");
+    return createHash("sha256").update(data).digest("hex");
+}
+export function evaluateProviderSessionDecision(input) {
+    if (input.capability === "unsupported") {
+        if (input.existingRecord?.providerSessionId || input.existingRecord?.providerSessionName) {
+            throw new Error("Invalid state: unsupported capability record cannot carry provider identity.");
+        }
+        return { mode: "fallback", reason: "unsupported" };
+    }
+    if (input.capability === "unverified") {
+        if (input.existingRecord?.providerSessionId || input.existingRecord?.providerSessionName) {
+            throw new Error("Invalid state: unverified capability record cannot carry provider identity.");
+        }
+        return { mode: "fallback", reason: "unverified" };
+    }
+    if (!input.nativeResumeEnabled) {
+        return { mode: "fallback", reason: "native_resume_not_enabled" };
+    }
+    const getNewSessionDecision = () => {
+        const uuid = randomUUID();
+        const displayName = `backburner:${input.requestedScope.repoKey}:${input.taskKind}:${input.requestedScope.workstreamId}`;
+        return {
+            mode: "new_session",
+            providerSessionId: uuid,
+            providerSessionName: displayName
+        };
+    };
+    if (!input.existingRecord) {
+        if (input.requestedScope.provider === "claude") {
+            return getNewSessionDecision();
+        }
+        return { mode: "fallback", reason: "no_session_record" };
+    }
+    // Exact scope comparison
+    const sE = input.existingRecord.scope;
+    const sR = input.requestedScope;
+    const match = sE.repoKey === sR.repoKey &&
+        sE.workstreamId === sR.workstreamId &&
+        sE.job === sR.job &&
+        sE.modelClass === sR.modelClass &&
+        sE.configuredAgentId === sR.configuredAgentId &&
+        sE.provider === sR.provider &&
+        sE.localRepoPath === sR.localRepoPath &&
+        sE.branchName === sR.branchName;
+    if (!match) {
+        return { mode: "fallback", reason: "scope_mismatch" };
+    }
+    if (input.existingRecord.capability === "unsupported") {
+        return { mode: "fallback", reason: "unsupported" };
+    }
+    if (input.existingRecord.capability === "unverified") {
+        return { mode: "fallback", reason: "unverified" };
+    }
+    if (input.existingRecord.status === "closed") {
+        if (input.requestedScope.provider === "claude") {
+            return getNewSessionDecision();
+        }
+        return { mode: "fallback", reason: "no_session_record" };
+    }
+    if (input.existingRecord.status === "stale") {
+        if (input.requestedScope.provider === "claude") {
+            return getNewSessionDecision();
+        }
+        return { mode: "fallback", reason: "no_session_record" };
+    }
+    return { mode: "native_resume_candidate", record: input.existingRecord };
+}

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

@@ -0,0 +1,255 @@
+import { Task } from "../tasks/task.js";
+export class GitHubPullRequestReviewPublisher {
+    gitHubGateway;
+    logger;
+    reposById;
+    constructor(gitHubGateway, repos, logger) {
+        this.gitHubGateway = gitHubGateway;
+        this.logger = logger;
+        this.reposById = new Map(repos.map((repo) => [repo.id, repo]));
+    }
+    async publishReview(task, execution) {
+        if (task.kind !== "review_pr" || execution.taskStatus !== "completed") {
+            return;
+        }
+        const review = execution.result?.review;
+        if (!review) {
+            this.logger?.warn(`Completed review task ${task.id} did not return a structured review result.`);
+            return;
+        }
+        const repo = this.reposById.get(task.repoId);
+        const pullRequestNumber = Task.from(task).owningPullRequestNumber();
+        if (!repo || pullRequestNumber === undefined) {
+            this.logger?.warn(`Could not resolve repo or pull request number for review task ${task.id}.`);
+            return;
+        }
+        try {
+            const pr = await this.gitHubGateway.getPullRequest(repo.owner, repo.name, pullRequestNumber);
+            const changedFiles = await this.gitHubGateway.listPullRequestChangedFiles(repo.owner, repo.name, pullRequestNumber);
+            const headSha = pr.headSha;
+            const validation = this.validateReview(review, changedFiles);
+            if (!validation) {
+                this.logger?.warn(`Review task ${task.id} returned an invalid review result (missing summary or action).`);
+                return;
+            }
+            const reviewBody = buildReviewBody(validation);
+            try {
+                await this.gitHubGateway.submitPullRequestReview({
+                    owner: repo.owner,
+                    name: repo.name,
+                    pullRequestNumber,
+                    event: "COMMENT",
+                    body: reviewBody,
+                    ...(headSha ? { commitId: headSha } : {}),
+                    comments: validation.validInlineComments
+                });
+                this.logger?.info(`Published PR review for ${repo.owner}/${repo.name}#${pullRequestNumber}: ` +
+                    `${validation.validInlineComments.length} inline, ${validation.movedToSummary.length} moved to summary.`);
+            }
+            catch (error) {
+                if (validation.validInlineComments.length > 0) {
+                    this.logger?.warn(`Failed to submit PR review with inline comments, retrying summary-only. Error: ${error instanceof Error ? error.message : String(error)}`);
+                    const fallbackValidation = {
+                        ...validation,
+                        validInlineComments: [],
+                        movedToSummary: [
+                            ...validation.movedToSummary,
+                            ...validation.validInlineComments.map((c) => ({
+                                comment: c,
+                                reason: "GitHub rejected inline placement"
+                            }))
+                        ]
+                    };
+                    const fallbackBody = buildReviewBody(fallbackValidation);
+                    try {
+                        await this.gitHubGateway.submitPullRequestReview({
+                            owner: repo.owner,
+                            name: repo.name,
+                            pullRequestNumber,
+                            event: "COMMENT",
+                            body: fallbackBody,
+                            ...(headSha ? { commitId: headSha } : {})
+                        });
+                        this.logger?.info(`Published fallback PR review for ${repo.owner}/${repo.name}#${pullRequestNumber} with all comments moved to summary.`);
+                    }
+                    catch (fallbackError) {
+                        this.logger?.warn(`Failed to submit summary-only PR review, posting a PR thread comment instead. Error: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+                        await this.gitHubGateway.postIssueComment({
+                            owner: repo.owner,
+                            name: repo.name,
+                            issueNumber: pullRequestNumber,
+                            body: fallbackBody
+                        });
+                    }
+                }
+                else {
+                    await this.gitHubGateway.postIssueComment({
+                        owner: repo.owner,
+                        name: repo.name,
+                        issueNumber: pullRequestNumber,
+                        body: reviewBody
+                    });
+                }
+            }
+        }
+        catch (error) {
+            this.logger?.error?.(`Failed to publish PR review for ${repo.owner}/${repo.name}#${pullRequestNumber}: ${error instanceof Error ? error.message : String(error)}`);
+            // Let it propagate so safelyPublishReview can handle it (currently it swallows it)
+            throw error;
+        }
+    }
+    validateReview(review, changedFiles) {
+        const summary = review.summary?.trim();
+        if (!summary || !review.action) {
+            return undefined;
+        }
+        const validInlineComments = [];
+        const movedToSummary = [];
+        const changedFileByPath = new Map(changedFiles.map((f) => [f.path, f]));
+        if (review.inlineComments) {
+            for (const comment of review.inlineComments) {
+                const shapeResult = validateInlineComment(comment);
+                if (!shapeResult.isValid) {
+                    movedToSummary.push({ comment, reason: shapeResult.reason });
+                    continue;
+                }
+                const normalized = shapeResult.normalized;
+                const path = normalized.path;
+                if (path === undefined) {
+                    continue;
+                }
+                const anchorResult = validateInlineCommentAnchor(normalized, changedFileByPath.get(path));
+                if (anchorResult.isValid) {
+                    validInlineComments.push(normalized);
+                }
+                else {
+                    movedToSummary.push({ comment: normalized, reason: anchorResult.reason });
+                }
+            }
+        }
+        return {
+            validInlineComments,
+            movedToSummary,
+            normalizedReview: {
+                action: review.action,
+                summary
+            }
+        };
+    }
+}
+function validateInlineCommentAnchor(comment, changedFile) {
+    if (!changedFile) {
+        return { isValid: false, reason: "file is not in the PR diff" };
+    }
+    const { line, side, startLine, startSide } = comment;
+    if (line === undefined) {
+        return { isValid: false, reason: "missing line number" };
+    }
+    // Check line/side
+    const targetLines = side === "LEFT" ? changedFile.leftCommentableLines : changedFile.rightCommentableLines;
+    if (!targetLines.includes(line)) {
+        return { isValid: false, reason: `line ${line} on ${side} side is not available in the PR diff` };
+    }
+    // Check range if present
+    if (startLine !== undefined) {
+        const effectiveStartSide = startSide || side;
+        if (effectiveStartSide === side) {
+            // Single-side range: require every line in the range to be commentable
+            for (let l = startLine; l <= line; l++) {
+                if (!targetLines.includes(l)) {
+                    return {
+                        isValid: false,
+                        reason: `line ${l} in range ${startLine}-${line} on ${side} side is not available in the PR diff`
+                    };
+                }
+            }
+        }
+        else {
+            // Cross-side range: conservative MVP rule
+            const startTargetLines = effectiveStartSide === "LEFT" ? changedFile.leftCommentableLines : changedFile.rightCommentableLines;
+            if (!startTargetLines.includes(startLine)) {
+                return {
+                    isValid: false,
+                    reason: `start line ${startLine} on ${effectiveStartSide} side is not available in the PR diff`
+                };
+            }
+        }
+    }
+    return { isValid: true };
+}
+function validateInlineComment(comment) {
+    const path = comment.path?.trim();
+    const body = comment.body?.trim();
+    const line = comment.line;
+    if (!path)
+        return { isValid: false, reason: "missing path" };
+    if (!body)
+        return { isValid: false, reason: "missing body" };
+    if (line === undefined || !Number.isInteger(line) || line < 1) {
+        return { isValid: false, reason: "invalid line number" };
+    }
+    const side = comment.side === "LEFT" || comment.side === "RIGHT" ? comment.side : "RIGHT";
+    let startLine = comment.startLine;
+    let startSide = comment.startSide;
+    if (startLine !== undefined) {
+        if (!Number.isInteger(startLine) || startLine < 1) {
+            return { isValid: false, reason: "invalid startLine" };
+        }
+        if (startLine > line) {
+            return { isValid: false, reason: "startLine must be <= line" };
+        }
+        if (!startSide) {
+            startSide = side;
+        }
+        else if (startSide !== "LEFT" && startSide !== "RIGHT") {
+            return { isValid: false, reason: "invalid startSide" };
+        }
+    }
+    return {
+        isValid: true,
+        normalized: {
+            path,
+            line,
+            body,
+            side,
+            ...(startLine !== undefined ? { startLine } : {}),
+            ...(startSide !== undefined ? { startSide } : {})
+        }
+    };
+}
+function buildReviewBody(validation) {
+    const { normalizedReview, movedToSummary, validInlineComments } = validation;
+    const lines = [
+        withBotPrefix(`Review result: ${formatReviewAction(normalizedReview.action)}`),
+        "",
+        normalizedReview.summary
+    ];
+    if (movedToSummary.length > 0) {
+        lines.push("");
+        lines.push(`Inline comment publication: ${validInlineComments.length} posted inline, ${movedToSummary.length} moved into this summary.`);
+        lines.push("");
+        lines.push("Moved from inline comments:");
+        for (const { comment, reason } of movedToSummary) {
+            const location = `${comment.path}:${comment.line}`;
+            lines.push(`- ${location}: ${comment.body} (Reason: ${reason})`);
+        }
+    }
+    return lines.join("\n").trim();
+}
+function formatReviewAction(action) {
+    switch (action) {
+        case "APPROVE":
+            return "approved";
+        case "REQUEST_CHANGES":
+            return "changes requested";
+        case "COMMENT":
+            return "comment";
+    }
+}
+function withBotPrefix(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("🤖")) {
+        return trimmed;
+    }
+    return `🤖 ${trimmed}`;
+}

package/dist/src/agents/selection.js

@@ -0,0 +1,113 @@
+import { workflowRegistry } from "../workflows/registry.js";
+export class NoProviderAvailableError extends Error {
+    role;
+    modelClass;
+    limitedProviders;
+    constructor(role, modelClass, limitedProviders, message) {
+        super(message);
+        this.role = role;
+        this.modelClass = modelClass;
+        this.limitedProviders = limitedProviders;
+        this.name = "NoProviderAvailableError";
+    }
+}
+export function selectAgentForTask(task, agents, providerLimits, runtimeCompatibility) {
+    const definition = workflowRegistry.getDefinition(task.kind);
+    const requiredRole = resolveTaskRole(task, definition.role);
+    const requiredModelClass = definition.modelClass;
+    const candidates = agents.filter((agent) => agent.enabled &&
+        agent.roles.includes(requiredRole) &&
+        agent.modelClass === requiredModelClass);
+    if (candidates.length === 0) {
+        throw new Error(`No enabled agent configured for task ${task.id} with role "${requiredRole}" and modelClass "${requiredModelClass}"`);
+    }
+    const runtimeCompatibleCandidates = candidates.filter((agent) => providerRuntimeIsCompatible(agent.provider, runtimeCompatibility));
+    if (runtimeCompatibleCandidates.length === 0) {
+        if (runtimeCompatibility?.replacementForProvider) {
+            throw new NoProviderAvailableError(requiredRole, requiredModelClass, [runtimeCompatibility.replacementForProvider], `No runtime-compatible replacement provider for role "${requiredRole}" and modelClass "${requiredModelClass}" after ${runtimeCompatibility.replacementForProvider} was limited`);
+        }
+        throw new Error(`No runtime-compatible agent configured for task ${task.id} with role "${requiredRole}" and modelClass "${requiredModelClass}"`);
+    }
+    const limitedProviders = new Set();
+    const limits = providerLimits ?? [];
+    for (const limit of limits) {
+        if (limit.status === "limited") {
+            limitedProviders.add(limit.provider);
+        }
+    }
+    const availableCandidates = runtimeCompatibleCandidates.filter((agent) => !limitedProviders.has(agent.provider));
+    if (availableCandidates.length === 0) {
+        const candidateProviders = Array.from(new Set(runtimeCompatibleCandidates.map((a) => a.provider)));
+        throw new NoProviderAvailableError(requiredRole, requiredModelClass, candidateProviders, `No available provider for role "${requiredRole}" and modelClass "${requiredModelClass}" (all matching providers: ${candidateProviders.join(", ")} are currently limited)`);
+    }
+    const index = Math.floor(Math.random() * availableCandidates.length);
+    return availableCandidates[index];
+}
+export function roleForTask(task) {
+    return resolveTaskRole(task, workflowRegistry.getDefinition(task.kind).role);
+}
+function resolveTaskRole(task, defaultRole) {
+    if (task.kind === "respond_issue_comment" &&
+        (task.workflowPhase === "product_discovery" || task.workflowPhase === "product_specification")) {
+        return "product";
+    }
+    return defaultRole;
+}
+function providerRuntimeIsCompatible(candidateProvider, compatibility) {
+    const sourceProvider = compatibility?.replacementForProvider;
+    if (!sourceProvider || candidateProvider === sourceProvider) {
+        return true;
+    }
+    if (!providerAllowListCoversRequiredTools(compatibility.providerBrokerToolAllowLists, sourceProvider, candidateProvider)) {
+        return false;
+    }
+    return providerCapabilitiesCoverRequiredTools(compatibility.capabilitiesByProvider, sourceProvider, candidateProvider);
+}
+function providerAllowListCoversRequiredTools(allowLists, sourceProvider, candidateProvider) {
+    if (!allowLists) {
+        return true;
+    }
+    const requiredTools = allowLists.get(sourceProvider);
+    if (!requiredTools || requiredTools.length === 0) {
+        return true;
+    }
+    const candidateTools = allowLists.get(candidateProvider);
+    if (!candidateTools) {
+        return false;
+    }
+    return requiredTools.every((requiredTool) => allowListAllowsRequiredTool(candidateTools, requiredTool));
+}
+function allowListAllowsRequiredTool(candidateTools, requiredTool) {
+    if (candidateTools.includes("*") || candidateTools.includes(requiredTool)) {
+        return true;
+    }
+    if (requiredTool.endsWith(".*")) {
+        return candidateTools.includes(requiredTool);
+    }
+    return candidateTools.some((candidateTool) => candidateTool.endsWith(".*") && requiredTool.startsWith(candidateTool.slice(0, -1)));
+}
+function providerCapabilitiesCoverRequiredTools(capabilitiesByProvider, sourceProvider, candidateProvider) {
+    if (!capabilitiesByProvider) {
+        return true;
+    }
+    const sourceCapabilities = capabilitiesByProvider.get(sourceProvider);
+    if (!sourceCapabilities) {
+        return true;
+    }
+    const requiredTools = visibleCapabilityTools(sourceCapabilities);
+    if (requiredTools.size === 0) {
+        return true;
+    }
+    const candidateCapabilities = capabilitiesByProvider.get(candidateProvider);
+    if (!candidateCapabilities) {
+        return false;
+    }
+    const candidateTools = visibleCapabilityTools(candidateCapabilities);
+    return [...requiredTools].every((tool) => candidateTools.has(tool));
+}
+function visibleCapabilityTools(capabilities) {
+    return new Set([
+        ...capabilities.sensors.flatMap((sensor) => sensor.tools),
+        ...capabilities.controllers.flatMap((controller) => controller.tools)
+    ]);
+}