@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/conductor/recovery-operations.js

@@ -0,0 +1,219 @@
+/**
+ * Shared Bridge API operator-recovery operations (BAPI-872).
+ *
+ * Centralizes stop, abandon, and ticket unpark/adopt-current-head-and-unpark so
+ * the conductor CLI recovery verbs (`recovery-cli.ts`) and `plane down`
+ * (`../plane/shutdown.ts`, wired through `../plane/cli.ts`) share EXACTLY the
+ * same stop semantics, and so this module — never a caller — owns every
+ * ticket-recovery `row_version` read, retry, and idempotency-key decision.
+ *
+ * This module is a pure result-classification layer over the typed Bridge API
+ * client (`bridge-api-client.ts`). It prints nothing, never touches argv, and
+ * never renders operator-facing text — every result here is a discriminated
+ * union carrying only semantic outcomes and identifiers, and deliberately never
+ * a `row_version` or other CAS-internal value. Rendering belongs to the two
+ * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
+ */
+import { randomUUID } from "crypto";
+import { adoptCurrentHeadAndUnparkTicket, ConductorBridgeApiError, fetchEpicRunState, safeDiagnosticMessage, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, } from "./bridge-api-client.js";
+/**
+ * Bounded total attempts for a ticket-recovery CAS retry loop. Each attempt
+ * begins with a fresh, authoritative state read — so this bounds full
+ * read-then-mutate cycles, not raw HTTP calls.
+ */
+export const RECOVERY_TICKET_RETRY_LIMIT = 3;
+/**
+ * Stop an epic run through the existing `stop` endpoint, classifying every
+ * outcome the endpoint can produce: a freshly committed stop, an idempotent
+ * repeat, a terminal refusal, or an unreachable/failed API.
+ *
+ * State is re-read ONLY on a terminal refusal, to report the run's actual
+ * `done`/`abandoned` status — never on the ordinary committed or idempotent
+ * paths, which need no second read.
+ */
+export async function stopEpicRunRecovery(access, options) {
+    try {
+        const response = await stopEpicRun(access, {
+            epicRunId: options.epicRunId,
+            reason: options.reason,
+        });
+        return response.committed
+            ? { ok: true, kind: "committed", epicRunId: options.epicRunId }
+            : { ok: true, kind: "already-stopped", epicRunId: options.epicRunId };
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError &&
+            err.status === 409 &&
+            err.errorCode === "RUN_TERMINAL") {
+            const status = await readTerminalRunStatus(access, options.epicRunId);
+            return { ok: false, kind: "terminal", epicRunId: options.epicRunId, status };
+        }
+        return {
+            ok: false,
+            kind: "unavailable",
+            epicRunId: options.epicRunId,
+            message: safeDiagnosticMessage(err, "stop request failed"),
+        };
+    }
+}
+/**
+ * Best-effort read of a run's actual status for a terminal-refusal report.
+ * Never throws: an unreadable state still renders SOME terminal report rather
+ * than losing the stop refusal itself to a secondary read failure.
+ */
+async function readTerminalRunStatus(access, epicRunId) {
+    try {
+        const state = await fetchEpicRunState(access, epicRunId);
+        return state.epic_run.status;
+    }
+    catch {
+        return "terminal";
+    }
+}
+/**
+ * Abandon an epic run through the existing status-CAS PATCH lane
+ * (`updateEpicRunStatus`), reading the run's current status first so the PATCH
+ * always carries a freshly observed `expectedStatus` — never issued without
+ * one. An already-abandoned run is a safe no-op success; a lost CAS (the
+ * status moved concurrently) fails safely rather than retrying an unobserved
+ * transition or re-issuing an unguarded PATCH.
+ */
+export async function abandonEpicRunRecovery(access, options) {
+    let state;
+    try {
+        state = await fetchEpicRunState(access, options.epicRunId);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            kind: "unavailable",
+            epicRunId: options.epicRunId,
+            message: safeDiagnosticMessage(err, "could not read run state"),
+        };
+    }
+    const currentStatus = state.epic_run.status;
+    if (currentStatus === "abandoned") {
+        return { ok: true, kind: "already-abandoned", epicRunId: options.epicRunId };
+    }
+    try {
+        await updateEpicRunStatus(access, {
+            epicKey: options.epicRunId,
+            status: "abandoned",
+            expectedStatus: currentStatus,
+        });
+        return { ok: true, kind: "abandoned", epicRunId: options.epicRunId };
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError && err.status === 400) {
+            // The status-CAS PATCH refused: the run's status moved concurrently since
+            // the read above. Never retried here — an unobserved transition must not
+            // be guessed at, and this is precisely why abandon reads state fresh on
+            // every invocation rather than caching or reusing a prior read.
+            return {
+                ok: false,
+                kind: "concurrent-change",
+                epicRunId: options.epicRunId,
+                message: "the run's status changed concurrently; re-check its state and retry",
+            };
+        }
+        return {
+            ok: false,
+            kind: "unavailable",
+            epicRunId: options.epicRunId,
+            message: safeDiagnosticMessage(err, "abandon request failed"),
+        };
+    }
+}
+/**
+ * The shared bounded-retry engine behind both ticket recovery operations.
+ *
+ * Every attempt — including every retry after a CAS conflict — begins with a
+ * fresh, authoritative `fetchEpicRunState` read. A conflict's own
+ * `current_row_version` is NEVER substituted for that reread: the reread is
+ * what proves the version is authoritative, not merely the latest one the
+ * conflict payload happened to report. Bounded to
+ * {@link RECOVERY_TICKET_RETRY_LIMIT} full read-then-mutate cycles; exhausting
+ * it is reported as `concurrent-change-exhausted`, never as an infinite loop.
+ *
+ * ONE idempotency key is generated per invocation and reused across every
+ * retry within it — a distinct recovery-operation call gets its own key.
+ */
+async function ticketRecoveryWithRetry(access, options, mutate) {
+    const idempotencyKey = randomUUID();
+    for (let attempt = 0; attempt < RECOVERY_TICKET_RETRY_LIMIT; attempt += 1) {
+        let state;
+        try {
+            state = await fetchEpicRunState(access, options.epicRunId);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                kind: "unavailable",
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+                message: safeDiagnosticMessage(err, "could not read run state"),
+            };
+        }
+        const ticket = state.ticket_statuses.find((t) => t.ticket_key === options.ticketKey);
+        if (!ticket) {
+            return {
+                ok: false,
+                kind: "ticket-not-found",
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+            };
+        }
+        let result;
+        try {
+            result = await mutate(access, {
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+                expectedRowVersion: ticket.row_version,
+                idempotencyKey,
+                reason: options.reason,
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                kind: "unavailable",
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+                message: safeDiagnosticMessage(err, "recovery request failed"),
+            };
+        }
+        if (result.ok) {
+            return {
+                ok: true,
+                kind: "unparked",
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+                status: result.ticket_status.status,
+            };
+        }
+        // `result.kind === "cas-conflict"`: a concurrent write moved the ticket's
+        // row_version between our read and our mutate. Loop back to a fresh read —
+        // never reuse `result.current_row_version` here.
+    }
+    return {
+        ok: false,
+        kind: "concurrent-change-exhausted",
+        epicRunId: options.epicRunId,
+        ticketKey: options.ticketKey,
+    };
+}
+/**
+ * Unpark a parked `needs_human` ticket, with a bounded authoritative-reread
+ * retry on a concurrent `row_version` bump.
+ */
+export async function unparkEpicTicketWithRetry(access, options) {
+    return ticketRecoveryWithRetry(access, options, (a, args) => unparkEpicTicket(a, args));
+}
+/**
+ * Adopt the current PR head and unpark a parked ticket, sharing the identical
+ * reread-and-retry discipline. The adopt-current-head client — never the
+ * ordinary unpark client — is called for every attempt.
+ */
+export async function adoptCurrentHeadAndUnparkWithRetry(access, options) {
+    return ticketRecoveryWithRetry(access, options, (a, args) => adoptCurrentHeadAndUnparkTicket(a, args));
+}

