llm_meta_widget 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56c8bf50409745cc9a6cc372bdf40c8e36bd546fce37eee67c6dbce16157bedd
-  data.tar.gz: 2506d6fc96004902b4618ff7a759a1139a13bae69ca4b272e6841326d55397ee
+  metadata.gz: bbae9759cecc8cdd66372f7ea040db98c55f3a19877aed2e44f8cdd21baa5815
+  data.tar.gz: 55d7003f06b621d67a58d2a6fbd0a072371c8e288a4bf1c33de16dd2cc2bd326
 SHA512:
-  metadata.gz: d9bcd580647795a610c6c7612a36e2fe60fbd9962d1842fd03c07702933d9b7cbfa1850f969b25dec0a719387b33f227729da747d7702d45d2be953ba3efaa14
-  data.tar.gz: 31c03d36d61ceece0ae0e4ea4b93fa9a78ed2bea461b6ff155f9e9ac9f8e6d2f589b2f7a8efc348258323574b3e1e6d8cea9cbd07b25ec937936f235d797ffb1
+  metadata.gz: e5240c9d3f3033c983f92d82ea3240b24049935cf7c26179f68f057540ada604292908aff6ca3c33ca4a443b42bfd19c181dadd674ec8655f6fe82646e09c0cc
+  data.tar.gz: d1d1750ce3d6d13a43be940afca2bb41c8978bc34b371b1c686e60b17c012d47c389462348ddf8c1b721e530ead404a7e66dbcffc9c50db781a6b64b48c48385

data/README.md

@@ -216,6 +216,7 @@ easy to get wrong:
 | `llm-provider` | `llm_meta_server` (default) or `ollama` |
 | `api-key-uuid`, `greeting`, `max-rounds` | as the helper options |
 | `actions-schema-id`, `state-global`, `actions-global`, `remote-tools-schema-id` | as the helper options |
+| `page-card-id`, `prompts-global`, `resources-global` | as the helper options |
 | `models`, `hub-tools` | comma-separated. Omitted **or empty** means no allowlist — an allowlist permitting nothing is never what anyone meant |
 | `enable-model-picker`, `enable-tool-picker` | **value attributes, not boolean attributes.** They default to true, so presence cannot mean true. Disable with `enable-tool-picker="false"`; any other value is true |
 | `well-known-urls` | **Three different states**, because an attribute cannot tell "not set" from "set to empty": omitted = auto-discover same-origin `/.well-known/mcp.json`; `""` = discovery off; `"a,b"` = fetch those |
@@ -401,6 +402,9 @@ translate directly.
 | `api_key_uuid:` | `"ollama-local"` | Hub API-key uuid to invoke |
 | `element_path:` | `"/llm_meta_widget_assets/llm-meta-widget.js"` | The bundled element the page loads. Served by the gem's engine; override to load it from elsewhere |
 | `actions_schema_id:` | `"ai-actions"` | DOM id of the Class-3 schema block |
+| `page_card_id:` | `"ai-page"` | DOM id of the page card (see "The page card"). Its tools replace the `actions_schema_id` block |
+| `prompts_global:` | `"aiPrompts"` | Global object holding page prompt handlers, keyed by prompt name |
+| `resources_global:` | `"aiResources"` | Global object holding page resource readers, keyed by resource URI |
 | `state_global:` | `"aiState"` | Global window object holding Class-3 state readers, each `{ description, read }` (see the breaking change in 0.8.0) |
 | `actions_global:` | `"aiActions"` | Global window object holding Class-3 implementations |
 | `remote_tools_schema_id:` | `"remote-mcp-tools"` | DOM id of a JSON block listing Class-1 tools (`{id, name, description, input_schema}`) to start with. They seed the picker rather than bypassing it — shown ticked, and the visitor may untick them. Read once, at boot |
@@ -412,6 +416,74 @@ translate directly.
 | `models:` | `nil` | Model-name allowlist; `nil` = all anon-available |
 | `hub_tools:` | `nil` | MCP-server-name allowlist; `nil` = all anon-public |
 
