llm_meta_widget 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d7a58b9b553be09b66ca6e9aa01f8264a280bb725f80820ec3de506573701ae
-  data.tar.gz: 7b171f0c86c5f45a6250975ab02da586d620602d8fc1bea95261dd963d17e67a
+  metadata.gz: 17cad71af08d5e4c49a3e7418055bd9c034880d9ab6cae2cbb3fb6cf3a0f0804
+  data.tar.gz: 24e7aa0c38400bccee9ddc832a6da10cf2788f42e343b67901d0cfc9a7748e24
 SHA512:
-  metadata.gz: e90d55856a37217816264730d1a65fd32af2ad4783ad0c1a09ed298fb5dfe35a618a1ca149bf77265aab346dba4437b960a98399e91b3b15695aa601ed9d2025
-  data.tar.gz: 042b6872987730e708758fee7c6043ac27b0a83b27935e33f0751a910307cd901e746f28a2557dc54dfc32f63d5a4039f43cefcbc1952d93613cc59568e4c44a
+  metadata.gz: 2e55a245ad87d21f2d235fe9c211751520172df72f7197ad70b558a546c0b80e62ce63e9f00718ac0f91145d2a14bf920db808f70a550c7822d603c20a565833
+  data.tar.gz: bdad3eda95fd643db1dc11fc10c4e2c48d0d3442d3e2a1a79012f1e8bb2af769dc98217d897b6fd7b173a17f06e7ba55ab3209d50a3cd7186349dbce5920030b

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

@@ -1,6 +1,9 @@
 # `rake build` / `rake release`, used by .github/workflows/gem_release.yml.
 # The widget has no Ruby test suite of its own: its logic is the browser
-# orchestrator, tested with `node --test` (see `rake test_js`).
+# orchestrator, tested with `node --test` (see `rake test_js`) and linted
+# with eslint (`rake lint_js`). The lint covers the panel's script too, by
+# extracting it from the ERB — three bugs reached a browser through that gap
+# before it existed: an undefined variable, a stale import, a redeclared one.
 require "bundler/gem_tasks"
 
 desc "Run the orchestrator's JavaScript tests"
@@ -8,4 +11,10 @@ task :test_js do
   sh "node --test app/assets/javascripts/llm_meta_widget/orchestrator.test.mjs"
 end
 
-task default: :test_js
+desc "Lint the widget's JavaScript, including the panel script inside the ERB"
+task :lint_js do
+  sh "npm install --silent" unless Dir.exist?("node_modules")
+  sh "npm run lint"
+end
+
+task default: [ :lint_js, :test_js ]

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

@@ -446,8 +446,22 @@ export async function runChatLoop(opts) {
     const localOut = await dispatchLocalToolCalls(localCalls, aiActions)
     allDispatched.push(...localOut.dispatched)
 
-    // Class 2: host-wide — direct MCP JSON-RPC POST to the host's own endpoint
+    // A page action's outcome goes back to the model like any other tool
+    // result. It used to be dropped, on the grounds that a write to the page
+    // has nothing to report — but a turn whose only calls were page actions
+    // then ended the loop, so any task that writes to the page and THEN needs
+    // a tool ("select these dictionaries, now annotate") was cut off after
+    // 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) {
+      roundTripResults.push({
+        tc: toolCall,
+        result: error ? { error: String(error.message || error) } : { ok: true, applied: toolCall.name }
+      })
+    }
+
+    // Class 2: host-wide — direct MCP JSON-RPC POST to the host's own endpoint
     for (const tc of hostWideCalls) {
       const tool = hostWideByName[tc.name]
       const args = coerceArguments(tc.arguments)
@@ -490,9 +504,10 @@ export async function runChatLoop(opts) {
       toolCalls: turnResult.toolCalls
     })
 
