@ggui-ai/mcp-server 0.24.0 → 0.26.0

package/dist/mcp-apps-outbound.js

@@ -34,12 +34,13 @@
 import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, filterDescriptorsToContract, findBlueprintExact, resolveSliceTheme, spreadRenderMetaViewOntoSlice, wsOriginToHttpOrigin, } from "@ggui-ai/mcp-server-handlers/renders";
 import { fontFaceRules } from "@ggui-ai/design/themes";
 import { GGUI_WAVE_VERSION, RESOURCE_NOT_FOUND_MESSAGE, deriveContextDefault, isRecord, resolveAppGadgets, resourceReadErrorToJsonRpc, } from "@ggui-ai/protocol";
-import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, GGUI_RENDER_SHELL_SCHEME_STYLE, GGUI_RENDER_SHELL_SURFACE, GGUI_SHELL_LOADING_INDICATOR_HTML, MCP_APPS_UI_CAPABILITY, MCP_APP_BOOTSTRAP_FAILED_TYPE, asGguiRenderBootstrap, composeSessionApiUrls, deriveContextName, escapeInlineScript, gguiShellHtml, parseEpochUri, toMcpAppEnvelope, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, GGUI_RENDER_SHELL_SCHEME_STYLE, GGUI_RENDER_SHELL_SURFACE, GGUI_SHELL_LOADING_INDICATOR_HTML, MCP_APPS_UI_CAPABILITY, MCP_APP_BOOTSTRAP_FAILED_TYPE, asGguiRenderBootstrap, composeSessionApiUrls, deriveContextName, escapeInlineScript, gguiShellHtml, parseEpochUri, runtimeBundleHashedNameSource, toMcpAppEnvelope, } from "@ggui-ai/protocol/integrations/mcp-apps";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
 import { createHash } from "node:crypto";
-import { renderReadAllowed } from "./render-read-gate.js";
+import { RENDER_READ_APP_TRUST_OVER_SUBJECT, renderReadVerdict } from "@ggui-ai/mcp-server-handlers/renders";
 import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
