llm_meta_widget 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20aa5babd648e80015577ece5c815b37f6fe5e06d6136c91647f49831016833b
-  data.tar.gz: 8dfc055787110255fbf32368bc3f29cf11b3be178477dac9dadf08243a48d096
+  metadata.gz: 2503371d1d6229fbe6e57a807fb8d672190de589ccdb877d2a90a06feae20be0
+  data.tar.gz: bce91755bb903ab02f886be7e9ab90733566699359e468624f3244f1202ad17a
 SHA512:
-  metadata.gz: 2545397e740fefb805c8b8b3f9c90ca78814d71b2138f91a35afd38e1499f9bace74428faaf9160cbda4d9a5b51421a81f16f51df82c7ce88389d07acb97293d
-  data.tar.gz: a05e51a8b8e94a0153d5c7612901cba9ff2f31beb3142e656852cfa43c87b65ecc513d42c2a6a7a9b2a7ef6b0be3f240ec067bd468afd4b320684089cddfff3b
+  metadata.gz: d833790ba0fcdb48cb291a9cde65ab45e2c07284a18a9699c755289a2ded830695e84b3125e552f770c66db8e9930e9c28410baaef2c5e0459d75ef9b93636a4
+  data.tar.gz: 819cd9aa17be97c44b3828980b9faa6a3f79476a2802337b3e59a4149c17a45058a0355a7e5a29f39594ed8c8dfae373cb6040dde762795b6c031b9467d70128

data/README.md

@@ -6,28 +6,71 @@ Client-orchestrated: the widget fetches host-side action schemas + host-publishe
 
 **No** Devise, DB migrations, ChatManager, or PromptNavigator. Adds only `rails >= 8.0` as a runtime dep — so hosts that haven't bumped to 8.1 can adopt it without a Rails upgrade.
 
-## Installation (local, path-based)
+## What you need first
 
