llm_meta_widget 0.7.6 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1590b5b56f4d164501425b88c2fddd28a07a19a229e6d3a6737a00a1f78b2a31
-  data.tar.gz: f8ba25f792c18736fd031757b18d8e2be7bdd85155f084e92f2cc683218a69c0
+  metadata.gz: 4f2938c7c0624169deea0320e4e0805c55555febd2eacbfb31be883dcb51b204
+  data.tar.gz: 4fc357cf41c9f420272babb65d9f85bf7eef3d7ea7f992de94f173ce0dba92df
 SHA512:
-  metadata.gz: 7cb9aad1047fca745e0c50c47e00c3c3504aaa34a104d2662ce1b2818abed81cddfdc7437a272b99629f4c61afba8b81a49deec8f97aff1f28a53ab29058410a
-  data.tar.gz: b5c75d48fc1e0583cf2e417e4f57f609742bf7342524f85a344c5ee89cb778db5b38f7703e15ebfc1d5f6a54d7b5bb2aab3c82765bbfadfc780104830712bd25
+  metadata.gz: c297b01c8588c9cdeafd6f58ba7b8f3c8898178c0110ed4d86403ee214e4fdb79023ed1622c037ba13ab4450d46e2bd1803391faf6f89187b208e67633ec73c7
+  data.tar.gz: da4ece5000dde3ce73b709a1648a01844d7c2b60ceef35c723e950ed2395dc85d018f24f2193f2f21a47eea5eeaf49c4b6c0f14c93d4717cfcdabf27896bd45c

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+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.8.0
+
+### Breaking: state readers must declare a description
+
+`window.aiState` entries are now objects, not bare functions:
+
+```js
+window.aiState = {
+  text: {
+    description: "the text the user wants to annotate",
+    read: function() { return $("#text").val() || ""; }
+  }
+};
+```
+
+The bare-function form (`text: function() {…}`) is **removed**, with no fallback.
+A key still using it is reported to the console by name, with the shape it should
+have, and skipped — the page's other readers keep working.
+
+**Why.** Every other channel the widget declares to the model already carries a
+developer-authored description: Class 3 action schemas, Class 2 `.well-known`
+tools, Class 1 hub-registered tools, static-primitives resources. State readers
+were the exception — the model saw a bare key and inferred meaning from its name.
+That holds for `text` and fails for `annotation_mode` or `pending_merges`.
+
+**What to change.** Wrap each reader in `{ description, read }`. The description
+is the place to tell the model what it must know about the value, not merely what
+the value is — an enumeration it must choose from, a unit, a null convention.
+
+The system prompt now renders one line per reader with the description inline:
+
+```
+Current page state:
+- text (the text the user wants to annotate): "The stomach was examined."
+- selected_dictionaries (the dictionaries the user has chosen): ["uberon"]
+```
+
+Prompt-argument pre-filling (`promptArgFromState`) reads the same shape, so a
+page left on the old form also stops pre-filling prompt arguments.

data/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

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

@@ -954,15 +954,69 @@ function boot(cfg) {
   		currentThinkingBody  = null;
   	}
 
-  	function currentPageState() {
-  		var reader = window[STATE_GLOBAL] || {};
-  		var out = {};
-  		Object.keys(reader).forEach(function(k) {
-  			try { out[k] = reader[k](); } catch (e) { out[k] = "<error: " + e.message + ">"; }
+  	// Every declaration channel the widget hands the model carries a
+  	// developer-authored description — Class 3 action schemas, Class 2
+  	// .well-known tools, Class 1 hub tools, static-primitives resources. State
+  	// readers used to be the exception: the model saw a bare key and had to
+  	// infer meaning from its name, which holds for `text` and falls apart for
+  	// `annotation_mode` or `pending_merges`. Each reader now declares what it
+  	// returns, in the same shape as everything else.
+  	//
+  	// The bare-function form is GONE as of 0.8.0 — no fallback branch. A page
+  	// that still uses it is told exactly what to change, per key, and that key
+  	// is skipped; the rest of the page still works.
+  	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 () { … } }, got " +
+  					(typeof entry === "function" ? "a bare function (the 0.7 form, removed in 0.8)" : describeValue(entry)) +
+  					". Skipping " + key + "."
+  				);
+  				return;
+  			}
+  			out.push({ key: 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() {
+  		return stateReaders().map(function(r) {
+  			var value;
+  			try { value = r.read(); } catch (e) { value = "<error: " + e.message + ">"; }
+  			return { key: r.key, description: r.description, value: value };
+  		});
+  	}
+
+  	// One line per reader, with its description inline. A separate glossary
+  	// above the values would make the model match names across two lists; the
+  	// point is that it reads the meaning and the value together.
+  	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);
+  		});
+  	}
+
   	function currentSystemPrompt(resourceLines) {
   		return [
   			"You are integrated into a web page as an AI assistant. You have tools available to change page state or fetch information.",
@@ -973,9 +1027,8 @@ function boot(cfg) {
   			"3. After a tool returns a result, use it: either take the next step the task needs, or — if the task is done — 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 — 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");
   	}
 
   	// Runs once per send, before the system prompt is built: a volatile

data/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({

data/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 {

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.7.6"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_meta_widget
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.8.1
 platform: ruby
 authors:
 - jdkim
@@ -35,6 +35,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile