@aibranch/llm-meta-widget 0.13.0 → 0.14.0

package/README.md

@@ -61,7 +61,7 @@ Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.13.0"
+gem "llm_meta_widget", "~> 0.14.0"
 ```
 
 ```bash
@@ -152,26 +152,25 @@ 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.13"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.14"></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.13` is a version range, and it stops at 0.13.x on purpose.** You receive
+**`@0.14` is a version range, and it stops at 0.14.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.14 is therefore a change you make yourself. Read
+Moving to 0.15 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
 new way while still loading `@0.9` lost every tool, prompt and resource it had
 declared. Nothing failed, anywhere. The CHANGELOG entry for 0.10.0 describes it.
 
-0.13.0 moves where a page declares its transport. That one is safe to take
-first, because 0.13.x still reads the old spelling and warns; the page can move
-afterwards.
+0.13.0 moved where a page declares its transport, and 0.14.0 stopped reading
+the old spelling. Move your card to `transports` before taking 0.14.x.
 
 A Rails app is protected from that mismatch, because the `Gemfile` will not
 resolve a widget version the page cannot use. A page that loads the widget from
@@ -272,8 +271,8 @@ primitive type:
 <script type="application/mcp-static-primitives+json">
 {
   "name": "org.example/your-page",
-  "remotes": [ { "type": "page-global", "global": "mcp" } ],
   "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ],
     "tools": [
       { "name": "add_dictionaries",
         "description": "Add the named dictionaries to the current selection.",
@@ -305,11 +304,18 @@ primitive type:
 A tool's schema may be spelled `inputSchema`, as MCP spells it, or
 `input_schema`. Both are accepted.
 
-`remotes` is how a consumer other than this widget finds your handlers, so the
-global is declared rather than assumed. Leave it out and the widget reads
+`transports` is how a consumer other than this widget finds your handlers, so
+the global is declared rather than assumed. It is a list, and the consumer uses
+the first entry whose `type` it supports; `page-global` is the only type this
+widget supports today. Leave `transports` out and the widget reads
 `window.aiActions`, `window.aiPrompts` and `window.aiResources` instead — see
 "Say where your handlers live".
 
+Widgets from 0.11.1 to 0.12.2 read this declaration from a `remotes` list at the
+top level of the card, and 0.13.x read either spelling. From 0.14.0 the old one
+is not read at all: a card that still carries it gets no handlers, and the
+widget reports that in the browser console. Write `transports`.
+
 A page may declare `prompts` in the same block. See [The page card](#the-page-card)
 for prompts, for the size and volatility hints on a resource, and for what
 happens when a document holds several blocks.
@@ -515,8 +521,8 @@ name the global that holds its handlers. Both are below.
 <script type="application/mcp-static-primitives+json">
 {
   "name": "org.example/your-page",
-  "remotes": [ { "type": "page-global", "global": "mcp" } ],
   "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ],
     "tools":     [ { "name": "set_text", "description": "…", "inputSchema": { } } ],
     "prompts":   [ { "name": "annotate", "description": "Annotate this page" } ],
     "resources": [ { "uri": "page:text", "name": "Text", "description": "the text to annotate",
@@ -526,8 +532,8 @@ name the global that holds its handlers. Both are below.
 </script>
 ```
 
-`name` identifies the card, as it does for a server. `remotes` says where the
-handlers live — see "Say where your handlers live" below. Only the `_meta`
+`name` identifies the card, as it does for a server. `transports` says where
+the handlers live — see "Say where your handlers live" below. Only the `_meta`
 block is required by this widget; the rest is what makes the card readable by
 anything else.
 
