@bridge_gpt/mcp-server 0.2.68 → 0.2.69

package/build/update-status.js

@@ -1,69 +1,86 @@
 /**
- * Process-wide cached update status (BAPI-728).
+ * Process-wide settled update status (BAPI-728, reshaped by BAPI-1446).
  *
- * The staleness signal already existed — `checkForUpdate()` ran on every server
- * start and computed the right answer. It was emitted through
- * `sendLoggingMessage({ level: "notice", ... })`, an MCP log sink that no user
- * or model surface reads. The published 0.2.16 tarball shipped that code, so a
- * stale server correctly computed `updateAvailable: true` and announced it to
- * nobody, on every session, for twenty releases.
+ * The staleness signal already existed: `checkForUpdate()` ran on every server
+ * start and computed the right answer, then announced it to a log sink nobody
+ * reads. BAPI-1446 moved delivery to surfaces a session actually reads (startup
+ * instructions, the first completed tool result, the SessionStart hook). This
+ * manager is now only the source of one fact for those surfaces: what the live
+ * check concluded, once it has settled.
  *
- * This manager gives that value two readers instead of zero: one stderr warning
- * per process (humans), and a `tools/list` advisory (models). It is:
+ * The settled-status contract:
  *
  *   - **single-flight** — one `checkForUpdate()` per process, cached forever;
- *   - **non-blocking** — started at boot, never awaited before `connect`;
- *   - **fail-open** — a null, malformed, rejected, or not-newer result yields
- *     no advisory and no warning, and never throws.
+ *   - **non-blocking** — `start()` returns at once and is never awaited before
+ *     `connect`; `getStatus()` is synchronous and never waits for the lookup;
+ *   - **known versus unknown** — `known: true` means a reliable live result
+ *     settled, including "you are current". Initial, in-flight, disabled,
+ *     rejected, null, and malformed outcomes are `known: false` and not stale, so
+ *     the tool-result channel never mistakes "unknown" for "confirmed current"
+ *     and can fall back to the local cache;
+ *   - **fail-open** — nothing here throws, and `whenSettled()` never rejects.
  *
- * The manager is default-on. Passing `enabled: false` (BAPI-917) makes it
- * permanently `NOT_STALE` from the moment `start()` returns, without ever
- * invoking the checker, touching the update cache, or making a registry
- * request — used so a hermetic measurement capture cannot be perturbed by
- * runtime update state.
+ * `stale` is kept for existing production consumers and is only ever true for a
+ * reliable newer result.
+ *
+ * Passing `enabled: false` (BAPI-917) makes the manager permanently unknown from
+ * the moment `start()` returns, without invoking the checker, touching the update
+ * cache, or making a registry request — used so a hermetic measurement capture
+ * cannot be perturbed by runtime update state.
  */
-import { checkForUpdate } from "./update-check.js";
-import { formatUpdateAdvice, formatToolSurfaceUpdateAdvisory } from "./upgrade-advice.js";
-/** The not-stale conclusion, used for every fail-open branch. */
-const NOT_STALE = { stale: false };
+import { checkForUpdate, isNewerVersion, isPlainReleaseVersion, readFakeLatestOverride, } from "./update-check.js";
+import { VERSION } from "./version.generated.js";
+/** The unknown conclusion, used for every fail-open branch. */
+const UNKNOWN = { stale: false, known: false };
 /**
  * Build the manager. Nothing runs until `start()` is called, so importing this
  * module never performs I/O.
  */
 export function createUpdateStatusManager(options = {}) {
-    const check = options.check ?? checkForUpdate;
-    const warn = options.warn ?? ((message) => console.error(message));
+    const env = options.env ?? process.env;
+    const check = options.check ?? (() => checkForUpdate({ env }));
     const enabled = options.enabled !== false;
+    const runningVersion = options.currentVersion ?? VERSION;
     let started = false;
     let settled = null;
     let settledPromise = null;
-    let warned = false;
-    let listServed = false;
-    let lateNotified = false;
     function conclude(result) {
-        // Every uncertain shape is fail-open. A malformed payload must never produce
-        // an advisory telling a user to upgrade to a version that may not exist.
+        // Every uncertain shape is unknown. A malformed payload must never produce a
+        // claim about a version that may not exist.
         if (!result || typeof result !== "object")
-            return NOT_STALE;
-        if (result.updateAvailable !== true)
-            return NOT_STALE;
+            return UNKNOWN;
+        if (typeof result.updateAvailable !== "boolean")
+            return UNKNOWN;
         const { currentVersion, latestVersion } = result;
-        if (typeof currentVersion !== "string" || currentVersion.length === 0)
-            return NOT_STALE;
-        if (typeof latestVersion !== "string" || latestVersion.length === 0)
-            return NOT_STALE;
-        return { stale: true, currentVersion, latestVersion };
+        if (!isPlainReleaseVersion(currentVersion))
+            return UNKNOWN;
+        if (!isPlainReleaseVersion(latestVersion))
+            return UNKNOWN;
+        return { stale: result.updateAvailable, known: true, currentVersion, latestVersion };
     }
     function start() {
         if (started)
             return;
         started = true;
         if (!enabled) {
-            // Disabled: settle immediately, without ever invoking `check`, warning,
-            // or scheduling a checker operation. `whenSettled()` stays usable — it
-            // just resolves to the same already-known conclusion.
-            settled = NOT_STALE;
-            settledPromise = Promise.resolve(NOT_STALE);
+            // Disabled: settle immediately, without ever invoking `check`. `whenSettled()`
+            // stays usable — it just resolves to the same already-known conclusion.
+            settled = UNKNOWN;
+            settledPromise = Promise.resolve(UNKNOWN);
+            return;
+        }
+        // A valid fake-latest override settles at once, before any filesystem or
+        // registry work, exactly as `checkForUpdate` honors it.
+        const override = readFakeLatestOverride(env);
+        if (override && isPlainReleaseVersion(runningVersion)) {
+            const status = {
+                stale: isNewerVersion(runningVersion, override),
+                known: true,
+                currentVersion: runningVersion,
+                latestVersion: override,
+            };
+            settled = status;
+            settledPromise = Promise.resolve(status);
             return;
         }
         settledPromise = (async () => {
@@ -72,46 +89,19 @@ export function createUpdateStatusManager(options = {}) {
                 status = conclude(await check());
             }
             catch {
-                status = NOT_STALE; // `checkForUpdate` is contracted not to reject; belt and braces.
+                status = UNKNOWN; // `checkForUpdate` is contracted not to reject; belt and braces.
             }
             settled = status;
-            if (status.stale && !warned) {
-                warned = true;
-                // stderr, never stdout: stdout is the JSON-RPC frame channel and any
-                // stray write there corrupts the protocol stream.
-                warn(formatUpdateAdvice(status.currentVersion, status.latestVersion));
-                if (listServed && !lateNotified) {
-                    lateNotified = true;
-                    try {
-                        options.onLateStale?.();
-                    }
-                    catch {
-                        // A notification failure must never affect server operation.
-                    }
-                }
-            }
             return status;
         })();
     }
     return {
         start,
-        getStatus: () => settled ?? NOT_STALE,
+        getStatus: () => settled ?? UNKNOWN,
         whenSettled: async () => {
             if (!started)
                 start();
-            return (await settledPromise) ?? NOT_STALE;
-        },
-        markListServed: () => {
-            listServed = true;
+            return (await settledPromise) ?? UNKNOWN;
         },
     };
 }