-Add to the host app's Gemfile:
+The widget is a browser front end. It does not talk to OpenAI, Anthropic or
+Ollama itself — it talks to **[llm_meta_server](https://github.com/pubannotation)**,
+a hub that holds the provider credentials and streams responses back over SSE.
+So adopting the widget means either running a hub or being given the URL of one.
+
+Nothing else is required: no database, no migrations, no JavaScript build step,
+no Node at runtime. The gem ships plain ES modules that the engine serves.
+
+| Requirement | Version |
+|---|---|
+| Ruby | >= 3.2 |
+| Rails | >= 8.0 (8.1 not required) |
+| A reachable llm_meta_server | any |
+
+## Installation
 
 ```ruby
-gem "llm_meta_widget", path: "../llm_meta/llm_meta_widget"
+# Gemfile
+gem "llm_meta_widget", "~> 0.4"
+```
+
+```
+bundle install
 ```
 
-Then `bundle install`. The engine auto-includes the widget helper into ActionView, so nothing else to wire up.
+That is the whole install. There is **no `mount` to add** — the engine
+deliberately skips `isolate_namespace`, so the helper is included into
+ActionView and the asset routes appear at the host's top level on their own.
+There are no migrations and no generators to run.
 
-## Usage
+## Minimal working example
 
-On any view where you want the widget:
+Put this on any view — a fresh `pages/demo.html.erb` is fine:
 
 ```erb
+<h1>Demo</h1>
+
 <%= llm_meta_widget(base_url: "https://your-meta-server.example",
-                    model:    "qwen3-6-35b-fast") %>
+                    model:    "qwen3-6-35b-fast",
+                    greeting: "Hi — ask me anything about this page.") %>
 ```
 
-That's the minimum. The widget renders a floating chat panel; visitors get a message-list, an input box, and (by default) a model dropdown + tool picker below the input.
+Start the app, open that page, and click the round toggle at the bottom right.
+**Success looks like:** a panel opens showing your greeting, you type "hello",
+the role label turns into a spinning gear reading "Working…", and the reply
+streams in.
+
+If the panel opens but nothing comes back, it is almost always CORS. The hub
+must list your app's origin in its `config/initializers/cors.rb` for the
+`/api/*` resource, because the widget calls the hub **from the visitor's
+browser**, not from your server. Open the browser console: a blocked request
+says so explicitly.
+
+Two more things worth knowing before you go further:
+
+- `base_url` must be reachable from your visitors' browsers, not just from
+  your server. `localhost` works only while you are the visitor.
+- The model name is the hub's name for it (`GET /api/llms` lists them), not
+  the provider's.
 
-To make the LLM able to do more than converse, declare tools using any of the **three tool classes** below.
+Once that works, the widget can converse but cannot *do* anything. To let the
+LLM act on your page or call your own services, declare tools using any of the
+**three tool classes** below.
 
 ## Three tool classes
 
@@ -72,7 +115,17 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 
 **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.
 
-**When the tool_call fires.** Fire-and-forget, dispatched **AFTER** the LLM's response text finishes streaming. The action's return value is NOT fed back to the LLM this turn — the model already produced its user-facing answer and moved on. This is a deliberate design choice (see `project_page_embedded_actions` memory): writes are separated from the conversation loop so the LLM can commit to an action without waiting for a round-trip. Use Class 1/2 instead when you need the LLM to actually see the tool's result.
+**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
+the error message if it raised — is fed back to the LLM as a tool result, and
+the turn continues. Before 0.4.0 these were fire-and-forget, which meant a
+turn whose only calls were page actions ended there: any task shaped *change
+the page, then do something with it* was cut off after the write. The change
+also means the LLM can see that an action failed and correct itself, instead
+of the failure being visible only to the visitor.
+
+Budget for it: every page action now costs a round, so a flow that writes twice
+and then calls a tool needs roughly five or six. See `max_rounds:` below.
 
 **Args**: parsed JS object matching the `input_schema`. Return value ignored. Async allowed (widget doesn't await, but browser will still execute the promise). Exceptions logged and surfaced as an `❌ <name>` chip in the message footer.
 
@@ -115,7 +168,7 @@ Declared out-of-band on the meta-server (via the hub's admin UI or `/user/:id/mc
 
 **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.
 
-**When the tool_call fires.** Synchronously during the turn — widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/chat_streams` endpoint with `tool_ids: [...]`; the hub proxies to each MCP server and streams results back through SSE.
+**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.
 
 **Error path.** Hub-side errors (rate limit, timeout, MCP server unavailable, upstream failure) arrive as SSE `event: error` frames with typed codes (`mcp_unavailable`, `timeout`, `rate_limit`, …); the widget surfaces them in the message bubble with a per-code prefix.
 
@@ -162,12 +215,69 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 | `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) |
 | `well_known_urls:` | `nil` | `nil` = auto-discover same-origin; explicit array = fetch those; `[]` = disable |
-| `max_rounds:` | `3` | Cap on tool-call rounds per LLM turn |
+| `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 |
 | `enable_model_picker:` | `true` | Show model dropdown (Level-1) |
 | `enable_tool_picker:` | `true` | Show tool picker (Level-1) |
 | `models:` | `nil` | Model-name allowlist; `nil` = all anon-available |
 | `hub_tools:` | `nil` | MCP-server-name allowlist; `nil` = all anon-public |
 
+## Declaring resources and prompts (static-primitives extension)
+
+If you operate the MCP endpoint behind your `.well-known/mcp.json`, you can
+also offer **prompts** (one-click starting points, shown as buttons above the
+input) and **resources** (reference data the widget can put in the model's
+context). The widget reads two optional fields the
+`io.modelcontextprotocol/static-primitives` extension defines on a
+`resources/list` entry:
+
+```json
+{
+  "uri": "yourhost://catalog",
+  "name": "Catalog",
+  "mimeType": "application/json",
+  "_meta": {
+    "io.modelcontextprotocol/static-primitives": {
+      "sizeBytes": 1298,
+      "volatility": "stable",
+      "autoAttach": true
+    }
+  }
+}
+```
+
+- **`sizeBytes`** — the byte length of the payload `resources/read` returns.
+  The widget decides whether it can afford the resource *before* fetching it;
+  over its budget (8 KB), the bytes never cross the wire and the LLM is left
+  to ask for what it needs through your tools instead.
+- **`volatility`** — `"stable"` (read once, re-used) or `"volatile"` (re-read
+  on every turn that uses it).
+- **`autoAttach`** — may the widget put this in the model's context without
+  the visitor asking?
+
+All three are optional. A server that declares none behaves exactly as one
+that predates the extension: the resource is fetched, trimmed to budget and
+carried in the model's context.
+
+A prompt is offered as a button labelled by its `title`. Declare its arguments
+as **optional** and fill them from page state where you can: an argument the
+visitor must supply by hand makes the button useless to the visitor who needed
+it most, since they must already know your form to press it.
+
+## Further reading
+
+- **The static-primitives extension** — `io.modelcontextprotocol/static-primitives`,
+  a follow-on to [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol)
+  (Server Cards). The fields above are a reference implementation of its
+  current draft shape.
+- **MCP itself** — <https://modelcontextprotocol.io>
+- **A worked adopter** — PubDictionaries' annotation page
+  (<https://pubdictionaries.org/text_annotation>) runs this widget with all
+  three tool classes plus prompts and resources. Its
+  `app/views/annotation/text_annotation.html.erb` and `app/controllers/mcp_controller.rb`
+  are the fullest example available.
+- **Issues and questions** — <https://github.com/jdkim/llm_meta_widget/issues>
+
 ## License
 
 Apache-2.0.

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

@@ -32,6 +32,7 @@
 //     onTextDelta:     (str)  => {},
 //     onThinkingDelta: (str)  => {},
 //     onToolCall:      (tc)   => {},         // { id, name, arguments }
+//     onToolDispatched: ({toolCall, value, error}) => {},  // after it ran
 //     onPhase:         (name) => {},         // 'thinking' | 'tool_execution' | ...
 //     signal:          abortController.signal
 //   })
@@ -329,6 +330,11 @@ export async function runChatLoop(opts) {
     onTextDelta,
     onThinkingDelta,
     onToolCall,
+    // Fired as each tool finishes, so a caller can show what ran WHILE the
+    // turn is still going. The returned `dispatched` array says the same
+    // thing, but only once the whole loop ends — which on a slow model is
+    // minutes after the work happened, with the user watching unnamed tools.
+    onToolDispatched,
     onPhase,
     ...singleOpts
   } = opts
@@ -454,7 +460,8 @@ export async function runChatLoop(opts) {
     // the write. It also means a failed action is something the model can
     // see and correct, instead of a red mark only the user notices.
     const roundTripResults = []
-    for (const { toolCall, error } of localOut.dispatched) {
+    for (const { toolCall, value, error } of localOut.dispatched) {
+      onToolDispatched?.({ toolCall, value, error })
       roundTripResults.push({
         tc: toolCall,
         result: error ? { error: String(error.message || error) } : { ok: true, applied: toolCall.name }
@@ -468,9 +475,11 @@ export async function runChatLoop(opts) {
       try {
         const value = await callMcpTool({ endpoint: tool.endpoint, name: tc.name, args, signal })
         allDispatched.push({ toolCall: tc, value })
+        onToolDispatched?.({ toolCall: tc, value })
         roundTripResults.push({ tc, result: value })
       } catch (error) {
         allDispatched.push({ toolCall: tc, error })
+        onToolDispatched?.({ toolCall: tc, error })
         roundTripResults.push({ tc, result: { error: String(error.message || error) } })
       }
     }
@@ -488,9 +497,11 @@ export async function runChatLoop(opts) {
           signal
         })
         allDispatched.push({ toolCall: tc, value })
+        onToolDispatched?.({ toolCall: tc, value })
         roundTripResults.push({ tc, result: value })
       } catch (error) {
         allDispatched.push({ toolCall: tc, error })
+        onToolDispatched?.({ toolCall: tc, error })
         // Feed the error text back to the LLM as the tool result — better
         // than dropping it (the LLM can react, apologize, retry differently).
         roundTripResults.push({ tc, result: { error: String(error.message || error) } })

data/app/views/llm_meta_widget/_chat_panel.html.erb

@@ -1070,8 +1070,54 @@
 		label.textContent = roleLabel("assistant");
 	}
 
+	// Tool chips, written as the tools run rather than assembled at the end.
+	// The end-of-turn footer was invisible for as long as the turn lasted —
+	// minutes on a thinking model — so a visitor watched tools execute with
+	// no idea which ones.
+	var liveChips = null;      // the container inside the current bubble
+	var pendingChips = [];     // chips awaiting their outcome, oldest first
+
+	function chipRow() {
+		if (liveChips && liveChips.parentNode) return liveChips;
+		if (!activeAssistantBody || !activeAssistantBody.parentNode) return null;
+		liveChips = document.createElement("div");
+		liveChips.className = "lmw-tool-chips";
+		// Inside the bubble but OUTSIDE .message-content: every text delta
+		// re-renders that element's markdown from scratch, which silently
+		// erased any chip already written into it.
+		activeAssistantBody.parentNode.appendChild(liveChips);
+		return liveChips;
+	}
+
+	function announceToolCall(toolCall) {
+		var row = chipRow();
+		if (!row) return;
+		var chip = document.createElement("span");
+		chip.className = "lmw-tool-chip running";
+		chip.textContent = "⏳ " + toolCall.name;
+		chip.dataset.tool = toolCall.name;
+		row.appendChild(chip);
+		pendingChips.push(chip);
+		historyEl.scrollTop = historyEl.scrollHeight;
+	}
+
+	function resolveToolCall(outcome) {
+		// Match by name, oldest first: ids are not always echoed back, and a
+		// repeated name resolves in call order.
+		var idx = pendingChips.findIndex(function(c) { return c.dataset.tool === outcome.toolCall.name; });
+		var chip = idx === -1 ? null : pendingChips.splice(idx, 1)[0];
+		if (!chip) return;
+		chip.className = "lmw-tool-chip" + (outcome.error ? " error" : "");
+		chip.textContent = (outcome.error ? "❌ " : "🔧 ") + outcome.toolCall.name;
+		if (outcome.error) chip.title = outcome.error.message || String(outcome.error);
+	}
+
 	var currentThinkingBlock = null;
 	var currentThinkingBody  = null;
+	// The assistant bubble of the turn in flight. Reasoning belongs ABOVE that
+	// bubble's content, the way llm_meta_chat places it — appending it to the
+	// transcript instead left it below the answer it was reasoning towards.
+	var activeAssistantBody  = null;
 
 	function ensureThinkingBlock() {
 		if (currentThinkingBody) return currentThinkingBody;
@@ -1095,7 +1141,11 @@
 		body.className = "message-thinking-content";
 		details.appendChild(summary);
 		details.appendChild(body);
-		historyEl.appendChild(details);
+		if (activeAssistantBody && activeAssistantBody.parentNode) {
+			activeAssistantBody.parentNode.insertBefore(details, activeAssistantBody);
+		} else {
+			historyEl.appendChild(details);
+		}
 		historyEl.scrollTop = historyEl.scrollHeight;
 		currentThinkingBlock = details;
 		currentThinkingBody  = body;
@@ -1187,6 +1237,9 @@
 		currentAbort = new AbortController();
 
 		var assistantBody = appendTurn("assistant", "");
+		activeAssistantBody = assistantBody;
+		liveChips = null;
+		pendingChips = [];
 		markWorking(assistantBody.roleLabel);
 		var assistantMarkdown = "";  // accumulate raw markdown, re-render on each delta
 
@@ -1213,6 +1266,8 @@
 				aiActions:     window[ACTIONS_GLOBAL] || {},
 				maxRounds:     MAX_ROUNDS,
 				signal:        currentAbort.signal,
+				onToolCall: function(toolCall) { announceToolCall(toolCall); },
+				onToolDispatched: function(outcome) { resolveToolCall(outcome); },
 				onPhase: function(name) {
 					// 'thinking' covers the long silence before the first
 					// token; 'responding' means text is on its way.
@@ -1249,23 +1304,15 @@
 			conversation.push({ role: "user",      content: userText });
 			conversation.push({ role: "assistant", content: result.content });
 
-			// Append a compact "tools used" footer INSIDE the assistant
-			// bubble so users have visual confirmation of what the LLM
-			// actually did — especially important when the LLM's own text
-			// is incomplete (e.g. "Let me first search…" with no follow-up
-			// synthesis, common with weaker tool-use models).
-			if (result.dispatched.length > 0) {
-				var chips = document.createElement("div");
-				chips.className = "lmw-tool-chips";
-				result.dispatched.forEach(function(d) {
-					var chip = document.createElement("span");
-					chip.className = "lmw-tool-chip" + (d.error ? " error" : "");
-					chip.textContent = (d.error ? "❌ " : "🔧 ") + d.toolCall.name;
-					if (d.error) chip.title = d.error.message;
-					chips.appendChild(chip);
-				});
-				assistantBody.appendChild(chips);
-			}
+			// Anything still pending never reported an outcome (a class that
+			// does not round-trip, or a dispatch that vanished). Reconcile
+			// from the loop's own record so no chip is left spinning.
+			result.dispatched.forEach(function(d) { resolveToolCall(d); });
+			pendingChips.forEach(function(chip) {
+				chip.className = "lmw-tool-chip";
+				chip.textContent = "🔧 " + chip.dataset.tool;
+			});
+			pendingChips = [];
 
 			// Skipped = LLM tried a tool that doesn't exist. Real signal.
 			if (result.skipped.length > 0) {
@@ -1296,6 +1343,7 @@
 			// no spinner: it says "still working" about a turn that ended.
 			markDone(assistantBody.roleLabel);
 			collapseThinkingBlock();
+			activeAssistantBody = null;
 			currentAbort = null;
 		}
 	});

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

metadata

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