@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/plan-phase-routing.js

@@ -0,0 +1,272 @@
+/**
+ * BAPI-763 — the orchestration seam between a pipeline recipe and the plan ledger.
+ *
+ * {@link ./plan-execution-ledger.js} holds the domain rules. This module is the thin
+ * layer that connects them to a running pipeline: which recipe steps are routed
+ * phases, how plan metadata is recovered from the plan-generation step's result, what
+ * routing context is injected into a paused agent task, and how a returned phase
+ * result is parsed and merged.
+ *
+ * Two constraints shape it.
+ *
+ * First, an `agent_task` is not executed by the orchestrator — the recipe pauses, the
+ * calling agent does the work, and it resumes with free-form `agent_result` text. So
+ * the phase-result envelope has to survive a round trip through prose, which is why
+ * it is a fenced JSON block that {@link parsePhaseResultEnvelope} extracts rather
+ * than a typed return value.
+ *
+ * Second, this contract is new and only three instruction files implement it. Every
+ * other pipeline (review-ticket, full-automation, plan-epic) still returns ordinary
+ * prose. Routing therefore applies only to {@link ROUTED_PHASE_INSTRUCTIONS}; an
+ * unrouted step is untouched.
+ *
+ * Pure: no I/O, no transport. The orchestrator supplies the persisted state.
+ */
+import { PlanLedgerError, assertStepClassCoverage, mergePlanStepRecords, resolveOwnedParts, resolveOwnedSteps, sanitizePlanStepRecords, validatePhaseResult, validatePlanMetadata, } from "./plan-execution-ledger.js";
+/** Instruction file -> the phase whose steps it must settle. */
+export const ROUTED_PHASE_INSTRUCTIONS = Object.freeze({
+    "execute-plan.md": "produce",
+    "execute-plan-verification.md": "pre_pr_verification",
+    "verify-plan.md": "post_pr_gap_close",
+});
+export function phaseForInstructionFile(instructionFile) {
+    if (!instructionFile)
+        return undefined;
+    return ROUTED_PHASE_INSTRUCTIONS[instructionFile];
+}
+// ---------------------------------------------------------------------------
+// Recovering plan metadata from the plan-generation step
+// ---------------------------------------------------------------------------
+/**
+ * Pull the provenance envelope out of whatever `request_plan_generation` returned.
+ *
+ * The tool result reaches the orchestrator as MCP content, so the metadata may be an
+ * object already or JSON embedded in a text block. Returns `undefined` when there is
+ * nothing to find; the caller decides whether that is fatal.
+ */
+export function extractPlanMetadata(result) {
+    const candidate = findPlanMetadataCandidate(result, 0);
+    if (candidate === undefined)
+        return undefined;
+    return validatePlanMetadata(candidate);
+}
+function findPlanMetadataCandidate(value, depth) {
+    if (depth > 6 || value === null || value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed.startsWith("{") && !trimmed.includes("plan_metadata"))
+            return undefined;
+        try {
+            return findPlanMetadataCandidate(JSON.parse(trimmed), depth + 1);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const found = findPlanMetadataCandidate(entry, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        if (record.plan_metadata !== undefined && record.plan_metadata !== null) {
+            return record.plan_metadata;
+        }
+        // An already-unwrapped envelope.
+        if (record.version !== undefined && Array.isArray(record.parts)) {
+            return record;
+        }
+        for (const entry of Object.values(record)) {
+            const found = findPlanMetadataCandidate(entry, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+export function buildPhaseRoutingContext(metadata, phase, ledger, checkpoint) {
+    return {
+        phase,
+        ownedSteps: resolveOwnedSteps(metadata, phase),
+        ownedRanges: resolveOwnedParts(metadata, phase).map((part) => ({
+            partId: part.part_id,
+            provenanceClass: part.provenance_class,
+            startStep: part.start_step,
+            endStep: part.end_step,
+            declaredAdvisory: part.declared_advisory,
+        })),
+        ledger: sanitizePlanStepRecords(ledger),
+        ...(checkpoint ? { checkpoint } : {}),
+    };
+}
+/**
+ * Append the routing context to the instruction text a paused phase receives.
+ *
+ * Injected through the instruction rather than left to conversation on purpose: the
+ * durable record has to survive an approval pause, a compaction, and a resumed
+ * session, and the conversational hand-off it replaces survived none of those.
+ */
+export function injectPhaseRoutingContext(instruction, context) {
+    const block = JSON.stringify(context, null, 2);
+    return (`${instruction}\n\n` +
+        `---\n\n` +
+        `## Routed phase context (BAPI-763 — orchestration-supplied, authoritative)\n\n` +
+        `You are executing the \`${context.phase}\` phase. The block below is the plan's ` +
+        `provenance routing and the durable ledger as it stands right now. Settle every ` +
+        `step in \`ownedSteps\` — each must end as \`executed\`, \`adapted\`, \`escalated\`, ` +
+        `or \`unrun-advisory\`. Steps outside \`ownedSteps\` belong to another phase.\n\n` +
+        `Entries already present in \`ledger\` are done; do not redo them.\n\n` +
+        "```json\n" +
+        `${block}\n` +
+        "```\n\n" +
+        `When the phase finishes, end your result with a fenced \`json\` block tagged ` +
+        `\`bapi-phase-result\` in this shape:\n\n` +
+        "```bapi-phase-result\n" +
+        `{"version":1,"phase":"${context.phase}","records":[{"stepId":<n>,"provenanceClass":"<class>","disposition":"executed","evidence":"<what ran and what was observed>"}]}\n` +
+        "```\n");
+}
+// ---------------------------------------------------------------------------
+// Parsing the returned phase result
+// ---------------------------------------------------------------------------
+const PHASE_RESULT_FENCE = /```(?:bapi-phase-result|json)\s*\n([\s\S]*?)\n?```/g;
+/**
+ * Extract the phase-result envelope from an agent's free-form result text.
+ *
+ * Scans every candidate fence and takes the last one that parses into an envelope
+ * shape, so an instruction's own example block earlier in the text cannot be mistaken
+ * for the real result.
+ */
+export function parsePhaseResultEnvelope(agentResult) {
+    if (!agentResult)
+        return undefined;
+    let found;
+    PHASE_RESULT_FENCE.lastIndex = 0;
+    let match;
+    while ((match = PHASE_RESULT_FENCE.exec(agentResult)) !== null) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            if (parsed && Array.isArray(parsed.records) && parsed.phase !== undefined) {
+                found = parsed;
+            }
+        }
+        catch {
+            // Not an envelope; keep scanning.
+        }
+    }
+    return found;
+}
+const CHECKPOINT_FENCE = /```(?:bapi-checkpoint|json)\s*\n([\s\S]*?)\n?```/g;
+/**
+ * Extract the checkpoint result `checkpoint-work.md` returns.
+ *
+ * Only a checkpoint that reports its work durable on origin is accepted: a block
+ * claiming `pushed: false` or `remoteMatchesHead: false` describes a checkpoint that
+ * did not achieve the one thing it exists for, so treating it as one would defeat
+ * the guarantee. Returns undefined when no usable block is present, which the caller
+ * distinguishes from a durable one.
+ */
+export function parseCheckpointResult(agentResult) {
+    if (!agentResult)
+        return undefined;
+    let found;
+    CHECKPOINT_FENCE.lastIndex = 0;
+    let match;
+    while ((match = CHECKPOINT_FENCE.exec(agentResult)) !== null) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            if (typeof parsed.branch === "string" &&
+                parsed.branch.trim() !== "" &&
+                typeof parsed.sha === "string" &&
+                parsed.sha.trim() !== "" &&
+                parsed.pushed === true &&
+                parsed.remoteMatchesHead === true) {
+                found = {
+                    branch: parsed.branch,
+                    sha: parsed.sha,
+                    pushed: true,
+                    remoteMatchesHead: true,
+                };
+            }
+        }
+        catch {
+            // Not a checkpoint block; keep scanning.
+        }
+    }
+    return found;
+}
+/**
+ * Settle a routed phase: parse, validate, and merge its result into the ledger.
+ *
+ * The two failure modes are treated differently, deliberately.
+ *
+ * A **malformed or incomplete envelope** is a contract violation by a phase that
+ * tried to report — it is flagged with `contractViolation`, and the orchestrator
+ * refuses to advance on it. The phase made a claim that does not hold, and advancing
+ * would record that claim as the durable truth.
+ *
+ * A **missing envelope** records an escalation for every owned step instead. This
+ * path exists because only three instruction files implement the contract and an
+ * agent's formatting can drift; turning that into a hard stop would wedge the
+ * pipeline. Crucially it is not silent — each owned step lands in the durable record
+ * as `escalated` with the reason, which is what surfaces as unresolved. The failure
+ * this ticket exists to fix was work vanishing with no trace, not work being flagged.
+ */
+export function settlePhaseResult(agentResult, metadata, phase, existingLedger) {
+    const envelope = parsePhaseResultEnvelope(agentResult);
+    if (!envelope) {
+        const owned = resolveOwnedSteps(metadata, phase);
+        if (owned.length === 0) {
+            return { ledger: [...existingLedger], contractViolation: false };
+        }
+        const reason = `phase '${phase}' returned no machine-readable result envelope, so the outcome of ` +
+            `its owned steps is unknown and is recorded as escalated rather than assumed complete`;
+        const records = owned.map((stepId) => ({
+            stepId,
+            provenanceClass: classForStep(metadata, stepId),
+            phase,
+            disposition: "escalated",
+            escalationReason: reason,
+        }));
+        return {
+            ledger: mergePlanStepRecords(existingLedger, records),
+            diagnostic: reason,
+            contractViolation: false,
+        };
+    }
+    try {
+        const validated = validatePhaseResult(envelope, metadata, phase);
+        return {
+            ledger: mergePlanStepRecords(existingLedger, sanitizePlanStepRecords(validated)),
+            contractViolation: false,
+        };
+    }
+    catch (err) {
+        const message = err instanceof PlanLedgerError ? err.message : String(err);
+        return {
+            ledger: [...existingLedger],
+            diagnostic: `phase '${phase}' returned an invalid result envelope: ${message}`,
+            contractViolation: true,
+        };
+    }
+}
+function classForStep(metadata, stepId) {
+    const part = metadata.parts.find((entry) => stepId >= entry.start_step && stepId <= entry.end_step);
+    // resolveOwnedSteps only emits step IDs that came from a part, so the fallback is
+    // unreachable in practice; it exists so a future caller cannot crash here.
+    return part ? part.provenance_class : "implementation";
+}
+/**
+ * Validate metadata and prove complete class coverage before any phase runs.
+ *
+ * Deliberately called before the first routed phase, not lazily at each one: the
+ * point is to discover an unowned step class while nothing has been produced yet,
+ * rather than after a pull request is already open.
+ */
+export function assertPlanIsRoutable(metadata) {
+    assertStepClassCoverage(metadata);
+}

package/build/plane/alembic-head.js

@@ -0,0 +1,110 @@
+/**
+ * Alembic head preflight check (BAPI-756).
+ *
+ * A database behind the migration head blocks conductor dispatch
+ * (`CONTRACT_MIGRATION_BEHIND`), so catching it before anything spawns saves an
+ * operator a confusing run that starts cleanly and then refuses every job.
+ *
+ * This check is deliberately asymmetric: it **blocks only on a confirmed
+ * mismatch** — both commands ran, both parsed, and the revision sets differ.
+ * Every other outcome (no repository virtualenv, a command failure, output it
+ * cannot parse) is a named "could not verify" warning that lets startup
+ * proceed. A false refusal here is worse than a skipped check, because the
+ * condition it guards is already reported loudly by the server at dispatch time.
+ */
+import path from "path";
+/** Remediation embedded in a confirmed-mismatch diagnostic. */
+export const PLANE_ALEMBIC_REMEDIATION = "alembic -c alembic.ini upgrade head";
+/** Fixed prefix of the fail-open warning, so tests and greps can match it. */
+export const PLANE_ALEMBIC_UNVERIFIED_PREFIX = "could not verify database migration head";
+/**
+ * Path to the repository virtualenv's Alembic executable.
+ *
+ * Deliberately NOT a bare `alembic` from `PATH`: the repository venv is the one
+ * whose installed migrations and driver match `alembic.ini`, and an unrelated
+ * global Alembic would answer a different question.
+ */
+export function resolveRepositoryAlembicCommand(repoRoot, platform) {
+    return platform === "win32"
+        ? path.join(repoRoot, ".venv", "Scripts", "alembic.exe")
+        : path.join(repoRoot, ".venv", "bin", "alembic");
+}
+// Log lines Alembic writes alongside its answer. Skipped before token parsing
+// so a logging configuration change cannot be mistaken for a revision id.
+const LOG_LINE_PATTERN = /^(INFO|WARNING|ERROR|DEBUG|CRITICAL)\b|\[alembic/i;
+// This repository's revision ids are slugged (`0004_add_error_count`), not the
+// hex default, so the pattern must accept letters, digits, `_`, `-`, and `.`.
+const REVISION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z_.-]*$/;
+// Tokens Alembic prints that are annotations or sentinels rather than revisions.
+const NON_REVISION_TOKENS = new Set(["head", "heads", "base", "none", "(head)"]);
+/**
+ * Parse `alembic heads` / `alembic current` output into a normalized revision
+ * set.
+ *
+ * Returns `null` when no revision token is found — including for empty output,
+ * which is what `current` prints for a database stamped at base. The caller
+ * turns `null` into the fail-open warning rather than a mismatch, per the
+ * ratified "never refuse on an unconfirmed reading" policy.
+ */
+export function parseAlembicRevisions(output) {
+    const revisions = new Set();
+    for (const rawLine of output.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (LOG_LINE_PATTERN.test(line))
+            continue;
+        const token = line.split(/\s+/)[0];
+        if (!token || NON_REVISION_TOKENS.has(token.toLowerCase()))
+            continue;
+        if (!REVISION_PATTERN.test(token))
+            continue;
+        revisions.add(token);
+    }
+    if (revisions.size === 0)
+        return null;
+    return [...revisions].sort();
+}
+/**
+ * Compare the repository's migration heads with the database's current
+ * revisions. Blocks only on a confirmed mismatch; warns on anything unverifiable.
+ */
+export async function checkAlembicHead(repoRoot, deps) {
+    const alembic = resolveRepositoryAlembicCommand(repoRoot, deps.platform);
+    if (!(await deps.fileExists(alembic))) {
+        return unverified("the repository virtualenv Alembic executable was not found");
+    }
+    const heads = await deps.execFile(alembic, ["-c", "alembic.ini", "heads"], { cwd: repoRoot });
+    if (!heads.ok) {
+        return unverified(`\`alembic heads\` did not complete (${heads.error})`);
+    }
+    const current = await deps.execFile(alembic, ["-c", "alembic.ini", "current"], { cwd: repoRoot });
+    if (!current.ok) {
+        return unverified(`\`alembic current\` did not complete (${current.error})`);
+    }
+    const headRevisions = parseAlembicRevisions(heads.stdout);
+    const currentRevisions = parseAlembicRevisions(current.stdout);
+    if (headRevisions === null || currentRevisions === null) {
+        return unverified("Alembic output did not contain a readable revision");
+    }
+    const matches = headRevisions.length === currentRevisions.length &&
+        headRevisions.every((rev, i) => rev === currentRevisions[i]);
+    if (matches)
+        return null;
+    return {
+        check: "alembic-head",
+        severity: "blocking",
+        message: `the database is not at the migration head — heads [${headRevisions.join(", ")}], ` +
+            `current [${currentRevisions.join(", ")}]. A database behind the head blocks ` +
+            `conductor dispatch. Run \`${PLANE_ALEMBIC_REMEDIATION}\``,
+    };
+}
+function unverified(detail) {
+    return {
+        check: "alembic-head",
+        severity: "warning",
+        message: `${PLANE_ALEMBIC_UNVERIFIED_PREFIX}: ${detail}. Startup continues — verify with ` +
+            `\`alembic -c alembic.ini heads\` and \`alembic -c alembic.ini current\` if a run ` +
+            "later reports CONTRACT_MIGRATION_BEHIND.",
+    };
+}

package/build/plane/build-freshness.js

@@ -0,0 +1,167 @@
+/**
+ * Executor build-freshness preflight check (BAPI-756).
+ *
+ * A stale `mcp_server/build/` is one of the quietest traps in an attended run:
+ * the executor starts, reports healthy, and runs yesterday's code. Comparing
+ * the newest `src/**` modification time against the build's own timestamp turns
+ * that silent wrong-code condition into a refusal naming `npm run build`.
+ *
+ * The authoritative build timestamp is `build/index.js`, not the directory.
+ * `npm run build` runs tsc, then re-bundles the bin entry points with esbuild,
+ * then prepends shebangs — so `build/index.js` is written at the END of the
+ * pipeline, while the directory's mtime only tracks direct child creation and
+ * can be older than a rebuild that overwrote files in place.
+ */
+import path from "path";
+/** Remediation text embedded in every blocking build diagnostic. */
+export const PLANE_BUILD_REMEDIATION = "cd mcp_server && npm run build";
+/**
+ * Source subtrees and files excluded from the freshness comparison.
+ *
+ * `*.generated.ts` files are written by the bundle scripts during the SAME
+ * `npm run build` that produces `build/index.js`, so they are always newer than
+ * a tsc run that preceded them and would stale every build immediately.
+ */
+const EXCLUDED_DIR_NAMES = new Set(["node_modules", "build"]);
+function isRelevantSourceFile(name) {
+    if (!name.endsWith(".ts"))
+        return false;
+    if (name.endsWith(".generated.ts"))
+        return false;
+    return true;
+}
+/**
+ * Newest modification time across the compiled package's TypeScript sources.
+ *
+ * Returns `null` when the tree contains no relevant source file at all, which
+ * the caller treats as "nothing to be stale against" rather than as an error.
+ */
+export async function findNewestSourceMtime(srcDir, deps) {
+    let newest = null;
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await deps.fs.readdir(dir);
+        }
+        catch (err) {
+            return sanitize(err);
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIR_NAMES.has(entry.name))
+                    continue;
+                const error = await walk(path.join(dir, entry.name));
+                if (error)
+                    return error;
+                continue;
+            }
+            if (!entry.isFile() || !isRelevantSourceFile(entry.name))
+                continue;
+            try {
+                const stat = await deps.fs.stat(path.join(dir, entry.name));
+                if (newest === null || stat.mtimeMs > newest)
+                    newest = stat.mtimeMs;
+            }
+            catch (err) {
+                return sanitize(err);
+            }
+        }
+        return null;
+    };
+    const error = await walk(srcDir);
+    if (error)
+        return { ok: false, error };
+    return { ok: true, mtimeMs: newest };
+}
+/**
+ * The authoritative build timestamp: the mtime of the compiled entrypoint the
+ * executor members are actually launched from.
+ */
+export async function findBuildMtime(executorEntrypoint, deps) {
+    try {
+        const stat = await deps.fs.stat(executorEntrypoint);
+        return { ok: true, mtimeMs: stat.mtimeMs };
+    }
+    catch (err) {
+        return { ok: false, error: sanitize(err) };
+    }
+}
+/**
+ * Verify the executor build exists and is not older than its sources.
+ *
+ * Returns a blocking diagnostic (never a warning): running an executor from a
+ * stale or absent build is exactly the failure this check exists to prevent, so
+ * unlike the Alembic check there is no fail-open branch.
+ */
+export async function checkPlaneBuildFreshness(repoRoot, deps) {
+    const packageRoot = path.join(repoRoot, "mcp_server");
+    const buildDir = path.join(packageRoot, "build");
+    const executorEntrypoint = path.join(buildDir, "index.js");
+    const srcDir = path.join(packageRoot, "src");
+    const buildMtime = await findBuildMtime(executorEntrypoint, deps);
+    if (!buildMtime.ok) {
+        return {
+            check: "executor-build",
+            severity: "blocking",
+            message: `the executor build entrypoint is missing or unreadable at ` +
+                `mcp_server/build/index.js — run \`${PLANE_BUILD_REMEDIATION}\``,
+        };
+    }
+    const sourceMtime = await findNewestSourceMtime(srcDir, deps);
+    if (!sourceMtime.ok) {
+        return {
+            check: "executor-build",
+            severity: "blocking",
+            message: `could not read mcp_server/src to compare against the build ` +
+                `(${sourceMtime.error}) — run \`${PLANE_BUILD_REMEDIATION}\``,
+        };
+    }
+    // Equality passes: a build written in the same millisecond as its newest
+    // source is current, and treating the boundary as stale would refuse a
+    // perfectly good build on a coarse-resolution filesystem.
+    if (sourceMtime.mtimeMs !== null && sourceMtime.mtimeMs > buildMtime.mtimeMs) {
+        return {
+            check: "executor-build",
+            severity: "blocking",
+            message: "mcp_server/build/ is STALE — a source file under mcp_server/src is newer " +
+                `than mcp_server/build/index.js, so executors would run old code. ` +
+                `Run \`${PLANE_BUILD_REMEDIATION}\``,
+        };
+    }
+    return null;
+}
+/**
+ * Fixed refusal prose for an unresolvable runtime re-exec target (BAPI-768).
+ *
+ * Exported so the private entrypoint diagnostic and the preflight refusal say
+ * the same thing, and so a test can pin the wording rather than a substring.
+ */
+export const PLANE_RUNTIME_ENTRYPOINT_REFUSAL = "the currently executing MCP build could not be re-entered — `plane up` re-execs this " +
+    "package's own compiled entrypoint to create the detached runtime, and no existing " +
+    `entrypoint belonging to it could be found. Run \`${PLANE_BUILD_REMEDIATION}\` and retry ` +
+    "from the rebuilt CLI.";
+/**
+ * Verify the launcher can identify the compiled entrypoint it is running from.
+ *
+ * Separate from {@link checkPlaneBuildFreshness} because the two answer
+ * different questions about different files. Build freshness asks whether *this
+ * repository's* executor build is current; this asks whether the *executing*
+ * artifact can re-enter itself. BAPI-768 was a failure of the second while the
+ * first was perfectly green, so collapsing them would hide the next one.
+ *
+ * Blocking, never a warning: a plane whose runtime cannot start is not a
+ * degraded plane, it is no plane at all.
+ */
+export function checkPlaneRuntimeEntrypoint(resolution) {
+    if (resolution.ok)
+        return null;
+    return {
+        check: "runtime-entrypoint",
+        severity: "blocking",
+        message: PLANE_RUNTIME_ENTRYPOINT_REFUSAL,
+    };
+}
+function sanitize(err) {
+    const code = err?.code;
+    return typeof code === "string" ? code : "unreadable";
+}