@bridge_gpt/mcp-server 0.1.14 → 0.1.17

package/build/index.js

@@ -16,16 +16,20 @@ import { writeFile, mkdir, readFile, stat } from "fs/promises";
 import path from "path";
 import { execSync } from "child_process";
 import { createRequire } from "module";
-import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS } from "./pipelines.generated.js";
+import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS, CHAIN_RECIPES } from "./pipelines.generated.js";
 import { COMMANDS } from "./commands.generated.js";
 import { AGENTS } from "./agents.generated.js";
 import { VERSION } from "./version.generated.js";
 import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
+import { runStartTicketsCli } from "./start-tickets.js";
+import { runDoctorCli } from "./doctor.js";
+import { runScheduleRunCli } from "./schedule-run.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
-import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, } from "./pipeline-orchestrator.js";
+import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, deriveIdeaHash, } from "./pipeline-orchestrator.js";
+import { runFullAutomation, resumeFullAutomation, } from "./chain-orchestrator.js";
 // Mutable pipeline/instruction state — starts with bundled, merged with user at startup
 const PIPELINES = { ...BUNDLED_PIPELINES };
 const INSTRUCTIONS = { ...BUNDLED_INSTRUCTIONS };
@@ -125,6 +129,8 @@ async function createTicketRequest(params) {
         payload.labels = params.labels;
     if (params.assignee)
         payload.assignee = params.assignee;
+    if (params.parent_key)
+        payload.parent_key = params.parent_key;
     const resp = await fetch(buildUrl("/create-ticket"), {
         method: "POST",
         headers: POST_HEADERS,
@@ -610,41 +616,54 @@ body explicitly says to serialize structured output.
     }
 }
 // ---------------------------------------------------------------------------
-// CLI: --init
+// CLI subcommand dispatch
 // ---------------------------------------------------------------------------
-if (process.argv.includes("--init")) {
+//
+// `--init`, `--upgrade`, and the positional `start-tickets` subcommand are all
+// routed through a single ``dispatchCliSubcommand`` guard that runs and exits
+// BEFORE the MCP server is constructed and connected. This keeps the single
+// existing ``bridge-api-mcp-server`` bin and leaves a clean seam for future
+// subcommands.
+/**
+ * Ensure a ``package.json`` exists in ``cwd`` for CLI commands that scaffold
+ * into a project. Returns ``null`` on success, or the exact user-facing error
+ * string (preserved verbatim from the previous standalone guards).
+ */
+async function ensurePackageJsonForCliCommand(flagName, cwd) {
     try {
-        await stat(path.join(process.cwd(), "package.json"));
+        await stat(path.join(cwd, "package.json"));
+        return null;
     }
     catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--init must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+        return ("Error: No package.json found in current directory.\n" +
+            `${flagName} must be run from your project root (the directory containing package.json).`);
+    }
+}
+/** Run the ``--init`` scaffolding flow. Returns a process exit code. */
+async function runInitCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--init", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        await runInit(process.cwd());
-        process.exit(0);
+        await runInit(cwd);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --init failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
-// ---------------------------------------------------------------------------
-// CLI: --upgrade
-// ---------------------------------------------------------------------------
-if (process.argv.includes("--upgrade")) {
-    try {
-        await stat(path.join(process.cwd(), "package.json"));
-    }
-    catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--upgrade must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+/** Run the ``--upgrade`` flow (npm install latest + re-scaffold). */
+async function runUpgradeCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--upgrade", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        const cwd = process.cwd();
         const oldVersion = VERSION;
         console.log("Upgrading @bridge_gpt/mcp-server to latest...\n");
         execSync("npm i @bridge_gpt/mcp-server@latest", { stdio: "inherit" });
@@ -660,14 +679,58 @@ if (process.argv.includes("--upgrade")) {
         console.log("\nRefreshing scaffolded artifacts...\n");
         await runInit(cwd);
         console.log("\nUpgrade complete.");
-        process.exit(0);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --upgrade failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
+/**
+ * Route CLI subcommands before MCP server startup. Returns an exit code to
+ * exit the process with, or ``null`` to continue to normal MCP server startup.
+ *
+ * ``--init`` takes precedence over ``--upgrade`` (both are position-independent
+ * flags); ``start-tickets`` is a positional subcommand. Any other unknown,
+ * non-flag positional first token is rejected.
+ */
+async function dispatchCliSubcommand(argv) {
+    const cwd = process.cwd();
+    // A positional subcommand owns the rest of argv, so e.g. `start-tickets --init`
+    // is a start-tickets invocation, not an --init one. Check it before the
+    // position-independent --init / --upgrade flag guards.
+    if (argv[0] === "start-tickets") {
+        return runStartTicketsCli(argv.slice(1));
+    }
+    // The read-only `doctor` subcommand is routed beside start-tickets, before the
+    // flag guards and well before MCP server construction (it never starts the server).
+    if (argv[0] === "doctor") {
+        return runDoctorCli(argv.slice(1));
+    }
+    // The local-only `schedule-run` subcommand (BAPI-327) is likewise a positional
+    // subcommand that owns the rest of argv, routed before the --init / --upgrade
+    // flag guards and never starts the MCP server.
+    if (argv[0] === "schedule-run") {
+        return runScheduleRunCli(argv.slice(1));
+    }
+    // --init takes precedence over --upgrade; both are position-independent flags.
+    if (argv.includes("--init")) {
+        return runInitCli(cwd);
+    }
+    if (argv.includes("--upgrade")) {
+        return runUpgradeCli(cwd);
+    }
+    if (argv.length > 0 && !argv[0].startsWith("-")) {
+        console.error(`Error: Unknown subcommand '${argv[0]}'. Run with --help for usage, or omit subcommands to start the MCP server.`);
+        return 1;
+    }
+    return null;
+}
+const cliExitCode = await dispatchCliSubcommand(process.argv.slice(2));
+if (cliExitCode !== null) {
+    process.exit(cliExitCode);
+}
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
@@ -801,7 +864,7 @@ registerTool("get_project_standards", {
 });
 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. " +
+        "Filters by query text, status name, label, 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.",
     inputSchema: {
         query: z
@@ -814,6 +877,12 @@ registerTool("get_tickets", {
             .string()
             .optional()
             .describe("Filter by Jira status name (e.g. 'To Do', 'In Progress', 'Done')"),
+        labels: z
+            .string()
+            .optional()
+            .describe("Comma-separated Jira labels. Filters tickets via JQL labels in (...) " +
+            "(matches tickets carrying any of the given labels). Labels cannot contain spaces. " +
+            "Example: \"bapi-idea-to-ticket-fa-1a2b3c\""),
         limit: z
             .number()
             .optional()
@@ -829,12 +898,14 @@ registerTool("get_tickets", {
             .optional()
             .describe("ISO date string (YYYY-MM-DD). Only return tickets updated on or after this date"),
     },
-}, async ({ query, status, limit, offset, updated_since }) => {
+}, async ({ query, status, labels, limit, offset, updated_since }) => {
     const params = { repo_name: REPO_NAME };
     if (query)
         params.query = query;
     if (status)
         params.status = status;
+    if (labels)
+        params.labels = labels;
     if (limit !== undefined)
         params.limit = String(limit);
     if (offset !== undefined && offset > 0)
@@ -849,7 +920,8 @@ registerTool("get_tickets", {
 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.",
+        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets. " +
+        "Use get_comments to fetch comments on the ticket.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -861,11 +933,29 @@ registerTool("get_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
+registerTool("get_comments", {
+    description: "Retrieve all comments on a Jira ticket, oldest-first. " +
+        "Returns an array of {id, author, body, created, updated}. " +
+        "Comment bodies are Markdown (converted from Jira wiki markup). " +
+        "Use this to read what a developer or stakeholder has said on a ticket. " +
+        "Use add_comment to post a new comment.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/comments`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
 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. " +
-        "The description field supports Jira markdown formatting.",
+        "The description field supports Jira markdown formatting. " +
+        "Pass parent_key ONLY when creating a child ticket under an existing Jira Epic; omit it for standalone tickets and for Epic parent creation itself.",
     inputSchema: {
         summary: z.string().describe("Ticket title — keep under 100 characters"),
         description: z
@@ -895,12 +985,17 @@ registerTool("create_ticket", {
             .string()
             .optional()
             .describe("Jira username or account ID of the assignee. Omit to leave unassigned"),
+        parent_key: z
+            .string()
+            .optional()
+            .describe("Optional Jira Epic key to set as the parent of the newly created child issue. " +
+            "Omit for standalone tickets and Epic parent creation."),
     },
-}, async ({ summary, description, file_path, issue_type, priority, labels, assignee }) => {
+}, async ({ summary, description, file_path, issue_type, priority, labels, assignee, parent_key }) => {
     const resolved = await resolveTextOrFile(description, file_path, "description");
     if (!resolved.ok)
         return resolved.errorResponse;
-    const text = await createTicketRequest({ summary, description: resolved.text, issue_type, priority, labels, assignee });
+    const text = await createTicketRequest({ summary, description: resolved.text, issue_type, priority, labels, assignee, parent_key });
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
 registerTool("get_plan", {
@@ -1971,6 +2066,9 @@ const VALID_CONFIG_FIELDS = [
     "template_correctness_standards", "style_correctness_standards",
     "design_principles",
     "post_pr_target_status", "ci_check_config", "ci_followup_config",
+    "allow_mutating_smoke_ops",
+    "selected_mcp_slugs",
+    "base_branch",
 ].join(", ");
 registerTool("list_config_fields", {
     description: "List all configurable fields available for reading and updating via the Bridge API. " +
@@ -2016,18 +2114,104 @@ registerTool("update_config_field", {
         "Returns 400 if the field name is invalid, 404 if the repository has no configuration row yet.",
     inputSchema: {
         field_name: z.string().describe(`The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}`),
-        value: z.string().optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
-            "Omit both value and file_path to set the field to NULL (clearing it)."),
+        value: z.union([z.string(), z.boolean(), z.array(z.string())]).optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
+            "Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops) take true/false. " +
+            "The selected_mcp_slugs field takes a JSON array of supported MCP validation manual slug strings " +
+            "(e.g. [\"b2c-commerce-developer\", \"playwright-mcp\", \"pwa-kit-mcp\"]) — pass an array of strings, " +
+            "not a comma-delimited string; an empty array clears the selection. " +
+            "The base_branch field is a string/null field controlling the development base branch used by PR " +
+            "creation (/create-pr) and start-tickets worktree creation; an empty/null value clears it and " +
+            "automations fall back to 'main'. " +
+            "For string fields, omit both value and file_path to set the field to NULL (clearing it). " +
+            "Scalar boolean fields are NOT NULL and have no clear/null state: omitting the value writes false " +
+            "(matching the API-layer coercion), so pass true/false explicitly."),
         file_path: z.string().optional().describe("Path to a local file whose contents will be used as the new value. " +
             "Useful for large configuration values like detailed review instructions. " +
-            "The file must be UTF-8 encoded and under 1MB."),
+            "The file must be UTF-8 encoded and under 1MB. " +
+            "Not supported for scalar boolean fields like allow_mutating_smoke_ops."),
     },
 }, async ({ field_name, value, file_path }) => {
+    // JSONB array config fields (e.g. selected_mcp_slugs): forward the array value
+    // as JSON. Never join into a comma-delimited string — the backend expects a
+    // real JSON array and validates each slug against the mcp_docs allowlist.
+    const ARRAY_CONFIG_FIELDS = ["selected_mcp_slugs"];
+    if (ARRAY_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a JSON array field; file_path updates are not supported. Pass value as an array of slug strings.`,
+                        }),
+                    }],
+            };
+        }
+        // An omitted value clears the selection (empty array). Any defined value is
+        // forwarded verbatim as JSON so the backend can validate/reject it.
+        const arrayValue = value === undefined ? [] : value;
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: arrayValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    // Scalar boolean config fields: reject file-path updates and normalize boolean
+    // true/false and string "true"/"false" to a real boolean before persisting.
+    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops"];
+    if (BOOLEAN_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a scalar boolean field; file_path updates are not supported. Pass value: true or value: false.`,
+                        }),
+                    }],
+            };
+        }
+        // NOT NULL boolean column: an omitted value writes false (no clear/null state),
+        // intentionally aligned with the API-layer coercion in update_config_field_endpoint.
+        let boolValue = false;
+        if (typeof value === "boolean") {
+            boolValue = value;
+        }
+        else if (typeof value === "string") {
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true") {
+                boolValue = true;
+            }
+            else if (normalized === "false" || normalized === "") {
+                boolValue = false;
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `Invalid value for '${field_name}': '${value}'. Expected true or false.`,
+                            }),
+                        }],
+                };
+            }
+        }
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: boolValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
     // Allow omitting both value and file_path to set NULL
     let finalValue = null;
     let note = "";
     if (value || file_path) {
-        const resolved = await resolveTextOrFile(value, file_path, "value");
+        const resolved = await resolveTextOrFile(typeof value === "string" ? value : undefined, file_path, "value");
         if (!resolved.ok)
             return resolved.errorResponse;
         finalValue = resolved.text;
@@ -2635,7 +2819,7 @@ registerTool("list_pipelines", {
     const list = Object.entries(PIPELINES).map(([key, pipeline]) => ({
         name: key,
         description: pipeline.description ?? "",
-        variables: (pipeline.variables ?? []).filter((v) => v !== "docs_dir"),
+        variables: (pipeline.variables ?? []).filter((v) => v !== "docs_dir" && v !== "idea_hash"),
         source: userPipelineKeys.has(key) ? "user" : "bundled",
     }));
     return {
@@ -2653,7 +2837,7 @@ registerTool("get_pipeline_recipe", {
             .string()
             .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
         variables: z
-            .record(z.string())
+            .record(z.string(), z.string())
             .optional()
             .describe("Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' })"),
         skip_steps: z
@@ -2704,6 +2888,11 @@ registerTool("get_pipeline_recipe", {
             auto_approve: auto_approve ? "true" : "",
             ...(variables ?? {}),
         };
+        // Auto-inject the stable idea-hash (like docs_dir) for the standalone
+        // /idea-to-ticket path, mirroring runPipeline.
+        if ("idea" in mergedVariables) {
+            mergedVariables.idea_hash = deriveIdeaHash(mergedVariables.idea);
+        }
         const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps, !!auto_approve);
         return {
             content: [{
@@ -2756,6 +2945,21 @@ function buildPipelineOrchestratorDeps() {
         toolHandlers: TOOL_HANDLERS,
     };
 }
+// BAPI-326: dependency injection for the full-automation chain orchestrator.
+// Same shape as the pipeline deps plus the bundled chain-recipe registry. The
+// chain orchestrator never imports index.ts; everything flows through here.
+function buildChainOrchestratorDeps() {
+    return {
+        baseUrl: BASE_URL,
+        apiKey: API_KEY,
+        repoName: REPO_NAME,
+        docsDir: BAPI_DOCS_DIR,
+        pipelines: PIPELINES,
+        chainRecipes: CHAIN_RECIPES,
+        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 " +
@@ -2773,7 +2977,7 @@ registerTool("run_pipeline", {
             .string()
             .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
         variables: z
-            .record(z.string())
+            .record(z.string(), z.string())
             .optional()
             .describe("Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' }). " +
             "Do NOT pass `auto_approve` here — use the top-level parameter."),
@@ -2865,6 +3069,85 @@ registerTool("delete_pipeline_run", {
     };
 });
 // ---------------------------------------------------------------------------
+// Full Automation Chain Tools (BAPI-326)
+// ---------------------------------------------------------------------------
+//
+// run_full_automation / resume_full_automation drive an idea through three
+// chained stages (idea-to-ticket -> review-ticket fan-out -> start-tickets CLI
+// seam) via the existing pipeline runner. They share the chain envelope shape
+// (status: needs_agent_task | completed | failed) with a strict error_code
+// enum (VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). Chain
+// state is persisted server-side via /jira/chain-runs/runs. Registered AFTER
+// TOOL_HANDLERS and the pipeline tools so the orchestrator can dispatch the
+// existing child pipelines in-process.
+registerTool("run_full_automation", {
+    description: "Run the full-automation chain for an idea: create ticket(s) " +
+        "(idea-to-ticket), review each created ticket (review-ticket fan-out), " +
+        "then emit the exact `/start-tickets ...` command for you to invoke in " +
+        "this same session. Returns the chain envelope keyed on `status`: " +
+        "`needs_agent_task` (perform the `next_action.instruction`, then call " +
+        "`resume_full_automation` with the result as `agent_result`), `completed`, " +
+        "or `failed` (check `error_code`: VALIDATION | NOT_FOUND | EXPIRED | " +
+        "REPO_MISMATCH | TOOL_ERROR). Provide the idea via `idea` or `idea_file` " +
+        "(mutually exclusive).",
+    inputSchema: {
+        idea: z.string().optional(),
+        idea_file: z.string().optional(),
+        auto_approve: z
+            .union([z.boolean(), z.literal("true"), z.literal("false")])
+            .optional(),
+        scheduled_at: z.string().optional(),
+        max_children: z.number().int().positive().optional(),
+        allow_duplicate: z.boolean().optional(),
+        agent: z.enum(["claude"]).optional(),
+        ttl_seconds: z.number().int().positive().optional(),
+    },
+}, async (input) => {
+    const { idea, idea_file, ...rest } = input;
+    if (idea !== undefined && idea_file !== undefined) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "BAD_REQUEST",
+                        status: 400,
+                        message: "Provide exactly one of `idea` or `idea_file`, not both.",
+                    }),
+                }],
+        };
+    }
+    const resolved = await resolveTextOrFile(idea, idea_file, "idea");
+    if (!resolved.ok) {
+        return resolved.errorResponse;
+    }
+    const result = await runFullAutomation(buildChainOrchestratorDeps(), {
+        idea: resolved.text,
+        ...rest,
+    });
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("resume_full_automation", {
+    description: "Resume a paused full-automation chain run. Provide the `chain_run_id` " +
+        "returned by the prior needs_agent_task envelope and the string the " +
+        "instruction asked you to produce as `agent_result`. Returns the same " +
+        "chain envelope shape as `run_full_automation`.",
+    inputSchema: {
+        chain_run_id: z.string(),
+        agent_result: z.string(),
+    },
+}, async (input) => {
+    const result = await resumeFullAutomation(buildChainOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
 // generate_decision_page
 // ---------------------------------------------------------------------------
 registerTool("generate_decision_page", {

package/build/pipeline-orchestrator.js

@@ -16,7 +16,21 @@
  *     are inlined into the instruction string so the agent can review and
  *     confirm before resuming. (BAPI-275 decisions E-4 / E-36.)
  */
+import { createHash } from "node:crypto";
 import { resolveRecipe } from "./pipeline-utils.js";
+/**
+ * Derive a STABLE, content-addressed hash of an idea — the basis for the
+ * cross-run idempotency label ``bapi-idea-hash-{idea_hash}``. Normalizes
+ * (trim + lowercase + collapse internal whitespace) so cosmetic edits don't
+ * change the hash, then takes the first 12 hex chars of the SHA-256. Unlike the
+ * per-run ``run_id`` label, this is identical every time the same idea is run,
+ * so a re-run of the same idea is reliably caught by label (not just fuzzy
+ * keyword search). Auto-injected as the ``idea_hash`` pipeline variable.
+ */
+export function deriveIdeaHash(idea) {
+    const normalized = String(idea ?? "").trim().toLowerCase().replace(/\s+/g, " ");
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+}
 class PipelinePersistenceError extends Error {
     code;
     constructor(code, message) {
@@ -175,6 +189,10 @@ const ORCHESTRATION_TOOLS = new Set([
     "resume_pipeline",
     "list_pipeline_runs",
     "delete_pipeline_run",
+    // BAPI-326: chain orchestration tools must never be invoked from within a
+    // declarative pipeline step (avoids accidental orchestration recursion).
+    "run_full_automation",
+    "resume_full_automation",
 ]);
 // ---------------------------------------------------------------------------
 // runPipeline
@@ -196,6 +214,12 @@ export async function runPipeline(deps, input) {
         auto_approve: autoApprove ? "true" : "",
         ...(input.variables ?? {}),
     };
+    // Auto-inject the stable idea-hash (like docs_dir) whenever the pipeline was
+    // given an `idea`, so both the chain and standalone callers get the cross-run
+    // idempotency label without computing it themselves.
+    if ("idea" in mergedVariables) {
+        mergedVariables.idea_hash = deriveIdeaHash(mergedVariables.idea);
+    }
     let recipe;
     try {
         recipe = resolveRecipe(pipelineDef, deps.instructions, mergedVariables, undefined, autoApprove);
@@ -227,6 +251,39 @@ export async function runPipeline(deps, input) {
     }
     return continuePipelineExecution(deps, persistence, row, recipe, autoApprove);
 }
+/**
+ * Read-only snapshot of a pipeline run's current persisted state — performs no
+ * execution and no state transition. Used by the chain orchestrator to decide,
+ * at a stage boundary, whether the inner pipeline still needs resuming
+ * (``paused``), has already reached a terminal state (``completed`` / ``failed``)
+ * so the stage can be advanced/failed idempotently, or is in an indeterminate
+ * state that cannot be safely resumed or recovered.
+ */
+export async function peekPipelineRun(deps, pipeline_run_id) {
+    const persistence = createPipelinePersistenceClient({
+        baseUrl: deps.baseUrl,
+        apiKey: deps.apiKey,
+        repoName: deps.repoName,
+    });
+    let row;
+    try {
+        row = await persistence.getRun(pipeline_run_id);
+    }
+    catch (err) {
+        if (err instanceof PipelinePersistenceError) {
+            return failedEnvelope(err.code, err.message, { pipeline_run_id });
+        }
+        return failedEnvelope("TOOL_ERROR", err instanceof Error ? err.message : String(err), { pipeline_run_id });
+    }
+    return {
+        status: row.status,
+        pipeline_run_id: row.pipeline_run_id,
+        pipeline: row.pipeline_name,
+        total_steps: row.resolved_recipe.total_steps,
+        current_step_index: row.current_step_index,
+        results: row.results,
+    };
+}
 // ---------------------------------------------------------------------------
 // resumePipeline
 // ---------------------------------------------------------------------------