-    // Terminate when there's nothing to feed back. Locals (Class 3) are
-    // fire-and-forget; unknowns can't be handled; only Class 2 + Class 1
-    // execution produces tool results the LLM should see.
+    // Terminate when there's nothing to feed back: a turn with no tool calls
+    // at all, or one whose only calls were unknown. Anything that executed —
+    // page action, host tool or proxied tool — produces a result the model
+    // sees, and gets another round to act on.
     if (roundTripResults.length === 0) {
       return {
         content: turnResult.content,
@@ -836,22 +851,6 @@ export function planResourceAttachment(entry, budgetBytes) {
   }
 }
 
-// Per-turn gate. A stable resource is attached once and re-used; a volatile
-// one is owed a fresh copy every turn.
-export function createResourceAttacher(plan) {
-  let attachedOnce = false
-  return {
-    take() {
-      if (!plan || !plan.autoAttach) return false
-      if (plan.volatility === "volatile") return true
-      if (attachedOnce) return false
-      attachedOnce = true
-      return true
-    },
-    get volatility() { return plan ? plan.volatility : null }
-  }
-}
-
 // Safety net for a server that declares no size: shrink an oversized
 // catalog to its names rather than dropping it, and hard-truncate anything
 // that is not a recognised catalog shape.
@@ -917,13 +916,21 @@ export function resourceContextLines(context) {
   return [ "", "Reference data — " + context.name + " (" + context.uri + "):", context.text ]
 }
 
-// What to attach on THIS turn. Asking consumes the turn, so the decision and
-// the fetch live together: a stable resource re-uses the copy read at boot,
-// a volatile one is read again right now.
-export async function resourceLinesForTurn({ plan, attacher, cached, endpoint, read, budgetBytes }) {
-  if (!attacher || !attacher.take()) return { lines: [], cached }
+// What to attach on THIS turn.
+//
+// `volatility` governs RE-FETCHING, not re-inclusion: a stable resource is
+// read once and then re-used, but it stays in every turn's system prompt for
+// as long as the conversation lasts. Showing it only on the first turn put
+// the reference data in the one turn that could not use it — the model then
+// spent several tool calls rediscovering what it had already been given,
+// which costs more tokens than simply keeping it.
+//
+// Whether a resource is affordable at all is decided once, from sizeBytes,
+// before it is ever fetched.
+export async function resourceLinesForTurn({ plan, cached, endpoint, read, budgetBytes }) {
+  if (!plan || !plan.autoAttach) return { lines: [], cached }
 
-  if (plan && plan.volatility === "volatile") {
+  if (plan.volatility === "volatile") {
     const fresh = await readResourceContext({
       endpoint, uri: plan.uri, name: plan.name, read, budgetBytes
     })
@@ -971,6 +978,16 @@ export function resolvePromptArguments(prompt, state) {
   return { args, missing }
 }
 
+// What a template will take from the page, and what it will have to ask for.
+// Shown to a first-time visitor so the offer is concrete rather than a bare
+// verb: they can see that the text box is empty before they click.
+export function promptArgumentSummary(prompt, state) {
+  return ((prompt && prompt.arguments) || []).map((arg) => {
+    const value = promptArgFromState(arg.name, state)
+    return { name: arg.name, value, filled: value.length > 0, required: !!arg.required }
+  })
+}
+
 export function promptButtonProps(prompt) {
   return {
     label: prompt.title || prompt.name,

data/app/assets/stylesheets/llm_meta_widget/conversation.css

@@ -181,3 +181,51 @@
 	max-height: 10em;
 	overflow-y: auto;
 }
+
+/* ---- "working" signals, ported from llm_meta_chat's chats.css ------------
+ *
+ * The wait is often long on local models — a tool round re-processes the
+ * whole prompt plus the tool results before the first token — so a still
+ * label reads as a hang. Same class names as the chat app, so the two
+ * surfaces behave identically. */
+.message-role .role-spinner {
+  display: inline-block;
+  animation: role-working-spin 1.8s linear infinite;
+  transform-origin: 50% 50%;
+}
+
+@keyframes role-working-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+/* Staggered three-dot indicator on the reasoning summary while thinking is
+ * still streaming. Hidden unless .thinking-active is present. */
+.thinking-dots {
+  display: none;
+  margin-left: 0.35em;
+  letter-spacing: 0.15em;
+  font-weight: bold;
+}
+
+.message-thinking.thinking-active .thinking-dots { display: inline-block; }
+
+.message-thinking.thinking-active .thinking-dots span {
+  display: inline-block;
+  opacity: 0.25;
+  animation: thinking-dot 1.4s ease-in-out infinite;
+}
+
+.message-thinking.thinking-active .thinking-dots span:nth-child(2) { animation-delay: 0.2s; }
+.message-thinking.thinking-active .thinking-dots span:nth-child(3) { animation-delay: 0.4s; }
+
+@keyframes thinking-dot {
+  0%, 60%, 100% { opacity: 0.25; }
+  30%           { opacity: 1; }
+}
+
+/* Respect a reader's motion preference: keep the label, drop the movement. */
+@media (prefers-reduced-motion: reduce) {
+  .message-role .role-spinner,
+  .message-thinking.thinking-active .thinking-dots span { animation: none; }
+}

data/app/helpers/llm_meta_widget/widget_helper.rb

@@ -35,7 +35,11 @@ module LlmMetaWidget
       # anon" (all Ollama models / all public_to_anonymous MCP servers).
       # Pass arrays to curate.
       models:                  nil,   # e.g. ["qwen3-6-35b-fast", "qwen3-6-35b-no-think"]
-      hub_tools:               nil    # e.g. ["togomcp", "pubdictionaries"] — MCP server names
+      hub_tools:               nil,   # e.g. ["togomcp", "pubdictionaries"] — MCP server names
+      # First thing a visitor sees when the panel opens, above the offered
+      # prompt templates. nil → a generic line. A blank panel tells a
+      # first-time visitor nothing about what the assistant can do for them.
+      greeting:                nil
     }.freeze
 
     def llm_meta_widget(base_url:, model:, **overrides)

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

@@ -268,6 +268,59 @@
 		border-radius: 8px;
 		padding: 8px;
 	}
+	#llm-meta-widget-chat .message-content details > summary {
+		cursor: pointer;
+		font-weight: 600;
+	}
+	#llm-meta-widget-chat .lmw-sent-text {
+		margin-top: 6px;
+		font-size: 12px;
+		opacity: 0.8;
+		white-space: pre-wrap;
+	}
+
+	/* Opening state: greeting + the offers themselves. Shown until the first
+	 * real turn, and again after Clear. */
+	#llm-meta-widget-chat .lmw-welcome { padding: 4px 2px 2px; }
+	#llm-meta-widget-chat .lmw-welcome-hello {
+		margin: 0 0 12px;
+		font-size: 14px;
+		line-height: 1.5;
+		color: #374151;
+	}
+	#llm-meta-widget-chat .lmw-welcome-card {
+		background-color: #f9fafb;
+		border: 1px solid #e5e7eb;
+		border-radius: 8px;
+		padding: 10px 12px;
+		margin-bottom: 8px;
+	}
+	#llm-meta-widget-chat .lmw-welcome-start {
+		background-color: #eff6ff;
+		color: #1d4ed8;
+		border: 1px solid #bfdbfe;
+		border-radius: 999px;
+		padding: 4px 12px;
+		font-size: 13px;
+		font-family: inherit;
+		cursor: pointer;
+	}
+	#llm-meta-widget-chat .lmw-welcome-start:hover { background-color: #dbeafe; }
+	#llm-meta-widget-chat .lmw-welcome-why {
+		margin: 8px 0 0;
+		font-size: 13px;
+		line-height: 1.45;
+		color: #4b5563;
+	}
+	#llm-meta-widget-chat .lmw-welcome-slots {
+		margin: 8px 0 0;
+		padding-left: 16px;
+		font-size: 12px;
+		color: #6b7280;
+	}
+	#llm-meta-widget-chat .lmw-welcome-slots li { margin-bottom: 2px; }
+	#llm-meta-widget-chat .lmw-welcome-slots li.filled { color: #047857; }
+
 	/* Server-offered prompt templates. The row is display:none in markup and
 	 * gets its display back only when a prompt actually exists, so the inline
 	 * style and this rule have to agree on "flex". */
