@bridge_gpt/mcp-server 0.2.52 → 0.2.53

package/build/conductor/tools.js

@@ -14,7 +14,7 @@
  */
 import { z } from "zod";
 import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
-import { resolveConductorBridgeApiAccess, fetchEpicRunState, ConductorBridgeApiError } from "./bridge-api-client.js";
+import { resolveConductorBridgeApiAccess, fetchEpicRunState, fetchExplainRun, ConductorBridgeApiError, } from "./bridge-api-client.js";
 function jsonResult(value) {
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
 }
@@ -70,6 +70,57 @@ function registerGetEpicSnapshotTool(registerTool) {
         }
     }));
 }
+function registerExplainRunTool(registerTool) {
+    registerTool("explain_run", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        // Compressed to fit MAX_DESC_CHARS (350) without a waiver. What survives
+        // is the field list: a caller cannot discover the answer shape from a
+        // tool that only says "explain a run", and the whole point of the tool is
+        // that the answer is in one place.
+        description: "Explain why a Conductor epic run, or one ticket in it, is stuck. One snapshot: " +
+            "current gate, latest observation and age, outstanding jobs with queue position, " +
+            "lease owner/expiry, blocker reasons, expected-vs-observed head SHA, committed and " +
+            "pending disposition, usage ceiling. Pass ticket_key to narrow. Read-only; 404 " +
+            "returns status 'unknown'.",
+        inputSchema: {
+            epic_run_id: z
+                .string()
+                .min(1)
+                .describe("Epic run UUID or epic key (e.g. EPIC-123)."),
+            ticket_key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Narrow the answer to one ticket in the run."),
+        },
+    }, withConductorToolErrorHandling(async (args) => {
+        const epicRunId = args.epic_run_id;
+        const ticketKey = args.ticket_key;
+        const scope = ticketKey === undefined ? "run" : "ticket";
+        const accessResult = await resolveConductorBridgeApiAccess();
+        if (!accessResult.ok) {
+            throw new ConductorValidationError(accessResult.error);
+        }
+        try {
+            return jsonResult(await fetchExplainRun(accessResult.access, epicRunId, ticketKey));
+        }
+        catch (error) {
+            if (error instanceof ConductorBridgeApiError && error.status === 404) {
+                // Scope-specific, so a caller can tell "no such run" from "that run
+                // exists but has no such ticket" — the server distinguishes them and
+                // collapsing both to one envelope would throw that away. No server
+                // detail is echoed either way.
+                return jsonResult({ status: "unknown", scope });
+            }
+            throw error;
+        }
+    }));
+}
 /**
  * Register the conductor MCP tool surface through the host's `registerTool`
  * wrapper. Keeping registration in this single module keeps `index.ts` thin.
@@ -78,10 +129,12 @@ function registerGetEpicSnapshotTool(registerTool) {
  * handler returns the same `{ content: [{ type: "text", text }] }` shape every
  * Bridge tool uses, just expressed with a simpler local type.
  *
- * BAPI-909 reduced this registrar to `get_epic_snapshot`. It stays a registrar
- * rather than a bare call so the `conductor` group keeps one registration seam.
+ * BAPI-909 reduced this registrar to `get_epic_snapshot`; BAPI-1028 added
+ * `explain_run` beside it. The registrar shape is what made that a one-line
+ * change rather than an edit to `index.ts`.
  */
 export function registerConductorTools(registerTool) {
     const reg = registerTool;
     registerGetEpicSnapshotTool(reg);
+    registerExplainRunTool(reg);
 }