@aibranch/llm-meta-widget 0.7.6 → 0.8.1

package/README.md

@@ -124,7 +124,7 @@ that is not Rails needs no gem, no template engine and no asset pipeline — two
 lines of HTML:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.7"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.8"></script>
 <llm-meta-widget llm-url="https://your-meta-server.example"
                  model="qwen3-6-35b-fast"
                  greeting="Hi — ask me anything about this page."></llm-meta-widget>
@@ -135,6 +135,16 @@ instead of ERB. Both produce the same widget, so the advice in that section
 — CORS, a reachable `llm_url`, the hub's name for the model — applies here
 too.
 
+**`@0.8` is a range, and it stops at 0.8.x on purpose.** You get patches without
+touching your page, and you do not get a breaking release by surprise. The cost
+is that moving to 0.9 is a deliberate edit: read [CHANGELOG.md](CHANGELOG.md)
+first, because a major-or-minor bump here is where the page's own contract can
+change — 0.8.0 changed the shape of `window.aiState`, and a page that followed
+the new documentation while still loading `@0.7` would have had every state
+value silently replaced by an error string. Rails hosts are protected from that
+mismatch by the Gemfile constraint; a CDN embed has no such guard, so the
+version in that URL is the guard.
+
 Nothing else is needed: the stylesheets and the markdown renderer are bundled
 in, and the element injects its own styles. The host serves no CSS and no JS.
 
@@ -211,10 +221,17 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 
 <!-- (b) State readers folded into the LLM's system prompt EVERY turn, -->
 <!--     so the LLM can answer from page state without a tool_call. -->
+<!--     Each reader declares what it returns, like every other channel. -->
 <script>
   window.aiState = {
-    text:                  function() { return $("#text").val() || ""; },
-    selected_dictionaries: function() { return getSelected(); }
+    text: {
+      description: "the text the user wants to annotate",
+      read: function() { return $("#text").val() || ""; }
+    },
+    selected_dictionaries: {
+      description: "the dictionaries the user has chosen for annotation",
+      read: function() { return getSelected(); }
+    }
   };
 </script>
 
@@ -226,7 +243,17 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 </script>
 ```
 
-**What the LLM sees.** The `ai-actions` JSON is passed to the meta-server as `local_tools` for every turn. Alongside it, every reader in `window.aiState` is invoked (each turn) and the results are JSON-serialized into a `Current page state:` block appended to the system prompt — the LLM can answer from state directly instead of tool-calling for lookups.
+**What the LLM sees.** The `ai-actions` JSON is passed to the meta-server as `local_tools` for every turn. Alongside it, every reader in `window.aiState` is invoked (each turn) and rendered into a `Current page state:` block appended to the system prompt, one line per reader, with its description beside its value:
+
+```
+Current page state:
+- text (the text the user wants to annotate): "The stomach was examined."
+- selected_dictionaries (the dictionaries the user has chosen for annotation): ["uberon"]
+```
+
+So the LLM can answer from state directly instead of tool-calling for lookups, and knows what each value *means* rather than guessing from the key.
+
+**Breaking change in 0.8.0.** A reader must be `{ description, read }`. The bare-function form — `text: function() {…}` — is removed, with no fallback. A key that still uses it is reported to the console by name, with the shape it should have, and skipped; the page's other readers keep working. Descriptions are not decoration: every other channel the widget declares to the model already carries one (Class 3 tool schemas, Class 2 `.well-known` tools, Class 1 hub tools, resources), and state readers were the exception.
 
 **When the tool_call fires.** During the turn, as soon as the LLM emits the
 call. Since 0.4.0 the action's outcome — `{ok: true, applied: "<name>"}`, or
@@ -279,7 +306,7 @@ Declared out-of-band on the meta-server (via the hub's admin UI or `/user/:id/mc
 
 **Declaration.** No widget-side change. Register the server on the hub → flip `public: true` (visible to signed-in users) and optionally `public_to_anonymous: true` (visible to widget visitors without a login). See the meta-server's `Api::McpServersController`.
 
