@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/build/conductor/run-branch.js

@@ -0,0 +1,137 @@
+/**
+ * Canonical TypeScript run-branch DECLARATION resolution (BAPI-1127).
+ *
+ * The TypeScript counterpart of `api/models/run_branch.py`, and the only place
+ * in this package that answers "which base branch, if any, does this persisted
+ * run's `policy_json` DECLARE?" Before BAPI-1127 the question was answered in
+ * three places that disagreed — the defaulting resolver in `epic-runtime.ts`
+ * (a `??` scan that stopped on a present-but-blank `base_branch` and therefore
+ * never consulted the camelCase alias), `bridge-api-client.ts#readEpicRunCompletionState`
+ * (snake_case only, and it did not trim), and the Python resolver across the
+ * wire. The two runtimes feed the SAME epic run from opposite sides, so a
+ * disagreement means the server provisions one branch while the CLI cuts worker
+ * branches from another, silently.
+ *
+ * **Declaration only.** This module answers exactly one question and stops:
+ * what branch did the policy declare? It deliberately does NOT:
+ *
+ *   - apply the TypeScript-only `main` default. That is a DISPATCH-layer policy
+ *     owned by `epic-runtime.ts#resolveEffectiveRunBaseBranch`. A classification
+ *     or observation consumer that adopted it would report `main` for a run that
+ *     declared nothing, conflating "declared no branch" with "dispatches from
+ *     main" — the exact confusion that kept `featureBranch` honest before.
+ *   - apply branch-name validity rules. `validateBranchName` is an OPERATIONAL
+ *     judgment made by whichever caller is about to hand the value to git or a
+ *     provider, and it is applied there.
+ *
+ * **The frozen cross-runtime dispositions** (BAPI-1127, and the same two rules
+ * `api/models/run_branch.py` states):
+ *
+ *   - A NON-STRING candidate is ABSENT, not fatal. The ordered scan skips it and
+ *     continues to the next key, so the legacy row
+ *     `{"base_branch": 42, "baseBranch": "epic/X"}` resolves to `epic/X` rather
+ *     than failing closed on the unusable snake_case value. The strict server-side
+ *     `RunPolicy` boundary already rejects a non-string `base_branch` before it can
+ *     be stored, so this rule governs legacy and out-of-band rows only.
+ *   - A MALFORMED or over-length declaration is still a DECLARATION. It is
+ *     returned complete and trimmed, never truncated, rejected, or replaced with
+ *     a default; format and length are validated at the point of operational use.
+ *
+ * **Why a leaf.** `epic-runtime.ts` already imports from `bridge-api-client.ts`,
+ * so putting the shared resolver in either one and importing it from the other
+ * would close a cycle. This module imports NOTHING — not the API client, not a
+ * command runner, not `base-ref.js`'s validator — so every consumer can depend on
+ * it freely. That is the same reasoning `api/models/run_branch.py:13-24` gives for
+ * its own placement.
+ *
+ * The cross-language contract is frozen as data in
+ * `tests/pytest/fixtures/run_branch_vectors.json` and enforced from both sides by
+ * `mcp_server/src/conductor/run-branch.test.ts` and
+ * `tests/pytest/models/test_run_branch_vectors.py`.
+ */
+/**
+ * The policy keys consulted, IN ORDER. Both spellings are accepted because both
+ * have been written by real clients; `base_branch` is canonical and `baseBranch`
+ * is the legacy alias. Named once so the precedence is stated in exactly one
+ * place, mirroring `POLICY_BASE_BRANCH_KEYS` in `api/models/run_branch.py`.
+ */
+export const POLICY_BASE_BRANCH_KEYS = ["base_branch", "baseBranch"];
+/**
+ * Return the trimmed string, or `undefined` for anything that is not a usable
+ * one.
+ *
+ * A blank or whitespace-only value is NOT a branch: accepting it would let a run
+ * created with `base_branch: "   "` classify as a feature-branch run, which at
+ * the merge-admission boundary would hand it the ungated-auto-merge exception on
+ * the strength of whitespace. The Python twin is `run_branch._nonblank`.
+ *
+ * KNOWN GAP — the trim is proven equivalent only for ASCII whitespace
+ * (BAPI-1127 review). `String.prototype.trim()` and Python's `str.strip()` do
+ * not strip the same character class, so four inputs resolve differently and
+ * none is in the vector table:
+ *
+ * | declared value      | Python `_nonblank`   | this function        |
+ * |---------------------|----------------------|----------------------|
+ * | `"\u001cepic/X"`    | `"epic/X"`           | `"\u001cepic/X"`     |
+ * | `"\u0085"`          | absent (blank)       | `"\u0085"`           |
+ * | `"\u0085epic/X"`    | `"epic/X"`           | `"\u0085epic/X"`     |
+ * | `"\ufeffmain"`      | `"\ufeffmain"`       | `"main"`             |
+ *
+ * `str.strip()` also strips U+001C-U+001F and U+0085; `trim()` also strips
+ * U+FEFF. Note the second row is the sharp one: U+0085 is above 0x7F, so
+ * `validateBranchName`'s control-character rule does NOT reject it either.
+ *
+ * Left as FOLLOW-UP rather than fixed here, deliberately. Picking the canonical
+ * class is a contract decision of the same kind BAPI-1127 froze for the
+ * non-string and malformed-name rows — and it was frozen in the TICKET, not by
+ * the implementer. Normalizing Python's class would additionally change
+ * feature-branch classification for a policy the `RunPolicy` boundary accepts
+ * today (`{"base_branch": "\u0085"}` classifies as no-feature-branch now), which
+ * BAPI-1127's acceptance criteria forbid. `RunPolicy` accepts any strict string,
+ * so these values are storable, but they are vanishingly unlikely in practice.
+ * Recorded alongside the `git check-ref-format` follow-up in `base-ref.ts`.
+ */
+function nonblank(candidate) {
+    if (typeof candidate !== "string")
+        return undefined;
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve the branch a persisted run's `policy_json` declares, if any.
+ *
+ * Returns the first non-blank string found across {@link POLICY_BASE_BRANCH_KEYS},
+ * in that order, trimmed; or `undefined` when the policy declares none.
+ *
+ * The scan is SEQUENTIAL, not nullish-coalescing: a candidate that is not a
+ * non-blank string is skipped and the scan CONTINUES to the next key. `??` falls
+ * through only for `null`/`undefined`, which is why the pre-BAPI-1127 expression
+ * stopped at a present-but-blank `base_branch` and reported the dispatch default
+ * for a policy that plainly declared `baseBranch: "epic/X"`.
+ *
+ * A non-mapping policy (`null`, `undefined`, a primitive, an array) declares
+ * nothing. Shape is the typed boundary's job, not this resolver's — the Python
+ * twin makes the same call for the same reason.
+ *
+ * The returned value is never truncated and carries no operational length or
+ * format bound. See the module docstring for both frozen dispositions.
+ */
+export function resolveDeclaredRunBaseBranch(policyJson) {
+    if (policyJson === null || typeof policyJson !== "object" || Array.isArray(policyJson)) {
+        return undefined;
+    }
+    const policy = policyJson;
+    for (const key of POLICY_BASE_BRANCH_KEYS) {
+        // OWN properties only. A Python dict has no prototype chain, so a plain
+        // `policy[key]` would not be the same read: it also sees `Object.prototype`,
+        // and a polluted prototype would make EVERY policy in the process appear to
+        // declare a branch. Real inputs come from `JSON.parse`, which never produces
+        // inherited keys, so this costs nothing and closes the gap.
+        if (!Object.prototype.hasOwnProperty.call(policy, key))
+            continue;
+        const resolved = nonblank(policy[key]);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return undefined;
+}

package/build/conductor/test-run-branch-vectors.js

@@ -0,0 +1,165 @@
+/**
+ * BAPI-1127 — TypeScript-side loader for the SHARED cross-runtime vector table.
+ *
+ * `tests/pytest/fixtures/run_branch_vectors.json` lives at the repository root,
+ * outside this package, because it is not this package's fixture: it is the
+ * contract between this package and the Python server, and both sides read the
+ * same bytes. Python reaches it from `tests/pytest/models/`; this module is how
+ * the compiled `node:test` suites reach it.
+ *
+ * **Why `readFileSync` and not a JSON import.** Importing the JSON would require
+ * `resolveJsonModule` plus a widened `include` in `tsconfig.json`, which would
+ * inline a test fixture into the PUBLISHED bundle. `build/**\/*.test.js` is
+ * excluded from the package `files` list, so a compiled test reading a
+ * repository-root path ships nothing; a JSON module baked into the emitted
+ * source would.
+ *
+ * **Why the path is searched rather than computed.** The compiled test executes
+ * from `mcp_server/build/conductor/`, not `mcp_server/src/conductor/`, so a
+ * hard-coded `../../../` is correct for exactly one of the two and silently
+ * wrong for the other. Walking up until the fixture is found is correct from
+ * either, and from any CI checkout depth.
+ *
+ * Nothing here is reachable from the MCP server runtime — it is imported only by
+ * `*.test.ts` — so it adds no startup cost and touches no stdio.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Repository-root-relative location of the shared table. */
+const FIXTURE_RELATIVE_PATH = path.join("tests", "pytest", "fixtures", "run_branch_vectors.json");
+function repositoryRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    // 8 levels is far more than the 3 either real layout needs; the loop exists to
+    // be layout-independent, not to search the whole filesystem.
+    for (let i = 0; i < 8; i++) {
+        try {
+            readFileSync(path.join(dir, FIXTURE_RELATIVE_PATH));
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    throw new Error(`run_branch_vectors.json not found above ${fileURLToPath(import.meta.url)}. ` +
+        "The shared cross-runtime vector table is required; this suite must not " +
+        "pass without it.");
+}
+function readDocument() {
+    const fixturePath = path.join(repositoryRoot(), FIXTURE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = readFileSync(fixturePath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`shared vector fixture is unreadable at ${fixturePath}: ${String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`shared vector fixture is not valid JSON (${fixturePath}): ${String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`shared vector fixture is not a JSON object (${fixturePath}).`);
+    }
+    return parsed;
+}
+/** JSON `null` means "no declaration"; TypeScript spells that `undefined`. */
+function nullToUndefined(value) {
+    return value === null ? undefined : value;
+}
+/**
+ * Load the shared resolution vectors, THROWING on every vacuous state.
+ *
+ * A missing, unreadable, malformed, or empty table is a failure and never a
+ * skip: a parity suite that quietly parametrizes zero cases reports green while
+ * proving nothing, which is the exact outcome these vectors exist to prevent.
+ */
+export function loadResolutionVectors() {
+    const raw = readDocument()["resolution_vectors"];
+    if (!Array.isArray(raw)) {
+        throw new Error("shared vector fixture has no 'resolution_vectors' array.");
+    }
+    if (raw.length === 0) {
+        throw new Error("shared vector fixture declares zero resolution vectors; every parity " +
+            "assertion below would be vacuous.");
+    }
+    return raw.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`resolution vector #${index} is not an object.`);
+        }
+        const e = entry;
+        if (typeof e["id"] !== "string" || e["id"].length === 0) {
+            throw new Error(`resolution vector #${index} has no id.`);
+        }
+        if (typeof e["policy_present"] !== "boolean") {
+            throw new Error(`resolution vector ${e["id"]} has no boolean policy_present.`);
+        }
+        if (!("expected_declared_branch" in e)) {
+            throw new Error(`resolution vector ${e["id"]} has no expected_declared_branch.`);
+        }
+        return {
+            id: e["id"],
+            note: typeof e["note"] === "string" ? e["note"] : "",
+            policyPresent: e["policy_present"],
+            policyJson: e["policy_present"] ? e["policy_json"] : undefined,
+            expectedDeclaredBranch: nullToUndefined(e["expected_declared_branch"]),
+            typescriptEffectiveBase: nullToUndefined(e["typescript_effective_base"]),
+            typescriptEffectiveErrorType: nullToUndefined(e["typescript_effective_error_type"]),
+        };
+    });
+}
+/** Load the shared branch-name validity vectors, with the same loud failures. */
+export function loadBranchNameVectors() {
+    const raw = readDocument()["branch_name_validation"];
+    if (!Array.isArray(raw)) {
+        throw new Error("shared vector fixture has no 'branch_name_validation' array.");
+    }
+    if (raw.length === 0) {
+        throw new Error("shared vector fixture declares zero branch-name vectors; every validator " +
+            "assertion below would be vacuous.");
+    }
+    return raw.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`branch-name vector #${index} is not an object.`);
+        }
+        const e = entry;
+        if (typeof e["id"] !== "string" || e["id"].length === 0) {
+            throw new Error(`branch-name vector #${index} has no id.`);
+        }
+        if (typeof e["input"] !== "string") {
+            throw new Error(`branch-name vector ${e["id"]} has a non-string input.`);
+        }
+        if (typeof e["valid"] !== "boolean") {
+            throw new Error(`branch-name vector ${e["id"]} has no boolean 'valid'.`);
+        }
+        return {
+            id: e["id"],
+            note: typeof e["note"] === "string" ? e["note"] : "",
+            input: e["input"],
+            valid: e["valid"],
+            errorType: nullToUndefined(e["error_type"]),
+        };
+    });
+}
+/**
+ * The substring each `error_type` must appear as in a validator diagnostic.
+ *
+ * The adapters assert the ACTUAL message, not merely that some error occurred,
+ * so a validator that started reporting the wrong rule would fail rather than
+ * pass on a coincidentally-truthy result. Kept here, beside the loader, because
+ * both the TypeScript validator suite and the effective-base suite need it.
+ */
+export const ERROR_TYPE_MESSAGE_FRAGMENTS = {
+    empty: "must not be empty",
+    too_long: "255 characters or fewer",
+    leading_hyphen: "must not start with '-'",
+    double_dot: "must not contain '..'",
+    lock_suffix: "must not end with '.lock'",
+    control_character: "must not contain control characters",
+};

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