-/**
- * Produce the model-visible advisory for a settled status, or null when the
- * status is not (yet) known-stale. Pure — safe to call on every list request.
- */
-export function updateAdvisoryFor(status) {
-    if (!status.stale || !status.currentVersion || !status.latestVersion)
-        return null;
-    return formatToolSurfaceUpdateAdvisory(status.currentVersion, status.latestVersion);
-}

package/build/upgrade-advice.js

@@ -29,20 +29,24 @@ function sanitizeVersion(value) {
     return typeof value === "string" && SAFE_VERSION_RE.test(value) ? value : "unknown";
 }
 /**
- * Format the one-line staleness advisory shown to humans (stderr) and models
- * (tool discovery). Only the two version values vary; the command is constant.
+ * Format the human-facing staleness line (stderr, terminal, `doctor`, and the
+ * `ping` advice item). It names both versions and the slash command, and carries
+ * no instruction for a model; the model-directed text is
+ * {@link formatSessionUpgradeNotice}.
  */
 export function formatUpdateAdvice(currentVersion, latestVersion) {
-    return (`Bridge API MCP server update available: running ${sanitizeVersion(currentVersion)}, ` +
-        `latest ${sanitizeVersion(latestVersion)} — run ${CANONICAL_UPGRADE_COMMAND}`);
+    return (`Bridge MCP: installed ${sanitizeVersion(currentVersion)}, ` +
+        `latest ${sanitizeVersion(latestVersion)} — upgrade available — run /upgrade-bridge`);
 }
 /**
- * The compact form attached to `tools/list`, so a model can see that the tool
- * surface it is looking at may be missing or misnaming tools that exist in a
- * newer release (the BAPI-645 `council` rename is the canonical example).
+ * Format the one-line, plain-text notice delivered to a model session (startup
+ * instructions, the first completed tool result, the SessionStart hook). It tells
+ * the model to inform the user, offer the upgrade, and run `/upgrade-bridge`
+ * only if they say yes. Both versions go through `sanitizeVersion`, so no
+ * caller can interpolate arbitrary text.
  */
-export function formatToolSurfaceUpdateAdvisory(currentVersion, latestVersion) {
-    return (`NOTE: this Bridge API MCP server is running ${sanitizeVersion(currentVersion)}, ` +
-        `but ${sanitizeVersion(latestVersion)} is published. Some tools may be missing or ` +
-        `renamed in this older build. To update, run: ${CANONICAL_UPGRADE_COMMAND}`);
+export function formatSessionUpgradeNotice(current, latest) {
+    return (`Bridge MCP upgrade available: this session is running ${sanitizeVersion(current)} ` +
+        `and ${sanitizeVersion(latest)} is published. Tell the user an upgrade is available, ` +
+        "offer to run /upgrade-bridge, and run it only if they say yes.");
 }