-**What the LLM sees.** Only tools from servers the visitor has **enabled via the tool picker** (see "Level-1 pickers" below). Nothing is auto-selected — the visitor opts in per session.
+**What the LLM sees.** Only tools the visitor has **enabled via the tool picker** (see "Level-1 pickers" below) — nothing is auto-selected, the visitor opts in per session. A page can set the starting selection instead, with `remote_tools_schema_id:`: those tools arrive already ticked, and the visitor can still untick them.
 
 **When the tool_call fires.** Synchronously during the turn — widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/single_llm_calls` endpoint with `tool_ids: [...]`; the hub proxies to each MCP server and streams results back through SSE.
 
@@ -332,9 +359,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 |
-| `state_global:` | `"aiState"` | Global window object holding Class-3 state readers |
+| `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"` | Optional DOM id for pre-configured Class-1 tools (bypasses picker) |
+| `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 |
 | `well_known_urls:` | `nil` | `nil` = auto-discover same-origin; explicit array = fetch those; `[]` = disable |
 | `greeting:` | `nil` | First thing a visitor sees when the panel opens, above the offered prompt templates. `nil` = a generic line |
 | `max_rounds:` | `3` | Cap on tool-call rounds per LLM turn. Page actions cost a round each since 0.4.0 — raise it for multi-step flows |
@@ -457,6 +484,10 @@ it most, since they must already know your form to press it.
   behind the custom-element move: the npm package and its CDN URL, why `main`,
   `exports` and `sideEffects` are set the way they are, and why the gem and the npm
   package must never drift in version.
+- **A page you can run** — `examples/connection-test.html` checks every call the
+  widget makes to a hub, one at a time, then mounts the widget with a tool
+  already selected. Serve it from an origin the hub allows and open it: if
+  something in the chain is wrong, it names which step.
 - **Issues and questions** — <https://github.com/jdkim/llm_meta_widget/issues>
 
 ## License

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

@@ -642,7 +642,8 @@ async function resourceLinesForTurn({ plan, cached, endpoint, read, budgetBytes
 }
 var PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" };
 function promptArgFromState(argName, state) {
-  const reader = state && state[argName] || state && state[PROMPT_ARG_ALIASES[argName]];
+  const entry = state && state[argName] || state && state[PROMPT_ARG_ALIASES[argName]];
+  const reader = entry && typeof entry.read === "function" ? entry.read : null;
   if (typeof reader !== "function") return "";
   let value;
   try {
@@ -4266,17 +4267,51 @@ function boot(cfg) {
     currentThinkingBlock = null;
     currentThinkingBody = null;
   }
+  function stateReaders() {
+    var declared = window[STATE_GLOBAL] || {};
+    var out = [];
+    Object.keys(declared).forEach(function(key) {
+      var entry = declared[key];
+      var hasDescription = entry && typeof entry.description === "string" && entry.description.trim() !== "";
+      var hasRead = entry && typeof entry.read === "function";
+      if (!hasDescription || !hasRead) {
+        console.error(
+          "[llm-meta-widget] " + STATE_GLOBAL + "." + key + ' is not a valid state reader. Expected { description: "what this value is", read: function () { \u2026 } }, got ' + (typeof entry === "function" ? "a bare function (the 0.7 form, removed in 0.8)" : describeValue(entry)) + ". Skipping " + key + "."
+        );
+        return;
+      }
+      out.push({ key, description: entry.description, read: entry.read });
+    });
+    return out;
+  }
+  function describeValue(v) {
+    if (v === null) return "null";
+    if (Array.isArray(v)) return "an array";
+    if (typeof v === "object") {
+      var missing = [];
+      if (typeof v.description !== "string" || v.description.trim() === "") missing.push("description");
+      if (typeof v.read !== "function") missing.push("read");
+      return "an object missing " + missing.join(" and ");
+    }
+    return typeof v;
+  }
   function currentPageState() {
-    var reader = window[STATE_GLOBAL] || {};
-    var out = {};
-    Object.keys(reader).forEach(function(k) {
+    return stateReaders().map(function(r) {
+      var value;
       try {
-        out[k] = reader[k]();
+        value = r.read();
       } catch (e) {
-        out[k] = "<error: " + e.message + ">";
+        value = "<error: " + e.message + ">";
       }
+      return { key: r.key, description: r.description, value };
+    });
+  }
+  function pageStateLines() {
+    var readers = currentPageState();
+    if (readers.length === 0) return ["(this page declares no state)"];
+    return readers.map(function(r) {
+      return "- " + r.key + " (" + r.description + "): " + JSON.stringify(r.value);
     });
-    return out;
   }
   function currentSystemPrompt(resourceLines) {
     return [
@@ -4288,9 +4323,8 @@ function boot(cfg) {
       "3. After a tool returns a result, use it: either take the next step the task needs, or \u2014 if the task is done \u2014 answer in plain text. Do not stop silently after a tool call.",
       "4. NEVER repeat a call you have already made with the same or similar arguments \u2014 its result is already in the conversation history.",
       "",
-      "Current page state:",
-      JSON.stringify(currentPageState(), null, 2)
-    ].concat(resourceLines || []).join("\n");
+      "Current page state:"
+    ].concat(pageStateLines()).concat(resourceLines || []).join("\n");
   }
   async function resourceLinesForThisTurn() {
     var turn = await resourceLinesForTurn({

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

@@ -971,7 +971,12 @@ export async function resourceLinesForTurn({ plan, cached, endpoint, read, budge
 const PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" }
 
 export function promptArgFromState(argName, state) {
-  const reader = (state && state[argName]) || (state && state[PROMPT_ARG_ALIASES[argName]])
+  // 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
+  // simply not a reader — the prompt argument stays empty and the visitor fills
+  // it, which is the documented behaviour for state the page cannot supply.
+  const entry = (state && state[argName]) || (state && state[PROMPT_ARG_ALIASES[argName]])
+  const reader = entry && typeof entry.read === "function" ? entry.read : null
   if (typeof reader !== "function") return ""
   let value
   try {

package/docs/custom-element-distribution.md

@@ -17,7 +17,7 @@ reduced to the element tag. The gem keeps its helper signature, so
 PubDictionaries needs no edit.
 
 Landed since: the npm package and the CDN URL. `@aibranch/llm-meta-widget` is on
-npm, and `https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.7` resolves to
+npm, and `https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.8` resolves to
 the bundle, so the two-line integration in the example below is now literally
 true — no gem, no Rails and no self-hosting required. The gem and the npm package
 ship the identical file, which is checked rather than assumed: both 0.7.2 copies
@@ -95,7 +95,7 @@ to npm and served from a CDN. Integration in any stack, or none:
 
 ```html
 <script type="module"
-        src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.7"></script>
+        src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.8"></script>
 <llm-meta-widget llm-url="https://hub.aibranch.org"
                  tool-hub-url="https://hub.aibranch.org"
                  model="qwen3-8-27b-fast"
@@ -195,7 +195,7 @@ adopter of it.
 The CDN URL has no path:
 
 ```
-https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.7
+https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.8
 ```
 
 `main` and `exports["."]` both point at the bundle, so jsdelivr resolves the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibranch/llm-meta-widget",
-  "version": "0.7.6",
+  "version": "0.8.1",
   "//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": [