llm_meta_widget 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f32625e105ab751f473e79517d113c8b84465e676cddaab0f3db861c8f3e563e
-  data.tar.gz: 249d09f198b93e1b8382b2f5ef719736b260fc4c0c2f53d77e68c203b8e236b2
+  metadata.gz: 6d7a58b9b553be09b66ca6e9aa01f8264a280bb725f80820ec3de506573701ae
+  data.tar.gz: 7b171f0c86c5f45a6250975ab02da586d620602d8fc1bea95261dd963d17e67a
 SHA512:
-  metadata.gz: 841f81296bed31dbe0ebd7c67253b08990be954a0e5b6939f0563c3d97cb525b8826654149350dbae4afd74ce5b61750058f289c9df25ed4fca5b577783db72b
-  data.tar.gz: ced44aaf75dc424014f878360a4f769247cda1856abb7ffde7e3d66e829e8ae953e1c5b0ba21aea6521abab19b10ac821631e490d9ca47cba7876ea41b5ef8d1
+  metadata.gz: e90d55856a37217816264730d1a65fd32af2ad4783ad0c1a09ed298fb5dfe35a618a1ca149bf77265aab346dba4437b960a98399e91b3b15695aa601ed9d2025
+  data.tar.gz: 042b6872987730e708758fee7c6043ac27b0a83b27935e33f0751a910307cd901e746f28a2557dc54dfc32f63d5a4039f43cefcbc1952d93613cc59568e4c44a

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

