@backburner/cli 0.1.0

package/dist/src/mcps/smithery.js

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { SmitherySdkClient } from "./smithery-client.js";
+export function deriveSmitheryConnectionId(handle, smitheryId) {
+    const hash = createHash("sha256")
+        .update(`${handle}|${smitheryId}`)
+        .digest("hex")
+        .slice(0, 8);
+    const sanitizedHandle = handle.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 20);
+    return `backburner-${sanitizedHandle}-${hash}`;
+}
+function isOwnedConnection(connection, handle, smitheryId, localConnectionIdentity) {
+    const meta = connection.metadata;
+    return (meta?.backburner === "backburner" &&
+        meta.backburnerHandle === handle &&
+        meta.providerMcpId === smitheryId &&
+        meta.localConnectionIdentity === localConnectionIdentity);
+}
+export class SmitheryMcpResolver {
+    client;
+    runtimeConfig;
+    constructor(client, runtimeConfig) {
+        this.client = client;
+        this.runtimeConfig = runtimeConfig;
+    }
+    async resolveDependencies(dependencies, previous = []) {
+        const previousByHandle = new Map(previous.map((r) => [r.handle, r]));
+        return Promise.all(dependencies.map((dependency) => this.resolveOne(dependency, previousByHandle.get(dependency.handle))));
+    }
+    async resolveOne(dependency, prev) {
+        const result = {
+            handle: dependency.handle,
+            provider: "smithery",
+            providerMcpId: dependency.smitheryId,
+            status: "error", // Default to error
+        };
+        if (!this.runtimeConfig.apiKey) {
+            result.status = "error";
+            result.message = "Missing Smithery API key. Set SMITHERY_API_KEY to resolve Smithery MCP dependencies.";
+            return result;
+        }
+        if (!this.runtimeConfig.namespace) {
+            result.status = "error";
+            result.message = "Missing Smithery namespace. Set SMITHERY_NAMESPACE to resolve Smithery MCP dependencies.";
+            return result;
+        }
+        try {
+            // 1. Verify server exists
+            const lookup = await this.client.getServerByExactId(dependency.smitheryId);
+            if (lookup.status === "not_found") {
+                result.status = "resolution_failed";
+                result.message = lookup.message || `Smithery server "${dependency.smitheryId}" not found.`;
+                return result;
+            }
+            if (lookup.status === "error") {
+                result.status = "error";
+                result.message = lookup.message || "Unknown Smithery error during server lookup.";
+                return result;
+            }
+            if (lookup.status === "action_required") {
+                result.status = "action_required";
+                result.actionRequired = lookup.actionRequired;
+                result.message = lookup.message;
+                return result;
+            }
+            result.discovered = lookup.server;
+            if (!lookup.connection) {
+                result.status = "resolved";
+                result.message = "Server lookup succeeded but no usable hosted HTTP connection was found.";
+                return result;
+            }
+            // 2. Manage connection
+            const namespace = this.runtimeConfig.namespace;
+            const localConnectionIdentity = deriveSmitheryConnectionId(dependency.handle, dependency.smitheryId);
+            const candidateIds = [];
+            if (prev?.connection?.localConnectionIdentity === localConnectionIdentity && prev.connection.providerConnectionId) {
+                candidateIds.push(prev.connection.providerConnectionId);
+            }
+            if (!candidateIds.includes(localConnectionIdentity)) {
+                candidateIds.push(localConnectionIdentity);
+            }
+            let connection;
+            for (const candidateId of candidateIds) {
+                const candidate = await this.client.getConnection(namespace, candidateId);
+                if (candidate.status === "not_found") {
+                    continue;
+                }
+                if (candidate.status === "connected" ||
+                    candidate.status === "auth_required" ||
+                    candidate.status === "input_required" ||
+                    candidate.status === "disconnected") {
+                    if (!isOwnedConnection(candidate, dependency.handle, dependency.smitheryId, localConnectionIdentity)) {
+                        continue;
+                    }
+                }
+                connection = candidate;
+                break;
+            }
+            if (!connection || connection.status === "disconnected") {
+                connection = await this.client.createOrUpdateConnection({
+                    namespace,
+                    connectionId: localConnectionIdentity,
+                    smitheryId: dependency.smitheryId,
+                    handle: dependency.handle,
+                    transport: lookup.connection?.transport,
+                    mcpUrl: lookup.connection?.mcpUrl,
+                });
+            }
+            if (connection.status === "connected" &&
+                !isOwnedConnection(connection, dependency.handle, dependency.smitheryId, localConnectionIdentity)) {
+                result.status = "error";
+                result.message = `Smithery connection "${localConnectionIdentity}" is connected but its metadata does not match Backburner handle "${dependency.handle}" and Smithery id "${dependency.smitheryId}"; refusing to mark ready.`;
+                return result;
+            }
+            result.connection = {
+                localConnectionIdentity,
+                readiness: connection.status,
+                ...(connection.connectionId ? { providerConnectionId: connection.connectionId } : {}),
+                namespace: connection.namespace || namespace,
+                ...(connection.transport ? { transport: connection.transport } : {}),
+                ...(connection.mcpUrl ? { mcpUrl: connection.mcpUrl } : {}),
+                ...(connection.message ? { message: connection.message } : {}),
+            };
+            switch (connection.status) {
+                case "connected":
+                    result.status = "ready";
+                    result.message = connection.message || `Smithery connection is ready for "${dependency.handle}".`;
+                    break;
+                case "auth_required":
+                case "input_required":
+                    result.status = "action_required";
+                    result.actionRequired = {
+                        reason: connection.status === "auth_required" ? "auth_required" : "input_required",
+                        message: connection.message || `Smithery connection for "${dependency.handle}" requires user action.`,
+                        ...(connection.setupUrl ? { url: connection.setupUrl } : {}),
+                        ...(connection.fields ? { fields: connection.fields } : {}),
+                    };
+                    break;
+                case "disconnected":
+                    result.status = "resolved";
+                    result.message = connection.message || `Smithery connection for "${dependency.handle}" exists but is disconnected.`;
+                    break;
+                case "error":
+                    result.status = "error";
+                    result.message = connection.message || "Unknown Smithery connection error.";
+                    break;
+                default:
+                    result.status = "error";
+                    result.message = `Unexpected Smithery connection status: ${connection.status}`;
+            }
+        }
+        catch (err) {
+            result.status = "error";
+            result.message = err instanceof Error ? err.message : String(err);
+        }
+        return result;
+    }
+}
+export function createSmitheryMcpResolverFromEnv(env = process.env) {
+    const apiKey = env.SMITHERY_API_KEY;
+    const namespace = env.SMITHERY_NAMESPACE;
+    const config = { apiKey, namespace };
+    const client = new SmitherySdkClient(config);
+    return new SmitheryMcpResolver(client, config);
+}

