@webmcp-auto-ui/agent 2.5.27 → 2.5.28

package/src/recipes/_generated.ts

@@ -1134,7 +1134,7 @@ Do NOT render any widget.
 id: create-interactive-notebook-playbook
 name: Create an interactive notebook playbook
 components_used: [notebook-compact, notebook-workspace, notebook-document, notebook-editorial]
-when: the user wants to experiment with data, prototype a small analysis, share a reusable scenario, let others fork and try a dataset, or prepare a hackathon-ready playground. Keywords include "playground", "playbook", "experiment", "try", "prototype", "hackathon", "share a notebook", "template", "starter".
+when: the user wants to experiment with data, prototype a small analysis, share a reusable scenario, or prepare a hackathon-ready playground. Keywords include "playground", "playbook", "experiment", "try", "prototype", "hackathon", "share a notebook", "template", "starter", "publish".
 servers: [autoui]
 layout:
   type: single
@@ -1148,6 +1148,7 @@ The user asks for a **notebook-like interactive playground** that combines text,
 - "I want to prototype a small analysis"
 - "Set up a hackathon starter"
 - "Make a reusable template for exploring CSVs / this API / these tables"
+- "Publish this analysis as a short memo"
 
 This recipe applies across domains (parliamentary data, biodiversity, news, business datasets, etc.) — it only prescribes the **shape** of the answer, not its content.
 