@@ -780,38 +780,50 @@ function parseSseFrame(raw) {
 // ---- static-primitives extension ---------------------------------------
 //
 // Prototype of `io.modelcontextprotocol/static-primitives` (the SEP-2127
-// follow-on): two optional fields a server may declare on a resources/list
-// entry. `sizeBytes` is the byte length of the payload resources/read would
-// return, so a client can decide whether to attach it BEFORE fetching it.
-// `attachmentHint` says how often attaching is worth it.
+// follow-on). Three optional fields a server may declare on a resources/list
+// entry:
 //
-// Both are optional, and a server that declares neither must behave exactly
-// as it did before the extension existed: fetch, trim to budget, attach once.
+//   sizeBytes  - byte length of the payload resources/read would return, so a
+//                client can decide whether to attach it BEFORE fetching it.
+//   volatility - "stable" (content fixed) or "volatile" (varies between
+//                turns, so a client re-reads it each turn).
+//   autoAttach - may a client attach this without the user asking for it?
+//
+// volatility and autoAttach are separate on purpose. Whether content changes
+// says nothing about whether it may be attached unasked, and the client needs
+// autoAttach as a boolean anyway, because its own byte budget can withhold a
+// resource the server was happy to hand over.
+//
+// All three are optional, and a server declaring none must behave exactly as
+// it did before the extension existed: fetch once, trim to budget, attach on
+// the first turn only.
 export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives"
 
-const ATTACHMENT_HINTS = [ "once", "each-turn", "on-demand" ]
+const VOLATILITIES = [ "stable", "volatile" ]
 
 export function resourceHints(entry) {
   const meta = (entry && entry._meta && entry._meta[STATIC_PRIMITIVES_META]) || {}
-  const hint = meta.attachmentHint
   return {
     // A non-numeric or absent size means "unknown", never 0 — 0 would read
     // as a free resource and sail through every budget check.
     sizeBytes: typeof meta.sizeBytes === "number" && isFinite(meta.sizeBytes) ? meta.sizeBytes : null,
-    attachmentHint: ATTACHMENT_HINTS.indexOf(hint) === -1 ? "once" : hint
+    volatility: VOLATILITIES.indexOf(meta.volatility) === -1 ? "stable" : meta.volatility,
+    autoAttach: typeof meta.autoAttach === "boolean" ? meta.autoAttach : true
   }
 }
 
 // The pre-flight decision, made from the resources/list entry alone.
 // `fetch: false` means the bytes never cross the wire at all.
 export function planResourceAttachment(entry, budgetBytes) {
-  const { sizeBytes, attachmentHint } = resourceHints(entry)
-  const base = { sizeBytes, attachmentHint, uri: entry && entry.uri }
+  const { sizeBytes, volatility, autoAttach } = resourceHints(entry)
+  const base = { sizeBytes, volatility, uri: entry && entry.uri }
 
-  if (attachmentHint === "on-demand") {
-    return { ...base, fetch: false, autoAttach: false, reason: "on-demand" }
+  if (!autoAttach) {
+    return { ...base, fetch: false, autoAttach: false, reason: "not-auto-attach" }
   }
   if (sizeBytes !== null && sizeBytes > budgetBytes) {
+    // The client's budget overrides the server's willingness — which is why
+    // autoAttach has to be a boolean here rather than a restatement of a hint.
     return { ...base, fetch: false, autoAttach: false, reason: "over-budget" }
   }
   return {
@@ -824,21 +836,19 @@ export function planResourceAttachment(entry, budgetBytes) {
   }
 }
 
-// Per-turn gate. Replaces a single `sent` boolean, which silently assumed
-// every resource was "once" and would have re-sent nothing for a resource
-// whose content actually varies between turns.
+// 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 {
-    // Returns whether to attach on THIS turn, and records the answer.
     take() {
       if (!plan || !plan.autoAttach) return false
-      if (plan.attachmentHint === "each-turn") return true
+      if (plan.volatility === "volatile") return true
       if (attachedOnce) return false
       attachedOnce = true
       return true
     },
-    get attachmentHint() { return plan ? plan.attachmentHint : null }
+    get volatility() { return plan ? plan.volatility : null }
   }
 }
 
@@ -858,38 +868,69 @@ export function trimResourceText(text, maxBytes) {
   return text.slice(0, maxBytes) + "\n…truncated"
 }
 
-// The whole discovery sequence for one endpoint's reference resource, kept
-// here rather than in the panel so the decision AND the call site are
-// testable together: a gate that nothing consults is the failure mode this
-// replaces. `list` and `read` are injected so a test can assert that an
-// over-budget resource is never read.
+// Read one resource and shape it for the system prompt. The trim is applied
+// on every read, not just the first: a declared size can go stale, and a
+// volatile resource is a fresh gamble each turn.
+async function readResourceContext({ endpoint, uri, name, read, budgetBytes }) {
+  try {
+    const result = await read({ endpoint, uri })
+    const entry = ((result && result.contents) || [])[0]
+    if (!entry || !entry.text) return null
+    return { uri, name: name || uri, text: trimResourceText(entry.text, budgetBytes) }
+  } catch (e) {
+    // Optional context — a failed read must never block the widget.
+    return null
+  }
+}
+
+// The discovery sequence for one endpoint's reference resource, kept here
+// rather than in the panel so the decision AND the call site are testable
+// together: a gate nothing consults is exactly the bug this shape prevents.
+//
+// A volatile resource is NOT read here. Its content is only meaningful for
+// the turn it is attached to, so reading it at boot would buy a copy that is
+// already suspect by the time anyone sends a message.
 export async function loadHostResource({ endpoint, budgetBytes, list, read, onSkip }) {
   const resources = await list({ endpoint })
   const candidate = (resources || []).filter((r) => (r.mimeType || "") === "application/json")[0]
   if (!candidate) return null
 
   const plan = planResourceAttachment(candidate, budgetBytes)
+  plan.name = candidate.name || candidate.uri
+  // Carried so a volatile re-read knows where to go: discovery happens once
+  // at boot, but the fetch it authorises happens on every later turn.
+  plan.endpoint = endpoint
   if (!plan.fetch) {
     if (onSkip) onSkip(plan)
     return { plan, context: null }
   }
+  if (plan.volatility === "volatile") return { plan, context: null }
 
-  try {
-    const result = await read({ endpoint, uri: candidate.uri })
-    const entry = ((result && result.contents) || [])[0]
-    if (!entry || !entry.text) return { plan, context: null }
-    return {
-      plan,
-      context: {
-        uri: candidate.uri,
-        name: candidate.name || candidate.uri,
-        text: trimResourceText(entry.text, budgetBytes)
-      }
-    }
-  } catch (e) {
-    // Optional context — a failed read must never block the widget.
-    return { plan, context: null }
+  const context = await readResourceContext({
+    endpoint, uri: candidate.uri, name: plan.name, read, budgetBytes
+  })
+  return { plan, context }
+}
+
+export function resourceContextLines(context) {
+  if (!context) return []
+  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 }
+
+  if (plan && plan.volatility === "volatile") {
+    const fresh = await readResourceContext({
+      endpoint, uri: plan.uri, name: plan.name, read, budgetBytes
+    })
+    return fresh ? { lines: resourceContextLines(fresh), cached: fresh } : { lines: [], cached }
   }
+
+  return { lines: resourceContextLines(cached), cached }
 }
 
 // ---- prompt templates ---------------------------------------------------
@@ -937,9 +978,3 @@ export function promptButtonProps(prompt) {
   }
 }
 
