@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/ticket-delivery.js

@@ -0,0 +1,205 @@
+/**
+ * BAPI-1426 — the thin client for the server's ticket delivery authority.
+ *
+ * The Bridge API decides whether a managed ticket is ready to publish, merge, or
+ * complete. This module only carries requests to `/ticket-delivery/...` and hands
+ * the server's answer back. It holds no readiness policy: it never counts ledger
+ * records, never decides an outcome, and never turns a failed call into a green
+ * result.
+ *
+ * Every function returns a result object instead of throwing on an HTTP or
+ * network failure, so a caller can keep local work and retry later. Messages are
+ * sanitized and never carry the API key or any request header.
+ */
+import { redactSecrets } from "./secret-redaction.js";
+export const READINESS_BOUNDARIES = ["publish", "merge", "complete"];
+const STATUS_CODES = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    422: "VALIDATION_ERROR",
+    429: "RATE_LIMITED",
+    500: "INTERNAL_ERROR",
+    502: "BAD_GATEWAY",
+    503: "SERVICE_UNAVAILABLE",
+    504: "GATEWAY_TIMEOUT",
+};
+const MAX_MESSAGE_LENGTH = 500;
+/** Strip credentials and bound the length of any text that leaves this module. */
+export function sanitizeDeliveryMessage(raw, apiKey) {
+    let text = typeof raw === "string" ? raw : raw instanceof Error ? raw.message : String(raw);
+    if (apiKey && apiKey.length >= 4)
+        text = text.split(apiKey).join("[REDACTED]");
+    text = redactSecrets(text);
+    return text.length > MAX_MESSAGE_LENGTH ? `${text.slice(0, MAX_MESSAGE_LENGTH)}…` : text;
+}
+function deliveryUrl(baseUrl, path, query) {
+    const url = new URL(`${baseUrl.replace(/\/+$/, "")}/ticket-delivery${path}`);
+    for (const [key, value] of Object.entries(query ?? {}))
+        url.searchParams.set(key, value);
+    return url.toString();
+}
+async function request(deps, method, path, options = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let headers = {};
+    try {
+        headers = await deps.headers();
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            error: "CREDENTIALS_UNAVAILABLE",
+            message: sanitizeDeliveryMessage(err),
+        };
+    }
+    const apiKey = headers["X-API-Key"];
+    let resp;
+    try {
+        resp = await fetchImpl(deliveryUrl(deps.baseUrl, path, options.query), {
+            method,
+            headers: options.body === undefined ? headers : { ...headers, "Content-Type": "application/json" },
+            ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            error: "NETWORK_ERROR",
+            message: sanitizeDeliveryMessage(err, apiKey),
+        };
+    }
+    let raw = "";
+    try {
+        raw = await resp.text();
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: resp.status,
+            error: "INVALID_RESPONSE",
+            message: sanitizeDeliveryMessage(err, apiKey),
+        };
+    }
+    if (resp.ok) {
+        try {
+            const body = JSON.parse(raw);
+            if (body === null || typeof body !== "object" || Array.isArray(body)) {
+                throw new Error("response body is not a JSON object");
+            }
+            return { ok: true, status: resp.status, body: body };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                status: resp.status,
+                error: "INVALID_RESPONSE",
+                message: sanitizeDeliveryMessage(err, apiKey),
+            };
+        }
+    }
+    let error = STATUS_CODES[resp.status] ?? "UNKNOWN_ERROR";
+    let message = raw ? raw : `HTTP ${resp.status}`;
+    let detail;
+    try {
+        const parsed = JSON.parse(raw);
+        detail = parsed?.detail;
+        if (detail !== null && typeof detail === "object" && !Array.isArray(detail)) {
+            const d = detail;
+            if (typeof d.error === "string")
+                error = d.error;
+            message = typeof d.message === "string" ? d.message : JSON.stringify(d);
+        }
+        else if (typeof detail === "string") {
+            message = detail;
+        }
+        else if (detail !== undefined) {
+            message = JSON.stringify(detail);
+        }
+    }
+    catch {
+        // Not JSON: keep the raw text as the message.
+    }
+    return {
+        ok: false,
+        status: resp.status,
+        error,
+        message: sanitizeDeliveryMessage(message, apiKey),
+        ...(detail !== undefined ? { detail: JSON.parse(sanitizeDeliveryDetail(detail, apiKey)) } : {}),
+    };
+}
+function sanitizeDeliveryDetail(detail, apiKey) {
+    let text = JSON.stringify(detail);
+    if (apiKey && apiKey.length >= 4)
+        text = text.split(apiKey).join("[REDACTED]");
+    return redactSecrets(text);
+}
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+/** Bind a managed execution. Replaying the same registration key resumes it. */
+export function registerExecution(deps, body) {
+    return request(deps, "POST", "/executions", { body });
+}
+/** Find the active attempt for a ticket and branch. A 404 means there is none. */
+export function recoverExecution(deps, query) {
+    return request(deps, "GET", "/executions/recover", { query });
+}
+const RUN_RECOVERY_CODES = {
+    TICKET_DELIVERY_RUN_UNMANAGED: "unmanaged",
+    TICKET_DELIVERY_RUN_NO_RECOVERABLE_EXECUTION: "no_recoverable_execution",
+    TICKET_DELIVERY_RUN_AMBIGUOUS: "ambiguous",
+    TICKET_DELIVERY_RUN_LOOKUP_FAILED: "lookup_failed",
+};
+const RUN_RECOVERY_MESSAGES = {
+    unmanaged: "The server confirmed no managed execution exists for this run and ticket.",
+    no_recoverable_execution: "The ticket belongs to the run but has no active or completed execution to read.",
+    ambiguous: "More than one active execution exists for this run and ticket.",
+    lookup_failed: "The run-scoped lookup failed. This is not proof the ticket is unmanaged.",
+};
+/**
+ * Find a run child's execution by run id and ticket, with no branch. Only an
+ * allowlisted server code maps to `unmanaged`, `no_recoverable_execution` or
+ * `ambiguous`. Every other failure, including a bare 404 from an older server,
+ * a 5xx, an unreadable body and a transport error, is `lookup_failed`.
+ */
+export async function recoverExecutionForRun(deps, query) {
+    const result = await request(deps, "GET", "/executions/recover", {
+        query,
+    });
+    if (result.ok)
+        return { ok: true, body: result.body };
+    const detail = result.detail;
+    const code = typeof detail?.error === "string" ? detail.error : undefined;
+    const mapped = code !== undefined ? RUN_RECOVERY_CODES[code] : undefined;
+    const outcome = mapped ?? "lookup_failed";
+    return { ok: false, outcome, status: result.status, message: RUN_RECOVERY_MESSAGES[outcome] };
+}
+/** Whether a branch is held by a managed ticket. Grants no submission authority. */
+export function getBranchHold(deps, query) {
+    return request(deps, "GET", "/holds", { query });
+}
+/** Upload one durable evidence batch. `retryable: true` means nothing was stored. */
+export function submitEvidence(deps, attemptId, body) {
+    return request(deps, "POST", `/executions/${encodeURIComponent(attemptId)}/evidence`, { body });
+}
+/** The server-accepted ledger, which is the only source of post-PR ownership. */
+export function getAcceptedLedger(deps, attemptId, query) {
+    return request(deps, "GET", `/executions/${encodeURIComponent(attemptId)}/ledger`, { query });
+}
+/** The server's readiness decision at one boundary. */
+export function getReadiness(deps, attemptId, query) {
+    const params = { repo_name: query.repo_name };
+    if (query.boundary)
+        params.boundary = query.boundary;
+    return request(deps, "GET", `/executions/${encodeURIComponent(attemptId)}/readiness`, {
+        query: params,
+    });
+}
+/** Ask the server to confirm delivery after merge. Only it can say `delivery_complete`. */
+export function completeDelivery(deps, attemptId, body) {
+    return request(deps, "POST", `/executions/${encodeURIComponent(attemptId)}/complete`, { body });
+}

