@bridge_gpt/mcp-server 0.2.68 → 0.2.69

package/build/session-upgrade-notice.js

@@ -0,0 +1,86 @@
+/**
+ * The single "should this session be told about an upgrade?" decision (BAPI-1446).
+ *
+ * Every notice surface asks here: the startup instructions, the first completed
+ * tool result, the Claude SessionStart hook, the `ping` advice, and the
+ * `start-tickets` reminder. One synchronous, non-throwing function holds every
+ * eligibility and silence rule, so the surfaces cannot drift apart.
+ *
+ * Nothing in this module touches the network or starts asynchronous work. The
+ * only I/O is the synchronous read of the local update cache.
+ */
+import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { isNewerVersion, isPlainReleaseVersion, readCachedLatestVersion, readFakeLatestOverride, } from "./update-check.js";
+import { formatSessionUpgradeNotice } from "./upgrade-advice.js";
+/** The kill switch for every update check and notice. Default on. */
+export const UPDATE_CHECK_ENABLED_ENV = "BAPI_MCP_UPDATE_CHECK_ENABLED";
+/** Worker markers: either one means no person is watching the session. */
+export const UNATTENDED_MARKER_ENVS = [
+    "BAPI_WORKER_BRANCH",
+    "BAPI_EPIC_IMPLEMENTER_WORKER_ID",
+];
+const SILENT = { show: false };
+/** True when either worker marker holds a non-empty string. */
+export function isUnattendedSession(env) {
+    return UNATTENDED_MARKER_ENVS.some((name) => {
+        const value = env[name];
+        return typeof value === "string" && value.trim().length > 0;
+    });
+}
+/**
+ * Decide whether to show the upgrade notice. Never throws and never starts
+ * asynchronous work.
+ *
+ * Silence comes first: a disabled kill switch, an unattended session, or an
+ * invalid current version returns `{ show: false }` before any latest-version
+ * source is read.
+ *
+ * Latest-version sources, in order:
+ *   1. a valid `BAPI_MCP_UPDATE_CHECK_FAKE_LATEST` override;
+ *   2. a reliable, known authoritative latest from a settled live check, which
+ *      stays authoritative even when it says "current" and an older cache
+ *      would suggest an update;
+ *   3. the local cache, when the authoritative source is absent, still in
+ *      flight, or failed.
+ *
+ * The cache ignores its own age on purpose. It is a lower bound: it can
+ * under-claim an update but never claims one that does not exist. Unknown,
+ * equal, older, or invalid versions are silent.
+ */
+export function getNoticeDecision(env, currentVersion, authoritativeLatest) {
+    try {
+        if (!parseDefaultOnEnvFlag(env[UPDATE_CHECK_ENABLED_ENV]))
+            return SILENT;
+        if (isUnattendedSession(env))
+            return SILENT;
+        if (!isPlainReleaseVersion(currentVersion))
+            return SILENT;
+        let latest = readFakeLatestOverride(env);
+        if (latest === null &&
+            authoritativeLatest &&
+            authoritativeLatest.known === true &&
+            isPlainReleaseVersion(authoritativeLatest.latest)) {
+            latest = authoritativeLatest.latest;
+        }
+        if (latest === null)
+            latest = readCachedLatestVersion(env);
+        if (!isPlainReleaseVersion(latest))
+            return SILENT;
+        if (!isNewerVersion(currentVersion, latest))
+            return SILENT;
+        return { show: true, current: currentVersion, latest };
+    }
+    catch {
+        return SILENT;
+    }
+}
+/**
+ * Append the session notice to the server's startup instructions when eligible.
+ * The base string is returned unchanged when the decision is silent.
+ */
+export function composeServerInstructions(baseInstructions, env, currentVersion) {
+    const decision = getNoticeDecision(env, currentVersion);
+    if (!decision.show)
+        return baseInstructions;
+    return `${baseInstructions} ${formatSessionUpgradeNotice(decision.current, decision.latest)}`;
+}

package/build/start-tickets.js