+## The page card
+
+Since 0.9.0 a page can declare what it offers in one block of JSON, instead of
+using a separate channel for each kind of thing. The block uses the same envelope
+an MCP server puts in its Server Card, so the page and the server describe
+themselves the same way.
+
+```html
+<script type="application/mcp-static-primitives+json">
+{ "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "tools":     [ { "name": "set_text", "description": "…", "inputSchema": { } } ],
+    "prompts":   [ { "name": "annotate", "description": "Annotate this page" } ],
+    "resources": [ { "uri": "page:text", "name": "Text", "description": "the text to annotate",
+                     "volatility": "volatile" } ]
+} } }
+</script>
+```
+
+The card says what exists. Three global objects say what it does, and each one is
+keyed by the identifier that the matching MCP operation takes:
+
+| declared in the card | implemented in | keyed by |
+|---|---|---|
+| `tools` | `window.aiActions` | tool `name`, as `tools/call` takes |
+| `prompts` | `window.aiPrompts` | prompt `name`, as `prompts/get` takes |
+| `resources` | `window.aiResources` | resource `uri`, as `resources/read` takes |
+
+```js
+window.aiActions   = { set_text: (args) => { /* change the page */ } }
+window.aiPrompts   = { annotate: (args) => "Annotate this: " + args.text }
+window.aiResources = { "page:text": () => document.querySelector("#text").value }
+```
+
+A prompt handler may return a plain string or the full `messages` array that
+`prompts/get` returns. A resource reader may return a string or any value that
+can be turned into JSON.
+
+**Resources carry two optional hints.** `volatility` is `"volatile"` when the
+value changes between turns, so the widget reads it again every turn; the default
+is `"stable"`, which is read once and reused. `autoAttach: false` keeps a resource
+out of the turn unless something asks for it. A `size` in bytes lets the widget
+decide whether the value fits its budget before reading it.
+
+**The `page:` scheme is experimental.** It is not a registered URI scheme, and
+nothing outside this widget gives it meaning. It is used because the protocol
+asks for a URI, and because `https://` is reserved for resources a client can
+fetch from the web by itself — which page resources are not. The form is
+`page:<name>` with no path, because a page has only one namespace. Expect this to
+change.
+
+**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
+it, and it follows SEP-0000's "HTML-delivery mode". The `page_card_id:` option
+is kept only for a host that cannot set the type; it is read when no block with
+the media type is present.
+
+**A document may hold several blocks.** A page built from components can let
+each component declare its own primitives, and the arrays join by primitive
+type. Declaring the same tool or prompt `name`, or the same resource `uri`,
+twice is an error: every copy is dropped and a message is written to the
+console. The first one does not win, because which block comes first depends on
+the order the page's parts are rendered in, and that is not something the author
+chose.
+
+**The card is optional.** A page that declares nothing keeps working exactly as
+before, and a page that declares no `tools` still uses its `ai-actions` block.
+
 ## Surviving navigation
 
 A page action that navigates — submitting a form, following a link — no longer

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

@@ -24,7 +24,9 @@ import { runChatLoop, fetchMcpManifest, listMcpPrompts, getMcpPrompt,
          promptButtonProps, promptArgumentSummary, fetchOllamaModels,
          createConversationStore, conversationKeyFor,
          readStaticPrimitivesCard, getPagePrompt,
-         planPageResources, pageResourceLinesForTurn } from "./orchestrator.js";
+         planPageResources, pageResourceLinesForTurn,
+         promptArgState, mergeStaticPrimitivesCards,
+         PAGE_CARD_MEDIA_TYPE } from "./orchestrator.js";
 import { marked } from "./marked.esm.js";
 import { readConfig } from "./config.js";
 import conversationCss from "../../stylesheets/llm_meta_widget/conversation.css";