package/build/ticket-review-summary.js

@@ -0,0 +1,14 @@
+export function ticketReviewSummary(projection, proposed) {
+    if (projection?.enabled === true && projection.provenance === 'enabled')
+        return 'on';
+    if (projection?.enabled === false && projection.provenance === 'recorded' &&
+        typeof projection.actor === 'string' && /^actor_[a-z0-9]{4,32}$/.test(projection.actor) &&
+        typeof projection.recorded_at === 'string' && /^\d{4}-\d{2}-\d{2}T.+(?:Z|\+00:00)$/.test(projection.recorded_at) && Number.isFinite(Date.parse(projection.recorded_at))) {
+        return `off (set by ${projection.actor} on ${projection.recorded_at.slice(0, 10)})`;
+    }
+    if (projection?.enabled === false)
+        return 'off (legacy choice not recorded)';
+    if (proposed?.spec_review_gate === false)
+        return 'off requested (admin key required; choice recorded at create)';
+    return 'on';
+}

package/build/tool-call-advisory.js

@@ -0,0 +1,162 @@
+/**
+ * First-completed-tool-result upgrade notice (BAPI-1446).
+ *
+ * Wraps the SDK's `tools/call` handler so the first eligible completed result in
+ * a stdio session carries one extra text content item naming both versions and
+ * `/upgrade-bridge`. Tool execution is untouched: the original handler runs
+ * outside the decoration error boundary, so a thrown tool error propagates
+ * exactly as it would without this wrapper, and any failure while decorating
+ * returns the original result.
+ *
+ * Eligibility is decided synchronously, after the original handler resolves, by
+ * `getNoticeDecision`. It never waits for a background lookup. The once-per-
+ * session flag is set only after a successful decoration, so an unknown latest
+ * version, a silent decision, or a result that cannot be decorated safely leaves
+ * the opportunity for a later call.
+ *
+ * Like `installToolSurfaceListOverride`, this reads the SDK's private
+ * `_requestHandlers` map through one localized compatibility adapter.
+ */
+import { getMethodLiteral } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
+import { getNoticeDecision } from "./session-upgrade-notice.js";
+import { formatSessionUpgradeNotice } from "./upgrade-advice.js";
+/** Fixed diagnostic. It never carries exception text or private map contents. */
+export const TOOL_CALL_ADVISORY_INSTALL_FAILURE = "Bridge MCP upgrade notice: tools/call advisory could not be installed (incompatible MCP SDK).";
+/**
+ * Private provenance mark for the genuine, server-sourced `ping` advice item. A
+ * symbol-keyed property survives a shallow copy and is ignored by
+ * `JSON.stringify`, so it never reaches the wire. The symbol is not exported, so
+ * only this module can create or recognize the mark.
+ */
+const SERVER_ADVICE_MARK = Symbol("bridge.serverUpgradeAdvice");
+/** Mark a content item as the genuine server-sourced upgrade advice. Returns it. */
+export function markServerUpgradeAdvice(item) {
+    Object.defineProperty(item, SERVER_ADVICE_MARK, {
+        value: true,
+        enumerable: true,
+        configurable: true,
+        writable: false,
+    });
+    return item;
+}
+function isServerUpgradeAdvice(item) {
+    return (item !== null &&
+        typeof item === "object" &&
+        item[SERVER_ADVICE_MARK] === true);
+}
+/** Protocol servers that already carry the wrapper, so reinstall is a no-op. */
+const installedServers = new WeakSet();
+function authoritativeFrom(getStatus) {
+    const status = getStatus?.();
+    if (status && status.known === true && typeof status.latestVersion === "string") {
+        return { known: true, latest: status.latestVersion };
+    }
+    return { known: false };
+}
+function emit(stderr) {
+    try {
+        stderr?.(TOOL_CALL_ADVISORY_INSTALL_FAILURE);
+    }
+    catch {
+        // A diagnostic sink failure must never affect startup.
+    }
+}
+/**
+ * Install the wrapper. Returns true when it is in place (including an earlier
+ * install on the same protocol server) and false after emitting the one fixed
+ * diagnostic. Never throws, and leaves the original handler in place on failure.
+ */
+export function installToolCallAdvisory(options) {
+    const { protocolServer, callSchema, env, currentVersion, getStatus, stderr } = options;
+    try {
+        if (protocolServer && installedServers.has(protocolServer))
+            return true;
+        let method;
+        try {
+            method = getMethodLiteral(callSchema);
+        }
+        catch {
+            emit(stderr);
+            return false;
+        }
+        if (method !== "tools/call") {
+            emit(stderr);
+            return false;
+        }
+        const handlers = protocolServer?._requestHandlers;
+        if (!handlers || typeof handlers.get !== "function") {
+            emit(stderr);
+            return false;
+        }
+        const original = handlers.get(method);
+        if (typeof original !== "function") {
+            emit(stderr);
+            return false;
+        }
+        // Delivery state belongs to this installation, so it is isolated to one
+        // stdio session.
+        let delivered = false;
+        const decorate = (result) => {
+            if (delivered)
+                return result;
+            if (result === null || typeof result !== "object")
+                return result;
+            const content = result.content;
+            if (!Array.isArray(content))
+                return result;
+            const decision = getNoticeDecision(env, currentVersion, authoritativeFrom(getStatus));
+            if (!decision.show)
+                return result;
+            if (content.some(isServerUpgradeAdvice)) {
+                // The genuine ping advice already told the session.
+                delivered = true;
+                return result;
+            }
+            const notice = formatSessionUpgradeNotice(decision.current, decision.latest);
+            const decorated = {
+                ...result,
+                content: [...content, { type: "text", text: notice }],
+            };
+            delivered = true;
+            return decorated;
+        };
+        const wrapped = async (request, extra) => {
+            // Outside the boundary below: a tool-call error propagates unchanged.
+            const result = await original(request, extra);
+            try {
+                return decorate(result);
+            }
+            catch {
+                return result;
+            }
+        };
+        try {
+            // Replace in place; never remove the original first.
+            protocolServer.setRequestHandler(callSchema, wrapped);
+        }
+        catch {
+            // The replacement may have begun before the failure. Put the original back.
+            try {
+                if (handlers.get(method) !== original) {
+                    try {
+                        protocolServer.setRequestHandler(callSchema, original);
+                    }
+                    catch {
+                        handlers.set(method, original);
+                    }
+                }
+            }
+            catch {
+                // Nothing more can be done safely.
+            }
+            emit(stderr);
+            return false;
+        }
+        installedServers.add(protocolServer);
+        return true;
+    }
+    catch {
+        emit(stderr);
+        return false;
+    }
+}

