llm_meta_widget 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e67bd92aa30299ffd0f7d6e3a9291dc5c398800cf9276b04768101077e212880
-  data.tar.gz: 487c187c3d20631b38f72cc4b6b9241db285ae5a7e2e5e5ef50f814bcb8cee42
+  metadata.gz: 5b7d8d8ce878a102002639b418702b741535fb67a23002ed74a6bb8382b4791f
+  data.tar.gz: 9f2482cef0da260962f8fa2ff5d78952d6bdf6d6ae9bdbab2b3abe9348d8b2b9
 SHA512:
-  metadata.gz: 39e08820f2551e2eccd15b71b7bba68e2342911cb7ec57de0b1f9ee8d26a720b8e36283f2c033a019fe206de3dc1d10b4337c5fedaee94a39c72ba9482c36bcc
-  data.tar.gz: e373ab9a30c2274817d7fae2da1bdea107d024c92f6204af3ae404debcbc22011b6de131bfaf6d25205d420f8f1b98ce8e9328220dcff81ae8142822dbec2a6e
+  metadata.gz: dc3ad442ac618dd9f8fa74af526a2d6e5a4d042a318af9492da7a5482dcb92f7fdcc1b22e004cdb5c6ce8d1b226ae81d9d425535d714ccac188fed1e6a6522e5
+  data.tar.gz: aa0875cbba4e0af9d92588db27718bf846143b019510418209c5146972a245223e6f92e7e5927cdd9f8a0de2a884b14f76db8fb885b276c4873b1c01b35f5956

data/CHANGELOG.md

@@ -3,6 +3,70 @@
 This file starts at 0.8.0, the first release with a breaking change worth
 calling out. Earlier releases are in the git history (`git log --oneline v0.7.6`).
 
+## 0.15.1
+
+### A repeat visit no longer loses the model's context window or the hub tools
+
+The hub answers `/api/llms` and `/api/mcp_servers` with an ETag and
+`must-revalidate`, so a browser revalidated them on the second page load and
+got `304 Not Modified`. `Response.ok` is false for a 304, and both handlers
+turned that into an empty payload.
+
+Nothing announced it. Without the model's context window the resource budget
+fell to its 8 KB floor, so a page's reference data was reported as skipped even
+when it would have fitted; and tool-result truncation and oldest-result
+eviction both stood down, because each returns its input unchanged when it has
+no window to spend. An empty hub list meanwhile showed as "No hub-registered
+tools available". It all worked on a first load and stopped on every one after,
+which is why a hard reload always looked fine.
+
+Both requests now set `cache: "no-store"`, so no conditional request is sent
+and the answer always carries a body. A response that is not ok is reported in
+the browser console, naming what is lost, rather than being treated as an empty
+result.
+
+The hub stopped sending those ETags as well, so this release is not required to
+fix a page served by an up-to-date hub. It matters for any other server that
+does send them, and for making the next failure audible.
+
+## 0.15.0
+
+### The declared global is resolved when a handler is needed, not at startup
+
+A page card is parsed from the DOM before the page's own scripts have
+necessarily run, and a consumer may be injected before them. Until now the
+widget looked up the global named by the card's `page-global` transport once, at
+startup, and kept the result: a page whose handler script ran later — with
+`defer`, as an ES module, or from a `<script>` near the end of the document —
+got no handlers at all for the rest of its life, with only a console warning to
+explain it.
+
+The lookup now happens each time a handler is wanted, so script order no longer
+matters. A global defined after the card was read is found; a global that
+disappears falls back to the older globals again instead of serving a stale map.
+
+The "declares a global the page never defines" message moved with it. At startup
+it was a false alarm, because the defining script may simply not have run yet;
+it is now said when a handler is actually wanted, and said once rather than on
+every lookup.
+
+This is what SEP-0000 asks of a consumer: handler availability is a runtime
+binding, and the burden sits on the consumer, which is the side that can know
+its own injection timing.
+
+### Two smaller fixes from the same conformance audit
+
+- A transport type declared twice was reported as "two blocks declare different
+  globals" even when a single block declared it twice. The message now covers
+  both cases.
+- A card addressed by `page_card_id:` — the escape hatch for a host that cannot
+  set the media type — was read without the merge step, which is where a
+  duplicated transport is caught. It was therefore the one path where that
+  authoring error went unreported. It now goes through the same check.
+
+Nothing a conformant page declares behaves differently, and no card needs
+changing.
+
 ## 0.14.0
 
 ### Breaking: a transport declared in top-level `remotes` is no longer read

data/README.md