@@ -398,8 +451,8 @@
 <script type="module">
 	import { runChatLoop, fetchMcpManifest, listMcpPrompts, getMcpPrompt,
 	         listMcpResources, readMcpResource, promptMessagesToText,
-	         loadHostResource, createResourceAttacher, resourceLinesForTurn, resolvePromptArguments,
-	         promptButtonProps } from "<%= orchestrator_path %>";
+	         loadHostResource, resourceLinesForTurn, resolvePromptArguments,
+	         promptButtonProps, promptArgumentSummary } from "<%= orchestrator_path %>";
 	import { marked } from "/llm_meta_widget_assets/marked.esm.js";
 
 	// Standard prose settings — GFM (tables, autolinks, strikethrough),
@@ -411,6 +464,7 @@
 	var API_KEY_UUID           = <%= api_key_uuid.to_json.html_safe %>;
 	var MODEL                  = <%= model.to_json.html_safe %>;
 	var ACTIONS_SCHEMA_ID      = <%= actions_schema_id.to_json.html_safe %>;
+	var GREETING               = <%= greeting.to_json.html_safe %>;
 	var STATE_GLOBAL           = <%= state_global.to_json.html_safe %>;
 	var ACTIONS_GLOBAL         = <%= actions_global.to_json.html_safe %>;
 	var REMOTE_TOOLS_SCHEMA_ID = <%= remote_tools_schema_id.to_json.html_safe %>;