-// The per-turn attach decision AND its formatting, so the two cannot drift
-// apart: asking whether to attach is what consumes the turn.
-export function nextResourceContextLines(context, attacher) {
-  if (!context || !attacher || !attacher.take()) return []
-  return [ "", "Reference data — " + context.name + " (" + context.uri + "):", context.text ]
-}

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

@@ -398,8 +398,8 @@
 <script type="module">
 	import { runChatLoop, fetchMcpManifest, listMcpPrompts, getMcpPrompt,
 	         listMcpResources, readMcpResource, promptMessagesToText,
-	         loadHostResource, createResourceAttacher, resolvePromptArguments,
-	         promptButtonProps, nextResourceContextLines } from "<%= orchestrator_path %>";
+	         loadHostResource, createResourceAttacher, resourceLinesForTurn, resolvePromptArguments,
+	         promptButtonProps } from "<%= orchestrator_path %>";
 	import { marked } from "/llm_meta_widget_assets/marked.esm.js";
 
 	// Standard prose settings — GFM (tables, autolinks, strikethrough),
@@ -789,7 +789,7 @@
 			var prompts = await listMcpPrompts({ endpoint: endpoint });
 			hostWidePrompts = hostWidePrompts.concat(prompts);
 
-			if (resourceContext === null) {
+			if (resourcePlan === null) {
 				// Listing, size gate and read all live in the orchestrator, where
 				// they are tested together — a gate nothing consults is exactly
 				// the bug this shape prevents.
@@ -804,7 +804,10 @@
 						             " (" + plan.reason + ", sizeBytes=" + plan.sizeBytes + ")");
 					}
 				});
-				if (loaded && loaded.context) {
+				// A volatile resource comes back with no context — it is read
+				// 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);
@@ -960,7 +963,7 @@
 		return out;
 	}
 
-	function currentSystemPrompt() {
+	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.",
 			"",
@@ -972,16 +975,27 @@
 			"",
 			"Current page state:",
 			JSON.stringify(currentPageState(), null, 2)
-		].concat(resourceContextLines()).join("\n");
+		].concat(resourceLines || []).join("\n");
 	}
 
-	// How often the resource is attached is the SERVER's call, via the
-	// extension's attachmentHint: 'once' for static reference data (the
-	// default, and what a hint-unaware server gets), 'each-turn' for content
-	// that varies. The attacher records each turn's answer, replacing a
-	// client-side boolean that assumed every resource was static.
-	function resourceContextLines() {
-		return nextResourceContextLines(resourceContext, resourceAttacher);
+	// 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.
+	async function resourceLinesForThisTurn() {
+		var turn = await resourceLinesForTurn({
+			plan:        resourcePlan,
+			attacher:    resourceAttacher,
+			cached:      resourceContext,
+			endpoint:    resourcePlan && resourcePlan.endpoint,
+			read:        readMcpResource,
+			budgetBytes: RESOURCE_BUDGET_BYTES
+		});
+		resourceContext = turn.cached;
+		return turn.lines;
 	}
 
 	// Per-turn AbortController — lets the Clear button (or a new submit)
@@ -1028,7 +1042,8 @@
 			// it as sent.
 			await wellKnownReady;
 
-			var messages = [{ role: "system", content: currentSystemPrompt() }]
+			var resourceLines = await resourceLinesForThisTurn();
+			var messages = [{ role: "system", content: currentSystemPrompt(resourceLines) }]
 				.concat(conversation)
 				.concat([{ role: "user", content: userText }]);
 

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

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