@bridge_gpt/mcp-server 0.1.12 → 0.1.14

package/build/index.js

@@ -24,6 +24,8 @@ import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
+import { DecisionPageInputShape } from "./decision-page-schema.js";
+import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, } from "./pipeline-orchestrator.js";
 // Mutable pipeline/instruction state — starts with bundled, merged with user at startup
 const PIPELINES = { ...BUNDLED_PIPELINES };
 const INSTRUCTIONS = { ...BUNDLED_INSTRUCTIONS };
@@ -48,6 +50,9 @@ const POST_HEADERS = {
 function buildUrl(path) {
     return `${BASE_URL.replace(/\/+$/, "")}/jira${path}`;
 }
+function buildApiUrl(path) {
+    return `${BASE_URL.replace(/\/+$/, "")}${path}`;
+}
 function buildGetUrl(path, params) {
     const url = new URL(buildUrl(path));
     for (const [key, value] of Object.entries(params)) {
@@ -517,6 +522,32 @@ automatically provided by the server.
 
 - \`"halt"\` (default) — stop the pipeline immediately on failure
 - \`"warn_and_continue"\` — log a warning and proceed to the next step
+
+## Executing Pipelines
+
+Pipelines defined here can be executed end-to-end via the \`run_pipeline\` MCP
+tool. \`run_pipeline\` returns a unified envelope keyed on \`status\`:
+
+- \`completed\` — the pipeline finished and \`results\` holds the per-step output.
+- \`needs_agent_task\` — the orchestrator paused on an \`agent_task\` step (or an
+  approval-gated \`mcp_call\` when \`auto_approve\` was false). Perform the task
+  described by \`instruction\`, then call \`resume_pipeline\` with the
+  \`pipeline_run_id\` and the resulting string as \`agent_result\`.
+- \`failed\` — terminal failure; \`error_code\` is one of \`VALIDATION\`,
+  \`NOT_FOUND\`, \`EXPIRED\`, \`REPO_MISMATCH\`, or \`TOOL_ERROR\`.
+
+Paused runs auto-expire after an idle TTL (default 24 hours, override via
+\`ttl_seconds\` on \`run_pipeline\`). The TTL is reset on every state transition.
+Use \`list_pipeline_runs\` to recover a \`pipeline_run_id\` if the prior
+\`needs_agent_task\` envelope is no longer in scope.
+
+## \`agent_task\` Instruction Files
+
+When you reference an instruction file (\`instruction_file: "…"\`), the file
+markdown MUST end with a terminal \`## Return\` H2 section describing what the
+agent should pass back as \`resume_pipeline.agent_result\`. The return value
+is a string — do NOT ask the agent to wrap it in JSON unless the instruction
+body explicitly says to serialize structured output.
 `;
     const exampleContent = JSON.stringify({
         name: "Example Pipeline",
@@ -645,9 +676,70 @@ const server = new McpServer({
     version: "1.0.0",
 });
 // ---------------------------------------------------------------------------
+// Tool registration wrapper (BAPI-275)
+// ---------------------------------------------------------------------------
+//
+// Every MCP tool registered through ``registerTool`` is also recorded in
+// ``TOOL_HANDLERS`` so the new pipeline orchestrator can dispatch existing
+// tools in-process (without round-tripping through stdio). The wrapper
+// preserves the exact return value of ``server.registerTool`` — including
+// its ``.enable()`` / ``.disable()`` methods — and keeps a closure-local
+// ``active`` flag in sync with them, so disabling a tool through the SDK
+// also blocks in-process dispatch through ``TOOL_HANDLERS``.
+const TOOL_HANDLERS = new Map();
+// The wrapper preserves the SDK's generic type signature so existing call
+// sites keep their per-tool input-type inference.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const registerTool = ((name, config, handler) => {
+    let active = true;
+    const wrappedHandler = async (args, extra) => {
+        if (!active) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "TOOL_DISABLED",
+                            status: 503,
+                            message: `Tool "${name}" is currently disabled.`,
+                        }),
+                    },
+                ],
+            };
+        }
+        return await handler(args, extra);
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sdkRegister = server.registerTool.bind(server);
+    const toolHandle = sdkRegister(name, config, wrappedHandler);
+    const inProcessHandler = async (params) => {
+        return await wrappedHandler(params);
+    };
+    TOOL_HANDLERS.set(name, {
+        handler: inProcessHandler,
+        isEnabled: () => active,
+    });
+    // Wrap enable/disable to keep the closure flag in sync with SDK state.
+    if (toolHandle && typeof toolHandle.enable === "function") {
+        const sdkEnable = toolHandle.enable.bind(toolHandle);
+        toolHandle.enable = () => {
+            active = true;
+            return sdkEnable();
+        };
+    }
+    if (toolHandle && typeof toolHandle.disable === "function") {
+        const sdkDisable = toolHandle.disable.bind(toolHandle);
+        toolHandle.disable = () => {
+            active = false;
+            return sdkDisable();
+        };
+    }
+    return toolHandle;
+});
+// ---------------------------------------------------------------------------
 // Tools
 // ---------------------------------------------------------------------------