package/build/tool-surface-gating.js

@@ -372,116 +372,55 @@ function setsEqual(a, b) {
     return true;
 }
 // ---------------------------------------------------------------------------
-// Update-staleness advisory decoration (BAPI-728)
+// Asset-recovery advisory composition
 // ---------------------------------------------------------------------------
-/** The `_meta` key carrying the structured staleness advisory. */
-export const UPDATE_ADVISORY_META_KEY = "bridge-api/update-advisory";
-/** The tool whose description carries the model-visible advisory when stale. */
+//
+// BAPI-1446 removed the update-staleness decoration (BAPI-728) from `tools/list`:
+// the `_meta` key and the text prepended to the `ping` description were an
+// invisible channel, and the upgrade notice now reaches a session through the
+// startup instructions, the first completed tool result, and the SessionStart
+// hook. Only the asset-recovery advisory decorates the list now.
+/** The tool whose description carries the model-visible recovery advisory. */
 const ADVISORY_HOST_TOOL = "ping";
-/**
- * Wrap a `tools/list` handler so a KNOWN-stale server tells the model so.
- *
- * Why decorate the list at all: the staleness value was already computed on every
- * server start and emitted to an MCP log sink nothing reads, so a session talking
- * to a twenty-release-old build looked completely normal — the visible symptom was
- * an agent that could not find `council`, with no signal explaining why. Tool
- * discovery is the one surface every session reads without being asked to.
- *
- * What is preserved, exactly: tool NAMES, their ORDER, their input/output SCHEMAS,
- * their enabled state, and every other response property. The advisory is added in
- * two places, both additive:
- *
- *   - `_meta` — the protocol's sanctioned extension point, for clients that
- *     surface structured metadata;
- *   - the `ping` tool's DESCRIPTION — the surface a model actually reads. `ping`
- *     is the topically correct host: its description already documents the
- *     version/upgrade metadata it returns. Note this does not require anyone to
- *     CALL `ping` — reading its description during ordinary discovery is enough,
- *     which is the precise gap the ticket describes.
- *
- * The description text is appended at RUNTIME only, over the `ping` description
- * from the static tool catalog. That static catalog is untouched, so the
- * description prose pins that guard `mcp_server/src/index.ts` are unaffected —
- * but a LIVE `tools/list` capture DOES include this decoration whenever the
- * update status is stale, and so is NOT automatically safe for tools-budget
- * measurement. Budget measurements stay repository-owned only because their
- * child process explicitly disables the update check via
- * `BAPI_MCP_UPDATE_CHECK_ENABLED=false` (BAPI-917) — see
- * `mcp_server/src/integration/measure-tools.ts`.
- *
- * Fail-open: if the advisory cannot be produced, the original result is returned
- * byte-for-byte.
- */
-export function decorateListResultWithUpdateAdvisory(original, advisory) {
-    if (!advisory)
-        return original;
-    try {
-        const tools = original.tools.map((tool) => tool.name === ADVISORY_HOST_TOOL
-            ? { ...tool, description: `${advisory}\n\n${tool.description ?? ""}`.trimEnd() }
-            : tool);
-        return {
-            ...original,
-            tools,
-            _meta: { ...(original._meta ?? {}), [UPDATE_ADVISORY_META_KEY]: advisory },
-        };
-    }
-    catch {
-        return original;
-    }
-}
-/**
- * Compose an advisory-decorating handler over `inner`.
- *
- * `inner` is the capability gate's handler when dynamic gating is enabled, and
- * the SDK's own captured handler when it is disabled — so turning gating off
- * never turns update visibility off with it.
- */
-export function createUpdateAdvisoryListHandler(inner, getAdvisory, onListServed) {
-    return async (request, extra) => {
-        const result = await inner(request, extra);
-        try {
-            onListServed?.();
-            return decorateListResultWithUpdateAdvisory(result, getAdvisory());
-        }
-        catch {
-            // Never let advisory decoration break tool discovery.
-            return result;
-        }
-    };
-}
-/** Compose once over undecorated SDK results, preserving both metadata keys.
+/** Compose once over undecorated SDK results, preserving the recovery metadata.
  * Weak keys prevent retained results from accumulating session-wide state. */
 const undecoratedResults = new WeakMap();