@@ -1160,8 +1161,8 @@ Choose one of the four \`notebook-*\` widgets based on the user's implicit inten
 | Layout | Use when |
 |---|---|
 | \`notebook-compact\` | Quick data exploration, reactive dataflow with named outputs, minimal chrome. **Default for most "playground" and "hackathon" requests.** |
-| \`notebook-workspace\` | The user expects a multi-cell analyst workspace with sources, cell navigation, and a "publish" step. Use when they mention "dashboard", "app", "workspace". |
-| \`notebook-document\` | The user plans to share and discuss with a team. Use when "collaborate", "review", "comment" appear. |
+| \`notebook-workspace\` | The user expects a multi-cell analyst workspace with sources, cell navigation, \`run all\`, and a \`publish\` step. Use when they mention "dashboard", "app", "workspace", "publish". |
+| \`notebook-document\` | The user plans to share and discuss with a team. Use when "collaborate", "review", "comment", "reply" appear. |
 | \`notebook-editorial\` | The user wants a polished, article-like final deliverable mixing prose and code. Use for "memo", "report", "writeup", "blog-style". |
 
 When in doubt, pick \`notebook-compact\`.
@@ -1172,8 +1173,8 @@ Never create an empty notebook. Always seed with 3–5 cells that give the user
 
 1. **First cell: markdown** — title + one-sentence context of what the notebook is for
 2. **Second cell: markdown or code** — if an MCP data source is connected, a starter query that returns something visible (e.g. \`SELECT * FROM {table} LIMIT 10\`). Otherwise a markdown cell describing the next step
-3. **Third cell: code** — a transformation or a visualization that uses the output of step 2. Use \`varname\` on the SQL cell (\`varname: "rows"\`) and reference it in the JS cell
-4. **Last cell: markdown** — a short "to you to play" note inviting the user to add cells, edit, or fork
+3. **Third cell: code** — a transformation or a visualization that uses the output of step 2. Use \`varname\` on the SQL cell (\`varname: "rows"\`) and reference it in the JS cell — this activates the **reactive dataflow** (the downstream JS cell is flagged stale automatically when its upstream re-runs)
+4. **Last cell: markdown** — a short "to you to play" note inviting the user to add cells or edit
 
 Example seed for a generic data playground:
 
@@ -1198,14 +1199,61 @@ If a specific MCP server is connected, replace the generic \`source\` and \`sele
 
 Always keep queries **short** and **limited** so the first run returns quickly and visually.
 
-### Step 4 — Share and fork
+SQL cells are dispatched automatically to the server's \`*_query_sql\` tool (first match). JS cells run in a Web Worker with upstream named outputs injected as scope.
+
+### Step 4 — Exporting & publishing
+
+All four notebook layouts share the same \`share\` button in the toolbar, offering **four export formats**:
+
+| Format | What it does |
+|---|---|
+| **Hyperskill link** | Copies both the canonical Hyperskill URL and a short domain-scoped URL (\`?n=<token>\`). The short URL opens the read-only public viewer at \`nb.hyperskills.net\`. |
+| **Markdown** | Downloads a \`.md\` file containing the notebook content. |
+| **PNG** | Snapshots the rendered notebook to an image. |
+| **JSON** | Exports the full widget state — re-importable for programmatic reuse. |
+
+**Layout-specific share affordances:**
+- \`notebook-workspace\` has a dedicated \`publish\` button (primary, accent-coloured) that flips \`mode: 'view'\`, tags the notebook \`published\` (from \`draft\`), and copies the Hyperskill link in one gesture. Use this when the user wants a clean hand-off.
+- \`notebook-document\` shows a single \`share\` link (live invite/collaboration is not available in this build; presence avatars only render when the \`presence\` param is explicitly provided).
+
+### Step 5 — Working with connected data servers
+
+When one or more MCP data servers are connected, every notebook layout exposes a **collapsible left pane** (bookmark-bar styling, collapsed by default) that lists:
+- **Recipes** published by each server (\`{server}_list_recipes()\`)
+- **Tools / tables** exposed by each server (\`{server}_list_tools()\`)
+
+Clicking any recipe opens a viewer modal. Each fenced code block inside the recipe has a \`↳ inject\` button that drops the snippet into the notebook as a new cell — the user never has to copy-paste.
+
+Two toolbar buttons flank the left pane on every layout:
+- **\`+ md\`** — 3-tab modal (New / File / URL) to create a markdown cell from scratch, from a local \`.md\` file, or from a URL
+- **\`+ recipe\`** — 3-tab modal (Browser / File / URL) to import a recipe from a connected server, a local \`.recipe.md\` file, or a URL
+
+Pass the server metadata via the \`servers:\` param so these affordances populate correctly:
+
+\`\`\`ts
+widget_display({
+  name: 'notebook-compact',
+  params: {
+    title: '...',
+    cells: [...],
+    servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+  }
+})
+\`\`\`
+
+**Filter rule**: only MCP *data* servers (\`kind: 'data'\`) belong in \`servers:\`. Do NOT include WebMCP UI servers such as \`autoui\` — they expose no queryable data.
+
+### Step 6 — Hand-off guidance
 
 After creating the notebook, mention to the user that they can:
-- Click \`share\` in the toolbar to open the export modal (hyperskill link for in-session sharing, markdown/png/json for external export)
-- Switch to \`view\` mode (read-only, no controls visible) when presenting to someone
-- Access the \`⟲ history\` panel to see the trace of edits, and restore deleted cells
+- **Share in four formats** via the toolbar \`share\` button (Hyperskill / Markdown / PNG / JSON)
+- **Switch to \`view\` mode** (read-only) when presenting
+- Use **\`run all\`** (workspace) or **\`publish\`** (workspace) for one-shot execution and publication
+- **Reply** to margin comments in a document layout (\`+ reply\` under each comment)
+- Access the \`⟲ history\` panel to see the edit trace and restore deleted cells
+- **Import recipes** from connected MCP servers via the left pane or the \`+ recipe\` modal
 
-For hackathon contexts, prefer seeding a **document** layout (comments + avatars) so participants feel they are joining a shared space.
+For hackathon contexts, prefer seeding a \`notebook-document\` layout so participants can leave margin comments and replies on cells (presence stays opt-in — pass a \`presence\` array only if you have real editors to show).
 
 ## Examples
 
@@ -1217,20 +1265,34 @@ widget_display({name: "notebook-compact", params: {
   cells: [
     {type: "md", content: "### CSV playground\\n\\nRun the SQL cell to see the first rows, then iterate."},
     {type: "sql", content: "select * from source limit 20", varname: "rows"},
-    {type: "js", content: "// summarize, chart, or filter rows here"}
+    {type: "js", content: "// summarize, chart, or filter rows here\\nconsole.table(rows)"}
+  ]
+}})
+\`\`\`
+
+### Publishable analyst workspace
+\`\`\`
+// user: "Set up an analysis I can publish to the team as an app"
+widget_display({name: "notebook-workspace", params: {
+  title: "Sales review",
+  cells: [
+    {type: "md", name: "intro", content: "What this analysis covers."},
+    {type: "sql", name: "fetch_sales", content: "select * from sales limit 100"},
+    {type: "js", name: "plot", content: "// chart the rows"}
   ]
 }})
+// Then tell the user: click \`run all\` to execute, then \`publish\` to flip to view mode and copy the Hyperskill link.
 \`\`\`
 
-### Collaborative analysis
+### Collaborative analysis with comments
 \`\`\`
-// user: "Set up a notebook my team can edit together"
+// user: "Set up a notebook my team can edit and comment on"
 widget_display({name: "notebook-document", params: {
   title: "Team analysis",
   cells: [
     {type: "md", content: "Kick-off: describe the question here."},
-    {type: "sql", content: "select * from source limit 10"},
-    {type: "md", content: "Your findings: add thoughts, highlights (<mark>key sentence</mark>), and comments on the code cells above."}
+    {type: "sql", content: "select * from source limit 10", comment: {who: "reviewer", when: "2m", body: "Should we filter to last quarter only?"}},
+    {type: "md", content: "Your findings: add thoughts, <mark>highlights</mark>, and reply to the comment on the query above."}
   ]
 }})
 \`\`\`
@@ -1257,8 +1319,10 @@ widget_display({name: "notebook-editorial", params: {
 - **Empty notebook**: never call \`widget_display\` without at least 3 seed cells. The user expects something they can immediately run.
 - **Wrong layout for the intent**: do not use \`notebook-editorial\` for quick exploration — it signals "finished article" and intimidates. Use \`notebook-compact\` unless the user explicitly asks for a publication feel.
 - **Heavy initial queries**: always \`LIMIT 10\` or \`LIMIT 20\` in seed SQL cells. Users will expand later if needed.
-- **Missing \`varname\` on SQL cells** (in compact layout): the named output is what the compact layout showcases. Without it, the notebook loses half its reactive story.
-- **Inventing UUIDs or fork IDs**: leave \`id\` and \`forkId\` unset — the widget generates sensible defaults. Only pass \`id\` when restoring an existing notebook.
+- **Missing \`varname\` on SQL cells** (in compact layout): the named output is what the compact layout showcases, and it drives the stale-flag dataflow. Without it, the notebook loses half its reactive story.
+- **Inventing UUIDs**: leave \`id\` unset — the widget generates a sensible default. Only pass \`id\` when restoring an existing notebook.
+- **Faking presence**: do not pass a \`presence\` array to \`notebook-document\` unless there are real editors to show. Presence is opt-in by design — empty \`presence\` hides the avatar row entirely.
+- **Including \`autoui\` in \`servers:\`**: only MCP *data* servers (\`kind: 'data'\`) belong there. UI servers like \`autoui\` would pollute the left pane.
 `,
   'parlementaire-profile': `---
 id: display-parliamentary-profile-with-hemicycle-and-votes

package/src/recipes/notebook-playbook.md

@@ -2,7 +2,7 @@
 id: create-interactive-notebook-playbook
 name: Create an interactive notebook playbook
 components_used: [notebook-compact, notebook-workspace, notebook-document, notebook-editorial]
-when: the user wants to experiment with data, prototype a small analysis, share a reusable scenario, let others fork and try a dataset, or prepare a hackathon-ready playground. Keywords include "playground", "playbook", "experiment", "try", "prototype", "hackathon", "share a notebook", "template", "starter".
+when: the user wants to experiment with data, prototype a small analysis, share a reusable scenario, or prepare a hackathon-ready playground. Keywords include "playground", "playbook", "experiment", "try", "prototype", "hackathon", "share a notebook", "template", "starter", "publish".
 servers: [autoui]
 layout:
   type: single
@@ -16,6 +16,7 @@ The user asks for a **notebook-like interactive playground** that combines text,
 - "I want to prototype a small analysis"
 - "Set up a hackathon starter"
 - "Make a reusable template for exploring CSVs / this API / these tables"
+- "Publish this analysis as a short memo"
 
 This recipe applies across domains (parliamentary data, biodiversity, news, business datasets, etc.) — it only prescribes the **shape** of the answer, not its content.
 
@@ -28,8 +29,8 @@ Choose one of the four `notebook-*` widgets based on the user's implicit intent:
 | Layout | Use when |
 |---|---|
 | `notebook-compact` | Quick data exploration, reactive dataflow with named outputs, minimal chrome. **Default for most "playground" and "hackathon" requests.** |
-| `notebook-workspace` | The user expects a multi-cell analyst workspace with sources, cell navigation, and a "publish" step. Use when they mention "dashboard", "app", "workspace". |
-| `notebook-document` | The user plans to share and discuss with a team. Use when "collaborate", "review", "comment" appear. |
+| `notebook-workspace` | The user expects a multi-cell analyst workspace with sources, cell navigation, `run all`, and a `publish` step. Use when they mention "dashboard", "app", "workspace", "publish". |
+| `notebook-document` | The user plans to share and discuss with a team. Use when "collaborate", "review", "comment", "reply" appear. |
 | `notebook-editorial` | The user wants a polished, article-like final deliverable mixing prose and code. Use for "memo", "report", "writeup", "blog-style". |
 
 When in doubt, pick `notebook-compact`.
@@ -40,8 +41,8 @@ Never create an empty notebook. Always seed with 3–5 cells that give the user
 
 1. **First cell: markdown** — title + one-sentence context of what the notebook is for
 2. **Second cell: markdown or code** — if an MCP data source is connected, a starter query that returns something visible (e.g. `SELECT * FROM {table} LIMIT 10`). Otherwise a markdown cell describing the next step
-3. **Third cell: code** — a transformation or a visualization that uses the output of step 2. Use `varname` on the SQL cell (`varname: "rows"`) and reference it in the JS cell
-4. **Last cell: markdown** — a short "to you to play" note inviting the user to add cells, edit, or fork
+3. **Third cell: code** — a transformation or a visualization that uses the output of step 2. Use `varname` on the SQL cell (`varname: "rows"`) and reference it in the JS cell — this activates the **reactive dataflow** (the downstream JS cell is flagged stale automatically when its upstream re-runs)
+4. **Last cell: markdown** — a short "to you to play" note inviting the user to add cells or edit
 
 Example seed for a generic data playground:
 
@@ -66,14 +67,61 @@ If a specific MCP server is connected, replace the generic `source` and `select
 
 Always keep queries **short** and **limited** so the first run returns quickly and visually.
 