package/build/conductor/tools.js

@@ -10,7 +10,7 @@
  */
 import { z } from "zod";
 import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
-import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+import { ConductorValidationError, ConductorWorkerContextRequiredError, toConductorErrorEnvelope, } from "./errors.js";
 import { emitConductorEvent, pollConductorEvents, waitForConductorEvent, getSupervisorSnapshot, sendWorkerMessage, } from "./store.js";
 import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
 import { waitForDoneGate, resolveDispatchRunIdForBinding } from "./pr-ci-producer.js";
@@ -266,6 +266,15 @@ function registerWaitForDoneGateTool(registerTool) {
             // deterministic id are derived purely and the id is forwarded to the CLI,
             // so dedup happens server-side on the events.id UNIQUE constraint — the
             // worker path performs NO in-process ledger read or write.
+            //
+            // BAPI-772: this emit leg inherits the runtime contract from
+            // `resolveWorkerLedgerCliRuntime`, which is reached only when an emit is
+            // actually attempted — read-only gate work (binding resolution, CI
+            // polling) is never preemptively rejected. In a plain session with no
+            // worker env at all, that resolver raises WORKER_CONTEXT_REQUIRED, so the
+            // gate explains itself instead of surfacing an opaque 503; a partially
+            // configured or corrupted worker runtime still fails loud with
+            // LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE. Nothing falls back in-process.
             emitIfNew: (input, dimensions) => emitConductorEventIfNewViaCli(input, dimensions),
         });
         return jsonResult({
@@ -351,8 +360,28 @@ function registerCheckMessagesTool(registerTool) {
             limit: z.number().int().positive().max(100).optional().describe("Max messages to deliver/ack (default 10, max 100)."),
         },
     }, withConductorToolErrorHandling(async (args) => {
-        const runId = args.run_id ?? process.env.BAPI_CONDUCTOR_RUN_ID ?? "";
-        const workerId = args.worker_id ?? process.env.BAPI_CONDUCTOR_WORKER_ID ?? "";
+        const runIdArg = args.run_id;
+        const workerIdArg = args.worker_id;
+        const runIdEnv = process.env.BAPI_CONDUCTOR_RUN_ID;
+        const workerIdEnv = process.env.BAPI_CONDUCTOR_WORKER_ID;
+        // BAPI-772: a call with NEITHER argument supplied and NEITHER env var set is
+        // a plain MCP session — nothing is broken, the tool is simply worker-scoped.
+        // Return the typed guidance envelope instead of an opaque validation error.
+        // Any other shape (an explicit blank id, one id present and the other not, a
+        // partially-set worker env) is still malformed identity and keeps the
+        // existing fail-loud VALIDATION_ERROR: a broken worker context must never be
+        // relabeled as an ordinary session.
+        if (runIdArg === undefined &&
+            workerIdArg === undefined &&
+            runIdEnv === undefined &&
+            workerIdEnv === undefined) {
+            throw new ConductorWorkerContextRequiredError([
+                "BAPI_CONDUCTOR_RUN_ID",
+                "BAPI_CONDUCTOR_WORKER_ID",
+            ]);
+        }
+        const runId = runIdArg ?? runIdEnv ?? "";
+        const workerId = workerIdArg ?? workerIdEnv ?? "";
         if (runId.trim().length === 0 || workerId.trim().length === 0) {
             throw new ConductorValidationError("Conductor worker identity is unavailable: provide run_id + worker_id, or set BAPI_CONDUCTOR_RUN_ID and BAPI_CONDUCTOR_WORKER_ID.");
         }

package/build/conductor/worker-ledger-cli.js

@@ -16,6 +16,12 @@
  * to the worker's own `process.execPath`. Falling back would re-introduce the
  * native load into the worker Node — the exact failure mode this slice removes.
  *
+ * BAPI-772 adds ONE distinction on top of that contract, and it changes no
+ * fallback behavior: when BOTH worker variables are undefined there is no worker
+ * at all (a plain MCP session), which raises the typed
+ * {@link ConductorWorkerContextRequiredError} guidance envelope instead. Every
+ * partially-configured or invalid runtime keeps failing loud exactly as before.
+ *
  * Security: argv is always a fixed LIST (`execFile`, never `shell: true`, never a
  * command string). Event JSON payloads cross via STDIN (`--data-json-stdin`), so
  * raw payloads/secrets never enter the process argument list. Every failure is
@@ -24,7 +30,7 @@
  */
 import * as nodeChildProcess from "node:child_process";
 import { isAbsolute as pathIsAbsolute } from "node:path";
-import { ConductorLedgerSubprocessRuntimeError, } from "./errors.js";
+import { ConductorLedgerSubprocessRuntimeError, ConductorWorkerContextRequiredError, } from "./errors.js";
 import { makeProducerDedupeKey, makeStableProducerEventId, } from "./producer-ledger.js";
 /** The env key that carries the captured conductor Node executable path. */
 export const CONDUCTOR_NODE_PATH_ENV = "CONDUCTOR_NODE_PATH";
@@ -60,10 +66,30 @@ function nonEmpty(value) {
  * non-empty. On any failure this throws a typed
  * {@link ConductorLedgerSubprocessRuntimeError}; it NEVER falls back to
  * `process.execPath`.
+ *
+ * BAPI-772 splits ABSENCE from BREAKAGE, and only at the top:
+ *
+ *   - BOTH variables undefined → {@link ConductorWorkerContextRequiredError}.
+ *     There is no worker runtime because there is no worker: this is a plain MCP
+ *     session, and the caller deserves guidance, not a 503.
+ *   - anything else — one variable present and the other not, an empty or
+ *     whitespace-only value, a relative path, an unusable CLI file — keeps the
+ *     existing fail-loud `LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE` mapping. A
+ *     half-configured or corrupted worker runtime is a real fault and must never
+ *     be relabeled as an ordinary plain session.
  */
 export function resolveWorkerLedgerCliRuntime(deps = {}) {
     const env = deps.env ?? process.env;
     const isAbsolute = deps.isAbsolute ?? pathIsAbsolute;
+    // `undefined` specifically — an env var SET to "" is present-but-invalid and
+    // falls through to the fail-loud path below.
+    if (env[CONDUCTOR_NODE_PATH_ENV] === undefined &&
+        env[BAPI_CONDUCTOR_CLI_FILE_ENV] === undefined) {
+        throw new ConductorWorkerContextRequiredError([
+            CONDUCTOR_NODE_PATH_ENV,
+            BAPI_CONDUCTOR_CLI_FILE_ENV,
+        ]);
+    }
     const nodePathRaw = env[CONDUCTOR_NODE_PATH_ENV];
     if (!nonEmpty(nodePathRaw)) {
         throw new ConductorLedgerSubprocessRuntimeError("missing", CONDUCTOR_NODE_PATH_ENV);