@bridge_gpt/mcp-server 0.2.42 → 0.2.43

package/build/conductor/recovery-cli.js

@@ -0,0 +1,313 @@
+/**
+ * `conductor` operator recovery verbs (BAPI-872): `stop-run`, `abandon-run`,
+ * `unpark`, `adopt-current-head-and-unpark`.
+ *
+ * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
+ * none of these four command names is ever registered as an MCP tool, tool
+ * description, or generated tool-schema input (`index-static.test.ts` guards
+ * this). They exist so an operator (or `plane down`, via
+ * `recovery-operations.ts`) can recover a stuck run or ticket WITHOUT
+ * hand-rolling an HTTP request — the exact thing setup-epic's old raw-PATCH
+ * guidance used to ask for.
+ *
+ * Every ticket command's `row_version` CAS handling is entirely internal to
+ * `recovery-operations.ts`. This surface never accepts, echoes, or asks the
+ * operator for a version counter — see {@link REJECTED_VERSION_FLAGS}.
+ */
+import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+const RUN_VALUE_FLAGS = new Set(["--epic-run-id"]);
+const TICKET_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key"]);
+const RECOVERY_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Every spelling of an operator-supplied version counter this surface must
+ * refuse outright (BAPI-872) — row_version handling is internal to
+ * {@link module:./recovery-operations}, and no ticket command may accept one.
+ */
+const REJECTED_VERSION_FLAGS = new Set([
+    "--row-version",
+    "--expected-row-version",
+    "--row_version",
+    "--expected_row_version",
+]);
+/**
+ * Tokenize `--flag value` / `--flag=value` / boolean flags for the recovery
+ * verbs. A rejected version flag throws BEFORE its value (if any) is ever
+ * read, so the offending value is never echoed, normalized, or invited.
+ */
+function tokenizeRecoveryFlags(argv, valueFlags, boolFlags) {
+    const values = new Map();
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h") {
+            bools.add("--help");
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            throw new ConductorValidationError(`Unexpected argument "${token}".`);
+        }
+        const eq = token.indexOf("=");
+        const name = eq >= 0 ? token.slice(0, eq) : token;
+        if (REJECTED_VERSION_FLAGS.has(name)) {
+            throw new ConductorValidationError(`Flag "${name}" is not supported here — row-version handling is internal to ` +
+                "recovery and cannot be supplied by the operator. Omit it; recovery reads the " +
+                "current version itself.");
+        }
+        if (boolFlags.has(name)) {
+            bools.add(name);
+            continue;
+        }
+        if (!valueFlags.has(name)) {
+            throw new ConductorValidationError(`Unknown flag "${name}".`);
+        }
+        let value;
+        if (eq >= 0) {
+            value = token.slice(eq + 1);
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                throw new ConductorValidationError(`Flag "${name}" requires a value.`);
+            }
+            value = next;
+            i += 1;
+        }
+        values.set(name, value);
+    }
+    return { values, bools };
+}
+function parseRunRecoveryArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, RUN_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required and must be non-empty.');
+    }
+    return { epicRunId: epicRunId.trim(), json: bools.has("--json"), help: false };
+}
+function parseTicketRecoveryArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, TICKET_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", ticketKey: "", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required and must be non-empty.');
+    }
+    const ticketKey = values.get("--ticket-key");
+    if (ticketKey === undefined || ticketKey.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--ticket-key" is required and must be non-empty.');
+    }
+    return {
+        epicRunId: epicRunId.trim(),
+        ticketKey: ticketKey.trim(),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared access resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve Bridge API access through the shared credential-store resolution
+ * (never `BAPI_API_KEY` read directly). Prints the sanitized failure itself
+ * and returns `null` on failure so the caller can return exit code `1`
+ * without duplicating the rendering.
+ */
+async function resolveRecoveryAccess(json) {
+    const { resolveConductorBridgeApiAccess } = await import("./bridge-api-client.js");
+    const result = await resolveConductorBridgeApiAccess();
+    if (!result.ok) {
+        if (json) {
+            console.log(JSON.stringify({ ok: false, kind: "unauthorized", error: result.error }));
+        }
+        else {
+            console.error(`Error: ${result.error}`);
+        }
+        return null;
+    }
+    return result.access;
+}
+// ---------------------------------------------------------------------------
+// stop-run
+// ---------------------------------------------------------------------------
+const STOP_RUN_USAGE = [
+    "Usage: conductor stop-run --epic-run-id <id> [--json]",
+    "",
+    "Stop an epic run: block new dispatch and cancel its queued work. The run",
+    "record is preserved (never deleted) so its history stays inspectable.",
+    "Idempotent — repeating it once stopped is a safe no-op.",
+].join("\n");
+function renderStopRunResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok && result.kind === "committed") {
+        console.log(`Run ${result.epicRunId}: stopped. Its queued work was cancelled; the run record ` +
+            "remains available for inspection.");
+        return 0;
+    }
+    if (result.ok && result.kind === "already-stopped") {
+        console.log(`Run ${result.epicRunId}: already stopped; no further action.`);
+        return 0;
+    }
+    if (!result.ok && result.kind === "terminal") {
+        console.error(`Run ${result.epicRunId}: terminal (${result.status}) and cannot be stopped.`);
+        return 1;
+    }
+    console.error(`Run ${result.epicRunId}: could not be stopped — ${result.message}.`);
+    return 1;
+}
+export async function runStopRunCommand(argv) {
+    try {
+        const parsed = parseRunRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(STOP_RUN_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { stopEpicRunRecovery } = await import("./recovery-operations.js");
+        const result = await stopEpicRunRecovery(access, { epicRunId: parsed.epicRunId });
+        return renderStopRunResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// abandon-run
+// ---------------------------------------------------------------------------
+const ABANDON_RUN_USAGE = [
+    "Usage: conductor abandon-run --epic-run-id <id> [--json]",
+    "",
+    "Abandon an epic run — a TERMINAL, IRREVERSIBLE transition. An abandoned run",
+    "can never resume or be reused; start a new run instead. Idempotent —",
+    "repeating it on an already-abandoned run is a safe no-op.",
+].join("\n");
+function renderAbandonRunResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok && result.kind === "abandoned") {
+        console.log(`Run ${result.epicRunId}: abandoned (terminal).`);
+        return 0;
+    }
+    if (result.ok && result.kind === "already-abandoned") {
+        console.log(`Run ${result.epicRunId}: already abandoned (terminal); no further action.`);
+        return 0;
+    }
+    console.error(`Run ${result.epicRunId}: could not be abandoned — ${result.message}.`);
+    return 1;
+}
+export async function runAbandonRunCommand(argv) {
+    try {
+        const parsed = parseRunRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(ABANDON_RUN_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { abandonEpicRunRecovery } = await import("./recovery-operations.js");
+        const result = await abandonEpicRunRecovery(access, { epicRunId: parsed.epicRunId });
+        return renderAbandonRunResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// unpark / adopt-current-head-and-unpark (shared rendering)
+// ---------------------------------------------------------------------------
+const UNPARK_USAGE = [
+    "Usage: conductor unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "",
+    "Move a parked (needs_human) ticket back into its gate machine, once the",
+    "operator has resolved what parked it. Retries a bounded number of times on",
+    "its own if the ticket changes concurrently — never accepts a version counter.",
+].join("\n");
+const ADOPT_CURRENT_HEAD_USAGE = [
+    "Usage: conductor adopt-current-head-and-unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "",
+    "Recover a ticket parked because a human/external push drifted the PR head",
+    "off its anchored commit: adopt the CURRENT PR head and unpark in one step.",
+    "Retries a bounded number of times on its own if the ticket changes",
+    "concurrently — never accepts a version counter.",
+].join("\n");
+function renderTicketRecoveryResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok) {
+        console.log(`Ticket ${result.ticketKey} (run ${result.epicRunId}): unparked — status: ${result.status}.`);
+        return 0;
+    }
+    if (result.kind === "ticket-not-found") {
+        console.error(`Ticket ${result.ticketKey}: not found in run ${result.epicRunId}.`);
+        return 1;
+    }
+    if (result.kind === "concurrent-change-exhausted") {
+        console.error(`Ticket ${result.ticketKey} (run ${result.epicRunId}): could not recover — it kept ` +
+            "changing concurrently. Re-check the run/ticket status and try again.");
+        return 1;
+    }
+    console.error(`Ticket ${result.ticketKey} (run ${result.epicRunId}): could not recover — ${result.message}.`);
+    return 1;
+}
+export async function runUnparkCommand(argv) {
+    try {
+        const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(UNPARK_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { unparkEpicTicketWithRetry } = await import("./recovery-operations.js");
+        const result = await unparkEpicTicketWithRetry(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        return renderTicketRecoveryResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+export async function runAdoptCurrentHeadAndUnparkCommand(argv) {
+    try {
+        const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(ADOPT_CURRENT_HEAD_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { adoptCurrentHeadAndUnparkWithRetry } = await import("./recovery-operations.js");
+        const result = await adoptCurrentHeadAndUnparkWithRetry(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        return renderTicketRecoveryResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}

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));
+}