-### Step 4 — Share and fork
+SQL cells are dispatched automatically to the server's `*_query_sql` tool (first match). JS cells run in a Web Worker with upstream named outputs injected as scope.
+
+### Step 4 — Exporting & publishing
+
+All four notebook layouts share the same `share` button in the toolbar, offering **four export formats**:
+
+| Format | What it does |
+|---|---|
+| **Hyperskill link** | Copies both the canonical Hyperskill URL and a short domain-scoped URL (`?n=<token>`). The short URL opens the read-only public viewer at `nb.hyperskills.net`. |
+| **Markdown** | Downloads a `.md` file containing the notebook content. |
+| **PNG** | Snapshots the rendered notebook to an image. |
+| **JSON** | Exports the full widget state — re-importable for programmatic reuse. |
+
+**Layout-specific share affordances:**
+- `notebook-workspace` has a dedicated `publish` button (primary, accent-coloured) that flips `mode: 'view'`, tags the notebook `published` (from `draft`), and copies the Hyperskill link in one gesture. Use this when the user wants a clean hand-off.
+- `notebook-document` shows a single `share` link (live invite/collaboration is not available in this build; presence avatars only render when the `presence` param is explicitly provided).
+
+### Step 5 — Working with connected data servers
+
+When one or more MCP data servers are connected, every notebook layout exposes a **collapsible left pane** (bookmark-bar styling, collapsed by default) that lists:
+- **Recipes** published by each server (`{server}_list_recipes()`)
+- **Tools / tables** exposed by each server (`{server}_list_tools()`)
+
+Clicking any recipe opens a viewer modal. Each fenced code block inside the recipe has a `↳ inject` button that drops the snippet into the notebook as a new cell — the user never has to copy-paste.
+
+Two toolbar buttons flank the left pane on every layout:
+- **`+ md`** — 3-tab modal (New / File / URL) to create a markdown cell from scratch, from a local `.md` file, or from a URL
+- **`+ recipe`** — 3-tab modal (Browser / File / URL) to import a recipe from a connected server, a local `.recipe.md` file, or a URL
+
+Pass the server metadata via the `servers:` param so these affordances populate correctly:
+
+```ts
+widget_display({
+  name: 'notebook-compact',
+  params: {
+    title: '...',
+    cells: [...],
+    servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+  }
+})
+```
+
+**Filter rule**: only MCP *data* servers (`kind: 'data'`) belong in `servers:`. Do NOT include WebMCP UI servers such as `autoui` — they expose no queryable data.
+
+### Step 6 — Hand-off guidance
 
 After creating the notebook, mention to the user that they can:
