@bridge_gpt/mcp-server 0.1.13 → 0.1.14

package/build/pipeline-orchestrator.js

@@ -0,0 +1,593 @@
+/**
+ * Pipeline orchestrator — sequential server-side execution for the new
+ * ``run_pipeline`` / ``resume_pipeline`` / ``list_pipeline_runs`` MCP tools.
+ *
+ * Design rules (BAPI-275):
+ *   - The orchestrator never imports ``mcp_server/src/index.ts``. All runtime
+ *     dependencies (Bridge API config, pipelines/instructions registries, the
+ *     tool-handler map) are injected through ``PipelineOrchestratorDeps``.
+ *   - Pipeline runs are persisted server-side via the Bridge API routes at
+ *     ``/jira/pipelines/runs``. Every state transition extends the idle TTL.
+ *   - ``mcp_call`` failure detection uses a strict envelope match: the parsed
+ *     ``content[0].text`` value must be an object with a string ``error`` key
+ *     AND a numeric ``status`` key (matches ``handleResponse`` in index.ts).
+ *   - Approval-gated ``mcp_call`` steps synthesise a ``needs_agent_task``
+ *     pause unless ``auto_approve`` is true; the resolved tool name + params
+ *     are inlined into the instruction string so the agent can review and
+ *     confirm before resuming. (BAPI-275 decisions E-4 / E-36.)
+ */
+import { resolveRecipe } from "./pipeline-utils.js";
+class PipelinePersistenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function createPipelinePersistenceClient(deps) {
+    const headers = {
+        "X-API-Key": deps.apiKey,
+        "Content-Type": "application/json",
+    };
+    const base = deps.baseUrl.replace(/\/+$/, "");
+    function urlFor(suffix, query) {
+        const u = new URL(`${base}/jira/pipelines${suffix}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                u.searchParams.set(k, v);
+            }
+        }
+        return u.toString();
+    }
+    async function readError(resp) {
+        const raw = await resp.text();
+        let codeFromBody = null;
+        let messageFromBody = null;
+        try {
+            const parsed = JSON.parse(raw);
+            const detail = parsed?.detail;
+            if (detail && typeof detail === "object") {
+                if (typeof detail.error_code === "string") {
+                    codeFromBody = detail.error_code;
+                }
+                if (typeof detail.error === "string") {
+                    messageFromBody = detail.error;
+                }
+            }
+        }
+        catch {
+            // not JSON
+        }
+        const codeFromStatus = resp.status === 404
+            ? "NOT_FOUND"
+            : resp.status === 410
+                ? "EXPIRED"
+                : resp.status === 403
+                    ? "REPO_MISMATCH"
+                    : resp.status === 400 || resp.status === 422
+                        ? "VALIDATION"
+                        : "TOOL_ERROR";
+        return {
+            code: codeFromBody ?? codeFromStatus,
+            message: messageFromBody ?? (raw || `HTTP ${resp.status}`),
+        };
+    }
+    async function createRun(input) {
+        const resp = await fetch(urlFor("/runs"), {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                repo_name: deps.repoName,
+                pipeline_name: input.pipeline_name,
+                resolved_recipe: input.resolved_recipe,
+                current_step_index: input.current_step_index,
+                results: input.results,
+                status: input.status,
+                ttl_seconds: input.ttl_seconds,
+            }),
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new PipelinePersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function getRun(pipelineRunId) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(pipelineRunId)}`, {
+            repo_name: deps.repoName,
+        }), { headers: { "X-API-Key": deps.apiKey } });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new PipelinePersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function patchRun(pipelineRunId, body) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(pipelineRunId)}`), {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ repo_name: deps.repoName, ...body }),
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new PipelinePersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function listRuns(status) {
+        const query = { repo_name: deps.repoName };
+        if (status)
+            query.status = status;
+        const resp = await fetch(urlFor("/runs", query), {
+            headers: { "X-API-Key": deps.apiKey },
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new PipelinePersistenceError(err.code, err.message);
+        }
+        const body = (await resp.json());
+        return body.runs ?? [];
+    }
+    async function deleteRun(pipelineRunId) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(pipelineRunId)}`, {
+            repo_name: deps.repoName,
+        }), {
+            method: "DELETE",
+            headers: { "X-API-Key": deps.apiKey },
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new PipelinePersistenceError(err.code, err.message);
+        }
+    }
+    return { createRun, getRun, patchRun, listRuns, deleteRun };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function normalizeAutoApprove(value) {
+    if (value === true || value === "true")
+        return true;
+    return false;
+}
+function failedEnvelope(code, message, extras = {}) {
+    return {
+        status: "failed",
+        error_code: code,
+        error: message,
+        ...extras,
+    };
+}
+function isToolFailureEnvelope(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return (parsed !== null &&
+            typeof parsed === "object" &&
+            typeof parsed.error === "string" &&
+            typeof parsed.status === "number");
+    }
+    catch {
+        return false;
+    }
+}
+const ORCHESTRATION_TOOLS = new Set([
+    "run_pipeline",
+    "resume_pipeline",
+    "list_pipeline_runs",
+    "delete_pipeline_run",
+]);
+// ---------------------------------------------------------------------------
+// runPipeline
+// ---------------------------------------------------------------------------
+export async function runPipeline(deps, input) {
+    const pipelineDef = deps.pipelines[input.pipeline];
+    if (!pipelineDef) {
+        const available = Object.keys(deps.pipelines).join(", ");
+        return failedEnvelope("VALIDATION", `Pipeline "${input.pipeline}" not found. Available pipelines: ${available || "(none)"}`);
+    }
+    if (input.variables && "auto_approve" in input.variables) {
+        return failedEnvelope("VALIDATION", "Pass auto_approve via the top-level parameter, not via the variables map.");
+    }
+    const autoApprove = normalizeAutoApprove(input.auto_approve);
+    const mergedVariables = {
+        docs_dir: deps.docsDir,
+        provider: "",
+        second_opinion: "",
+        auto_approve: autoApprove ? "true" : "",
+        ...(input.variables ?? {}),
+    };
+    let recipe;
+    try {
+        recipe = resolveRecipe(pipelineDef, deps.instructions, mergedVariables, undefined, autoApprove);
+    }
+    catch (err) {
+        return failedEnvelope("VALIDATION", err instanceof Error ? err.message : String(err), { pipeline: input.pipeline });
+    }
+    const persistence = createPipelinePersistenceClient({
+        baseUrl: deps.baseUrl,
+        apiKey: deps.apiKey,
+        repoName: deps.repoName,
+    });
+    let row;
+    try {
+        row = await persistence.createRun({
+            pipeline_name: input.pipeline,
+            resolved_recipe: recipe,
+            current_step_index: 0,
+            results: [],
+            status: "running",
+            ttl_seconds: input.ttl_seconds,
+        });
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message, { pipeline: input.pipeline });
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err), { pipeline: input.pipeline });
+    }
+    return continuePipelineExecution(deps, persistence, row, recipe, autoApprove);
+}
+// ---------------------------------------------------------------------------
+// resumePipeline
+// ---------------------------------------------------------------------------
+export async function resumePipeline(deps, input) {
+    const persistence = createPipelinePersistenceClient({
+        baseUrl: deps.baseUrl,
+        apiKey: deps.apiKey,
+        repoName: deps.repoName,
+    });
+    let row;
+    try {
+        row = await persistence.getRun(input.pipeline_run_id);
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message, {
+                pipeline_run_id: input.pipeline_run_id,
+            });
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err), { pipeline_run_id: input.pipeline_run_id });
+    }
+    if (row.status !== "paused") {
+        return failedEnvelope("VALIDATION", `Cannot resume pipeline run in status "${row.status}". Only paused runs can be resumed.`, {
+            pipeline_run_id: row.pipeline_run_id,
+            pipeline: row.pipeline_name,
+            results: row.results,
+        });
+    }
+    const recipe = row.resolved_recipe;
+    const stepIndex = row.current_step_index;
+    const step = recipe.steps[stepIndex];
+    if (!step) {
+        return failedEnvelope("VALIDATION", `Paused step index ${stepIndex} is out of bounds for resolved recipe (total_steps=${recipe.total_steps}).`, {
+            pipeline_run_id: row.pipeline_run_id,
+            pipeline: row.pipeline_name,
+            results: row.results,
+        });
+    }
+    const accumulatedResults = [...row.results];
+    let nextIndex = stepIndex;
+    let approvalAgentResult;
+    if (step.type === "agent_task") {
+        accumulatedResults.push({
+            step: step.step,
+            type: "agent_task",
+            ok: true,
+            description: step.description,
+            result: input.agent_result,
+        });
+        nextIndex = stepIndex + 1;
+    }
+    else {
+        // Approval-gated mcp_call: don't push a synthetic acknowledgement here —
+        // ``continuePipelineExecution`` will push exactly one result entry for
+        // this step after executing the tool. Carry the confirmation forward so
+        // the eventual entry can record it via ``approval_agent_result``.
+        approvalAgentResult = input.agent_result;
+        nextIndex = stepIndex;
+    }
+    let updated;
+    try {
+        updated = await persistence.patchRun(row.pipeline_run_id, {
+            current_step_index: nextIndex,
+            results: accumulatedResults,
+            status: "running",
+            expected_status: "paused",
+            expected_current_step_index: stepIndex,
+        });
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message, {
+                pipeline_run_id: row.pipeline_run_id,
+                pipeline: row.pipeline_name,
+                results: accumulatedResults,
+            });
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err), {
+            pipeline_run_id: row.pipeline_run_id,
+            pipeline: row.pipeline_name,
+            results: accumulatedResults,
+        });
+    }
+    const autoApprove = recipe.auto_approve;
+    return continuePipelineExecution(deps, persistence, updated, recipe, autoApprove, step.type === "mcp_call" ? stepIndex : undefined, approvalAgentResult);
+}
+// ---------------------------------------------------------------------------
+// listPipelineRuns
+// ---------------------------------------------------------------------------
+export async function listPipelineRuns(deps, input = {}) {
+    const persistence = createPipelinePersistenceClient({
+        baseUrl: deps.baseUrl,
+        apiKey: deps.apiKey,
+        repoName: deps.repoName,
+    });
+    let metadata;
+    try {
+        metadata = await persistence.listRuns(input.status);
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message);
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err));
+    }
+    return {
+        status: "completed",
+        runs: metadata.map((row) => ({
+            pipeline_run_id: row.pipeline_run_id,
+            pipeline: row.pipeline_name,
+            step_index: row.total_steps !== null && row.status === "completed"
+                ? row.total_steps
+                : row.current_step_index + 1,
+            total_steps: row.total_steps,
+            status: row.status,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            expires_at: row.expires_at,
+        })),
+    };
+}
+// ---------------------------------------------------------------------------
+// deletePipelineRun
+// ---------------------------------------------------------------------------
+export async function deletePipelineRun(deps, input) {
+    if (!input ||
+        typeof input.pipeline_run_id !== "string" ||
+        input.pipeline_run_id.length === 0) {
+        return failedEnvelope("VALIDATION", "pipeline_run_id is required.");
+    }
+    const persistence = createPipelinePersistenceClient({
+        baseUrl: deps.baseUrl,
+        apiKey: deps.apiKey,
+        repoName: deps.repoName,
+    });
+    try {
+        await persistence.deleteRun(input.pipeline_run_id);
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message);
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err));
+    }
+    return {
+        status: "completed",
+        pipeline_run_id: input.pipeline_run_id,
+        deleted: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// continuePipelineExecution — shared by run + resume
+// ---------------------------------------------------------------------------
+async function continuePipelineExecution(deps, persistence, row, recipe, autoApprove, forceExecuteAtIndex, approvalAgentResult) {
+    let pipelineRunId = row.pipeline_run_id;
+    let stepIndex = row.current_step_index;
+    let results = [...row.results];
+    const totalSteps = recipe.total_steps;
+    while (stepIndex < totalSteps) {
+        const step = recipe.steps[stepIndex];
+        // Approval gate for mcp_call (E-4 / E-36): when the step declared
+        // requires_approval and auto_approve is false, synthesise a
+        // needs_agent_task pause unless we just resumed onto this same step.
+        if (step.type === "mcp_call" &&
+            step.requires_approval &&
+            !autoApprove &&
+            forceExecuteAtIndex !== stepIndex) {
+            const approvalInstruction = `Approval gate for pipeline step ${step.step} of ${totalSteps}: "${step.description}".\n\n` +
+                `The pipeline is about to call MCP tool \`${step.tool}\` with these resolved params:\n\n` +
+                `\`\`\`json\n${JSON.stringify(step.params ?? {}, null, 2)}\n\`\`\`\n\n` +
+                `Review the tool and params, then confirm with the user before resuming. ` +
+                `When confirmed, call \`resume_pipeline\` with \`pipeline_run_id\` "${pipelineRunId}" and ` +
+                `\`agent_result\` describing the confirmation (e.g. "approved" or a brief reason).`;
+            try {
+                await persistence.patchRun(pipelineRunId, {
+                    current_step_index: stepIndex,
+                    results,
+                    status: "paused",
+                });
+            }
+            catch (err) {
+                return handlePersistenceErrorForEnvelope(err, {
+                    pipeline_run_id: pipelineRunId,
+                    pipeline: recipe.pipeline,
+                    results,
+                    step_index: step.step,
+                });
+            }
+            return {
+                status: "needs_agent_task",
+                pipeline_run_id: pipelineRunId,
+                pipeline: recipe.pipeline,
+                step_index: step.step,
+                total_steps: totalSteps,
+                step_description: step.description,
+                instruction: approvalInstruction,
+                results,
+            };
+        }
+        if (step.type === "agent_task") {
+            try {
+                await persistence.patchRun(pipelineRunId, {
+                    current_step_index: stepIndex,
+                    results,
+                    status: "paused",
+                });
+            }
+            catch (err) {
+                return handlePersistenceErrorForEnvelope(err, {
+                    pipeline_run_id: pipelineRunId,
+                    pipeline: recipe.pipeline,
+                    results,
+                    step_index: step.step,
+                });
+            }
+            return {
+                status: "needs_agent_task",
+                pipeline_run_id: pipelineRunId,
+                pipeline: recipe.pipeline,
+                step_index: step.step,
+                total_steps: totalSteps,
+                step_description: step.description,
+                instruction: step.instruction ?? "",
+                results,
+            };
+        }
+        // mcp_call branch (executing now)
+        const callResult = await executeMcpCallStep(deps, step);
+        const capturedApprovalAgentResult = approvalAgentResult;
+        forceExecuteAtIndex = undefined;
+        approvalAgentResult = undefined;
+        if (callResult.ok) {
+            const entry = {
+                step: step.step,
+                type: "mcp_call",
+                ok: true,
+                description: step.description,
+                tool: step.tool,
+                result: callResult.value,
+            };
+            if (capturedApprovalAgentResult !== undefined) {
+                entry.approval_agent_result = capturedApprovalAgentResult;
+            }
+            results.push(entry);
+            stepIndex += 1;
+            try {
+                await persistence.patchRun(pipelineRunId, {
+                    current_step_index: stepIndex,
+                    results,
+                    status: stepIndex >= totalSteps ? "completed" : "running",
+                });
+            }
+            catch (err) {
+                return handlePersistenceErrorForEnvelope(err, {
+                    pipeline_run_id: pipelineRunId,
+                    pipeline: recipe.pipeline,
+                    results,
+                    step_index: step.step,
+                });
+            }
+            continue;
+        }
+        // Failure path
+        const failureEntry = {
+            step: step.step,
+            type: "mcp_call",
+            ok: false,
+            description: step.description,
+            tool: step.tool,
+            error: callResult.error,
+        };
+        if (capturedApprovalAgentResult !== undefined) {
+            failureEntry.approval_agent_result = capturedApprovalAgentResult;
+        }
+        results.push(failureEntry);
+        if (step.on_error === "warn_and_continue") {
+            stepIndex += 1;
+            try {
+                await persistence.patchRun(pipelineRunId, {
+                    current_step_index: stepIndex,
+                    results,
+                    status: stepIndex >= totalSteps ? "completed" : "running",
+                });
+            }
+            catch (err) {
+                return handlePersistenceErrorForEnvelope(err, {
+                    pipeline_run_id: pipelineRunId,
+                    pipeline: recipe.pipeline,
+                    results,
+                    step_index: step.step,
+                });
+            }
+            continue;
+        }
+        // halt
+        try {
+            await persistence.patchRun(pipelineRunId, {
+                current_step_index: stepIndex,
+                results,
+                status: "failed",
+            });
+        }
+        catch {
+            // best-effort — failure already happened
+        }
+        return failedEnvelope("TOOL_ERROR", callResult.error, {
+            pipeline_run_id: pipelineRunId,
+            pipeline: recipe.pipeline,
+            results,
+            step_index: step.step,
+        });
+    }
+    return {
+        status: "completed",
+        pipeline_run_id: pipelineRunId,
+        pipeline: recipe.pipeline,
+        total_steps: totalSteps,
+        results,
+    };
+}
+function handlePersistenceErrorForEnvelope(err, extras) {
+    if (err instanceof PipelinePersistenceError) {
+        return failedEnvelope(err.code, err.message, extras);
+    }
+    return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err), extras);
+}
+async function executeMcpCallStep(deps, step) {
+    if (!step.tool) {
+        return { ok: false, error: "mcp_call step missing 'tool' field" };
+    }
+    if (ORCHESTRATION_TOOLS.has(step.tool)) {
+        return {
+            ok: false,
+            error: `Refusing to invoke orchestration tool "${step.tool}" from within a pipeline step.`,
+        };
+    }
+    const entry = deps.toolHandlers.get(step.tool);
+    if (!entry) {
+        return { ok: false, error: `Unknown MCP tool "${step.tool}"` };
+    }
+    if (!entry.isEnabled()) {
+        return {
+            ok: false,
+            error: `MCP tool "${step.tool}" is currently disabled by server policy.`,
+        };
+    }
+    let toolResult;
+    try {
+        toolResult = await entry.handler(step.params ?? {});
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const text = toolResult?.content?.[0]?.type === "text"
+        ? toolResult.content[0].text
+        : "";
+    if (typeof text === "string" && isToolFailureEnvelope(text)) {
+        return { ok: false, error: text };
+    }
+    return { ok: true, value: text };
+}