package/dist/src/mcps/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/memory/json-store.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { readJsonFileIfExists, writeJsonFileAtomic } from "../utils/json.js";
+export class JsonJobMemoryStore {
+    filePath;
+    generateId;
+    now;
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.generateId = options.generateId ?? (() => randomUUID());
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    async add(scope, bankId, taskId, input) {
+        const state = await this.load();
+        const now = this.now();
+        const entry = {
+            id: this.generateId(),
+            bankId,
+            scope,
+            type: input.type,
+            text: input.text,
+            source: {
+                taskId,
+                ...input.source
+            },
+            createdAt: now,
+            updatedAt: now
+        };
+        if (input.confidence !== undefined) {
+            entry.confidence = input.confidence;
+        }
+        state.entries.push(entry);
+        // Sort entries deterministically by bankId and createdAt
+        state.entries.sort((a, b) => {
+            if (a.bankId !== b.bankId) {
+                return a.bankId.localeCompare(b.bankId);
+            }
+            return a.createdAt.localeCompare(b.createdAt);
+        });
+        await this.save(state);
+        return entry;
+    }
+    async search(bankId, input) {
+        const state = await this.load();
+        const query = input.query?.toLowerCase();
+        const results = state.entries.filter((entry) => {
+            if (entry.bankId !== bankId) {
+                return false;
+            }
+            if (input.type && entry.type !== input.type) {
+                return false;
+            }
+            if (query && !entry.text.toLowerCase().includes(query)) {
+                return false;
+            }
+            return true;
+        });
+        // Sort by recency (newest first) for search results
+        results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        if (input.limit !== undefined) {
+            return results.slice(0, input.limit);
+        }
+        return results;
+    }
+    async load() {
+        const data = await readJsonFileIfExists(this.filePath);
+        return data ?? { entries: [] };
+    }
+    async save(state) {
+        await writeJsonFileAtomic(this.filePath, state);
+    }
+}