+import { RUNTIME_BUNDLE_PLAIN_NAME } from "./runtime-bundle-hash.js";
 /**
  * Thin-shell body served from `ui://ggui/render` (C8 pivot).
  *
@@ -152,6 +153,12 @@ var rootEl=document.getElementById('ggui-root');
 rootEl.style.cssText='display:flex;flex-direction:column;height:100%;min-height:300px;margin:0';
 var mounted=false;
 var lastEnvelope=null;
+// ggui#1501: a content-hashed runtime URL -> its unhashed twin (same origin,
+// same path, only the hash removed). Every server replica serves the twin no-cache, so
+// a hash no serving replica has (rolling deploy, rollback, replay) retries it once.
+var RT_HASHED=new RegExp(${JSON.stringify(runtimeBundleHashedNameSource(RUNTIME_BUNDLE_PLAIN_NAME))});
+var RT_BASE=${JSON.stringify(RUNTIME_BUNDLE_PLAIN_NAME.slice(0, RUNTIME_BUNDLE_PLAIN_NAME.lastIndexOf(".")))};
+function plainRuntimeTwin(u){var m=RT_HASHED.exec(u);return m?m[1]+RT_BASE+m[2]+m[3]:null;}
 // Text color pairs with the shell surface: themed var when the runtime
 // injected theme CSS, else the scheme-scoped pre-theme ink the shell's
 // own scheme <style> defines (#662) — legible on whichever neutral
@@ -261,6 +268,10 @@ async function mountFromMeta(envelope){
   // bundle responds with the right CORS headers (the iframe-runtime
   // mount sets them). The self-contained shell already uses this
   // pattern; legacy postMessage shell now matches it.
+  rootEl.innerHTML='';
+  loadRuntime(runtimeUrl,false);
+}
+function loadRuntime(url,isTwin){
   try{
     var s=document.createElement('script');
     s.type='module';
@@ -272,14 +283,21 @@ async function mountFromMeta(envelope){
     // console -- the bundle ships ACAO=* so credentialed mode is
     // unnecessary.
     s.crossOrigin='anonymous';
-    s.src=runtimeUrl;
+    s.src=url;
     s.onload=function(){mounted=true;};
     s.onerror=function(e){
+      // ggui#1501: a hashed URL gets ONE retry through its unhashed twin;
+      // the twin, or any other URL, fails as before.
+      var twin=isTwin?null:plainRuntimeTwin(url);
+      if(twin){
+        try{console.warn('[ggui] runtime bundle failed to load; retrying its unhashed twin once');}catch(_){}
+        loadRuntime(twin,true);
+        return;
+      }
       var msg='Runtime bundle failed to load: '+(e&&e.message||'script error');
       showFailure('This view could not load','BUNDLE_FETCH_FAILED: '+msg,function(){mountFromMeta(lastEnvelope);});
       postBootstrapFailed('BUNDLE_FETCH_FAILED',msg);
     };
-    rootEl.innerHTML='';
     document.body.appendChild(s);
   }catch(e){
     var msg='Runtime bundle failed to load: '+(e&&e.message||e);
@@ -432,14 +450,20 @@ startInit();
 // The design scope root (`.ggui-rcr-*`) and the sandbox-proxy outer
 // document stay `background-color: transparent` by design (so a host
 // themeing the chat surface shows through AROUND the rendered content).
-// But nothing painted the rendered-content document's OWN backdrop:
-// Chrome composited the transparent iframe document over the dark host
-// app behind it (looked dark), while Safari renders a transparent
-// iframe document's backdrop as the opaque UA `Canvas` color (white) —
-// the per-browser divergence the bug reported. The component itself
-// themed correctly (its scoped vars resolve); only the page behind it
-// diverged. Painting the served document's own surface here removes the
-// dependency on a browser honoring iframe transparency.
+// But nothing painted the rendered-content document's OWN backdrop,
+// and an unpainted iframe document is only see-through while its used
+// `color-scheme` matches its embedder's: on a mismatch the browser
+// paints the iframe's canvas opaque in the document's own scheme
+// colour (white for light, near-black for dark). This shell declares
+// `light dark`, so its used scheme follows the viewer's preference,
+// not the host's — a dark host under a light-preferring viewer got a
+// white canvas. That is what the 2026-05-30 bug saw as
+// Chrome-dark-versus-Safari-white (`8b52c42ed`); measured 2026-09-26
+// (ggui#1125) Safari 26.3 and Chrome 154 behave alike, per scheme,
+// not per engine. The component itself themed correctly (its scoped
+// vars resolve); only the page behind it diverged. Painting the served
+// document's own surface here removes the dependency on the schemes
+// matching.
 //
 // The paint is inline, so no stylesheet `background` rule can undo
 // it — which is why the constant's `var()` chain opens with the
@@ -963,6 +987,7 @@ export function buildSelfContainedShell(opts) {
         // input is renamed to `wsToken` on the slice for wire-field parity.
         ...(opts.wsUrl !== undefined ? { wsUrl: opts.wsUrl } : {}),
         ...(opts.token !== undefined ? { wsToken: opts.token } : {}),
+        ...(opts.token !== undefined && opts.viewKey !== undefined ? { viewKey: opts.viewKey } : {}),
         ...(opts.expiresAt !== undefined ? { expiresAt: opts.expiresAt } : {}),
         // Polling fallback URL — lights up `@ggui-ai/live-channel`'s
         // events-polling transport when WS is unavailable. Absent ⇒
@@ -1030,7 +1055,11 @@ export function buildSelfContainedShell(opts) {
     // the only layer that can detect a compositing host at runtime —
     // drops the backdrop to transparent itself where that is right,
     // and every other context keeps the per-browser-consistent paint.
-    return gguiShellHtml(bootstrap, { background: "surface" });
+    // ggui#1501: a hashed runtime URL that 404s (a hash no serving replica has,
+    // during a rolling deploy, after a rollback, or on a replay) retries its
+    // unhashed twin once. A custom `runtime.path` with another filename, or a
+    // foreign URL, is not the hashed default name and gets no retry.
+    return gguiShellHtml(bootstrap, { background: "surface", runtimeBundlePlainName: RUNTIME_BUNDLE_PLAIN_NAME });
 }
 /**
  * A `resources/read` on a render locator that cannot return a mount.
@@ -1250,6 +1279,19 @@ function pickComponentFromGguiSession(render) {
  *
  * @public
  */