-export function composeListAdvisories(original, update, recovery) {
+export function composeListAdvisories(original, recovery) {
     const base = undecoratedResults.get(original) ?? original;
-    const updated = decorateListResultWithUpdateAdvisory(base, update);
     if (!recovery)
-        return updated;
+        return base;
     try {
-        const anchor = base.tools.find(t => t.name === "ping") ?? base.tools[0];
-        const result = { ...updated,
-            tools: updated.tools.map(tool => tool.name === anchor?.name
-                ? { ...tool, description: `${tool.name === "ping" && update ? `${update}\n\n` : ""}${recovery.text}\n\n${anchor?.description ?? ""}`.trimEnd() } : tool),
-            _meta: { ...(updated._meta ?? {}), "bridge-api/asset-recovery": { host: recovery.host,
+        const anchor = base.tools.find(t => t.name === ADVISORY_HOST_TOOL) ?? base.tools[0];
+        const result = { ...base,
+            tools: base.tools.map(tool => tool.name === anchor?.name
+                ? { ...tool, description: `${recovery.text}\n\n${anchor?.description ?? ""}`.trimEnd() } : tool),
+            _meta: { ...(base._meta ?? {}), "bridge-api/asset-recovery": { host: recovery.host,
                     missingCount: recovery.missingCount, paths: recovery.paths, capabilities: recovery.capabilities, command: recovery.command } },
         };
         undecoratedResults.set(result, base);
         return result;
     }
     catch {
-        return updated;
+        return base;
     }
 }
-export function createComposedAdvisoryListHandler(inner, getUpdate, getRecovery, onListServed) {
+/**
+ * Compose the recovery advisory over `inner`.
+ *
+ * `inner` is the capability gate's handler when dynamic gating is enabled, and
+ * the SDK's own captured handler when it is disabled — so turning gating off
+ * never turns recovery visibility off with it. A failure to retrieve or apply the
+ * advisory returns the undecorated original result.
+ */
+export function createComposedAdvisoryListHandler(inner, getRecovery) {
     return async (request, extra) => {
         const original = await inner(request, extra);
         try {
             const recovery = await getRecovery();
-            onListServed?.();
-            return composeListAdvisories(original, getUpdate(), recovery);
+            return composeListAdvisories(original, recovery);
         }
         catch {
-            return decorateListResultWithUpdateAdvisory(original, getUpdate());
+            return original;
         }
     };
 }