@@ -755,7 +809,6 @@
 	var hostWideTools = [];
 	var hostWidePrompts = [];
 	var resourceContext = null;   // payload of the host's reference resource
-	var resourceAttacher = null;  // per-turn gate, built from the server's hint
 	var resourcePlan = null;      // the pre-flight decision, kept so Clear can re-arm the gate
 
 	// Beyond ~2k tokens a reference resource starts crowding out the
@@ -763,9 +816,6 @@
 	// is 218 dictionaries / ~35KB / ~10k tokens.
 	var RESOURCE_BUDGET_BYTES = 8000;
 
-	// Set when a server declared a resource we deliberately did not attach,
-	// so the reason is inspectable rather than a silent absence.
-	var resourceSkip = null;
 
 	var wellKnownReady = (async function() {
 		var urls = WELL_KNOWN_URLS === null
@@ -799,7 +849,6 @@
 					list:        listMcpResources,
 					read:        readMcpResource,
 					onSkip: function(plan) {
-						resourceSkip = plan;
 						console.info("[llm_meta_widget] not attaching " + plan.uri +
 						             " (" + plan.reason + ", sizeBytes=" + plan.sizeBytes + ")");
 					}
@@ -808,13 +857,13 @@
 				// per turn instead — so the plan, not the payload, is what says
 				// whether this endpoint offered anything worth attaching.
 				if (loaded && loaded.plan && loaded.plan.fetch) {
-					resourceContext  = loaded.context;
-					resourcePlan     = loaded.plan;
-					resourceAttacher = createResourceAttacher(loaded.plan);
+					resourceContext = loaded.context;
+					resourcePlan    = loaded.plan;
 				}
 			}
 		}
 		renderPromptButtons();
+		renderWelcome();
 	})();
 
 	// ---- server-offered prompt templates --------------------------------
@@ -844,6 +893,66 @@
 		promptsEl.style.display = "";
 	}
 
+	// A blank panel tells a first-time visitor nothing. Open with a greeting
+	// and the offers themselves — each template showing what it will take from
+	// the page and what it will ask for — so the assistant is the page's way
+	// in rather than a box you must already know how to talk to.
+	function renderWelcome() {
+		if (!historyEl || historyEl.querySelector(".message")) return;
+		historyEl.textContent = "";
+
+		var box = document.createElement("div");
+		box.className = "lmw-welcome";
+
+		var hello = document.createElement("p");
+		hello.className = "lmw-welcome-hello";
+		hello.textContent = GREETING ||
+			"Hi — 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] || {};
+		hostWidePrompts.forEach(function(prompt) {
+			var props = promptButtonProps(prompt);
+			var card  = document.createElement("div");
+			card.className = "lmw-welcome-card";
+
+			var start = document.createElement("button");
+			start.type = "button";
+			start.className = "lmw-welcome-start";
+			start.textContent = props.label;
+			start.addEventListener("click", function() { runPromptTemplate(prompt, start); });
+			card.appendChild(start);
+
+			if (prompt.description) {
+				var why = document.createElement("p");
+				why.className = "lmw-welcome-why";
+				why.textContent = prompt.description;
+				card.appendChild(why);
+			}
+
+			// Name the placeholders, filled or not, so the offer is concrete:
+			// a newcomer can see the text box is empty before clicking.
+			var summary = promptArgumentSummary(prompt, state);
+			if (summary.length) {
+				var slots = document.createElement("ul");
+				slots.className = "lmw-welcome-slots";
+				summary.forEach(function(slot) {
+					var li = document.createElement("li");
+					li.className = slot.filled ? "filled" : "empty";
+					li.textContent = slot.filled
+						? slot.name + ": " + (slot.value.length > 60 ? slot.value.slice(0, 60) + "…" : slot.value)
+						: slot.name + ": not set yet — I'll ask, or work it out";
+					slots.appendChild(li);
+				});
+				card.appendChild(slots);
+			}
+			box.appendChild(card);
+		});
+
+		historyEl.appendChild(box);
+	}
+
 	async function runPromptTemplate(prompt, button) {
 		var resolved = resolvePromptArguments(prompt, window[STATE_GLOBAL] || {});
 		var args = resolved.args;
@@ -863,6 +972,7 @@
 			var text = promptMessagesToText(result);
 			if (!text) { appendTurn("error", "The server returned an empty prompt."); return; }
 			inputEl.value = text;
+			pendingTurnLabel = promptButtonProps(prompt).label;
 			if (typeof formEl.requestSubmit === "function") formEl.requestSubmit();
 			else formEl.dispatchEvent(new Event("submit", { cancelable: true }));
 		} catch (e) {
@@ -872,13 +982,22 @@
 		}
 	}
 