package/dist/src/memory/prompt.js

@@ -0,0 +1,16 @@
+/**
+ * Builds a compact memory prelude for inclusion in an agent prompt.
+ * Returns an empty string if there are no entries.
+ */
+export function buildMemoryPrelude(entries) {
+    if (entries.length === 0) {
+        return "";
+    }
+    const lines = [
+        "Durable memory background for this scoped job:",
+        ...entries.map((entry) => `- [${entry.type}] ${entry.text}`),
+        "",
+        "Memory is prior background, not current truth. Current GitHub and repository state are authoritative; verify conflicts before acting."
+    ];
+    return lines.join("\n");
+}

package/dist/src/memory/scope.js

@@ -0,0 +1,31 @@
+import { workflowRegistry } from "../workflows/registry.js";
+import { roleForTask } from "../agents/selection.js";
+/**
+ * Resolves the memory scope for a given task and agent configuration.
+ * Fails if workstreamId is missing.
+ */
+export function resolveJobMemoryScope(task, agentConfig) {
+    if (!task.workstreamId) {
+        throw new Error(`Memory access requires a workstreamId for task ${task.id}`);
+    }
+    const definition = workflowRegistry.getDefinition(task.kind);
+    const job = roleForTask(task);
+    const modelClass = agentConfig.modelClass;
+    // Assert that the selected agent's model class matches the workflow definition
+    // This is a safety check from the plan.
+    if (modelClass !== definition.modelClass) {
+        throw new Error(`Model class mismatch for task ${task.id}: agent model class is ${modelClass}, but workflow definition requires ${definition.modelClass}`);
+    }
+    return {
+        repoKey: task.repoSlug,
+        workstreamId: task.workstreamId,
+        job,
+        modelClass
+    };
+}
+/**
+ * Generates the canonical bank ID for a given scope.
+ */
+export function getJobMemoryBankId(scope) {
+    return `backburner:repo:${scope.repoKey}:workstream:${scope.workstreamId}:job:${scope.job}:model:${scope.modelClass}`;
+}

package/dist/src/memory/store.js

@@ -0,0 +1 @@
+export {};

package/dist/src/memory/tool-service.js