-server.registerTool("ping", {
+registerTool("ping", {
     description: "Test connectivity to Bridge API. Validates that the API key is accepted and the configured repository is accessible. " +
         "Returns JSON with {status: 'ok', repo_name: '<configured repo>'}. " +
         "Use this as a quick health check before other operations, or to verify your Bridge API configuration is working. " +
@@ -660,7 +752,42 @@ server.registerTool("ping", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_project_standards", {
+registerTool("second_opinion", {
+    description: "Consult a different LLM model family for a sanity check or technical pushback on a recommendation, plan, or analysis you have already produced. " +
+        "Use this when you want a second, independent opinion before acting on a non-trivial decision — for example, when committing to an implementation approach, a risky refactor, an architectural trade-off, or a recommendation you would otherwise present to a user with no further validation. " +
+        "Pick a provider from a DIFFERENT model family than the one you are running on so the response is genuinely independent (e.g. if you are an OpenAI agent, ask 'anthropic' or 'gemini'). " +
+        "Pick a model tier appropriate for the depth of pushback you want: CHEAP_MODEL for a quick sanity check, BASIC_MODEL for a focused review, PREMIUM_MODEL for serious architectural pushback. " +
+        "The 'prompt' you supply should be a complete, self-contained brief: the full plan, recommendation, or question you want challenged, along with whatever context is needed to evaluate it. The server adds a system prompt that frames the responder as an independent senior engineer and injects lightweight project context. " +
+        "Returns the responding model's reply text plus the resolved provider, tier, and model id. The reply is returned to you as-is; you decide whether to incorporate the feedback. " +
+        "Project authorization uses the standard repo access check; per-project provider gating is intentionally not enforced for this tool.",
+    inputSchema: {
+        prompt: z
+            .string()
+            .describe("The complete, self-contained brief to send to the second-opinion model. " +
+            "Include the full plan, recommendation, analysis, or question you want challenged, plus enough context for the responder to evaluate it independently. " +
+            "This is sent as the user message; the server constructs the system prompt."),
+        provider: z
+            .enum(["anthropic", "openai", "gemini"])
+            .describe("LLM provider family for the second opinion. Choose a family DIFFERENT from the one you are running on so the response is genuinely independent."),
+        model: z
+            .enum(["CHEAP_MODEL", "BASIC_MODEL", "PREMIUM_MODEL"])
+            .describe("Model tier within the chosen provider. CHEAP_MODEL for quick sanity checks, BASIC_MODEL for focused reviews, PREMIUM_MODEL for serious architectural pushback."),
+    },
+}, async ({ prompt, provider, model }) => {
+    const resp = await fetch(buildApiUrl("/llm/second-opinion"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify({
+            repo_name: REPO_NAME,
+            prompt,
+            provider,
+            model,
+        }),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+registerTool("get_project_standards", {
     description: "Retrieve project-specific coding standards, architecture guidelines, testing standards, code review standards, and project context (platform, version, project description) for the configured repository. " +
         "Returns structured markdown with sections for project context, architecture instructions, code review correctness standards, testing stack information, and build analysis. " +
         "Only sections with configured values are included. Returns 404 if no standards are configured. " +
@@ -672,7 +799,7 @@ server.registerTool("get_project_standards", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_tickets", {
+registerTool("get_tickets", {
     description: "Search for and list Jira tickets from the configured project. " +
         "Filters by query text, status name, or date. Returns up to 'limit' tickets ordered by most recently updated. " +
         "All data is fetched live from Jira. Use get_ticket to retrieve full details for a specific ticket.",
@@ -719,7 +846,7 @@ server.registerTool("get_tickets", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_ticket", {
+registerTool("get_ticket", {
     description: "Retrieve full details for a single Jira ticket by its key. " +
         "Returns summary, status, type, assignee, reporter, description, and timestamps. " +
         "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets.",
@@ -734,7 +861,7 @@ server.registerTool("get_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("create_ticket", {
+registerTool("create_ticket", {
     description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both — file_path takes precedence). " +
         "Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. " +
         "The ticket is created immediately in Jira — confirm details with the user before calling. " +
@@ -776,7 +903,7 @@ server.registerTool("create_ticket", {
     const text = await createTicketRequest({ summary, description: resolved.text, issue_type, priority, labels, assignee });
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("get_plan", {
+registerTool("get_plan", {
     description: "Retrieve the AI-generated implementation plan for a Jira ticket. " +
         "Returns the full plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes step-by-step implementation guidance with code file references. " +
@@ -804,7 +931,7 @@ server.registerTool("get_plan", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_architecture", {
+registerTool("get_architecture", {
     description: "Retrieve the AI-generated architecture plan for a Jira ticket. " +
         "Returns the full architecture plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes high-level architectural decisions, component design, and integration guidance. " +
@@ -832,7 +959,7 @@ server.registerTool("get_architecture", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_clarifying_questions", {
+registerTool("get_clarifying_questions", {
     description: "Retrieve AI-generated clarifying questions (for feature/task tickets) or debugging guidance (for bug tickets) for a Jira ticket. " +
         "Returns markdown text with questions that should be resolved before implementation begins. " +
         "Returns 404 if no questions have been generated yet. " +
@@ -859,7 +986,7 @@ server.registerTool("get_clarifying_questions", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("parse_repository", {
+registerTool("parse_repository", {
     description: "Queue a background job to parse and index the repository for Bridge API's AI agents. " +
         "This should be run after major codebase changes so that plans and questions reflect the latest code. " +
         "Returns 202 with {message: 'Repository parsing queued'} on success, " +
@@ -885,7 +1012,7 @@ server.registerTool("parse_repository", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("regenerate_directory_map", {
+registerTool("regenerate_directory_map", {
     description: "Regenerate the repository directory map and return the result. " +
         "Unlike parse_repository (which is async), this tool is synchronous — it blocks until " +
         "the directory map is generated and returns the full map text directly. " +
@@ -909,7 +1036,7 @@ server.registerTool("regenerate_directory_map", {
         clearTimeout(timeout);
     }
 });
-server.registerTool("get_parse_status", {
+registerTool("get_parse_status", {
     description: "Check whether a repository parse job is currently running. " +
         "Returns {status: 'in_progress', started_at: '<ISO timestamp>'} if a parse is active, " +
         "or {status: 'idle'} if no parse is running. " +
@@ -922,7 +1049,7 @@ server.registerTool("get_parse_status", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("add_comment", {
+registerTool("add_comment", {
     description: "Post a comment on a Jira ticket. The comment appears immediately in Jira. " +
         "Supports markdown formatting. " +
         "For long comments (over ~2000 characters), set attach_as_file to true — " +
@@ -976,7 +1103,7 @@ server.registerTool("add_comment", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("update_ticket_description", {
+registerTool("update_ticket_description", {
     description: "Update the description of an existing Jira ticket. This is a direct, synchronous update that overwrites the existing description with the provided text. " +
         "The description should be in markdown format — it will be automatically converted to Jira wiki markup. " +
         "This does NOT create a new ticket. Use create_ticket for that. " +
@@ -1008,7 +1135,7 @@ server.registerTool("update_ticket_description", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("upload_attachment", {
+registerTool("upload_attachment", {
     description: "Upload a local file as an attachment to a Jira ticket. " +
         "Supports text/UTF-8 files only (markdown, plain text, etc.). " +
         "Optionally syncs the content to Bridge API's tickets_links table so retrieval endpoints " +
@@ -1071,7 +1198,7 @@ server.registerTool("upload_attachment", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("list_attachments", {
+registerTool("list_attachments", {
     description: "List attachments on a Jira ticket. " +
         "Returns metadata (ID, filename, MIME type, size, created date) for each attachment. " +
         "By default, AI-generated attachments are excluded. " +
@@ -1096,7 +1223,7 @@ server.registerTool("list_attachments", {
     return { content: [{ type: "text", text }] };
 });
 const MAX_INLINE_TEXT_LENGTH = 50_000;
-server.registerTool("download_attachment", {
+registerTool("download_attachment", {
     description: "Download an attachment from a Jira ticket and save it to disk. " +
         "Specify either attachment_id or filename (not both). " +
         "For text files, the content is returned inline (truncated at ~50KB) and also saved to disk. " +
@@ -1184,7 +1311,7 @@ server.registerTool("download_attachment", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
-server.registerTool("request_plan_generation", {
+registerTool("request_plan_generation", {
     description: "Request AI-generated implementation plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes depending on ticket complexity and number of attachments. " +
@@ -1253,7 +1380,7 @@ server.registerTool("request_plan_generation", {
         `Use get_plan with ticket_number "${ticket_number}" to retrieve the plan once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("request_architecture", {
+registerTool("request_architecture", {
     description: "Request AI-generated architecture plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 2-4 minutes depending on ticket complexity. " +
@@ -1322,7 +1449,7 @@ server.registerTool("request_architecture", {
         `Use get_architecture with ticket_number "${ticket_number}" to retrieve the architecture plan once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("request_clarifying_questions", {
+registerTool("request_clarifying_questions", {
     description: "Request AI-generated clarifying questions or debugging guidance for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
@@ -1395,7 +1522,7 @@ server.registerTool("request_clarifying_questions", {
 // ---------------------------------------------------------------------------
 // Ticket Quality Critique
 // ---------------------------------------------------------------------------
-server.registerTool("get_ticket_critique", {
+registerTool("get_ticket_critique", {
     description: "Retrieve AI-generated ticket quality critique for a Jira ticket. " +
         "Returns markdown text with a structured critique covering Standards Conformance Analysis, " +
         "Standards Deviations, and Suggested Improvements. " +
@@ -1423,7 +1550,7 @@ server.registerTool("get_ticket_critique", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("request_ticket_critique", {
+registerTool("request_ticket_critique", {
     description: "Request AI-generated ticket critique for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
@@ -1495,7 +1622,7 @@ server.registerTool("request_ticket_critique", {
 // ---------------------------------------------------------------------------
 // Combined Ticket Review (clarify + critique)
 // ---------------------------------------------------------------------------
-server.registerTool("request_ticket_review", {
+registerTool("request_ticket_review", {
     description: "Request a combined ticket review that generates BOTH clarifying questions (or debugging guidance for bug tickets) " +
         "AND a ticket quality critique in parallel on the server, halving wall-clock latency vs. running the two " +
         "requests sequentially. This triggers an asynchronous background job — results are NOT immediate. " +
@@ -1602,7 +1729,7 @@ server.registerTool("request_ticket_review", {
 // ---------------------------------------------------------------------------
 // Reimplement Context
 // ---------------------------------------------------------------------------
-server.registerTool("request_reimplement_context", {
+registerTool("request_reimplement_context", {
     description: "Request processing of new attachments and context assembly for a previously-implemented Jira ticket. " +
         "Use this for follow-up requests on tickets that have already been through the plan+implement cycle. " +
         "This triggers an asynchronous background job to process new attachments/images. " +
@@ -1668,7 +1795,7 @@ server.registerTool("request_reimplement_context", {
         `Use get_reimplement_context with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("get_reimplement_context", {
+registerTool("get_reimplement_context", {
     description: "Retrieve the assembled reimplement context for a Jira ticket. " +
         "Returns a markdown document with new/changed information diffed against stored state, " +
         "the original ticket description, and the existing implementation plan. " +
@@ -1709,7 +1836,7 @@ server.registerTool("get_reimplement_context", {
 // ---------------------------------------------------------------------------
 // Ticket Lifecycle Tracking
 // ---------------------------------------------------------------------------
-server.registerTool("track_ticket", {
+registerTool("track_ticket", {
     description: "Insert a ticket into Bridge API's database for lifecycle tracking. This registers the ticket so that workflow state timestamps (critique, clarify, plan, implement) can be tracked. " +
         "If the ticket is already tracked, this is a safe no-op — it upserts the description and repo_name without error. " +
         "Call this after creating a ticket with create_ticket to enable state tracking. " +
@@ -1730,7 +1857,7 @@ server.registerTool("track_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_ticket_state", {
+registerTool("update_ticket_state", {
     description: "Update workflow state timestamps on a tracked ticket. Each specified field is set to the current UTC timestamp on the server. " +
         "Valid field names: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'. " +
         "The ticket must already be tracked (via track_ticket) or a 404 error is returned. " +
@@ -1750,7 +1877,7 @@ server.registerTool("update_ticket_state", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_ticket_state", {
+registerTool("get_ticket_state", {
     description: "Retrieve workflow state timestamps and artifact existence flags for a tracked ticket. " +
         "Returns timestamps for each state field (critique_called, critique_answered, clarify_called, clarify_answered, plan_generated, implemented, reimplement_called) " +
         "and boolean flags indicating whether artifacts exist (has_clarifying_questions, has_critique, has_plan). " +
@@ -1768,7 +1895,7 @@ server.registerTool("get_ticket_state", {
 // ---------------------------------------------------------------------------
 // Jira Transitions
 // ---------------------------------------------------------------------------
-server.registerTool("get_jira_transitions", {
+registerTool("get_jira_transitions", {
     description: "List available Jira workflow transitions for a ticket. Returns each transition's id, name, and target status. " +
         "Use this to discover what status changes are possible for a given ticket. " +
         "The repo_name is automatically injected from the configured environment.",
@@ -1781,7 +1908,7 @@ server.registerTool("get_jira_transitions", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_jira_status", {
+registerTool("update_jira_status", {
     description: "Transition a Jira ticket to a specified target status by executing a workflow transition. " +
         "Provide either target_status (matched case-insensitively against available transitions) or transition_id (used directly). " +
         "If transition_id is provided, it takes precedence over target_status. " +
@@ -1808,7 +1935,7 @@ server.registerTool("update_jira_status", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("resolve_target_status", {
+registerTool("resolve_target_status", {
     description: "Resolve the post-PR target Jira status for the configured repository using an LLM agent. " +
         "The agent selects the workflow status that best represents 'code committed via PR but not yet tested.' " +
         "Results are cached per-project — subsequent calls return the cached value unless force_rerun is true. " +
@@ -1839,12 +1966,13 @@ server.registerTool("resolve_target_status", {
 const VALID_CONFIG_FIELDS = [
     "review_instructions", "documentation_instructions", "architecture_instructions",
     "unit_testing_instructions", "e2e_testing_instructions",
+    "unit_testing_stack", "e2e_testing_stack",
     "frontend_correctness_standards", "backend_correctness_standards",
     "template_correctness_standards", "style_correctness_standards",
     "design_principles",
-    "post_pr_target_status", "ci_check_config",
+    "post_pr_target_status", "ci_check_config", "ci_followup_config",
 ].join(", ");
-server.registerTool("list_config_fields", {
+registerTool("list_config_fields", {
     description: "List all configurable fields available for reading and updating via the Bridge API. " +
         "Returns each field's name and a description of its purpose. No database values are returned — " +
         "use get_config_field to read a specific field's current value. " +
@@ -1856,7 +1984,7 @@ server.registerTool("list_config_fields", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_my_role", {
+registerTool("get_my_role", {
     description: "Check the role and auth source for the current API key. " +
         "Returns JSON with {role: \"admin\" | \"member\" | null, source: \"user_access\" | \"legacy\"}. " +
         "Use this to check if the current key has admin permissions before attempting configuration updates " +
@@ -1868,7 +1996,7 @@ server.registerTool("get_my_role", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_config_field", {
+registerTool("get_config_field", {
     description: "Read the current value and metadata for a specific configuration field. " +
         "Returns the field's current database value (or null if not set), along with a description of its purpose and examples of helpful content. " +
         "Use this before update_config_field to understand the current state and build upon it rather than overwriting blindly.",
@@ -1881,7 +2009,7 @@ server.registerTool("get_config_field", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_config_field", {
+registerTool("update_config_field", {
     description: "Update a specific configuration field in the Bridge database. " +
         "These fields control LLM behavior during code review, planning, and documentation. " +
         "Always call get_config_field first to read the current value and build upon it. " +
@@ -1913,10 +2041,63 @@ server.registerTool("update_config_field", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + note }] };
 });
-// ---------------------------------------------------------------------------
-// Deep Research
-// ---------------------------------------------------------------------------
-server.registerTool("request_deep_research", {
+function formatDeepResearchProviderReason(meta) {
+    if (!meta)
+        return "";
+    const parts = [];
+    const reason = meta.incomplete_details?.reason;
+    if (reason) {
+        parts.push(`provider reason: ${reason}`);
+    }
+    const errMsg = meta.error?.message;
+    const errCode = meta.error?.code;
+    if (errMsg || errCode) {
+        if (errCode && errMsg) {
+            parts.push(`provider error: ${errCode}: ${errMsg}`);
+        }
+        else if (errMsg) {
+            parts.push(`provider error: ${errMsg}`);
+        }
+        else if (errCode) {
+            parts.push(`provider error: ${errCode}`);
+        }
+    }
+    return parts.length ? ` (${parts.join("; ")})` : "";
+}
+function _safeIsoMs(value) {
+    if (!value)
+        return null;
+    const ms = new Date(value).getTime();
+    if (Number.isNaN(ms))
+        return null;
+    return ms;
+}
+function formatDeepResearchElapsed(createdAt, lastPollAt) {
+    const createdMs = _safeIsoMs(createdAt);
+    if (createdMs === null)
+        return "";
+    const now = Date.now();
+    const startedMs = Math.max(0, now - createdMs);
+    const startedMin = Math.floor(startedMs / 60_000);
+    const lastPollMs = _safeIsoMs(lastPollAt);
+    let pollSuffix = "";
+    if (lastPollMs !== null) {
+        const ageSec = Math.max(0, Math.floor((now - lastPollMs) / 1000));
+        pollSuffix = `, last poll ${ageSec}s ago`;
+    }
+    return ` (running ${startedMin}m${pollSuffix})`;
+}
+function formatDeepResearchFailure(body) {
+    const kind = body.error_kind || body.error_message || "Unknown error";
+    const reason = formatDeepResearchProviderReason(body.provider_status_meta);
+    return `Deep research failed: ${kind}${reason}. Consider using standard web searches to gather the information incrementally.`;
+}
+function formatDeepResearchStatus(body, taskId) {
+    const elapsed = formatDeepResearchElapsed(body.created_at, body.last_poll_at);
+    const reason = formatDeepResearchProviderReason(body.provider_status_meta);
+    return `Status: ${body.status}${elapsed}${reason} (task_id: ${taskId}). Try again in a minute.`;
+}
+registerTool("request_deep_research", {
     description: "Submit a deep research request on a technical topic using AI-powered web search. " +
         "Returns a task_id for tracking the research progress. " +
         "\n\n" +
@@ -1980,6 +2161,7 @@ server.registerTool("request_deep_research", {
     const MAX_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
     let pollIntervalMs = 15_000; // start at 15 seconds
     let lastStatus = "queued";
+    let latestStatusBody = null;
     while (Date.now() - startTime < MAX_TIMEOUT_MS) {
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
         const elapsed = Math.round((Date.now() - startTime) / 1000);
@@ -1992,15 +2174,15 @@ server.registerTool("request_deep_research", {
         }
         const statusBody = (await statusResp.json());
         lastStatus = statusBody.status;
+        latestStatusBody = statusBody;
         if (lastStatus === "completed") {
             break;
         }
         if (lastStatus === "failed") {
-            const errorMsg = statusBody.error_message || "Unknown error";
             return {
                 content: [{
                         type: "text",
-                        text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                        text: formatDeepResearchFailure(statusBody),
                     }],
             };
         }
@@ -2010,10 +2192,13 @@ server.registerTool("request_deep_research", {
         }
     }
     if (lastStatus !== "completed") {
+        const statusSuffix = latestStatusBody
+            ? ` ${formatDeepResearchStatus(latestStatusBody, taskId)}`
+            : "";
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ error: "GATEWAY_TIMEOUT", status: 504, message: `Deep research timed out after 15 minutes (task_id: ${taskId}). The task may still be processing on the server. Use get_deep_research with this task_id to check later, or use standard web searches to gather the information incrementally.` }),
+                    text: `Deep research timed out after 15 minutes (task_id: ${taskId}).${statusSuffix} The task may still be processing on the server. Use get_deep_research with this task_id to check later, or use standard web searches to gather the information incrementally.`,
                 }],
         };
     }
@@ -2033,7 +2218,7 @@ server.registerTool("request_deep_research", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
-server.registerTool("get_deep_research", {
+registerTool("get_deep_research", {
     description: "Retrieve the result of a previously submitted deep research request. " +
         "Returns the full markdown research report if the task is completed, " +
         "or a structured status response if still processing or failed. " +
@@ -2054,11 +2239,10 @@ server.registerTool("get_deep_research", {
     }
     const statusBody = (await statusResp.json());
     if (statusBody.status === "failed") {
-        const errorMsg = statusBody.error_message || "Unknown error";
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                    text: formatDeepResearchFailure(statusBody),
                 }],
         };
     }
@@ -2066,7 +2250,7 @@ server.registerTool("get_deep_research", {
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ status: statusBody.status, task_id, message: `Deep research is still ${statusBody.status}. Try again in a minute.` }),
+                    text: formatDeepResearchStatus(statusBody, task_id),
                 }],
         };
     }
@@ -2086,10 +2270,219 @@ server.registerTool("get_deep_research", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
+const BRAINSTORM_TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "skipped",
+]);
+function isBrainstormTerminalStatus(status) {
+    return BRAINSTORM_TERMINAL_STATUSES.has(status);
+}
+function sanitizeProviderForFilename(provider) {
+    // Defensive: allow letters/digits/hyphen/underscore only; collapse runs and
+    // trim trailing punctuation. Falls back to "provider" for an empty result.
+    const cleaned = provider
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "provider";
+}
+async function pollBrainstormUntilTerminal(brainstormId, repoName) {
+    const startTime = Date.now();
+    const MAX_TIMEOUT_MS = 15 * 60 * 1000;
+    let pollIntervalMs = 15_000;
+    let latest = null;
+    while (Date.now() - startTime < MAX_TIMEOUT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        const statusUrl = buildGetUrl(`/brainstorms/${brainstormId}/status`, { repo_name: repoName });
+        const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+        if (!statusResp.ok) {
+            return latest;
+        }
+        latest = (await statusResp.json());
+        const allTerminal = latest.rows.every((row) => isBrainstormTerminalStatus(row.status));
+        if (allTerminal) {
+            return latest;
+        }
+        if (Date.now() - startTime > 60_000) {
+            pollIntervalMs = 30_000;
+        }
+    }
+    return latest;
+}
+async function saveBrainstormResultsLocally(envelope) {
+    const dir = getDocsPath("brainstorm");
+    const savedPaths = [];
+    for (const row of envelope.results) {
+        const markdown = row.markdown;
+        if (!markdown) {
+            continue;
+        }
+        const providerSegment = sanitizeProviderForFilename(row.provider);
+        const filename = `${envelope.brainstorm_id}-${providerSegment}.md`;
+        const filePath = path.join(dir, filename);
+        try {
+            await mkdir(dir, { recursive: true });
+            await writeFile(filePath, markdown, "utf-8");
+            savedPaths.push(filePath);
+        }
+        catch {
+            // Skip rows that fail to write — never block the response.
+        }
+    }
+    return savedPaths;
+}
+function formatBrainstormToolResponse(envelope, savedPaths) {
+    const lines = [];
+    lines.push(`# Brainstorm ${envelope.brainstorm_id}`);
+    lines.push(`Repo: ${envelope.repo_name}`);
+    lines.push("");
+    for (const row of envelope.results) {
+        lines.push(`## ${row.provider} — status: ${row.status}`);
+        lines.push(`error_kind: ${row.error_kind ?? "null"}`);
+        if (row.error_message) {
+            lines.push(`error_message: ${row.error_message}`);
+        }
+        if (row.markdown) {
+            lines.push("");
+            lines.push(row.markdown);
+        }
+        lines.push("");
+    }
+    if (savedPaths.length > 0) {
+        lines.push("---");
+        lines.push("Saved files:");
+        for (const p of savedPaths) {
+            lines.push(`- ${p}`);
+        }
+    }
+    return lines.join("\n");
+}
+registerTool("request_brainstorm", {
+    description: "Submit a brainstorm request that fans out the task to two opinion-provider LLMs " +
+        "(default: OpenAI + Gemini) and then runs a synthesizer pass over the completed opinions. " +
+        "Returns a brainstorm_id you can use with get_brainstorm. " +
+        "\n\n" +
+        "BEHAVIOR: By default, returns immediately with a brainstorm_id. Set wait_for_result=true " +
+        "to poll for terminal status (up to 15 minutes), then retrieve and optionally save the result. " +
+        "When save_locally=true (default), each provider's markdown is written to " +
+        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md, including {brainstorm_id}-synthesizer.md.",
+    inputSchema: {
+        task_description: z.string().describe("Free-form description of the task to brainstorm about. Sent verbatim — " +
+            "this tool does NOT read task_description from a file."),
+        repo_name: z.string().optional().describe("Repository name. Defaults to BAPI_REPO_NAME from the environment."),
+        ticket_number: z.string().optional().describe("Optional Jira ticket key (e.g. PROJ-123) to associate with the brainstorm. " +
+            "Ticket 1 only stores this for cross-reference — no Jira writes happen."),
+        providers: z.array(z.string()).optional().describe("Opinion-provider LLMs. Defaults to ['openai', 'gemini']. " +
+            "A single-provider request still inserts a synthesizer row but pre-skips it."),
+        concerns: z.string().optional().describe("Optional caller-supplied concerns to surface to the brainstorm agents."),
+        wait_for_result: z.boolean().optional().describe("When true, polls until every row reaches a terminal status (max 15 minutes), " +
+            "then returns the full result envelope. When false (default), returns immediately."),
+        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/ " +
+            "after the result is fetched."),
+        prior_brainstorm_id: z.string().optional().describe("Optional brainstorm_id from an earlier brainstorm to refine. " +
+            "When provided, the new brainstorm receives the prior brainstorm's " +
+            "synthesizer markdown, or a completed opinion-provider fallback, as prior context."),
+    },
+}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, }) => {
+    const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
+    const effectiveProviders = providers !== undefined ? providers : ["openai", "gemini"];
+    const shouldWait = wait_for_result === true;
+    const shouldSave = save_locally !== false;
+    const submitPayload = {
+        repo_name: effectiveRepo,
+        task_description,
+        providers: effectiveProviders,
+    };
+    if (ticket_number)
+        submitPayload.ticket_number = ticket_number;
+    if (concerns)
+        submitPayload.concerns = concerns;
+    if (prior_brainstorm_id) {
+        submitPayload.prior_brainstorm_request_id = prior_brainstorm_id;
+    }
+    const submitResp = await fetch(buildUrl("/brainstorms"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(submitPayload),
+    });
+    if (!submitResp.ok) {
+        const errorText = await handleResponse(submitResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const submitBody = (await submitResp.json());
+    if (!shouldWait) {
+        const confirmation = `Brainstorm submitted (brainstorm_id: ${submitBody.brainstorm_id}). ` +
+            `Providers: ${submitBody.providers.join(", ")}. ` +
+            `Synthesizer status: ${submitBody.synthesizer_status}. ` +
+            `Use get_brainstorm with brainstorm_id ${submitBody.brainstorm_id} to retrieve results.`;
+        return { content: [{ type: "text", text: confirmation }] };
+    }
+    const finalStatus = await pollBrainstormUntilTerminal(submitBody.brainstorm_id, effectiveRepo);
+    if (!finalStatus) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Brainstorm timed out before reaching terminal status ` +
+                        `(brainstorm_id: ${submitBody.brainstorm_id}). Use get_brainstorm later.`,
+                }],
+        };
+    }
+    const resultUrl = buildGetUrl(`/brainstorms/${submitBody.brainstorm_id}/result`, { repo_name: effectiveRepo });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const envelope = (await resultResp.json());
+    let savedPaths = [];
+    if (shouldSave) {
+        savedPaths = await saveBrainstormResultsLocally(envelope);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: formatBrainstormToolResponse(envelope, savedPaths),
+            }],
+    };
+});
+registerTool("get_brainstorm", {
+    description: "Retrieve the result envelope for a previously submitted brainstorm by brainstorm_id. " +
+        "Returns all rows (opinion providers + synthesizer), including error_kind for every row. " +
+        "When save_locally=true (default), writes each provider's markdown to " +
+        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md (including the synthesizer file). " +
+        "DB-only retrieval — never falls back to Jira attachments.",
+    inputSchema: {
+        brainstorm_id: z.string().describe("The brainstorm_id (UUID) returned by request_brainstorm."),
+        repo_name: z.string().optional().describe("Repository name. Defaults to BAPI_REPO_NAME from the environment."),
+        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/."),
+    },
+}, async ({ brainstorm_id, repo_name, save_locally }) => {
+    const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
+    const shouldSave = save_locally !== false;
+    const resultUrl = buildGetUrl(`/brainstorms/${brainstorm_id}/result`, { repo_name: effectiveRepo });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const envelope = (await resultResp.json());
+    let savedPaths = [];
+    if (shouldSave) {
+        savedPaths = await saveBrainstormResultsLocally(envelope);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: formatBrainstormToolResponse(envelope, savedPaths),
+            }],
+    };
+});
 // ---------------------------------------------------------------------------
 // VCS & CI Tools
 // ---------------------------------------------------------------------------
-server.registerTool("create_pull_request", {
+registerTool("create_pull_request", {
     description: "Create a pull request on the configured VCS provider (GitHub or Bitbucket). " +
         "Returns a structured response with {available, reason, action, detail}. " +
         "If a PR already exists for the head branch, returns it with created=false. " +
@@ -2118,7 +2511,7 @@ server.registerTool("create_pull_request", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-const resolveCiChecksTool = server.registerTool("resolve_ci_checks", {
+const resolveCiChecksTool = registerTool("resolve_ci_checks", {
     description: "Discover and classify CI checks for the configured repository. " +
         "Queries GitHub Check Runs + Commit Statuses APIs (or Bitbucket Build Statuses), " +
         "then uses Branch Protection API or LLM to determine which checks are required for merging. " +
@@ -2154,7 +2547,7 @@ const resolveCiChecksTool = server.registerTool("resolve_ci_checks", {
     }
     return { content: [{ type: "text", text }] };
 });
-const pollCiChecksTool = server.registerTool("poll_ci_checks", {
+const pollCiChecksTool = registerTool("poll_ci_checks", {
     description: "Poll the current status of CI checks for a specific commit. " +
         "Requires that resolve_ci_checks has been called first to populate the check configuration. " +
         "Returns per-check status, all_complete, all_passed, and unknown_checks fields. " +
@@ -2203,9 +2596,30 @@ async function checkCiConfigAndDisablePoll() {
 // Check config before connecting
 await checkCiConfigAndDisablePoll();
 // ---------------------------------------------------------------------------
+// Custom pipeline loading (BAPI-275)
+// ---------------------------------------------------------------------------
+//
+// Custom user pipelines must be merged into PIPELINES + INSTRUCTIONS BEFORE
+// the run_pipeline tool is registered so its embedded catalog includes both
+// bundled and user entries. The merge result is also used by list_pipelines
+// and get_pipeline_recipe below — every caller must see the same final
+// objects.
+{
+    const instructionsDir = path.join(path.dirname(BAPI_PIPELINES_DIR), "instructions");
+    const customResult = await loadCustomPipelines(BAPI_PIPELINES_DIR, instructionsDir, BUNDLED_INSTRUCTIONS);
+    for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
+        if (key in BUNDLED_PIPELINES) {
+            console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
+        }
+        PIPELINES[key] = pipeline;
+    }
+    Object.assign(INSTRUCTIONS, customResult.instructions);
+    userPipelineKeys = customResult.userPipelineKeys;
+}
+// ---------------------------------------------------------------------------
 // Pipeline Recipe Tools
 // ---------------------------------------------------------------------------
-server.registerTool("get_docs_dir", {
+registerTool("get_docs_dir", {
     description: "Return the locally configured docs directory path (BAPI_DOCS_DIR, default docs/tmp). " +
         "No parameters. Use this instead of reading the BAPI_DOCS_DIR environment variable directly, " +
         "which requires shell access and may be blocked on some AI coding platforms.",
@@ -2213,7 +2627,7 @@ server.registerTool("get_docs_dir", {
 }, async () => {
     return { content: [{ type: "text", text: BAPI_DOCS_DIR }] };
 });
-server.registerTool("list_pipelines", {
+registerTool("list_pipelines", {
     description: "List all available pipeline recipes with their names, descriptions, and required variables. " +
         "No parameters. Use this to discover available pipelines before calling get_pipeline_recipe.",
     inputSchema: {},
@@ -2228,7 +2642,7 @@ server.registerTool("list_pipelines", {
         content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
     };
 });
-server.registerTool("get_pipeline_recipe", {
+registerTool("get_pipeline_recipe", {
     description: "Retrieve a fully resolved pipeline recipe by name. Substitutes variables, resolves instruction " +
         "file references to inline content, and returns an ordered array of executable steps. " +
         "Each step is either an mcp_call (with tool name and params) or an agent_task (with instruction text). " +
@@ -2246,8 +2660,16 @@ server.registerTool("get_pipeline_recipe", {
             .array(z.string())
             .optional()
             .describe("Step tool names or descriptions to omit from the recipe"),
+        auto_approve: z
+            .boolean()
+            .optional()
+            .describe("When true, automatically approve all approval-gated steps. " +
+            "For implement-ticket this skips the commit/push approval pause; " +
+            "for review-ticket this skips the HTML decision page and selects " +
+            "each item's recommended option. Pass via this top-level parameter, " +
+            "not via the variables map."),
     },
-}, async ({ pipeline: pipelineName, variables, skip_steps }) => {
+}, async ({ pipeline: pipelineName, variables, skip_steps, auto_approve }) => {
     const pipelineDef = PIPELINES[pipelineName];
     if (!pipelineDef) {
         const available = Object.keys(PIPELINES).join(", ");
@@ -2262,9 +2684,27 @@ server.registerTool("get_pipeline_recipe", {
                 }],
         };
     }
+    if (variables && "auto_approve" in variables) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: ERROR_CODES[400] ?? "BAD_REQUEST",
+                        status: 400,
+                        message: "Pass auto_approve via the top-level parameter, not via the variables map.",
+                    }),
+                }],
+        };
+    }
     try {
-        const mergedVariables = { docs_dir: BAPI_DOCS_DIR, provider: "", second_opinion: "", ...(variables ?? {}) };
-        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps);
+        const mergedVariables = {
+            docs_dir: BAPI_DOCS_DIR,
+            provider: "",
+            second_opinion: "",
+            auto_approve: auto_approve ? "true" : "",
+            ...(variables ?? {}),
+        };
+        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps, !!auto_approve);
         return {
             content: [{
                     type: "text",
@@ -2286,40 +2726,158 @@ server.registerTool("get_pipeline_recipe", {
     }
 });
 // ---------------------------------------------------------------------------
-// generate_decision_page
+// Pipeline Execution Tools (BAPI-275)
 // ---------------------------------------------------------------------------
-server.registerTool("generate_decision_page", {
-    description: "Generate a local HTML decision page for capturing user decisions on ticket review findings. " +
-        "Renders recommendation-driven review decisions with custom options from resolution guide " +
-        "decision trees, plus confirmed improvements. The user opens the HTML file " +
-        "in a browser, makes selections, and copies the resulting JSON output back to the agent.",
+//
+// run_pipeline / resume_pipeline / list_pipeline_runs promote pipelines from
+// declarative JSON recipes into first-class callable operations. They share
+// a unified response envelope (status: completed | needs_agent_task | failed)
+// with a strict error_code enum (VALIDATION | NOT_FOUND | EXPIRED |
+// REPO_MISMATCH | TOOL_ERROR). Pipeline state is persisted server-side; the
+// idle TTL defaults to 24 hours and is auto-extended on every state
+// transition.
+function buildPipelineCatalogDescription() {
+    const lines = [];
+    for (const [key, pipeline] of Object.entries(PIPELINES)) {
+        const source = userPipelineKeys.has(key) ? " (user)" : "";
+        const desc = pipeline.description ?? "";
+        lines.push(`- ${key}${source} — ${desc}`);
+    }
+    return lines.join("\n");
+}
+function buildPipelineOrchestratorDeps() {
+    return {
+        baseUrl: BASE_URL,
+        apiKey: API_KEY,
+        repoName: REPO_NAME,
+        docsDir: BAPI_DOCS_DIR,
+        pipelines: PIPELINES,
+        instructions: INSTRUCTIONS,
+        toolHandlers: TOOL_HANDLERS,
+    };
+}
+registerTool("run_pipeline", {
+    description: "Execute a Bridge API pipeline by name. The orchestrator runs steps sequentially, " +
+        "dispatching mcp_call steps in-process and pausing on agent_task steps with a " +
+        "needs_agent_task envelope. Returns a unified envelope keyed on `status`: " +
+        "`completed` (terminal success with `results`), `needs_agent_task` (pause — read " +
+        "`instruction`, perform the task, then call `resume_pipeline` with the resulting " +
+        "string as `agent_result`), or `failed` (terminal error — check `error_code`: " +
+        "VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). " +
+        "Paused runs auto-expire after an idle TTL (default 24 hours; override with " +
+        "`ttl_seconds`). The TTL is reset on every state transition.\n\n" +
+        "Available pipelines:\n" +
+        buildPipelineCatalogDescription(),
     inputSchema: {
-        ticket_key: z.string().describe("Jira ticket key, e.g. BAPI-123"),
-        actionable_items: z
-            .array(z.object({
-            id: z.string().min(1),
-            question: z.string().min(1),
-            context: z.string().min(1),
-            source: z.string().min(1).describe("Source reference from the evaluation, e.g. 'Clarifying Q3 (initial round)'"),
-            recommendation_index: z.number().int().min(0).describe("0-based index of the recommended option in the options array"),
-            options: z.array(z.string().min(1)).min(1).describe("Option labels from resolution guide decision tree branches. Values are auto-generated."),
-        }))
+        pipeline: z
+            .string()
+            .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+        variables: z
+            .record(z.string())
             .optional()
-            .default([])
-            .describe("Actionable review decisions with option labels from resolution guide decision trees. 'None of these' auto-appended."),
-        clear_improvements: z
-            .array(z.object({
-            id: z.string().min(1),
-            title: z.string().min(1),
-            action: z.string().min(1),
-            confidence: z.string().min(1),
-            source: z.string().min(1).describe("Source reference from the evaluation"),
-        }))
+            .describe("Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' }). " +
+            "Do NOT pass `auto_approve` here — use the top-level parameter."),
+        auto_approve: z
+            .union([z.boolean(), z.literal("true"), z.literal("false")])
             .optional()
-            .default([])
-            .describe("Confirmed improvements displayed as informational list, not submitted."),
+            .describe("When true, approval-gated mcp_call steps execute directly. When false or " +
+            "omitted, the orchestrator synthesises a needs_agent_task pause so the agent " +
+            "can confirm with the user before resuming. Accepts boolean or 'true'/'false' " +
+            "strings for MCP clients that serialize booleans as strings."),
+        ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Override the default 24-hour idle TTL for this run. Must be a positive integer."),
+    },
+}, async (input) => {
+    const result = await runPipeline(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("resume_pipeline", {
+    description: "Resume a paused pipeline run with the result of the agent_task. Provide the " +
+        "`pipeline_run_id` returned by the prior needs_agent_task envelope, and the string " +
+        "the instruction's `## Return` section asked you to produce as `agent_result`. " +
+        "`agent_result` is always a string — do not wrap it in JSON unless the instruction " +
+        "explicitly asked you to serialize structured output. Returns the same unified " +
+        "envelope shape as `run_pipeline`.",
+    inputSchema: {
+        pipeline_run_id: z
+            .string()
+            .describe("The pipeline_run_id returned by a prior needs_agent_task envelope"),
+        agent_result: z
+            .string()
+            .describe("The string the paused instruction's ## Return section asked you to produce"),
     },
 }, async (input) => {
+    const result = await resumePipeline(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("list_pipeline_runs", {
+    description: "List recent pipeline runs for the configured repository, newest first. Returns " +
+        "metadata only — `resolved_recipe`, resolved params, instruction text, results, " +
+        "and agent outputs are intentionally excluded. Use this to recover a " +
+        "`pipeline_run_id` when an earlier needs_agent_task envelope is no longer in " +
+        "scope (e.g. after compaction or a client restart). " +
+        "Optionally filter by `status`: running | paused | completed | failed | expired.",
+    inputSchema: {
+        status: z
+            .enum(["running", "paused", "completed", "failed", "expired"])
+            .optional()
+            .describe("Optional status filter"),
+    },
+}, async (input) => {
+    const result = await listPipelineRuns(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("delete_pipeline_run", {
+    description: "Delete a pipeline run row (any status). Use this to discard orphaned `running` " +
+        "rows from a previous session that can't be resumed (resume_pipeline only accepts " +
+        "`paused`), to clean up after a failed run, or to remove a no-longer-needed paused " +
+        "session. Returns `{ status: 'completed', deleted: true, pipeline_run_id }` on " +
+        "success, or a `failed` envelope with error_code in (VALIDATION | NOT_FOUND | " +
+        "REPO_MISMATCH | TOOL_ERROR). Repo-scoped: the row's stored repo_name must match " +
+        "the caller's repo.",
+    inputSchema: {
+        pipeline_run_id: z
+            .string()
+            .describe("UUID of the pipeline run to delete."),
+    },
+}, async (input) => {
+    const result = await deletePipelineRun(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// generate_decision_page
+// ---------------------------------------------------------------------------
+registerTool("generate_decision_page", {
+    description: "Generate a local HTML decision page for capturing user decisions on ticket review findings. " +
+        "Renders recommendation-driven review decisions sourced from the combined review-and-resolution " +
+        "document, with per-option consequence lines, a closed-by-default codebase-evidence disclosure, " +
+        "and confirmed improvements. The user opens the HTML file in a browser, makes selections, and " +
+        "copies the resulting JSON output back to the agent.",
+    inputSchema: DecisionPageInputShape,
+}, async (input) => {
+    // Returned messages travel through JSON.stringify in the MCP envelope below,
+    // never into HTML, so echoing untrusted input back to the caller is safe here.
+    // Do not reuse this helper in any path that renders the message into HTML.
     const validationError = (message) => ({
         content: [{
                 type: "text",
@@ -2343,21 +2901,27 @@ server.registerTool("generate_decision_page", {
                 }],
         };
     }
-    // Validate actionable_items
+    // Validate actionable_items: cross-item invariants Zod cannot express.
+    // Per-item bounds (recommendation_index < options.length, parity, branch
+    // count, etc.) are enforced by the schema's superRefine.
     const seenIds = new Set();
     for (const item of input.actionable_items) {
         if (seenIds.has(item.id)) {
             return validationError(`Duplicate actionable_items id: "${item.id}"`);
         }
         seenIds.add(item.id);
-        if (item.recommendation_index >= item.options.length) {
-            return validationError(`Item "${item.id}": recommendation_index ${item.recommendation_index} is out of bounds (${item.options.length} options).`);
-        }
         const noneLabel = item.options.find((label) => label.toLowerCase() === "none of these");
         if (noneLabel) {
             return validationError(`Item "${item.id}": option label "${noneLabel}" is reserved and auto-appended by the tool.`);
         }
     }
+    const seenCiIds = new Set();
+    for (const ci of input.clear_improvements) {
+        if (seenCiIds.has(ci.id)) {
+            return validationError(`Duplicate clear_improvements id: "${ci.id}"`);
+        }
+        seenCiIds.add(ci.id);
+    }
     // Read design assets and base64-encode for embedding
     const assetsDir = path.join(PROJECT_ROOT, "design-assets");
     const fontsDir = path.join(PROJECT_ROOT, "public", "fonts");
@@ -2399,17 +2963,6 @@ server.registerTool("generate_decision_page", {
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-// Load custom user pipelines before accepting connections
-const instructionsDir = path.join(path.dirname(BAPI_PIPELINES_DIR), "instructions");
-const customResult = await loadCustomPipelines(BAPI_PIPELINES_DIR, instructionsDir, BUNDLED_INSTRUCTIONS);
-for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
-    if (key in BUNDLED_PIPELINES) {
-        console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
-    }
-    PIPELINES[key] = pipeline;
-}
-Object.assign(INSTRUCTIONS, customResult.instructions);
-userPipelineKeys = customResult.userPipelineKeys;
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error("Bridge API MCP server running on stdio");