@@ -305,8 +307,24 @@ function boot(cfg) {
   	// older #ai-actions schema tag rather than merging with it: two sources
   	// for one list means a reader has to work out which the page meant, and a
   	// handler in window.aiActions answers to a name either way.
-  	var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  	var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  	//
+  	// Discovery is by MEDIA TYPE, which is the locator the spec defines: an id
+  	// the page chooses cannot be found by a client that was not told it.
+  	// Several blocks may appear, so a page built from components can let each
+  	// one declare its own primitives. `page-card-id` survives only as an escape
+  	// hatch for a host that cannot set the type, and is read when no typed
+  	// block is present.
+  	var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
+  	var pageCard;
+  	if (typedCards.length) {
+  		pageCard = mergeStaticPrimitivesCards(
+  			Array.prototype.map.call(typedCards, function(el) {
+  				return readStaticPrimitivesCard(el.textContent);
+  			}));
+  	} else {
+  		var pageCardEl = document.getElementById(PAGE_CARD_ID);
+  		pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  	}
   	var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   	var localTools = pageCard.tools.length
   		? pageCard.tools
@@ -685,6 +703,15 @@ function boot(cfg) {
   	// submits — so it travels the exact path a typed message does.
 
 
+  	// Where a prompt's declared arguments are filled from. A card-only page keeps
+  	// its state in aiResources under `page:<name>` URIs, so the names the resolver
+  	// looks up live there, not in aiState.
+  	function argState() {
+  		return promptArgState({ entries: pageCard.resources,
+  		                        resources: window[RESOURCES_GLOBAL] || {},
+  		                        state: window[STATE_GLOBAL] || {} });
+  	}
+
   	function renderPromptButtons() {
   		if (!promptsEl) return;
   		promptsEl.textContent = "";
@@ -749,7 +776,7 @@ function boot(cfg) {
   			(hostWidePrompts.length ? ", or start with one of these:" : ".");
   		box.appendChild(hello);
 
-  		var state = window[STATE_GLOBAL] || {};
+  		var state = argState();
   		hostWidePrompts.forEach(function(prompt) {
   			var props = promptButtonProps(prompt);
   			var card  = document.createElement("div");
@@ -792,7 +819,7 @@ function boot(cfg) {
   	}
 
   	async function runPromptTemplate(prompt, button) {
-  		var resolved = resolvePromptArguments(prompt, window[STATE_GLOBAL] || {});
+  		var resolved = resolvePromptArguments(prompt, argState());
   		var args = resolved.args;
   		var missing = resolved.missing;
 

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

@@ -560,6 +560,25 @@ function parseSseFrame(raw) {
   return { name, data };
 }
 var STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives";
+var PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json";
+function mergeStaticPrimitivesCards(cards, warn = console.warn) {
+  const merged = { tools: [], prompts: [], resources: [] };
+  const keyOf = { tools: "name", prompts: "name", resources: "uri" };
+  for (const kind of ["tools", "prompts", "resources"]) {
+    const key = keyOf[kind];
+    const all = [];
+    for (const card of cards || []) all.push(...card && card[kind] || []);
+    const counts = /* @__PURE__ */ new Map();
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1);
+    for (const [id, n] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; dropping every copy \u2014 remove the duplicate to say which one you mean`);
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1);
+  }
+  return merged;
+}
 function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] };
   if (typeof text !== "string" || text.trim() === "") return empty;
@@ -737,7 +756,20 @@ async function resourceLinesForTurn({ plan, cached, endpoint, read, budgetBytes
   }
   return { lines: resourceContextLines(cached), cached };
 }
+var PAGE_URI_PREFIX = "page:";
 var PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" };
+function promptArgState({ entries = [], resources = {}, state = {} } = {}) {
+  const merged = Object.assign({}, state);
+  for (const entry of entries) {
+    const uri = entry && entry.uri;
+    if (!uri || uri.indexOf(PAGE_URI_PREFIX) !== 0) continue;
+    const name = uri.slice(PAGE_URI_PREFIX.length);
+    const reader = resources[uri];
+    if (!name || merged[name] || typeof reader !== "function") continue;
+    merged[name] = { description: entry.description || "", read: reader };
+  }
+  return merged;
+}
 function promptArgFromState(argName, state) {
   const entry = state && state[argName] || state && state[PROMPT_ARG_ALIASES[argName]];
   const reader = entry && typeof entry.read === "function" ? entry.read : null;
@@ -3887,8 +3919,18 @@ function boot(cfg) {
       model: MODEL
     });
   }
-  var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
+  var pageCard;
+  if (typedCards.length) {
+    pageCard = mergeStaticPrimitivesCards(
+      Array.prototype.map.call(typedCards, function(el) {
+        return readStaticPrimitivesCard(el.textContent);
+      })
+    );
+  } else {
+    var pageCardEl = document.getElementById(PAGE_CARD_ID);
+    pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  }
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   var localTools = pageCard.tools.length ? pageCard.tools : actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);
@@ -4162,6 +4204,13 @@ function boot(cfg) {
     renderPromptButtons();
     renderWelcome();
   })();
+  function argState() {
+    return promptArgState({
+      entries: pageCard.resources,
+      resources: window[RESOURCES_GLOBAL] || {},
+      state: window[STATE_GLOBAL] || {}
+    });
+  }
   function renderPromptButtons() {
     if (!promptsEl) return;
     promptsEl.textContent = "";
@@ -4213,7 +4262,7 @@ function boot(cfg) {
     hello.className = "lmw-welcome-hello";
     hello.textContent = GREETING || "Hi \u2014 I can work this page for you. Tell me what you need in your own words" + (hostWidePrompts.length ? ", or start with one of these:" : ".");
     box.appendChild(hello);
-    var state = window[STATE_GLOBAL] || {};
+    var state = argState();
     hostWidePrompts.forEach(function(prompt) {
       var props = promptButtonProps(prompt);
       var card = document.createElement("div");
@@ -4249,7 +4298,7 @@ function boot(cfg) {
     historyEl.appendChild(box);
   }
   async function runPromptTemplate(prompt, button) {
-    var resolved = resolvePromptArguments(prompt, window[STATE_GLOBAL] || {});
+    var resolved = resolvePromptArguments(prompt, argState());
     var args = resolved.args;
     var missing = resolved.missing;
     if (missing.length) {

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

@@ -879,6 +879,43 @@ export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives
 // typo in it should cost that one entry, not the assistant. Everything
 // unparseable returns empty arrays and says so on the console, which is how
 // aiState already treats a reader missing its description.
+// The media type that locates a card inside an HTML document. It is the
+// locator, so it is NOT configurable: a client that has to be told where to
+// look cannot discover anything. SEP-0000, "HTML-delivery mode".
+export const PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json"
+
+// Several blocks may appear in one document, so that a page assembled from
+// components can let each component declare its own primitives. The arrays
+// concatenate by primitive type.
+//
+// A duplicate identifier across blocks is an ERROR, not a precedence puzzle:
+// the spec says a client should report it and should not silently pick one. So
+// every copy of a duplicated identifier is dropped and the author is told.
+// Picking the first would make which component wins depend on DOM order, which
+// is not something a page author controls when the components are partials.
+export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
+  const merged = { tools: [], prompts: [], resources: [] }
+  const keyOf = { tools: "name", prompts: "name", resources: "uri" }
+
+  for (const kind of [ "tools", "prompts", "resources" ]) {
+    const key = keyOf[kind]
+    const all = []
+    for (const card of cards || []) all.push(...((card && card[kind]) || []))
+
+    const counts = new Map()
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1)
+
+    for (const [ id, n ] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; ` +
+             "dropping every copy — remove the duplicate to say which one you mean")
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1)
+  }
+  return merged
+}
+
 export function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] }
   if (typeof text !== "string" || text.trim() === "") return empty
@@ -1129,8 +1166,35 @@ export async function resourceLinesForTurn({ plan, cached, endpoint, read, budge
 // (window.aiState) by name. `dictionaries` is read from a
 // `selected_dictionaries` reader: the page selects a LIST, and the prompt
 // declares the CSV shape the text_annotation tool already takes.
+// Page resources are addressed `page:<name>`: a custom scheme because the
+// protocol asks for a URI and `https:` is reserved for what a client can fetch
+// itself, and with no path because a page has one namespace.
+const PAGE_URI_PREFIX = "page:"
+
 const PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" }
 
+// Prompt arguments are declared by plain name (`text`); page resources are
+// addressed by URI (`page:text`). So on a page that declares its state as
+// resources and keeps no `aiState`, the resolver below finds nothing under the
+// names it looks up and every argument arrives empty — the visitor is asked to
+// retype what is already on screen. This presents those resources in the shape
+// the resolver consumes, keyed by the name inside the URI.
+//
+// An explicit `aiState` entry wins: a page running both channels has said what
+// it wants under that name.
+export function promptArgState({ entries = [], resources = {}, state = {} } = {}) {
+  const merged = Object.assign({}, state)
+  for (const entry of entries) {
+    const uri = entry && entry.uri
+    if (!uri || uri.indexOf(PAGE_URI_PREFIX) !== 0) continue
+    const name = uri.slice(PAGE_URI_PREFIX.length)
+    const reader = resources[uri]
+    if (!name || merged[name] || typeof reader !== "function") continue
+    merged[name] = { description: entry.description || "", read: reader }
+  }
+  return merged
+}
+
 export function promptArgFromState(argName, state) {
   // Same object shape the system-prompt annex consumes: { description, read }.
   // The bare-function form was removed in 0.8.0, so an entry without `read` is

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

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