@@ -0,0 +1,142 @@
+import { JOB_MEMORY_ENTRY_TYPES } from "./types.js";
+export class JobMemoryToolService {
+    store;
+    logger;
+    activeBinding;
+    constructor(store, logger) {
+        this.store = store;
+        this.logger = logger;
+    }
+    /**
+     * Binds the service to a specific job scope and task for the duration of a dispatch.
+     */
+    bind(scope, bankId, taskId) {
+        this.activeBinding = { scope, bankId, taskId };
+    }
+    /**
+     * Clears the current job scope binding.
+     */
+    unbind() {
+        this.activeBinding = undefined;
+    }
+    listTools() {
+        return [
+            {
+                name: "memory_add",
+                title: "Add to Job Memory",
+                description: "Adds a concise, typed fact, decision, or risk to the current scoped job memory. Do not store secrets or raw logs.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: {
+                            type: "string",
+                            enum: [...JOB_MEMORY_ENTRY_TYPES]
+                        },
+                        text: { type: "string", minLength: 1, maxLength: 2000 },
+                        confidence: { type: "string", enum: ["low", "medium", "high"] },
+                        source: {
+                            type: "object",
+                            properties: {
+                                commitSha: { type: "string" },
+                                filePath: { type: "string" }
+                            }
+                        }
+                    },
+                    required: ["type", "text"]
+                }
+            },
+            {
+                name: "memory_search",
+                title: "Search Job Memory",
+                description: "Searches for relevant background facts, decisions, or risks in the current scoped job memory.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        type: {
+                            type: "string",
+                            enum: [...JOB_MEMORY_ENTRY_TYPES]
+                        },
+                        limit: { type: "number", minimum: 1, maximum: 50 }
+                    }
+                }
+            }
+        ];
+    }
+    async callTool(name, rawArguments) {
+        const timestamp = new Date().toISOString();
+        if (!this.activeBinding) {
+            this.logger.warn(`[${timestamp}] [job-memory-tool-service] DENIED call=${name} status=unbound`);
+            return {
+                ok: false,
+                tool: name,
+                error: {
+                    code: "memory_scope_unbound",
+                    message: "Memory tools are only available when a task is actively being dispatched."
+                }
+            };
+        }
+        const { scope, bankId, taskId } = this.activeBinding;
+        try {
+            if (name === "memory_add") {
+                const input = rawArguments;
+                // Runtime validation
+                if (!input.type || !JOB_MEMORY_ENTRY_TYPES.includes(input.type)) {
+                    throw new Error(`Invalid memory type: ${input.type}. Must be one of: ${JOB_MEMORY_ENTRY_TYPES.join(", ")}`);
+                }
+                if (!input.text || input.text.length === 0) {
+                    throw new Error("Memory text is required.");
+                }
+                if (input.text.length > 2000) {
+                    throw new Error("Memory text exceeds maximum length of 2000 characters.");
+                }
+                const entry = await this.store.add(scope, bankId, taskId, input);
+                this.logger.info(`[${timestamp}] [job-memory-tool-service] call=memory_add bank=${bankId} task=${taskId} status=success entryId=${entry.id}`);
+                return {
+                    ok: true,
+                    tool: name,
+                    result: { entryId: entry.id },
+                    summary: `Added ${input.type} memory entry: ${entry.id}`
+                };
+            }
+            if (name === "memory_search") {
+                const input = rawArguments;
+                // Runtime validation for type if provided
+                if (input.type && !JOB_MEMORY_ENTRY_TYPES.includes(input.type)) {
+                    throw new Error(`Invalid search type: ${input.type}. Must be one of: ${JOB_MEMORY_ENTRY_TYPES.join(", ")}`);
+                }
+                const entries = await this.store.search(bankId, input);
+                this.logger.info(`[${timestamp}] [job-memory-tool-service] call=memory_search bank=${bankId} task=${taskId} status=success results=${entries.length}`);
+                return {
+                    ok: true,
+                    tool: name,
+                    result: {
+                        entries,
+                        note: "Memory is prior background, not current truth. Current GitHub and repository state are authoritative."
+                    },
+                    summary: `Found ${entries.length} memory entries in this bank.`
+                };
+            }
+            return {
+                ok: false,
+                tool: name,
+                error: {
+                    code: "tool_not_found",
+                    message: `Tool "${name}" not found in memory service.`
+                }
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`[${timestamp}] [job-memory-tool-service] FAILED call=${name} bank=${bankId} task=${taskId} error=${message}`);
+            return {
+                ok: false,
+                tool: name,
+                error: {
+                    code: "memory_error",
+                    message
+                }
+            };
+        }
+    }
+}

package/dist/src/memory/types.js

@@ -0,0 +1,12 @@
+export const JOB_MEMORY_ENTRY_TYPES = [
+    "decision",
+    "assumption",
+    "fact",
+    "risk",
+    "open_question",
+    "file_note",
+    "review_note",
+    "implementation_note",
+    "human_preference",
+    "other"
+];

package/dist/src/onboarding/config-writer.js