-- Click `share` in the toolbar to open the export modal (hyperskill link for in-session sharing, markdown/png/json for external export)
-- Switch to `view` mode (read-only, no controls visible) when presenting to someone
-- Access the `⟲ history` panel to see the trace of edits, and restore deleted cells
+- **Share in four formats** via the toolbar `share` button (Hyperskill / Markdown / PNG / JSON)
+- **Switch to `view` mode** (read-only) when presenting
+- Use **`run all`** (workspace) or **`publish`** (workspace) for one-shot execution and publication
+- **Reply** to margin comments in a document layout (`+ reply` under each comment)
+- Access the `⟲ history` panel to see the edit trace and restore deleted cells
+- **Import recipes** from connected MCP servers via the left pane or the `+ recipe` modal
 
-For hackathon contexts, prefer seeding a **document** layout (comments + avatars) so participants feel they are joining a shared space.
+For hackathon contexts, prefer seeding a `notebook-document` layout so participants can leave margin comments and replies on cells (presence stays opt-in — pass a `presence` array only if you have real editors to show).
 
 ## Examples
 
@@ -85,20 +133,34 @@ widget_display({name: "notebook-compact", params: {
   cells: [
     {type: "md", content: "### CSV playground\n\nRun the SQL cell to see the first rows, then iterate."},
     {type: "sql", content: "select * from source limit 20", varname: "rows"},
-    {type: "js", content: "// summarize, chart, or filter rows here"}
+    {type: "js", content: "// summarize, chart, or filter rows here\nconsole.table(rows)"}
+  ]
+}})
+```
+
+### Publishable analyst workspace
+```
+// user: "Set up an analysis I can publish to the team as an app"
+widget_display({name: "notebook-workspace", params: {
+  title: "Sales review",
+  cells: [
+    {type: "md", name: "intro", content: "What this analysis covers."},
+    {type: "sql", name: "fetch_sales", content: "select * from sales limit 100"},
+    {type: "js", name: "plot", content: "// chart the rows"}
   ]
 }})
