llm_meta_widget 0.7.5 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d2cc5c7bfb6fa54893df26cef21788e90384052cda6a60acc05aca7fdc90f61
-  data.tar.gz: 43aa3c8567f74595ff9b66e6fcbf2e71291da2c3699c4ac84c1b3b07b6c2a6b6
+  metadata.gz: 5bd30ac6cb4c389fbc600db77a91fd6cc9b363290c970043917706f26288041a
+  data.tar.gz: 44696139fdb278e97b039971e27284de9bb4a082a3b2fe12c1341a88b4e94b96
 SHA512:
-  metadata.gz: 43d04fc32c9e167cb7958f80ef2f5d8632621703542f7679e444c1f55b12cf68276945b4adb45a17e6e699a4ec9ee3c9ac017b646e8069ecf1688abd7e5376ef
-  data.tar.gz: b2b04bf2577dfc7ee3de38581734b4385354c81146b9523d2d33d78d6aa126ff0dfadc42018889f2f4fcd2ab859f7148bf5e0694f096377060497b28a91a9dd6
+  metadata.gz: 02277ce080547d0f35deb01b761abfa2a40face578f012c607594c08b80152c700c30b72d13652339b044d10ecf0d2e5eb305026ee816d5928290e39f28147d0
+  data.tar.gz: 4f349cddfa82766fd1a203d9c29ebd8f56b428ff0d241ec7399e19c29cf1d59c5783ca8122e225c33aa9c578abe4fa51db27d4d9dbeb8bb7894fd1a5803bdca5

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

@@ -211,10 +211,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 +233,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 +296,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 +349,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 +474,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

@@ -299,7 +299,11 @@ function boot(cfg) {
   	// baseline (if any), then the level-1 picker adds/removes entries as
   	// the visitor toggles server checkboxes. Passed to runChatLoop on
   	// every submit so the current selection is respected turn-by-turn.
-  	var remoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  	// Keep the baseline separately: refreshRemoteToolsFromPicker() rebuilds
+  	// remoteTools wholesale, so without a pristine copy the pre-configured
+  	// tools vanish the moment the picker first renders.
+  	var baselineRemoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  	var remoteTools = baselineRemoteTools.slice();
 
   	// Level-1 picker caches. hubMcpServers[] is the list of anon-visible
   	// servers fetched from GET /api/mcp_servers; each server has an
@@ -310,6 +314,10 @@ function boot(cfg) {
   	// state (all-on / indeterminate / all-off).
   	var hubMcpServers = [];
   	var selectedToolIds = new Set();
+  	// A pre-configured tool IS a selection: seed the set so the picker renders
+  	// it checked and the visitor can turn it off, rather than the picker
+  	// silently overriding the page.
+  	baselineRemoteTools.forEach(function(t) { selectedToolIds.add(t.id); });
 
   	function anyAllowedByAllowlist(name, allowlist) {
   		return allowlist === null || allowlist.indexOf(name) >= 0;
@@ -319,9 +327,11 @@ function boot(cfg) {
   		// Flatten every SELECTED tool (across all servers) into remoteTools,
   		// adapted to runChatLoop's expected { id, name, description, input_schema }.
   		var flat = [];
+  		var seen = {};
   		hubMcpServers.forEach(function(s) {
   			(s.tools || []).forEach(function(t) {
   				if (!selectedToolIds.has(t.id)) return;
+  				seen[t.id] = true;
   				flat.push({
   					id:           t.id,
   					name:         t.name,
@@ -330,6 +340,12 @@ function boot(cfg) {
   				});
   			});
   		});
+  		// A baseline tool whose server the picker never listed (not anon-visible,
+  		// or the fetch failed) has no checkbox to be found through — keep it
+  		// unless the visitor explicitly turned it off.
+  		baselineRemoteTools.forEach(function(t) {
+  			if (!seen[t.id] && selectedToolIds.has(t.id)) { flat.push(t); seen[t.id] = true; }
+  		});
   		remoteTools = flat;
   		if (toolsCountEl) {
   			toolsCountEl.textContent = flat.length;
@@ -938,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.",
@@ -957,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 {
@@ -3765,17 +3766,23 @@ function boot(cfg) {
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   var localTools = actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);
-  var remoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  var baselineRemoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  var remoteTools = baselineRemoteTools.slice();
   var hubMcpServers = [];
   var selectedToolIds = /* @__PURE__ */ new Set();
+  baselineRemoteTools.forEach(function(t) {
+    selectedToolIds.add(t.id);
+  });
   function anyAllowedByAllowlist(name, allowlist) {
     return allowlist === null || allowlist.indexOf(name) >= 0;
   }
   function refreshRemoteToolsFromPicker() {
     var flat = [];
+    var seen = {};
     hubMcpServers.forEach(function(s) {
       (s.tools || []).forEach(function(t) {
         if (!selectedToolIds.has(t.id)) return;
+        seen[t.id] = true;
         flat.push({
           id: t.id,
           name: t.name,
@@ -3784,6 +3791,12 @@ function boot(cfg) {
         });
       });
     });
+    baselineRemoteTools.forEach(function(t) {
+      if (!seen[t.id] && selectedToolIds.has(t.id)) {
+        flat.push(t);
+        seen[t.id] = true;
+      }
+    });
     remoteTools = flat;
     if (toolsCountEl) {
       toolsCountEl.textContent = flat.length;
@@ -4254,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 [
@@ -4276,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.5"
+  VERSION = "0.8.0"
 end

metadata

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