@@ -0,0 +1,96 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { writeJsonFileAtomic } from "../utils/json.js";
+export class ConfigWriter {
+    async detectExisting(managementDir) {
+        const reposFile = path.join(managementDir, "repos.json");
+        const agentsFile = path.join(managementDir, "agents.json");
+        const [reposExists, agentsExists] = await Promise.all([
+            fileExists(reposFile),
+            fileExists(agentsFile)
+        ]);
+        return { reposExists, agentsExists, reposFile, agentsFile };
+    }
+    /**
+     * Write repos.json and agents.json into managementDir.
+     *
+     * @param overwriteRepos  When false, skips repos.json if it already exists.
+     * @param overwriteAgents When false, skips agents.json if it already exists.
+     */
+    async write(draft, options = {}) {
+        const { managementDir } = draft;
+        await fs.mkdir(managementDir, { recursive: true });
+        const reposFile = path.join(managementDir, "repos.json");
+        const agentsFile = path.join(managementDir, "agents.json");
+        const skippedExisting = [];
+        const reposAlreadyExists = await fileExists(reposFile);
+        if (!reposAlreadyExists || options.overwriteRepos) {
+            await writeJsonFileAtomic(reposFile, buildReposJson(draft));
+        }
+        else {
+            skippedExisting.push(reposFile);
+        }
+        const agentsAlreadyExists = await fileExists(agentsFile);
+        if (!agentsAlreadyExists || options.overwriteAgents) {
+            await writeJsonFileAtomic(agentsFile, buildAgentsJson(draft));
+        }
+        else {
+            skippedExisting.push(agentsFile);
+        }
+        return { reposFile, agentsFile, skippedExisting };
+    }
+}
+function buildReposJson(draft) {
+    return {
+        allowedUsers: draft.allowedUsers,
+        repos: draft.repos.map(buildRepoEntry)
+    };
+}
+function buildRepoEntry(repo) {
+    const id = `${repo.owner}-${repo.name}`;
+    return {
+        id,
+        owner: repo.owner,
+        name: repo.name,
+        defaultBranch: repo.defaultBranch,
+        localPath: repo.localPath,
+        enabled: repo.enabled,
+        labels: {
+            agentInProgress: "agent-in-progress",
+            agentPlanApproved: "agent-plan-approved",
+            agentProductApproved: "agent-product-approved",
+            agentReview: "agent-review",
+            planBreakdownNeeded: "plan-breakdown-needed",
+            agentSyncParentBranch: "agent-sync-parent-branch",
+            prepareForMerge: "prepare-for-merge"
+        }
+    };
+}
+function buildAgentsJson(draft) {
+    return {
+        agents: draft.agents.map(buildAgentEntry)
+    };
+}
+function buildAgentEntry(agent) {
+    const base = {
+        id: agent.id,
+        provider: agent.provider,
+        command: agent.command,
+        modelClass: agent.modelClass,
+        roles: agent.roles,
+        enabled: agent.enabled
+    };
+    if (agent.model !== undefined) {
+        base["model"] = agent.model;
+    }
+    return base;
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/onboarding/engine.js

@@ -0,0 +1,86 @@
+export class OnboardingEngine {
+    steps;
+    prompter;
+    options;
+    constructor(steps, prompter, options = {}) {
+        this.steps = steps;
+        this.prompter = prompter;
+        this.options = options;
+    }
+    async run(ctx) {
+        const results = [];
+        for (const step of this.steps) {
+            process.stdout.write(`\n--- ${step.description} ---\n`);
+            let result;
+            try {
+                result = await step.run(ctx, this.prompter);
+            }
+            catch (err) {
+                result = {
+                    status: "failed",
+                    message: err instanceof Error ? err.message : String(err),
+                    issues: [
+                        {
+                            title: "Unexpected error in onboarding step",
+                            cause: err instanceof Error ? err.message : String(err),
+                            suggestedFix: "Check the error message above and retry",
+                            canAutoRemediate: false
+                        }
+                    ]
+                };
+            }
+            ctx.stepResults.set(step.name, result);
+            results.push({ stepName: step.name, result });
+            const icon = statusIcon(result.status);
+            process.stdout.write(`${icon} ${result.message}\n`);
+            if (result.details) {
+                for (const detail of result.details) {
+                    process.stdout.write(`  ${detail}\n`);
+                }
+            }
+            if (result.issues) {
+                for (const issue of result.issues) {
+                    process.stdout.write(`\n  Issue: ${issue.title}\n`);
+                    process.stdout.write(`  Cause: ${issue.cause}\n`);
+                    process.stdout.write(`  Fix:   ${issue.suggestedFix}\n`);
+                    if (issue.manualSteps) {
+                        process.stdout.write("  Steps:\n");
+                        for (const s of issue.manualSteps) {
+                            process.stdout.write(`    - ${s}\n`);
+                        }
+                    }
+                }
+            }
+            if (result.status === "failed" && this.options.stopOnFailure) {
+                break;
+            }
+        }
+        const overallStatus = deriveOverallStatus(results.map((r) => r.result));
+        return { context: ctx, results, overallStatus };
+    }
+}
+function statusIcon(status) {
+    switch (status) {
+        case "passed":
+            return "✓";
+        case "warning":
+            return "⚠";
+        case "failed":
+            return "✗";
+        case "skipped":
+            return "-";
+        case "requiresUserAction":
+            return "!";
+    }
+}
+export function deriveOverallStatus(results) {
+    if (results.some((r) => r.status === "failed"))
+        return "failed";
+    if (results.some((r) => r.status === "requiresUserAction"))
+        return "requiresUserAction";
+    if (results.some((r) => r.status === "warning"))
+        return "warning";
+    if (results.every((r) => r.status === "skipped"))
+        return "skipped";
+    return "passed";
+}