+/**
+ * Why the read door issues no view key on this read (ggui#1415), or
+ * `undefined` when it issues one: the mount does not opt in, or the caller
+ * is anonymous (or carries no auth source).
+ */
+function viewKeyWithheldAtReadDoor(opts) {
+    if (opts.issueViewKeys !== true)
+        return "not_a_view_mount";
+    const authSource = opts.getContext?.()?.authSource;
+    if (authSource === undefined || authSource === "anonymous")
+        return "anonymous_mount";
+    return undefined;
+}
 export function registerGguiRenderResourceTemplate(server, opts) {
     // TWO templates registered against the same handler core:
     //
@@ -1488,8 +1530,19 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 requestId: "resource-read",
             }
             : callerCtx;
-        if (renderReadAllowed(candidate, fallbackCtx))
+        const verdict = renderReadVerdict(candidate, fallbackCtx);
+        if (verdict.allowed) {
+            // ggui#1553: rung 4 admitted an app credential to a subject-bound
+            // session. Door, app, source; never the session or the subject.
+            if (verdict.appTrustOverSubject) {
+                opts.logger?.info(RENDER_READ_APP_TRUST_OVER_SUBJECT, {
+                    door: "resources_read",
+                    appId: candidate.appId,
+                    source: fallbackCtx?.authSource ?? null,
+                });
+            }
             return true;
+        }
         opts.logger?.warn("render_resource_read_denied", {
             sessionId,
             rowAppId: candidate.appId,
@@ -1552,6 +1605,16 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         if (record.blueprintId === null) {
             return { ok: false, failure: blueprintUnresolvable("the record names no blueprint") };
         }
+        // ggui#1405 — an ephemeral id was never registered: the render served
+        // fresh code at a key bound to other code. Say that, rather than
+        // calling a row that never existed "gone".
+        if (record.blueprintIdentity === "ephemeral") {
+            return {
+                ok: false,
+                failure: blueprintUnresolvable("the render served code no blueprint stores (an ephemeral identity)"),
+                terminal: true,
+            };
+        }
         const blueprint = await blueprintStore.get(record.blueprintId);
         if (blueprint === null) {
             return {
@@ -1816,9 +1879,25 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         let wsUrl;
         let wsToken;
         let wsExpiresAt;
+        let wsViewKey;
         if (opts.mintWsToken) {
             try {
-                const minted = opts.mintWsToken(sessionId, accessibleStored.appId);
+                // ggui#1415: a view root, and its key, only on a key-issuing mount
+                // and for a caller that is not anonymous; any other read mints the
+                // live credential alone.
+                const withheld = viewKeyWithheldAtReadDoor(opts);
+                let minted;
+                if (opts.mintViewRoot !== undefined && withheld === undefined) {
+                    const root = opts.mintViewRoot(sessionId, accessibleStored.appId);
+                    wsViewKey = root.viewKey;
+                    minted = root;
+                }
+                else {
+                    minted = opts.mintWsToken(sessionId, accessibleStored.appId);
+                    if (opts.mintViewRoot !== undefined && withheld !== undefined) {
+                        opts.logger?.info("view_key_not_issued", { sessionId, src: "read", reason: withheld });
+                    }
+                }
                 wsUrl = minted.wsUrl;
                 wsToken = minted.token;
                 // Forward the token TTL so the iframe-runtime can degrade to
@@ -1898,6 +1977,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                     wsUrl,
                     token: wsToken,
                     ...(wsExpiresAt !== undefined ? { expiresAt: wsExpiresAt } : {}),
+                    ...(wsViewKey !== undefined ? { viewKey: wsViewKey } : {}),
                 }
                 : {}),
             // Layered theme — the SAME resolver the tool-result slice uses
@@ -2165,6 +2245,11 @@ export function registerGguiRenderResourceTemplate(server, opts) {
             }
             else {
                 failure = reminted.failure;
+                // An entitled read of an ephemeral render stops here: the registry
+                // holds OTHER code at this key (ggui#1405), so the fallback below
+                // would mount the wrong card under this render's locator.
+                if (reminted.terminal === true)
+                    throw new ResourceReadFailure(failure);
             }
         }
         // Registry-only fallback: render is gone (TTL / restart) but the

package/dist/mcp-endpoint-routes.d.ts

@@ -46,6 +46,7 @@ interface PerAppRouting {
     readonly paramPattern: string;
     readonly pathPrefix?: string;
     readonly authorize?: (urlAppId: string, identity: AuthResult) => Promise<void>;
+    readonly perAppOnlySources?: readonly AuthResult["source"][];
 }
 /**
  * Return shape for an `errorMapper` hook — a domain error mapped onto

package/dist/mcp-endpoint-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,mFAAmF;AACnF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AA2CD,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4f1D"}

package/dist/mcp-endpoint-routes.js

@@ -284,6 +284,34 @@ export function mountMcpEndpoints(opts) {
         // may give the refusal a structured JSON-RPC `data` (bounded to
         // 401 / 403, see `mapAuthorizationRefusal`); otherwise — and for
         // every mapping outside those bounds — the default-deny 403 stands.
+        // ggui#1482 — a credential source the deployment lists as
+        // per-app-only is valid only at its app's endpoint. Every mount
+        // this handler serves without an app in its URL (the universal
+        // route, any isolated service) never runs `authorize`, so it
+        // refuses such a credential before dispatch rather than serve it
+        // without the checks that live there. (The control plane's own
+        // federated refusal above answers first on `/control`.) Named in
+        // the message so a caller corrects its URL instead of retrying.
+        // Untyped by contract, like every auth-class refusal (SPEC §7.1):
+        // it is about the caller's credential, not the app's state, so it
+        // carries no `data` and no registry code names it.
+        if (!hasUrlAppId && perAppRouting?.perAppOnlySources?.includes(identity.source)) {
+            reqLogger.warn("per_app_only_source_refused", {
+                route: handlerOpts?.mountPath ?? universalMcpPath,
+                path: req.path,
+                source: identity.source,
+                appId: appIdFromIdentity(identity),
+            });
+            res.status(403).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: MCP_ERROR_CODES.UNAUTHORIZED,
+                    message: "this credential is valid only at its app's endpoint",
+                },
+                id: null,
+            });
+            return;
+        }
         if (hasUrlAppId && perAppRouting?.authorize) {
             try {
                 await perAppRouting.authorize(urlAppId, identity);
@@ -342,6 +370,7 @@ export function mountMcpEndpoints(opts) {
         reqLogger.debug?.("mcp_request", { appId: ctx.appId });
         const mcp = buildMcpServer(info, routeHandlers, () => als.getStore() ?? ctx, reqLogger, {
             ...buildMcpOptions,
+            ...(handlerOpts?.issueViewKeys === true ? { issueViewKeys: true } : {}),
         });
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
@@ -405,10 +434,13 @@ export function mountMcpEndpoints(opts) {
     // intersects ['agent','runtime']. Handlers without an explicit tag
     // default to ['agent'], so every untagged handler is agent-callable.
     const agentRouteHandlers = filterHandlersByAudience(handlers, DATA_PLANE_AUDIENCES);
-    const agentMcpHandler = makeMcpHandler(agentRouteHandlers);
+    // The data plane delivers views to app-credentialed callers, so its read
+    // door is the one that issues view keys (ggui#1415).
+    const agentMcpHandler = makeMcpHandler(agentRouteHandlers, { issueViewKeys: true });
     // Control plane — anonymous-capable (design-time tools answer
     // bearer-less) with each ops tool re-imposing auth for itself.
     const controlMcpHandler = makeMcpHandler(controlHandlers, {
+        mountPath: CONTROL_PATH,
         anonymous: true,
         rejectFederated: true,
         // The control service captures this set BEFORE stripAudience
@@ -425,8 +457,10 @@ export function mountMcpEndpoints(opts) {
     // whose hostname already says "mcp" may serve it at `/` so the
     // bare-root URL is the universal endpoint — no path repeat.
     // Exposes audience tags ['agent', 'runtime'] — runtime tools stay
-    // routable on the same endpoint but invisible to the agent's
-    // `tools/list` via the `_meta.ui.visibility: ['app']` filter.
+    // routable on the same endpoint and ARE listed on its `tools/list`;
+    // their `_meta.ui.visibility: ['app']` marker asks a conforming HOST to
+    // withhold them from the model (SPEC §4.7 host obligation, ggui#1414) —
+    // the server validates the marker's shape and enforces nothing.
     app.post(universalMcpPath, agentMcpHandler);
     // Per-app endpoint — only mounted when the deployment opts in
     // via `perAppRouting`. The same handler reads `req.params[paramName]`
@@ -496,7 +530,7 @@ export function mountMcpEndpoints(opts) {
         // builder-kind identity with `source: 'anonymous'`. Default
         // (undefined / false) preserves the auth-required posture of
         // every canonical route.
-        const svcMcpHandler = makeMcpHandler(svc.handlers, svc.anonymous ? { anonymous: true } : undefined);
+        const svcMcpHandler = makeMcpHandler(svc.handlers, svc.anonymous ? { anonymous: true, mountPath: svc.path } : { mountPath: svc.path });
         app.post(svc.path, svcMcpHandler);
         app.get(svc.path, methodNotAllowed);
         app.delete(svc.path, methodNotAllowed);

package/dist/runtime-bundle-hash.d.ts

@@ -19,6 +19,13 @@
  * cache-busting across deploys; this is not an integrity check (SRI
  * would be a separate, full-length hash).
  */
+/**
+ * The runtime bundle's PLAIN filename (`iframe-runtime.js`): the name every
+ * server mounts `no-cache`, and the name the content hash is inserted into.
+ * The shells' one-shot fallback (ggui#1501) retries this name when a hashed
+ * URL fails.
+ */
+export declare const RUNTIME_BUNDLE_PLAIN_NAME: string;
 /** Truncated content hash used in the bundle's immutable URL name. */
 export declare function computeRuntimeBundleHash(bytes: Buffer): string;
 /**

package/dist/runtime-bundle-hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-bundle-hash.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,sEAAsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAA4B,GACvC,MAAM,CAYR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,GAAE,MAA4B,GACvC,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"runtime-bundle-hash.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAA4B,GACvC,MAAM,CASR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,GAAE,MAA4B,GACvC,MAAM,GAAG,SAAS,CAMpB"}

package/dist/runtime-bundle-hash.js

@@ -22,6 +22,13 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import { RUNTIME_BUNDLE_FILE, RUNTIME_BUNDLE_URL_PATH } from "@ggui-ai/iframe-runtime/server";
+/**
+ * The runtime bundle's PLAIN filename (`iframe-runtime.js`): the name every
+ * server mounts `no-cache`, and the name the content hash is inserted into.
+ * The shells' one-shot fallback (ggui#1501) retries this name when a hashed
+ * URL fails.
+ */
+export const RUNTIME_BUNDLE_PLAIN_NAME = RUNTIME_BUNDLE_URL_PATH.slice(RUNTIME_BUNDLE_URL_PATH.lastIndexOf("/") + 1);
 /** Truncated content hash used in the bundle's immutable URL name. */
 export function computeRuntimeBundleHash(bytes) {
     return createHash("sha256").update(bytes).digest("hex").slice(0, 12);
@@ -61,8 +68,7 @@ export function resolveHashedRuntimeBundleUrl(plainUrl, bundleFile = RUNTIME_BUN
         // Bundle not built / not shipped — mint the plain revalidated name.
         return plainUrl;
     }
-    const plainName = RUNTIME_BUNDLE_URL_PATH.slice(RUNTIME_BUNDLE_URL_PATH.lastIndexOf("/") + 1);
-    return insertRuntimeBundleHash(plainUrl, computeRuntimeBundleHash(bytes), plainName);
+    return insertRuntimeBundleHash(plainUrl, computeRuntimeBundleHash(bytes), RUNTIME_BUNDLE_PLAIN_NAME);
 }
 /**
  * The 12-hex runtime-bundle content hash for the bundle at

package/dist/runtime-bundle-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-bundle-route.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAwEhE"}
+{"version":3,"file":"runtime-bundle-route.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAuFhE"}

package/dist/runtime-bundle-route.js

@@ -55,6 +55,21 @@ export function mountRuntimeBundleRoute(opts) {
     }
     if (existsSync(runtimeBundleFile)) {
         app.get(runtimePath, (_req, res) => {
+            // ggui#1501: with the hashed twin mounted, every STAMPED runtime URL
+            // is hashed, so a load of the plain name is a shell's one-shot
+            // fallback (a hash no serving replica has: rolling deploy, rollback,
+            // replay), or a probe; a probe reads the same, and that is the
+            // count's stated gap. Counted on the response's finish, whatever its
+            // status: the name is `no-cache`, so a CDN revalidates it with a
+            // conditional GET on viewer loads, which keeps the count per load
+            // (a CDN's minimum TTL can coalesce a burst within it), and a 304 is
+            // a fallback as much as a 200 is. No user-agent field: behind a CDN
+            // the origin sees the CDN's own.
+            if (opts.hashed !== undefined) {
+                res.on("finish", () => {
+                    logger.info("runtime_bundle_plain_served", { status: res.statusCode });
+                });
+            }
             res.setHeader("Content-Type", "application/javascript; charset=utf-8");
             // Short cache — operators iterating on the renderer want fresh
             // copies after rebuild. Production long-term caching lives on