-	function appendTurn(role, text) {
+	// Set just before a template submits, so its turn is labelled by what the
+	// user actually did — "Annotate text" — instead of showing a paragraph of
+	// server-written instructions as though they had typed it. The instructions
+	// stay one click away rather than hidden: what was sent is what is shown.
+	var pendingTurnLabel = null;
+
+	function appendTurn(role, text, turnLabel) {
 		// Class names mirror llm_meta_chat's chats/_message.html.erb —
 		// `.message.<role>`, `.message-role`, `.message-content` — so the
 		// shared conversation.css styles apply directly (see the <link>
 		// above). The .lmw-* prefix is reserved for widget-CHROME classes
 		// (header, clear button, scroll region, input area) that aren't
 		// part of the shared conversation surface.
+		var welcome = historyEl.querySelector(".lmw-welcome");
+		if (welcome) welcome.remove();
+
 		var div = document.createElement("div");
 		div.className = "message " + role;
 		var label = document.createElement("div");
@@ -891,12 +1010,25 @@
 		// content is rendered as markdown but only after the assistant's
 		// text is streamed in via renderMarkdownInto — this appendTurn
 		// creates the empty container.
-		body.textContent = text;
+		if (turnLabel) {
+			var details = document.createElement("details");
+			var summary = document.createElement("summary");
+			summary.textContent = turnLabel;
+			var full = document.createElement("div");
+			full.className = "lmw-sent-text";
+			full.textContent = text;
+			details.appendChild(summary);
+			details.appendChild(full);
+			body.appendChild(details);
+		} else {
+			body.textContent = text;
+		}
 		div.appendChild(label);
 		div.appendChild(document.createTextNode(" "));
 		div.appendChild(body);
 		historyEl.appendChild(div);
 		historyEl.scrollTop = historyEl.scrollHeight;
+		body.roleLabel = label;   // so a turn in flight can show it is working
 		return body;
 	}
 
@@ -921,8 +1053,29 @@
 		return role;
 	}
 
+	// While a turn is in flight the assistant's label becomes a turning gear.
+	// Same markup and class names as llm_meta_chat's message_stream_controller,
+	// so the shared conversation.css drives both. Without it there is no sign
+	// whether the assistant is still working or has quietly stopped — and on a
+	// local model a tool round can take a long time before the first token.
+	function markWorking(label) {
+		if (!label || label.classList.contains("is-working")) return;
+		label.innerHTML = '<span class="role-spinner" aria-hidden="true">\u2699\uFE0F</span> Working…';
+		label.classList.add("is-working");
+	}
+
+	function markDone(label) {
+		if (!label || !label.classList.contains("is-working")) return;
+		label.classList.remove("is-working");
+		label.textContent = roleLabel("assistant");
+	}
+
 	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;
@@ -931,13 +1084,26 @@
 		var details = document.createElement("details");
 		details.className = "message-thinking";
 		details.open = true;
+		details.classList.add("thinking-active");
 		var summary = document.createElement("summary");
 		summary.textContent = "🤔 thinking…";
+		var dots = document.createElement("span");
+		dots.className = "thinking-dots";
+		for (var i = 0; i < 3; i++) {
+			var dot = document.createElement("span");
+			dot.textContent = ".";
+			dots.appendChild(dot);
+		}
+		summary.appendChild(dots);
 		var body = document.createElement("div");
 		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;
