@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/conductor/bridge-api-client.js

@@ -0,0 +1,625 @@
+/**
+ * TypeScript-side Bridge API access layer for the conductor producer (BAPI-395).
+ *
+ * The producer reads per-repo gate config and polls CI through the EXISTING
+ * Bridge API HTTP surface — it never opens a Postgres connection from TypeScript.
+ * Credential and repo identity resolution reuse the shared
+ * {@link resolveBapiCredentials} / {@link resolveStartTicketsRepoName} boundaries
+ * so the `bapi:<repo>` target can never drift. All errors are sanitized: a thrown
+ * {@link ConductorBridgeApiError} carries only a coarse `kind`, an optional HTTP
+ * status, and generic text — never a response body, header, token, or API key.
+ */
+import os from "node:os";
+import { readFile, stat } from "node:fs/promises";
+import { resolveBapiCredentials } from "../credential-store.js";
+import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
+import { DONE_GATE_CONFIG_FIELD, normalizePrNumber, normalizeSha } from "./git-ci-types.js";
+import { ConductorValidationError } from "./errors.js";
+/** Default Bridge API base URL when `BAPI_BASE_URL` is unset. */
+export const CONDUCTOR_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
+/** Default per-request timeout for conductor Bridge API calls. */
+export const CONDUCTOR_FETCH_TIMEOUT_MS = 30_000;
+/**
+ * Resolve `{ repoName, apiKey, baseUrl }` from the environment, the shared repo
+ * resolver, and the shared credential store. Never throws and never embeds the
+ * secret value in any failure text. No Postgres/DB module is imported here.
+ */
+export async function resolveConductorBridgeApiAccess(deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const homedir = deps.homedir ?? os.homedir;
+    const platform = deps.platform ?? process.platform;
+    const readFileImpl = deps.readFile ?? ((p) => readFile(p, "utf-8"));
+    const statImpl = deps.stat ?? ((p) => stat(p));
+    const repoName = await resolveStartTicketsRepoName({ env, cwd, readFile: readFileImpl });
+    if (!repoName) {
+        return {
+            ok: false,
+            kind: "repo-missing",
+            error: "could not resolve repo name (set BAPI_REPO_NAME or add a valid .bridge/config)",
+        };
+    }
+    let credResult;
+    try {
+        credResult = await resolveBapiCredentials(repoName, {
+            env,
+            homedir,
+            platform,
+            readFile: readFileImpl,
+            stat: statImpl,
+        });
+    }
+    catch {
+        return { ok: false, kind: "credentials-unavailable", error: "failed to resolve Bridge API credentials" };
+    }
+    if (!credResult.ok) {
+        return { ok: false, kind: "credentials-unavailable", error: "Bridge API credentials unavailable" };
+    }
+    const baseUrlRaw = env.BAPI_BASE_URL;
+    const baseUrl = typeof baseUrlRaw === "string" && baseUrlRaw.trim().length > 0
+        ? baseUrlRaw.trim()
+        : CONDUCTOR_DEFAULT_BASE_URL;
+    return { ok: true, access: { repoName, apiKey: credResult.credentials.apiKey, baseUrl } };
+}
+/**
+ * Build a `${baseUrl}/jira${apiPath}` URL with query params, trimming trailing
+ * slashes on the base so there is never a double slash after the host. Query
+ * values are URL-encoded by {@link URL}.
+ */
+export function buildConductorJiraUrl(baseUrl, apiPath, params = {}) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${trimmed}/jira${apiPath}`);
+    for (const [k, v] of Object.entries(params)) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/** Sanitized HTTP error for conductor Bridge API calls — never leaks secrets. */
+export class ConductorBridgeApiError extends Error {
+    kind;
+    status;
+    constructor(kind, status) {
+        super(`Conductor Bridge API request failed (${kind}${typeof status === "number" ? `, status ${status}` : ""})`);
+        this.name = "ConductorBridgeApiError";
+        this.kind = kind;
+        this.status = status;
+    }
+}
+/** GET auth headers. The API key travels ONLY in a header, never in the URL. */
+function conductorGetHeaders(access) {
+    return { "X-API-Key": access.apiKey };
+}
+/**
+ * GET JSON with an `AbortController` timeout. Throws a sanitized
+ * {@link ConductorBridgeApiError} on abort/timeout, network failure, or any
+ * non-2xx response — never including the response body, headers, or API key. The
+ * timer is always cleared.
+ */
+export async function fetchConductorJsonWithTimeout(url, headers, timeoutMs, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let resp;
+        try {
+            resp = await fetchImpl(url, { headers, signal: controller.signal });
+        }
+        catch {
+            // Aborts (timeout), DNS/connection failures, and other fetch exceptions.
+            throw new ConductorBridgeApiError(controller.signal.aborted ? "timeout" : "network");
+        }
+        if (!resp.ok) {
+            if (resp.status === 401 || resp.status === 403) {
+                throw new ConductorBridgeApiError("unauthorized", resp.status);
+            }
+            if (resp.status >= 500) {
+                throw new ConductorBridgeApiError("server", resp.status);
+            }
+            throw new ConductorBridgeApiError("http", resp.status);
+        }
+        try {
+            return await resp.json();
+        }
+        catch {
+            throw new ConductorBridgeApiError("network");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * GET `/jira/config-field/{fieldName}?repo_name=<repo>` and return the raw
+ * `value` payload (or `undefined` when the envelope lacks a `value`). The field
+ * name is URL-encoded; the repo scope is always included.
+ */
+export async function fetchConductorConfigField(access, fieldName, fetchImpl = fetch) {
+    const url = buildConductorJiraUrl(access.baseUrl, `/config-field/${encodeURIComponent(fieldName)}`, {
+        repo_name: access.repoName,
+    });
+    const body = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    if (body && typeof body === "object" && "value" in body) {
+        return body.value;
+    }
+    return undefined;
+}
+/** Fetch the per-repo `conductor_done_gate` config value (raw, unparsed). */
+export function fetchDoneGateConfigField(access, fetchImpl = fetch) {
+    return fetchConductorConfigField(access, DONE_GATE_CONFIG_FIELD, fetchImpl);
+}
+/**
+ * Poll CI checks for a commit through the existing `/poll-ci-checks` endpoint.
+ * Validates `commitRef` with {@link normalizeSha} and rejects BEFORE issuing the
+ * request when it is not a valid SHA. Returns the endpoint response verbatim —
+ * the client never invents `pr_number`/`head_sha` fields.
+ */
+export async function pollCiChecksForCommit(access, commitRef, fetchImpl = fetch) {
+    const sha = normalizeSha(commitRef);
+    if (sha === null) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, "/poll-ci-checks", {
+        repo_name: access.repoName,
+        commit_ref: sha,
+    });
+    return fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+}
+// ---------------------------------------------------------------------------
+// Conductor C6 (BAPI-398): protected VCS merge POST client
+// ---------------------------------------------------------------------------
+/**
+ * Build a `${baseUrl}${apiPath}` URL for non-`/jira` API routes (e.g. the
+ * protected `/vcs/...` merge endpoint), trimming trailing slashes on the base.
+ * Distinct from {@link buildConductorJiraUrl}, which forces a `/jira` prefix.
+ */
+export function buildConductorVcsUrl(baseUrl, apiPath) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    const path = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+    return new URL(`${trimmed}${path}`).toString();
+}
+/** POST auth + content headers. The API key travels ONLY in a header. */
+function conductorPostHeaders(access) {
+    return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
+}
+/**
+ * POST JSON with an `AbortController` timeout, mirroring
+ * {@link fetchConductorJsonWithTimeout}. Throws a sanitized
+ * {@link ConductorBridgeApiError} on abort/timeout, network failure, or any
+ * non-2xx response — never including the response body, headers, API key, or
+ * request body in the error. The timer is always cleared.
+ */
+export async function fetchConductorJsonPostWithTimeout(url, headers, body, timeoutMs, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let resp;
+        try {
+            resp = await fetchImpl(url, { method: "POST", headers, body, signal: controller.signal });
+        }
+        catch {
+            throw new ConductorBridgeApiError(controller.signal.aborted ? "timeout" : "network");
+        }
+        if (!resp.ok) {
+            if (resp.status === 401 || resp.status === 403) {
+                throw new ConductorBridgeApiError("unauthorized", resp.status);
+            }
+            if (resp.status >= 500) {
+                throw new ConductorBridgeApiError("server", resp.status);
+            }
+            throw new ConductorBridgeApiError("http", resp.status);
+        }
+        try {
+            return await resp.json();
+        }
+        catch {
+            throw new ConductorBridgeApiError("network");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Call the protected `POST /vcs/pull-requests/{pr_number}/merge` endpoint. The PR
+ * number lives ONLY in the path; the API key travels ONLY in headers; the body
+ * carries no branch name or provider token. PR number and head SHA are validated
+ * before the request is issued. Throws a sanitized {@link ConductorBridgeApiError}
+ * on any failure.
+ */
+export async function mergePullRequestForGate(access, request, fetchImpl = fetch) {
+    const pr = normalizePrNumber(request.pr_number);
+    const sha = normalizeSha(request.expected_head_sha);
+    if (pr === null || sha === null || !request.action_key || !request.repo_name) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+    const url = buildConductorVcsUrl(access.baseUrl, `/vcs/pull-requests/${pr}/merge`);
+    // The body deliberately omits pr_number (it is in the path) and never includes
+    // a branch name or provider token; extra fields would be rejected server-side.
+    const body = JSON.stringify({
+        repo_name: request.repo_name,
+        expected_head_sha: sha,
+        gate: request.gate,
+        action_key: request.action_key,
+        ...(request.gate_event ? { gate_event: request.gate_event } : {}),
+    });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Local boundary validators (reject before any fetch call)
+// ---------------------------------------------------------------------------
+function requireNonEmptyString(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+function requirePositiveSafeInteger(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+function requireNonNegativeSafeInteger(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+function requireNoSlashPathSegment(value) {
+    if (value.includes("/")) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+const EPIC_TICKET_STATUS_VALUES = [
+    "planned", "ready", "dispatched", "running", "blocked", "abandoned", "done",
+];
+function requireEpicTicketStatusValue(value) {
+    if (typeof value !== "string" || !EPIC_TICKET_STATUS_VALUES.includes(value)) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+const EPIC_DISPATCH_TRANSITION_STATUSES = ["run_spawned", "terminal"];
+function requireEpicDispatchTransitionStatus(value) {
+    if (typeof value !== "string" || !EPIC_DISPATCH_TRANSITION_STATUSES.includes(value)) {
+        throw new ConductorBridgeApiError("invalid-input");
+    }
+}
+// ---------------------------------------------------------------------------
+// Epic Run route constants and path helpers
+// ---------------------------------------------------------------------------
+// TODO(epic-run-store): confirm final protected route prefix remains /jira/epic-runs against the sibling durable-store routes.
+const EPIC_RUNS_API_PREFIX = "/epic-runs";
+function epicRunApiPath(epicKey) {
+    return `${EPIC_RUNS_API_PREFIX}/runs/${encodeURIComponent(epicKey)}`;
+}
+function epicDispatchTransitionApiPath(dispatchKey, nextStatus) {
+    if (nextStatus === "run_spawned") {
+        return `/epic-runs/dispatch/${encodeURIComponent(dispatchKey)}/run-spawned`;
+    }
+    return `/epic-runs/dispatch/${encodeURIComponent(dispatchKey)}/terminal`;
+}
+/**
+ * Build the canonical dispatch idempotency key in lock-step with the server-side
+ * `build_dispatch_key` Python helper.
+ *
+ * Format: `dispatch:{epicKey}:{ticketKey}:{planVersion}`.
+ *
+ * // TODO(epic-run-store): the epic component maps to the server-side epic_run_id component used by build_dispatch_key; confirm naming if the sibling renames it at integration.
+ */
+export function buildEpicDispatchKey(epicKey, ticketKey, planVersion) {
+    requireNonEmptyString(epicKey);
+    requireNonEmptyString(ticketKey);
+    requireNonNegativeSafeInteger(planVersion);
+    return `dispatch:${epicKey}:${ticketKey}:${planVersion}`;
+}
+// ---------------------------------------------------------------------------
+// Epic supervision lease claim/renew
+// ---------------------------------------------------------------------------
+function parseEpicSupervisionLeaseResult(parsed) {
+    if (!parsed || typeof parsed !== "object") {
+        throw new ConductorBridgeApiError("server");
+    }
+    const p = parsed;
+    const row = p["row"];
+    if (p["claimed"] === true && row && typeof row === "object") {
+        return { ok: true, kind: "acquired-or-renewed", row: row };
+    }
+    if (p["claimed"] === false && p["reason"] === "lease_held" && row && typeof row === "object") {
+        return { ok: false, kind: "held-by-other", reason: "lease_held", row: row };
+    }
+    if (p["claimed"] === false && p["reason"] === "terminal" && row && typeof row === "object") {
+        return { ok: false, kind: "terminal", reason: "terminal", row: row };
+    }
+    throw new ConductorBridgeApiError("server");
+}
+/**
+ * POST to the epic supervision lease endpoint. Returns a typed result distinguishing
+ * acquired/renewed from held-by-other and terminal so the control loop can decide
+ * whether to act or exit as an observer. Validates inputs before the request.
+ */
+export async function claimEpicSupervisionLease(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requireNonEmptyString(request.leaseOwner);
+    requirePositiveSafeInteger(request.ttlSeconds);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/lease/claim`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        lease_owner: request.leaseOwner,
+        ttl_seconds: request.ttlSeconds,
+    });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseEpicSupervisionLeaseResult(parsed);
+}
+// ---------------------------------------------------------------------------
+// Epic desired + observed state read
+// ---------------------------------------------------------------------------
+/**
+ * GET the durable epic run state (epic record + per-ticket statuses + dispatches).
+ * Returns the server payload verbatim — no ready-set computation, plan-hash
+ * assertion, or derived control-loop fields are added.
+ */
+export async function fetchEpicRunState(access, epicKey, fetchImpl = fetch) {
+    requireNonEmptyString(epicKey);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(epicKey)}/state`, { repo_name: access.repoName });
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Per-ticket CAS status advancement
+// ---------------------------------------------------------------------------
+function parseAdvanceEpicTicketStatusResult(parsed) {
+    if (!parsed || typeof parsed !== "object") {
+        throw new ConductorBridgeApiError("server");
+    }
+    const p = parsed;
+    // Structured CAS conflict envelope
+    if (p["ok"] === false && p["kind"] === "cas-conflict") {
+        return {
+            ok: false,
+            kind: "cas-conflict",
+            ...(typeof p["current_row_version"] === "number"
+                ? { current_row_version: p["current_row_version"] }
+                : {}),
+            ...(p["ticket_status"] && typeof p["ticket_status"] === "object"
+                ? { ticket_status: p["ticket_status"] }
+                : {}),
+        };
+    }
+    // Structured success envelope
+    if (p["ok"] === true && p["ticket_status"] && typeof p["ticket_status"] === "object") {
+        return { ok: true, ticket_status: p["ticket_status"] };
+    }
+    // Bare sibling success shape (EpicTicketStatusResponse): has ticket_key, status, row_version
+    if ("ticket_key" in p && "status" in p && "row_version" in p) {
+        return { ok: true, ticket_status: parsed };
+    }
+    throw new ConductorBridgeApiError("server");
+}
+/**
+ * POST to the per-ticket CAS status endpoint. Surfaces CAS conflicts as a distinct
+ * non-throwing outcome so the control loop can re-read rather than crashing.
+ * Transport/auth/server failures still throw a sanitized {@link ConductorBridgeApiError}.
+ *
+ * // TODO(epic-run-store): ticket requires POST but sibling currently declares PATCH /runs/{epic_run_id}/tickets/{ticket_key}; reconcile HTTP method at integration.
+ */
+export async function advanceEpicTicketStatus(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requireNonEmptyString(request.ticketKey);
+    requireNonNegativeSafeInteger(request.expectedRowVersion);
+    requireNonNegativeSafeInteger(request.planVersion);
+    requireEpicTicketStatusValue(request.nextStatus);
+    if (request.dispatchRunId !== undefined) {
+        requireNonEmptyString(request.dispatchRunId);
+    }
+    // TODO(epic-run-store): ticket requires POST; sibling is currently PATCH — reconcile at integration
+    const CAS_ENDPOINT_PATH = `${epicRunApiPath(request.epicKey)}/tickets/${encodeURIComponent(request.ticketKey)}`;
+    const url = buildConductorJiraUrl(access.baseUrl, CAS_ENDPOINT_PATH);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        status: request.nextStatus,
+        plan_version: request.planVersion,
+        expected_row_version: request.expectedRowVersion,
+        ...(request.dispatchRunId ? { dispatch_run_id: request.dispatchRunId } : {}),
+    });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseAdvanceEpicTicketStatusResult(parsed);
+}
+/**
+ * Idempotently seed an epic ticket status row via POST to the per-epic tickets
+ * endpoint. The backend uses ON CONFLICT DO NOTHING so repeated seeding across
+ * ticks and re-plans is safe. Throws a sanitized {@link ConductorBridgeApiError}
+ * on any transport/auth/server error.
+ */
+export async function createEpicTicketStatus(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requireNonEmptyString(request.ticketKey);
+    requireEpicTicketStatusValue(request.status);
+    requireNonNegativeSafeInteger(request.planVersion);
+    if (request.dispatchRunId !== undefined) {
+        requireNonEmptyString(request.dispatchRunId);
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/tickets`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        ticket_key: request.ticketKey,
+        status: request.status,
+        plan_version: request.planVersion,
+        ...(request.dispatchRunId ? { dispatch_run_id: request.dispatchRunId } : {}),
+    });
+    await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    // fetchConductorJsonPostWithTimeout already throws on 4xx/5xx;
+    // the 201 response body is not needed (we return void).
+}
+// ---------------------------------------------------------------------------
+// Idempotent dispatch recording
+// ---------------------------------------------------------------------------
+function parseEpicDispatchResult(parsed) {
+    if (!parsed || typeof parsed !== "object") {
+        throw new ConductorBridgeApiError("server");
+    }
+    const p = parsed;
+    const row = p["row"];
+    if (!row || typeof row !== "object") {
+        throw new ConductorBridgeApiError("server");
+    }
+    const dispatch = row;
+    if (p["claimed"] === true) {
+        return { ok: true, kind: "claimed", dispatch };
+    }
+    if (p["claimed"] === false) {
+        const reason = p["reason"];
+        if (reason === "already_spawned") {
+            return { ok: true, kind: "already-spawned", dispatch };
+        }
+        if (reason === "already_exists") {
+            return { ok: true, kind: "already-exists", dispatch };
+        }
+        if (reason === "terminal") {
+            return { ok: true, kind: "terminal", terminal: true, dispatch };
+        }
+        if (reason === "lease_held") {
+            return { ok: false, kind: "lease-held", dispatch };
+        }
+    }
+    throw new ConductorBridgeApiError("server");
+}
+/**
+ * POST to the dispatch claim endpoint. Treats dispatch creation as idempotent:
+ * re-recording the same `dispatch_key` returns the existing dispatch as a normal
+ * outcome so a crashed-then-retried tick never double-dispatches. The dispatch key
+ * is composed exclusively via {@link buildEpicDispatchKey}.
+ */
+export async function recordEpicDispatch(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requireNonEmptyString(request.ticketKey);
+    requireNonEmptyString(request.leaseOwner);
+    requireNonNegativeSafeInteger(request.planVersion);
+    requirePositiveSafeInteger(request.ttlSeconds);
+    const dispatchKey = buildEpicDispatchKey(request.epicKey, request.ticketKey, request.planVersion);
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/dispatch/claim`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        epic_run_id: request.epicKey,
+        ticket_key: request.ticketKey,
+        plan_version: request.planVersion,
+        lease_owner: request.leaseOwner,
+        ttl_seconds: request.ttlSeconds,
+        dispatch_key: dispatchKey,
+    });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseEpicDispatchResult(parsed);
+}
+// ---------------------------------------------------------------------------
+// Dispatch state transitions
+// ---------------------------------------------------------------------------
+/**
+ * POST to the appropriate dispatch transition endpoint (`run-spawned` or `terminal`).
+ * `run_spawned` requires a non-empty `runId`; `terminal` omits it even if supplied.
+ * Dispatch keys containing `/` are rejected before the request because transition
+ * endpoints embed the key as a URL path segment.
+ */
+export async function transitionEpicDispatch(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.dispatchKey);
+    requireNoSlashPathSegment(request.dispatchKey);
+    requireEpicDispatchTransitionStatus(request.nextStatus);
+    if (request.nextStatus === "run_spawned") {
+        requireNonEmptyString(request.runId);
+    }
+    const path = epicDispatchTransitionApiPath(request.dispatchKey, request.nextStatus);
+    const url = buildConductorJiraUrl(access.baseUrl, path);
+    const body = request.nextStatus === "run_spawned"
+        ? JSON.stringify({ repo_name: access.repoName, run_id: request.runId })
+        : JSON.stringify({ repo_name: access.repoName });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
+/**
+ * POST the immutable plan blob to the durable-store endpoint. The blob is
+ * written once per `(epic_run_id, plan_version)` and never mutated — a
+ * re-plan must use a strictly higher `plan_version`. The API key travels ONLY
+ * in the `X-API-Key` header, never in the URL. Throws a sanitized
+ * {@link ConductorBridgeApiError} on any transport/auth/server error.
+ */
+export async function storeEpicPlan(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requirePositiveSafeInteger(request.planVersion);
+    requireNonEmptyString(request.planHash);
+    const blobVersion = request.planBlob.plan_version;
+    if (blobVersion !== undefined && blobVersion !== request.planVersion) {
+        throw new ConductorValidationError(`planVersion mismatch: request.planVersion=${request.planVersion} but planBlob.plan_version=${blobVersion}`);
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/plan`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        plan_version: request.planVersion,
+        plan_blob: request.planBlob,
+        plan_hash: request.planHash,
+    });
+    return fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+}
+/**
+ * Atomically approve a plan version. Bumps `epic_runs.approved_plan_hash` to
+ * the named version's `plan_hash` in a single CAS write — never a
+ * read-then-write race. HTTP 409 (Conflict) is trapped and returned as a
+ * structured `{ ok: false, kind: "conflict" }` value (stale version or
+ * monotonic constraint violation). Other errors throw a sanitized
+ * {@link ConductorBridgeApiError}.
+ */
+export async function approveEpicPlan(access, request, fetchImpl = fetch) {
+    requireNonEmptyString(request.epicKey);
+    requirePositiveSafeInteger(request.planVersion);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/approve-plan`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        plan_version: request.planVersion,
+    });
+    try {
+        const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof ConductorBridgeApiError && error.status === 409) {
+            // ConductorBridgeApiError does not expose the response body, so server-provided
+            // conflict subtypes are not accessible here. "superseded" is used as a safe default.
+            return { ok: false, kind: "conflict", reason: "superseded" };
+        }
+        throw error;
+    }
+}
+/**
+ * GET the stored plan blob for a specific version or the currently-approved
+ * version. Pass `"approved"` for `planVersion` to retrieve the approved blob.
+ * Returns the response as a {@link GetEpicPlanResponse}. The API key travels
+ * ONLY in the `X-API-Key` header, never in the URL.
+ */
+export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = fetch) {
+    requireNonEmptyString(epicKey);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(epicKey)}/plan`, { repo_name: access.repoName, plan_version: String(planVersion) });
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Parse pipeline helpers (BAPI-415)
+// ---------------------------------------------------------------------------
+/**
+ * GET `/jira/parse-status?repo_name=<repo>` and return the live parse lock
+ * status. Only two states are possible: `"in_progress"` (the async parse job
+ * holds the lock) and `"idle"` (no lock is held). Throws a sanitized
+ * {@link ConductorBridgeApiError} on any transport/auth/server failure.
+ */
+export async function fetchParseStatus(access, fetchImpl = fetch) {
+    const url = buildConductorJiraUrl(access.baseUrl, "/parse-status", {
+        repo_name: access.repoName,
+    });
+    const body = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return body;
+}
+/**
+ * POST `/jira/parse-repository` to trigger an async repository parse. The
+ * endpoint is idempotent (coalesces concurrent requests via
+ * `mark_parse_repository_pending`) so duplicate triggers from re-ticking are
+ * safe. Returns the response envelope verbatim. Throws a sanitized
+ * {@link ConductorBridgeApiError} on any transport/auth/server failure.
+ */
+export async function triggerRepositoryParse(access, fetchImpl = fetch) {
+    const url = buildConductorJiraUrl(access.baseUrl, "/parse-repository");
+    const body = JSON.stringify({ repo_name: access.repoName });
+    return fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+}