@@ -63,6 +63,8 @@ import path from "path";
 import { fileURLToPath } from "node:url";
 import { validateHttpBaseUrl } from "./base-url.js";
 import { VERSION } from "./version.generated.js";
+import { getNoticeDecision } from "./session-upgrade-notice.js";
+import { formatUpdateAdvice } from "./upgrade-advice.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { LEGACY_SERVER_NAMES, MCP_PACKAGE_NAME, MCP_SERVER_NAME } from "./mcp-identity.js";
 // BAPI-941: the shared drift diagnostic formatter. The leaf drift module imports
@@ -4150,6 +4152,19 @@ export async function runStartTicketsCli(argv, overrides = {}) {
     const options = parsed.options;
     const rawDeps = overrides.deps ?? createDefaultStartTicketsDeps();
     const orchestrate = overrides.orchestrate ?? orchestrateStartTickets;
+    // BAPI-1446: one cache-only upgrade reminder per run, on the existing stderr
+    // sink. The decision is evaluated over the EFFECTIVE environment, so a worker's
+    // markers (set when this CLI is itself run by an unattended process) keep it
+    // silent. It reads the local cache only, never the network, and any failure is
+    // contained: it never changes command execution or the exit status.
+    try {
+        const decision = (overrides.upgradeNotice ?? ((env) => getNoticeDecision(env, VERSION)))(rawDeps.env);
+        if (decision.show)
+            errorLog(formatUpdateAdvice(decision.current, decision.latest));
+    }
+    catch {
+        // Advisory only.
+    }
     // The parser validates `--agent`, so this resolves to a real spec; the guard
     // is defensive only.
     const agent = resolveAgentSpec(options.agentName);

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

package/build/update-check.js

@@ -1,7 +1,10 @@
 /**
  * Update check logic — extracted for testability.
- * The main index.ts imports and calls checkForUpdate().
+ * `update-status.ts` (the background manager) and `doctor.ts` call checkForUpdate();
+ * the synchronous notice paths use `readCachedLatestVersion` and never touch the
+ * network.
  */
+import { readFileSync } from "fs";
 import { writeFile, mkdir, readFile } from "fs/promises";
 import path from "path";
 import os from "os";
@@ -10,13 +13,51 @@ import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 const CACHE_TTL = 86400000; // 24 hours
 const FETCH_TIMEOUT = 3000;
 const REGISTRY_URL = `https://registry.npmjs.org/${MCP_PACKAGE_NAME}/latest`;
+/** Manual-only override of the latest version, for exercising the notice paths. */
+export const FAKE_LATEST_ENV = "BAPI_MCP_UPDATE_CHECK_FAKE_LATEST";
+const PLAIN_RELEASE_RE = /^\d+\.\d+\.\d+$/;
 export function getCachePath() {
     return path.join(os.homedir(), ".config", ...MCP_PACKAGE_NAME.split("/"), "update-check.json");
 }
+/** True only for a plain `MAJOR.MINOR.PATCH` release string. */
+export function isPlainReleaseVersion(value) {
+    return typeof value === "string" && PLAIN_RELEASE_RE.test(value);
+}
+/**
+ * Read the manual fake-latest override. Returns the value only when it is a plain
+ * release string; anything else (absent, blank, a prerelease, shell text) is
+ * ignored and never echoed.
+ */
+export function readFakeLatestOverride(env = process.env) {
+    const value = env[FAKE_LATEST_ENV];
+    return isPlainReleaseVersion(value) ? value : null;
+}
+/** Compare two digit strings numerically without converting them to Numbers. */
+function compareDigitStrings(a, b) {
+    const x = a.replace(/^0+(?=\d)/, "");
+    const y = b.replace(/^0+(?=\d)/, "");
+    if (x.length !== y.length)
+        return x.length > y.length ? 1 : -1;
+    if (x === y)
+        return 0;
+    return x > y ? 1 : -1;
+}
 /**
  * Compare two semver strings. Returns true if `latest` is strictly greater.
+ * Valid release strings are compared segment by segment as digit strings, so a
+ * segment beyond the safe-integer range keeps its ordering.
  */
 export function isNewerVersion(current, latest) {
+    if (isPlainReleaseVersion(current) && isPlainReleaseVersion(latest)) {
+        const c = current.split(".");
+        const l = latest.split(".");
+        for (let i = 0; i < 3; i++) {
+            const order = compareDigitStrings(l[i], c[i]);
+            if (order !== 0)
+                return order > 0;
+        }
+        return false;
+    }
     const c = current.split(".").map(Number);
     const l = latest.split(".").map(Number);
     for (let i = 0; i < 3; i++) {
@@ -27,28 +68,66 @@ export function isNewerVersion(current, latest) {
     }
     return false;
 }
+/**
+ * Read the latest version the server last cached, synchronously and offline.
+ *
+ * A valid override wins before the cache is opened. The cache's age is ignored on
+ * purpose: a cached latest can only be older than the real latest, so it is a
+ * lower bound. It may under-claim an update, but it never claims one that does
+ * not exist. Any missing, corrupt, malformed, or unreadable cache returns null.
+ */
+export function readCachedLatestVersion(env = process.env) {
+    try {
+        const override = readFakeLatestOverride(env);
+        if (override)
+            return override;
+        const cache = JSON.parse(readFileSync(getCachePath(), "utf-8"));
+        if (cache === null || typeof cache !== "object" || Array.isArray(cache))
+            return null;
+        const { lastCheck, latestVersion } = cache;
+        if (typeof lastCheck !== "number" || !Number.isFinite(lastCheck))
+            return null;
+        return isPlainReleaseVersion(latestVersion) ? latestVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Checks the npm registry for a newer version of @bridge_gpt/mcp-server.
  * Results are cached for 24 hours. Returns null if the check fails.
  */
-export async function checkForUpdate() {
+export async function checkForUpdate(options = {}) {
     try {
+        const override = readFakeLatestOverride(options.env ?? process.env);
+        if (override) {
+            // An override is never cached, so it cannot outlive the manual test.
+            return {
+                updateAvailable: isNewerVersion(VERSION, override),
+                currentVersion: VERSION,
+                latestVersion: override,
+            };
+        }
+        const useCache = options.readCache !== false;
+        const saveCache = options.writeCache !== false;
         const cachePath = getCachePath();
         const cacheDir = path.dirname(cachePath);
         let latestVersion = null;
         // Try reading cache
-        try {
-            const raw = await readFile(cachePath, "utf-8");
-            const cache = JSON.parse(raw);
-            if (cache &&
-                typeof cache.lastCheck === "number" &&
-                typeof cache.latestVersion === "string" &&
-                Date.now() - cache.lastCheck < CACHE_TTL) {
-                latestVersion = cache.latestVersion;
+        if (useCache) {
+            try {
+                const raw = await readFile(cachePath, "utf-8");
+                const cache = JSON.parse(raw);
+                if (cache &&
+                    typeof cache.lastCheck === "number" &&
+                    isPlainReleaseVersion(cache.latestVersion) &&
+                    Date.now() - cache.lastCheck < CACHE_TTL) {
+                    latestVersion = cache.latestVersion;
+                }
+            }
+            catch {
+                // Cache missing, corrupt, or stale — will fetch fresh
             }
-        }
-        catch {
-            // Cache missing, corrupt, or stale — will fetch fresh
         }
         // Fetch from registry if no valid cache
         if (!latestVersion) {
@@ -57,10 +136,12 @@ export async function checkForUpdate() {
             try {
                 const res = await fetch(REGISTRY_URL, { signal: controller.signal });
                 const data = await res.json();
-                if (data.version) {
+                if (isPlainReleaseVersion(data.version)) {
                     latestVersion = data.version;
-                    await mkdir(cacheDir, { recursive: true });
-                    await writeFile(cachePath, JSON.stringify({ lastCheck: Date.now(), latestVersion }), "utf-8");
+                    if (saveCache) {
+                        await mkdir(cacheDir, { recursive: true });
+                        await writeFile(cachePath, JSON.stringify({ lastCheck: Date.now(), latestVersion }), "utf-8");
+                    }
                 }
             }
             finally {