@@ -573,8 +579,8 @@ them:
 ```html
 <script type="application/mcp-static-primitives+json">
 { "name": "org.example/your-page",
-  "remotes": [ { "type": "page-global", "global": "mcp" } ],
-  "_meta": { "io.modelcontextprotocol/static-primitives": { "tools": [ ... ] } } }
+  "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ], "tools": [ ... ] } } }
 </script>
 <script>
   window.mcp = {
@@ -722,6 +728,47 @@ as **optional**, and fill them from page state where you can. An argument the
 visitor must type in makes the button useless to the visitor who needed it most:
 to press it, they would already have to know your form.
 
+## When a turn does not fit the model's context
+
+A model holds a fixed number of tokens. A long conversation, a large reference
+resource and a few big tool results can exceed it, and the provider then refuses
+the whole turn. The widget tries to keep a turn inside the limit instead, and
+tells the reader whenever it has to change something. You do not configure any
+of this, but your page's visitors will see the messages, so it is worth knowing
+what they mean.
+
+The widget learns each model's context window from the server's model list. If
+the server does not report one, none of the behaviour below applies and the turn
+is sent as it is.
+
+**One oversized tool result is shortened.** A single result may use at most 40%
+of the window. A larger one is cut to that size, and the model is told in the
+result itself how much was shown and that it can call the tool again with a
+narrower query. The panel says, for example:
+
+> Shortened an oversized togovar_search_variant result to fit the context:
+> 121,000 tokens, where one result may use at most 51,000. Ask again with a
+> narrower question for the complete result.
+
+**Older tool results are given up when the whole turn is too long.** This is for
+a conversation that has grown over many turns, not for one large result. The
+oldest results go first, one at a time, until the turn fits. The questions, the
+answers and the model's own summaries of what it read are never touched, and a
+dropped result leaves a note in its place so the model knows to ask again.
+
+**A reference resource that does not fit is not attached.** Each turn may carry
+about 6% of the window as reference data — roughly 8 KB for a 32,000-token model
+and 32 KB for a 128,000-token one. A resource larger than that is not fetched at
+all, and the panel says so, naming the resource and both figures. The model is
+not told, because it cannot fetch a resource itself; the reader can act, by
+choosing a model with a larger window or asking you for a smaller resource.
+
+If you publish a large document through MCP, consider offering it in sections
+behind one tool that takes a section name, rather than as a single tool result.
+The list of section names in the tool's own schema costs a few hundred tokens
+and is visible to every client, while a document of tens of kilobytes crowds out
+the conversation it is supposed to support.
+
 ## Further reading
 
 - **The static-primitives extension** — `io.modelcontextprotocol/static-primitives`,

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

@@ -701,12 +701,8 @@ function declaredPageGlobal(card, warn = console.warn) {
     warn("[llm-meta-widget] page card declares transports " + JSON.stringify(declared.map((t) => t && t.type)) + ", none of which this widget supports; not dispatching to the page");
     return null;
   }
-  for (const remote of card && card.remotes || []) {
-    if (!remote || remote.type !== PAGE_GLOBAL_TRANSPORT) continue;
-    if (typeof remote.global === "string" && remote.global.trim() !== "") {
-      warn(`[llm-meta-widget] page card declares its transport in top-level "remotes", which is deprecated; move it to _meta["${STATIC_PRIMITIVES_META}"].transports`);
-      return remote.global.trim();
-    }
+  if ((card && card.remotes || []).some((r) => r && r.type === PAGE_GLOBAL_TRANSPORT)) {
+    warn(`[llm-meta-widget] page card declares its transport in top-level "remotes", which is no longer read. Move it to _meta["${STATIC_PRIMITIVES_META}"].transports`);
   }
   return null;
 }

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

@@ -1130,10 +1130,9 @@ export const PAGE_GLOBAL_TRANSPORT = "page-global"
 // `page-postmessage`, `page-jsonrpc` and `page-worker` are reserved, and a card
 // declaring only those gets no handlers rather than the wrong ones.
 //
-// Top-level `remotes` is the pre-d44bd25a shape that 0.11.1 and 0.12.2 read. It
-// is accepted for one release so a page and a widget can be updated in either
-// order without the page going dark in between, and it warns so the author
-// knows to move.
+// Top-level `remotes` is the pre-d44bd25a shape that 0.11.1 to 0.12.2 read and
+// 0.13.x accepted. It is no longer read, but a card still carrying it is
+// reported, because the alternative is a page that quietly stops working.
 export function declaredPageGlobal(card, warn = console.warn) {
   const declared = (card && card.transports) || []
   for (const transport of declared) {
@@ -1149,14 +1148,14 @@ export function declaredPageGlobal(card, warn = console.warn) {
     return null
   }
 
-  for (const remote of (card && card.remotes) || []) {
-    if (!remote || remote.type !== PAGE_GLOBAL_TRANSPORT) continue
-    if (typeof remote.global === "string" && remote.global.trim() !== "") {
-      warn('[llm-meta-widget] page card declares its transport in top-level ' +
-           '"remotes", which is deprecated; move it to ' +
-           `_meta["${STATIC_PRIMITIVES_META}"].transports`)
-      return remote.global.trim()
-    }
+  // No longer read. Reporting it is still worth a few lines: without this a
+  // card that declares its transport only in the old place gets no handlers,
+  // falls through to the legacy globals, and a page that deliberately defines
+  // none — as PubDictionaries does — simply stops working with nothing said.
+  if (((card && card.remotes) || []).some((r) => r && r.type === PAGE_GLOBAL_TRANSPORT)) {
+    warn('[llm-meta-widget] page card declares its transport in top-level ' +
+         '"remotes", which is no longer read. Move it to ' +
+         `_meta["${STATIC_PRIMITIVES_META}"].transports`)
   }
   return null
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibranch/llm-meta-widget",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "//version": "Must stay in step with lib/llm_meta_widget/version.rb. Two independently versioned copies of the same client is the drift docs/custom-element-distribution.md warns about: bump both, release both.",
   "description": "Embeddable browser chat widget: a custom element that discovers tools at page, origin and hub scope and dispatches each tool call to the right one. Two lines of HTML on any host, Rails or not.",
   "keywords": [