+// Then tell the user: click `run all` to execute, then `publish` to flip to view mode and copy the Hyperskill link.
 ```
 
-### Collaborative analysis
+### Collaborative analysis with comments
 ```
-// user: "Set up a notebook my team can edit together"
+// user: "Set up a notebook my team can edit and comment on"
 widget_display({name: "notebook-document", params: {
   title: "Team analysis",
   cells: [
     {type: "md", content: "Kick-off: describe the question here."},
-    {type: "sql", content: "select * from source limit 10"},
-    {type: "md", content: "Your findings: add thoughts, highlights (<mark>key sentence</mark>), and comments on the code cells above."}
+    {type: "sql", content: "select * from source limit 10", comment: {who: "reviewer", when: "2m", body: "Should we filter to last quarter only?"}},
+    {type: "md", content: "Your findings: add thoughts, <mark>highlights</mark>, and reply to the comment on the query above."}
   ]
 }})
 ```
@@ -125,5 +187,7 @@ widget_display({name: "notebook-editorial", params: {
 - **Empty notebook**: never call `widget_display` without at least 3 seed cells. The user expects something they can immediately run.
 - **Wrong layout for the intent**: do not use `notebook-editorial` for quick exploration — it signals "finished article" and intimidates. Use `notebook-compact` unless the user explicitly asks for a publication feel.
 - **Heavy initial queries**: always `LIMIT 10` or `LIMIT 20` in seed SQL cells. Users will expand later if needed.
-- **Missing `varname` on SQL cells** (in compact layout): the named output is what the compact layout showcases. Without it, the notebook loses half its reactive story.
-- **Inventing UUIDs or fork IDs**: leave `id` and `forkId` unset — the widget generates sensible defaults. Only pass `id` when restoring an existing notebook.
+- **Missing `varname` on SQL cells** (in compact layout): the named output is what the compact layout showcases, and it drives the stale-flag dataflow. Without it, the notebook loses half its reactive story.
+- **Inventing UUIDs**: leave `id` unset — the widget generates a sensible default. Only pass `id` when restoring an existing notebook.
+- **Faking presence**: do not pass a `presence` array to `notebook-document` unless there are real editors to show. Presence is opt-in by design — empty `presence` hides the avatar row entirely.
+- **Including `autoui` in `servers:`**: only MCP *data* servers (`kind: 'data'`) belong there. UI servers like `autoui` would pollute the left pane.

package/src/server/hawkProxy.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared Hawk proxy handler — used by apps' /api/hawk/+server.ts
+ * Hawk = OpenAI-compatible endpoint at https://hawk.hyperskills.net/v1
+ * Bearer token lives server-side in HAWK_API_KEY env var.
+ */
+function sanitizeId(id: string | undefined): string {
+  if (!id) return 'x';
+  const clean = id.replace(/[^a-zA-Z0-9]/g, '');
+  return clean || 'x';
+}
+
+/**
+ * Some llama-cpp chat templates (Qwen, Mistral family) enforce alphanumeric
+ * tool_call IDs via Jinja raise_exception. Gemma's template drops tool_use_id
+ * entirely (cf. gemma4-prompt-builder.ts:194) — safe passthrough.
+ * Mirrors the convention of sanitizeServerName (tool-layers.ts:24).
+ */
+function needsIdSanitize(model: string | null | undefined): boolean {
+  if (!model) return false;
+  return /^(qwen|mistral|ministral|devstral|codestral|bielik)/.test(model);
+}
+
+export async function hawkProxy(
+  body: Record<string, unknown>,
+  apiKey: string,
+  model?: string | null,
+): Promise<Response> {
+  if (!apiKey) {
+    return new Response('HAWK_API_KEY missing', { status: 500 });
+  }
+  const m = model ?? 'qwen35-4b';
+  const cloned = JSON.parse(JSON.stringify(body)) as Record<string, unknown>;
+  if (needsIdSanitize(m) && Array.isArray(cloned.messages)) {
+    for (const msg of cloned.messages as Array<Record<string, unknown>>) {
+      if (msg.role === 'assistant' && Array.isArray(msg.tool_calls)) {
+        for (const tc of msg.tool_calls as Array<Record<string, unknown>>) {
+          tc.id = sanitizeId(tc.id as string | undefined);
+        }
+      } else if (msg.role === 'tool' && typeof msg.tool_call_id === 'string') {
+        msg.tool_call_id = sanitizeId(msg.tool_call_id);
+      }
+    }
+  }
+  const res = await fetch('https://hawk.hyperskills.net/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ ...cloned, model: m }),
+  });
+  if (!res.ok) return new Response(await res.text(), { status: res.status });
+  return Response.json(await res.json());
+}

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export { llmProxy } from './llmProxy.js';
+export { hawkProxy } from './hawkProxy.js';

package/src/util/opfs-cache.ts

@@ -252,13 +252,112 @@ export async function loadOrDownloadModel(
 /**
  * Remove every cached file for a given repo. Silently no-ops if the repo
  * directory does not exist.
+ *
+ * Accepts either the original `owner/name` form OR the sanitized key form
+ * (`owner__name`). Both are tried so UIs that list cached repos via
+ * `listCachedModels()` (which only knows the sanitized key) can delete.
  */
 export async function clearModelCache(repo: string): Promise<void> {
   try {
     const root = await navigator.storage.getDirectory();
     const modelsDir = await root.getDirectoryHandle('webmcp-models', { create: false });
-    const repoKey = sanitizeRepoKey(repo);
-    await modelsDir.removeEntry(repoKey, { recursive: true });
+    const candidates = new Set<string>([repo, sanitizeRepoKey(repo)]);
+    for (const key of candidates) {
+      try { await modelsDir.removeEntry(key, { recursive: true }); } catch { /* not present */ }
+    }
+  } catch {
+    // Nothing to clear
+  }
+}
+
+/**
+ * Info about a single cached model repo in OPFS.
+ *
+ * Note: `repo` is the sanitized folder name as it appears on disk
+ * (e.g. `google__gemma-3n-E2B-it-litert-preview`). The original `owner/name`
+ * is not recoverable after sanitization.
+ */
+export interface CachedModelInfo {
+  repo: string;
+  size: number;
+  fileCount: number;
+  lastModified: number;
+}
+
+/**
+ * Recursively sum file sizes under a directory handle, tracking count and
+ * max lastModified. Ignores entries that fail to enumerate.
+ */
+export async function walkDirectoryStats(
+  dir: FileSystemDirectoryHandle,
+): Promise<{ size: number; fileCount: number; lastModified: number }> {
+  let size = 0;
+  let fileCount = 0;
+  let lastModified = 0;
+  try {
+    const iter = dir as unknown as { entries: () => AsyncIterable<[string, FileSystemHandle]> };
+    for await (const [, handle] of iter.entries()) {
+      if (handle.kind === 'file') {
+        try {
+          const f = await (handle as FileSystemFileHandle).getFile();
+          size += f.size;
+          fileCount += 1;
+          if (f.lastModified > lastModified) lastModified = f.lastModified;
+        } catch { /* skip */ }
+      } else if (handle.kind === 'directory') {
+        const sub = await walkDirectoryStats(handle as FileSystemDirectoryHandle);
+        size += sub.size;
+        fileCount += sub.fileCount;
+        if (sub.lastModified > lastModified) lastModified = sub.lastModified;
+      }
+    }
+  } catch { /* iteration unsupported */ }
+  return { size, fileCount, lastModified };
+}
+
+/**
+ * List every cached model repo in OPFS with cumulative size, file count and
+ * last-modified timestamp. Returns `[]` if `webmcp-models` does not exist
+ * or if OPFS itself is unavailable.
+ */
+export async function listCachedModels(): Promise<CachedModelInfo[]> {
+  try {
+    if (!navigator.storage?.getDirectory) return [];
+    const root = await navigator.storage.getDirectory();
+    let modelsDir: FileSystemDirectoryHandle;
+    try {
+      modelsDir = await root.getDirectoryHandle('webmcp-models', { create: false });
+    } catch {
+      return [];
+    }
+    const out: CachedModelInfo[] = [];
+    const iter = modelsDir as unknown as { entries: () => AsyncIterable<[string, FileSystemHandle]> };
+    try {
+      for await (const [name, handle] of iter.entries()) {
+        if (handle.kind !== 'directory') continue;
+        const stats = await walkDirectoryStats(handle as FileSystemDirectoryHandle);
+        if (stats.size === 0 || stats.fileCount === 0) {
+          // Orphan directory (e.g. worker bug that created an empty repo key).
+          try { await modelsDir.removeEntry(name, { recursive: true }); } catch { /* best-effort */ }
+          continue;
+        }
+        out.push({ repo: name, size: stats.size, fileCount: stats.fileCount, lastModified: stats.lastModified });
+      }
+    } catch { /* iteration unsupported */ }
+    out.sort((a, b) => b.size - a.size);
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Nuke the whole `webmcp-models` directory. No-op if it does not exist.
+ */
+export async function clearAllModelCaches(): Promise<void> {
+  try {
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry('webmcp-models', { recursive: true });
   } catch {
     // Nothing to clear
   }