@@ -61,7 +61,7 @@ Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.14.0"
+gem "llm_meta_widget", "~> 0.15.1"
 ```
 
 ```bash
@@ -152,17 +152,17 @@ The widget is a custom element in a single self-contained ES module, so the
 whole integration is two lines of HTML:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.14"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.15"></script>
 <llm-meta-widget llm-url="https://your-meta-server.example"
                  model="gpt-oss-120b"
                  greeting="Hi — ask me anything about this page."></llm-meta-widget>
 ```
 
-**`@0.14` is a version range, and it stops at 0.14.x on purpose.** You receive
+**`@0.15` is a version range, and it stops at 0.15.x on purpose.** You receive
 bug fixes without editing your page, and a release that breaks your page cannot
 arrive on its own.
 
-Moving to 0.15 is therefore a change you make yourself. Read
+Moving to 0.16 is therefore a change you make yourself. Read
 [CHANGELOG.md](CHANGELOG.md) before you do, because this is where what your page
 must provide can change. For example, 0.10.0 changed how the widget finds a page
 card: by media type rather than by element id. A page that declared its card the
@@ -602,6 +602,18 @@ so no other consumer can rely on them. Each kind falls back on its own, so you
 can move tools into the declared global and leave prompts and resources where
 they are.
 
+**Script order does not matter.** The widget looks up your global at the moment
+it needs a handler, not when it reads the card. The script that defines
+`window.mcp` may therefore run before or after the widget loads: a `defer`
+attribute, an ES module, or a `<script>` near the end of the page are all fine.
+If a handler is wanted while the global is still undefined, the widget says so
+in the browser console once, and falls back to the older globals for that call.
+
+Before 0.15.0 the lookup happened once at startup, so a page whose handler
+script ran later got no handlers at all for the rest of its life, with only a
+console warning to say why. If you are pinned below 0.15.0, define your global
+before the widget's own script tag.
+
 **The card is found by its media type.** A client matches
 `script[type="application/mcp-static-primitives+json"]`, so the element needs no
 `id`. This is how a client that was never told about your page can still read

data/app/assets/javascripts/llm_meta_widget/element.js

@@ -387,7 +387,11 @@ function boot(cfg) {
   			}));
   	} else {
   		var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  		pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  		// Through the merge as well, with one card: that is where a transport
+  		// declared twice is caught, and the escape hatch should not be the one
+  		// path where an authoring error goes unreported.
+  		pageCard = mergeStaticPrimitivesCards(
+  			[ readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null) ]);
   	}
   	// Where the page's handlers live. The card may declare a global, which is
 	// the only form an outside consumer can discover; the three legacy globals
@@ -499,8 +503,21 @@ function boot(cfg) {
   				if (flat.length > 1) modelPicker.style.display = "";
   			}));
   		} else if (ENABLE_MODEL_PICKER && modelPicker) {
-  			tasks.push(fetch(LLM_BASE + "/api/llms", { headers: { "Accept": "application/json" } })
-  				.then(function(r) { return r.ok ? r.json() : { llms: [] }; })
+  			// cache: "no-store" so the browser never sends a conditional request. The
+  			// hub answers /api/llms with an ETag and must-revalidate, so a REPEAT visit
+  			// got 304 Not Modified — and Response.ok is false for a 304, which became
+  			// an empty payload here. The model's context window was then unknown, so
+  			// the resource budget fell to its 8 KB floor and BOTH tool-result
+  			// truncation and eviction stood down, each returning unchanged without a
+  			// window. It worked on a first load and quietly stopped on every one after.
+  			tasks.push(fetch(LLM_BASE + "/api/llms", { headers: { "Accept": "application/json" }, cache: "no-store" })
+  				.then(function(r) {
+  					if (r.ok) return r.json();
+  					console.warn("[llm-meta-widget] /api/llms answered " + r.status +
+  					             "; the model context window is unknown, so reference data is" +
+  					             " budgeted at the floor and oversized tool results are not trimmed");
+  					return { llms: [] };
+  				})
   				.then(function(payload) {
   					// /api/llms is heterogeneous per family:
   					//   - OpenAI/Anthropic/Google: `models: [{ name, display_name, ... }]`
@@ -547,8 +564,16 @@ function boot(cfg) {
   		}
 
   		if (ENABLE_TOOL_PICKER && toolsListEl) {
-  			tasks.push(fetch(TOOL_HUB_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" } })
-  				.then(function(r) { return r.ok ? r.json() : { mcp_servers: [] }; })
+  			// Same reason as /api/llms above: a 304 on a repeat visit emptied this, and
+  			// the panel then said "No hub-registered tools available" although the hub
+  			// had them.
+  			tasks.push(fetch(TOOL_HUB_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" }, cache: "no-store" })
+  				.then(function(r) {
+  					if (r.ok) return r.json();
+  					console.warn("[llm-meta-widget] /api/mcp_servers answered " + r.status +
+  					             "; hub-registered tools will be listed as unavailable");
+  					return { mcp_servers: [] };
+  				})
   				.then(function(payload) {
   					hubMcpServers = (payload.mcp_servers || []).filter(function(s) {
   						return anyAllowedByAllowlist(s.name, HUB_TOOLS_ALLOWLIST);

data/app/assets/javascripts/llm_meta_widget/llm-meta-widget.js

@@ -708,24 +708,42 @@ function declaredPageGlobal(card, warn = console.warn) {
 }
 function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
   const name = declaredPageGlobal(card, warn);
-  const declared = name ? scope[name] : null;
-  if (name && !declared) {
-    warn(`[llm-meta-widget] the page card declares global "${name}", but window.${name} is not defined \u2014 is the script that defines it loaded, and did it run?`);
-  }
   const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  const said = /* @__PURE__ */ new Set();
+  const sayOnce = (key, message) => {
+    if (said.has(key)) return;
+    said.add(key);
+    warn(message);
+  };
   const pick = (kind, legacyName) => {
+    const declared = name ? scope[name] : null;
+    if (name && !declared) {
+      sayOnce(
+        "missing",
+        `[llm-meta-widget] the page card declares global "${name}", but window.${name} is not defined \u2014 is the script that defines it loaded, and did it run?`
+      );
+    }
     const fromGlobal = declared ? declared[kind] : void 0;
     if (isMap(fromGlobal)) return fromGlobal;
     if (declared && fromGlobal !== void 0 && !isMap(fromGlobal)) {
-      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`);
+      sayOnce(
+        `shape:${kind}`,
+        `[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`
+      );
     }
     return legacyName && scope[legacyName] || {};
   };
   return {
     global: name,
-    tools: pick("tools", legacy.tools),
-    prompts: pick("prompts", legacy.prompts),
-    resources: pick("resources", legacy.resources)
+    get tools() {
+      return pick("tools", legacy.tools);
+    },
+    get prompts() {
+      return pick("prompts", legacy.prompts);
+    },
+    get resources() {
+      return pick("resources", legacy.resources);
+    }
   };
 }
 function mergeStaticPrimitivesCards(cards, warn = console.warn) {
@@ -736,7 +754,7 @@ function mergeStaticPrimitivesCards(cards, warn = console.warn) {
         if (!entry || typeof entry.type !== "string") continue;
         const clash = merged[kind].find((r) => r.type === entry.type && r.global !== entry.global);
         if (clash) {
-          warn(`[llm-meta-widget] two blocks declare different ${entry.type} globals ("${clash.global}" and "${entry.global}"); using "${clash.global}"`);
+          warn(`[llm-meta-widget] the ${entry.type} transport is declared more than once, with different globals ("${clash.global}" and "${entry.global}"); using "${clash.global}". One block may declare it twice, or two blocks may disagree`);
           continue;
         }
         if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {
@@ -4163,7 +4181,9 @@ function boot(cfg) {
     );
   } else {
     var pageCardEl = document.getElementById(PAGE_CARD_ID);
-    pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+    pageCard = mergeStaticPrimitivesCards(
+      [readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null)]
+    );
   }
   var handlers = pageHandlers({
     card: pageCard,
@@ -4250,8 +4270,10 @@ function boot(cfg) {
         if (flat.length > 1) modelPicker.style.display = "";
       }));
     } else if (ENABLE_MODEL_PICKER && modelPicker) {
-      tasks.push(fetch(LLM_BASE + "/api/llms", { headers: { "Accept": "application/json" } }).then(function(r) {
-        return r.ok ? r.json() : { llms: [] };
+      tasks.push(fetch(LLM_BASE + "/api/llms", { headers: { "Accept": "application/json" }, cache: "no-store" }).then(function(r) {
+        if (r.ok) return r.json();
+        console.warn("[llm-meta-widget] /api/llms answered " + r.status + "; the model context window is unknown, so reference data is budgeted at the floor and oversized tool results are not trimmed");
+        return { llms: [] };
       }).then(function(payload) {
         llmsPayload = payload;
         modelWindow = modelWindowFrom(payload, MODEL);
@@ -4284,8 +4306,10 @@ function boot(cfg) {
       }));
     }
     if (ENABLE_TOOL_PICKER && toolsListEl) {
-      tasks.push(fetch(TOOL_HUB_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" } }).then(function(r) {
-        return r.ok ? r.json() : { mcp_servers: [] };
+      tasks.push(fetch(TOOL_HUB_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" }, cache: "no-store" }).then(function(r) {
+        if (r.ok) return r.json();
+        console.warn("[llm-meta-widget] /api/mcp_servers answered " + r.status + "; hub-registered tools will be listed as unavailable");
+        return { mcp_servers: [] };
       }).then(function(payload) {
         hubMcpServers = (payload.mcp_servers || []).filter(function(s) {
           return anyAllowedByAllowlist(s.name, HUB_TOOLS_ALLOWLIST);

data/app/assets/javascripts/llm_meta_widget/orchestrator.js

@@ -1165,19 +1165,36 @@ export function declaredPageGlobal(card, warn = console.warn) {
 // keeps working instead of losing the primitives it has not moved yet.
 export function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
   const name = declaredPageGlobal(card, warn)
-  const declared = name ? scope[name] : null
-
-  // A card that names a global the page never defines is almost always a load
-  // order problem, or a script that threw before it got there. Falling back in
-  // silence hides that: the page then behaves as if it had declared nothing,
-  // and the first symptom is a prompt or tool that "has no handler".
-  if (name && !declared) {
-    warn(`[llm-meta-widget] the page card declares global "${name}", but window.${name} ` +
-         "is not defined — is the script that defines it loaded, and did it run?")
+  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v)
+
+  // Each said at most once. These now fire on dispatch rather than at mount, so
+  // a page that never defines its global would otherwise repeat them every turn.
+  const said = new Set()
+  const sayOnce = (key, message) => {
+    if (said.has(key)) return
+    said.add(key)
+    warn(message)
   }
 
-  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v)
   const pick = (kind, legacyName) => {
+    // Resolved HERE, when a handler is wanted, not when the card was read. The
+    // card is parsed from the DOM before the page's own scripts have
+    // necessarily run, and a consumer may be injected before them, so a global
+    // that is missing at discovery may well be defined by the time a tool is
+    // called. Caching that first lookup turned a load-order detail into a page
+    // that silently had no handlers for the rest of its life.
+    const declared = name ? scope[name] : null
+
+    // A card that names a global the page never defines is almost always a load
+    // order problem, or a script that threw before it got there. Falling back in
+    // silence hides that: the page then behaves as if it had declared nothing,
+    // and the first symptom is a prompt or tool that "has no handler".
+    if (name && !declared) {
+      sayOnce("missing",
+              `[llm-meta-widget] the page card declares global "${name}", but window.${name} ` +
+              "is not defined — is the script that defines it loaded, and did it run?")
+    }
+
     // `declared ? … : undefined`, not `declared && …`: the second yields null
     // when nothing is declared, and `typeof null === "object"`, so the check
     // below then warned about "window.null.tools" on every page with no card.
@@ -1186,16 +1203,20 @@ export function pageHandlers({ card, scope = {}, legacy = {}, warn = console.war
     // An array is the mistake worth naming: it passes a typeof check, so it
     // would be used as a map and answer every lookup with undefined.
     if (declared && fromGlobal !== undefined && !isMap(fromGlobal)) {
-      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; ` +
-           `it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`)
+      sayOnce(`shape:${kind}`,
+              `[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; ` +
+              `it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`)
     }
     return (legacyName && scope[legacyName]) || {}
   }
+
+  // Getters, so each dispatch re-resolves. The call sites read
+  // `handlers.tools` at the moment they need it, which is what makes this work.
   return {
     global: name,
-    tools: pick("tools", legacy.tools),
-    prompts: pick("prompts", legacy.prompts),
-    resources: pick("resources", legacy.resources)
+    get tools() { return pick("tools", legacy.tools) },
+    get prompts() { return pick("prompts", legacy.prompts) },
+    get resources() { return pick("resources", legacy.resources) }
   }
 }
 
@@ -1224,8 +1245,9 @@ export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
         if (!entry || typeof entry.type !== "string") continue
         const clash = merged[kind].find((r) => r.type === entry.type && r.global !== entry.global)
         if (clash) {
-          warn(`[llm-meta-widget] two blocks declare different ${entry.type} globals ` +
-               `("${clash.global}" and "${entry.global}"); using "${clash.global}"`)
+          warn(`[llm-meta-widget] the ${entry.type} transport is declared more than once, ` +
+               `with different globals ("${clash.global}" and "${entry.global}"); using ` +
+               `"${clash.global}". One block may declare it twice, or two blocks may disagree`)
           continue
         }
         if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.14.0"
+  VERSION = "0.15.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_meta_widget
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - jdkim