@@ -946,6 +1112,7 @@
 
 	function collapseThinkingBlock() {
 		if (currentThinkingBlock) {
+			currentThinkingBlock.classList.remove("thinking-active");
 			currentThinkingBlock.open = false;
 			var summary = currentThinkingBlock.querySelector("summary");
 			if (summary) summary.textContent = "🤔 thinking (finished)";
@@ -970,25 +1137,21 @@
 			"RULES for tool use:",
 			"1. If the user's question can be answered from the Current page state below, answer directly with a plain-text response — do NOT invoke a tool.",
 			"2. If the user requests a state change, or needs information not in the page state, invoke the matching tool via a function call. Do not describe your intent in text without actually invoking (a textual promise like \"I will add X\" is a failure).",
-			"3. After a tool returns a result, YOUR NEXT MESSAGE MUST BE A PLAIN-TEXT ANSWER using that result. DO NOT emit another tool call.",
-			"4. NEVER call the SAME tool twice in a row with the same or similar arguments — its earlier result is already in the conversation history.",
+			"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");
 	}
 
-	// Whether to attach, and how often, is the SERVER's call — via the
-	// extension's autoAttach and volatility fields, which default to
-	// attach-once for a server that declares neither.
-	//
-	// Asking consumes the turn, and a volatile resource is re-read here rather
-	// than re-using the boot-time copy — so this runs once per send, before
-	// the system prompt is built.
+	// Runs once per send, before the system prompt is built: a volatile
+	// resource is re-read here, a stable one re-uses the copy taken at boot.
+	// Either way it is attached to every turn — the server's hint governs
+	// re-FETCHING; how often to include it is this client's call.
 	async function resourceLinesForThisTurn() {
 		var turn = await resourceLinesForTurn({
 			plan:        resourcePlan,
-			attacher:    resourceAttacher,
 			cached:      resourceContext,
 			endpoint:    resourcePlan && resourcePlan.endpoint,
 			read:        readMcpResource,
@@ -1006,9 +1169,7 @@
 		if (currentAbort) { try { currentAbort.abort(); } catch (e) { /* noop */ } }
 		conversation = [];
 		historyEl.innerHTML = "";
-		// Clear starts a new conversation, so a 'once' resource is owed to it
-		// again — the old boolean stayed latched and silently withheld it.
-		if (resourcePlan) resourceAttacher = createResourceAttacher(resourcePlan);
+		renderWelcome();
 	});
 
 	// Enter submits, Shift+Enter inserts a newline — matches llm_meta_chat's
@@ -1022,17 +1183,20 @@
 		}
 	});
 
-	formEl.addEventListener("submit", async function(e) {
-		e.preventDefault();
+	formEl.addEventListener("submit", async function(event) {
+		event.preventDefault();
 		var userText = inputEl.value.trim();
 		if (!userText) return;
 		inputEl.value = "";
-		appendTurn("user", userText);
+		appendTurn("user", userText, pendingTurnLabel);
+		pendingTurnLabel = null;
 
 		if (currentAbort) { try { currentAbort.abort(); } catch (e) { /* noop */ } }
 		currentAbort = new AbortController();
 
 		var assistantBody = appendTurn("assistant", "");
+		activeAssistantBody = assistantBody;
+		markWorking(assistantBody.roleLabel);
 		var assistantMarkdown = "";  // accumulate raw markdown, re-render on each delta
 
 		try {
@@ -1058,7 +1222,16 @@
 				aiActions:     window[ACTIONS_GLOBAL] || {},
 				maxRounds:     MAX_ROUNDS,
 				signal:        currentAbort.signal,
+				onPhase: function(name) {
+					// 'thinking' covers the long silence before the first
+					// token; 'responding' means text is on its way.
+					if (name === "responding") markDone(assistantBody.roleLabel);
+					else markWorking(assistantBody.roleLabel);
+				},
 				onRoundStart: function(roundIdx) {
+					// A new round means more work: tool results are going back
+					// to the model, which is the longest wait of all.
+					markWorking(assistantBody.roleLabel);
 					// Loop mechanics are debugging info, not user-facing signal.
 					// Reuse the same assistant bubble across rounds — text just
 					// keeps streaming into it (accumulating markdown). Weaker
@@ -1075,6 +1248,7 @@
 					historyEl.scrollTop = historyEl.scrollHeight;
 				},
 				onTextDelta: function(delta) {
+					markDone(assistantBody.roleLabel);
 					collapseThinkingBlock();
 					assistantMarkdown += delta;
 					renderMarkdownInto(assistantBody, assistantMarkdown);
@@ -1125,6 +1299,13 @@
 				appendTurn("error", err.message);
 			}
 		} finally {
+			// Whatever happened — answered, aborted, threw, or returned
+			// nothing at all — the turn is over and the label must stop
+			// claiming otherwise. A spinner left running is a worse lie than
+			// 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.3.0"
+  VERSION = "0.4.1"
 end

metadata

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