llm_meta_widget 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98514af704b8e59db0091c55a0d42f60cc3d9da77ed8debbf8aa2b94e514576d
-  data.tar.gz: e0b25d087956a31ad5bc21ce232b25abe1aa0ca78a917abdaf6f0e97c7ba7237
+  metadata.gz: b72c0af2bf75bb5a7d1b83b0048aac15dc0485d86448ca4ea99403737c7a95ec
+  data.tar.gz: 1c5dfb8782859c09727fde1f996a39055c0cbe8e75b6116258b9d547a4a7b7a4
 SHA512:
-  metadata.gz: 15101bd9cbac468ccc0c2f5e7e5206e153a459335954779f80694e7431713aa5835849b4b9278511df408bd237adc37cfc16ef658b7a85b279b23d6871eb46d8
-  data.tar.gz: e81e6404165550d0521eb1fba9aa18d4e10ebc0cac400f50e6ff9453084f84e082baba1f7b386155d0b0d567c2a0e51e6de93d16a6a80fba0260f949ad1460d7
+  metadata.gz: cf20127dce92b482a6c6a88a42e3a31fc2b80e127274c9cbae5e7d6f75d3043c9334e38459a7feddf90f0c985984f1a3cdced6550091953952ab44a9282fcf25
+  data.tar.gz: 5554707eda6744fdf8188c1c7d81765c27c068cb078a672d894825cb70f8f5c2c2e6ed4f3593f5a5432b7255bd7d0f01718c14804b1dcba9af661c0df7667a3c

data/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.13.1
+
+### Documentation: the README caught up with 0.12.x and 0.13.0
+
+Three examples and two explanations still told a page author to declare the
+transport in a top-level `remotes` list. Following the README would have
+produced a card this version warns about and a later version will stop reading.
+They now use `transports` inside the extension data, and say that the list is
+read in order and that the first supported type wins.
+
+The README also said nothing about what the widget does when a turn does not fit
+the model's context, although every part of that behaviour shipped in 0.12.x and
+puts messages in the panel that a page's visitors will read. There is now a
+section describing the three cases — one oversized tool result shortened, older
+results given up, a reference resource refused for its size — with the wording
+the reader actually sees.
+
+No code changed in this release.
+
 ## 0.13.0
 
 ### Changed: a page card declares its transport in `transports`, not `remotes`

data/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.13.1"
 ```
 
 ```bash
@@ -272,8 +272,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 +305,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 up to 0.12.2 read this declaration from a `remotes` list at the top
+level of the card instead. Version 0.13.0 still reads that, and warns, so a page
+and a widget can be updated in either order. Write `transports`; a page may
+declare both while a deployment is still catching up, and `transports` decides.
+
 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 +522,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 +533,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 +580,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 +729,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`,

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.13.0"
+  VERSION = "0.13.1"
 end

metadata

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