@spheredata/embed 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Zhang, Zihuai He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @spheredata/embed
+
+The embeddable SPHERE agent UI — a framework-agnostic `<sphere-agent>` Web
+Component any web page can drop in, plus optional in-browser tool packs. Shadow
+DOM keeps the host's CSS isolated; the agent loop runs client-side.
+
+The product/brand is **SPHERE** — this package is published under the
+`@spheredata` npm scope. The custom element is `<sphere-agent>` and the design
+tokens are `--sphere-*` (unchanged).
+
+## Install
+
+```sh
+npm i @spheredata/embed @spheredata/sdk
+```
+
+A partner needs **both**: `@spheredata/sdk` provides `createSphere` (the backend
+client), and this package provides the UI element you wire it into.
+
+## Quick start
+
+```html
+<sphere-agent id="agent" layout="split" attachments>
+  <span slot="title">SPHERE Agent · ADRC</span>
+  <span slot="notice">Python runs locally; your data never leaves the page.</span>
+</sphere-agent>
+
+<script type="module">
+  import { createSphere } from "@spheredata/sdk";
+  import { pyodideTools, learningStore } from "@spheredata/embed/tools";
+  import "@spheredata/embed"; // registers the <sphere-agent> element
+
+  const sphere = createSphere({ portal: "adrc" });
+  const mem = learningStore(sphere.portal);
+
+  const el = document.getElementById("agent");
+  el.sphere = sphere;
+  el.systemPrompt = "You are a SPHERE data analyst…";
+  el.examples = ["What datasets are available?"];
+  el.tools = [...pyodideTools({ baseUrl: "/data/", datasets: { scrna: "scrna.csv" } }), mem.tool];
+  el.seed = mem.seed;   // inject prior learnings at the start of each conversation
+  el.memory = mem;      // drive the memory badge (count())
+</script>
+```
+
+## Element API (properties)
+
+| Property | Type | Purpose |
+| --- | --- | --- |
+| `sphere` | client | The `@spheredata/sdk` client (required). |
+| `systemPrompt` | string | System message for the agent. |
+| `tools` | array | Tool objects `{ name, description, input_schema, run() }`. |
+| `examples` | string[] | Starter prompts shown in the welcome state. |
+| `model` | string | Model id override. |
+| `maxTokens` | number | Completion cap (default 4096). |
+| `layout` | `"chat"` \| `"split"` | Single pane, or two-pane with a results panel for figures. |
+| `attachments` | boolean | Enable file attach in the composer. |
+| `accountUrl` | string | Where the "Add credits" link redirects (billing is never embedded). |
+| `seed` | `() => messages[]` | Inject prior messages/learnings at conversation start. |
+| `seedMessages` | array | Static alternative to `seed()`. |
+| `memory` | `{ count() }` | Drives the memory badge. |
+
+**Reflected attributes:** `layout`, `attachments`, `account-url`.
+**Slots:** `title`, `notice`.
+
+## Tool packs — `@spheredata/embed/tools`
+
+- `pyodideTools({ baseUrl, datasets, dataDictionary, packages })` — Python/pandas in
+  the browser (load datasets, run code, return figures). No server round-trip.
+- `learningStore(namespace, storage?)` — persistent per-portal memory; exposes `.tool`,
+  `.seed`, and `.count()`.
+- `calculatorTool` — safe arithmetic.
+- `resolveDatasetUrl(baseUrl, datasets, name)` — helper for dataset URL resolution.
+
+## Theming
+
+Defaults are the SPHERE brand and match [`@spheredata/design`](https://www.npmjs.com/package/@spheredata/design)
+token values, so a host that imports `@spheredata/design/tokens.css` looks
+identical. To re-skin per partner, override any of this Tier-2 contract on a host
+ancestor (e.g. `:root` or the element):
+
+```css
+:root {
+  --sphere-accent: #1d4ed8;
+  --sphere-accent-hover: #1e40af;
+  --sphere-radius: 6px;
+  --sphere-font: "Inter", sans-serif;
+  --sphere-surface: #ffffff;
+  --sphere-panel: #eef2ff;
+  --sphere-user-bg: #e0e7ff;
+}
+```
+
+Full contract: `--sphere-accent`, `--sphere-accent-hover`, `--sphere-radius`,
+`--sphere-font`, `--sphere-surface`, `--sphere-panel`, `--sphere-line`,
+`--sphere-text`, `--sphere-text-muted`, `--sphere-user-bg`, `--sphere-good`,
+`--sphere-warn`, `--sphere-danger`, `--sphere-results-bg`, `--sphere-results-width`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@spheredata/embed",
+  "version": "0.0.1",
+  "publishConfig": { "access": "public" },
+  "description": "Embeddable SPHERE agent UI — the <sphere-agent> Web Component + optional tool packs.",
+  "keywords": ["sphere", "spheredata", "web-component", "custom-element", "ai", "agent", "embed", "pyodide"],
+  "homepage": "https://github.com/statzihuai/sphere-app-dev/tree/main/packages/embed#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/statzihuai/sphere-app-dev.git", "directory": "packages/embed" },
+  "contributors": ["Josh Zhang", "Zihuai He"],
+  "type": "module",
+  "main": "sphere-agent.js",
+  "module": "sphere-agent.js",
+  "exports": {
+    ".": "./sphere-agent.js",
+    "./tools": "./sphere-tools.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": ["sphere-agent.js", "sphere-tools.js"],
+  "license": "MIT"
+}

package/sphere-agent.js

@@ -0,0 +1,727 @@
+// <sphere-agent> — a drop-in agentic chat component any lab portal can import.
+//
+//   import { createSphere } from "./sphere-client.js";
+//   import { pyodideTools, learningStore } from "./sphere-tools.js";
+//   import "./sphere-agent.js";
+//   const el = document.querySelector("sphere-agent");
+//   const sphere = createSphere({ portal: "adrc" });
+//   const mem = learningStore(sphere.portal);
+//   el.sphere = sphere;
+//   el.systemPrompt = "You are a SPHERE data analyst…";
+//   el.tools = [ ...pyodideTools({ baseUrl: "/data/", datasets: {…}, dataDictionary: DD }), mem.tool ];
+//   el.examples = ["What datasets are available?"];
+//   el.seed = mem.seed;          // inject prior learnings at the start of each conversation
+//   el.memory = mem;             // drive the memory badge (count())
+//   el.layout = "split";         // two-pane: chat transcript + results panel for figures
+//   el.attachments = true;       // enable file attach in the composer
+//   el.accountUrl = "https://sphere.example/account";   // where "Add credits" redirects
+//
+// Theming: Shadow DOM keeps the host's CSS from leaking in, while CSS custom properties
+// (which inherit through the shadow boundary) carry the theme in. Defaults are the SPHERE
+// brand and match @spheredata/design's token values, so a host that imports
+// @spheredata/design/tokens.css looks identical. To re-skin per partner/portal, override any of
+// this Tier-2 contract on a host ancestor (e.g. :root or the element):
+//   --sphere-accent, --sphere-accent-hover, --sphere-radius, --sphere-font,
+//   --sphere-surface, --sphere-panel, --sphere-line, --sphere-text, --sphere-text-muted,
+//   --sphere-user-bg, --sphere-good, --sphere-warn, --sphere-danger,
+//   --sphere-results-bg, --sphere-results-width.
+//
+// Protocol: speaks the backend's OpenAI-compatible streaming + tool-calling contract (Butterbase is the
+// OpenAI<->Anthropic adapter). Runs the agent loop client-side: one /fn/agent call per model turn, tool
+// results fed back as messages. Account/billing is never embedded — the component redirects to accountUrl.
+
+const STYLE = `
+:host {
+  /* Per-portal theming (Tier-2 override contract): set any --sphere-* below to
+     re-skin this component for a partner. Defaults are the SPHERE brand and match
+     @spheredata/design's token values, so a host page that imports
+     @spheredata/design/tokens.css inherits identical values — no visual change. */
+  --_accent:        var(--sphere-accent, #8c1515);
+  --_accent-hover:  var(--sphere-accent-hover, #a51c1c);
+  --_radius:        var(--sphere-radius, 10px);
+  --_surface:       var(--sphere-surface, #ffffff);
+  --_panel:         var(--sphere-panel, #f8f1e2);
+  --_line:          var(--sphere-line, #e6dfd0);
+  --_text:          var(--sphere-text, #1a1817);
+  --_muted:         var(--sphere-text-muted, #7a7468);
+  --_user-bg:       var(--sphere-user-bg, #f0eee9);
+  --_good:          var(--sphere-good, #3f7a4a);
+  --_warn:          var(--sphere-warn, #b8801f);
+  --_danger:        var(--sphere-danger, #c0392b);
+  --_results-bg:    var(--sphere-results-bg, #fbfbfa);
+  --_results-width: var(--sphere-results-width, 40%);
+  display: flex; flex-direction: column; min-height: 420px; height: 100%;
+  font-family: var(--sphere-font, inherit);
+  color: var(--_text); background: var(--_surface);
+  border: 1px solid var(--_line); border-radius: var(--_radius); overflow: hidden;
+}
+* { box-sizing: border-box; }
+button { font-family: inherit; cursor: pointer; }
+.hidden { display: none !important; }
+
+/* auth */
+.auth { padding: 28px; max-width: 460px; margin: auto; width: 100%; }
+.auth h3 { margin: 0 0 6px; font-size: 19px; }
+.auth p { color: var(--_muted); font-size: 14px; margin: 0 0 16px; }
+.tabs { display: flex; gap: 14px; margin-bottom: 12px; }
+.tabs button { background: none; border: none; padding: 6px 2px; font-size: 15px; color: var(--_muted); border-bottom: 2px solid transparent; }
+.tabs button.active { color: var(--_accent); border-bottom-color: var(--_accent); font-weight: 600; }
+label { display: block; font-size: 13px; color: var(--_muted); margin: 10px 0 4px; }
+input, textarea, select { width: 100%; padding: 9px 11px; border: 1px solid var(--_line); border-radius: var(--_radius); font: inherit; font-size: 14px; background: var(--_surface); color: inherit; }
+input:focus, textarea:focus, select:focus { outline: none; border-color: var(--_accent); }
+.primary { background: var(--_accent); color: #fff; border: none; padding: 10px 18px; border-radius: var(--_radius); font-size: 14px; }
+.primary:hover:not(:disabled) { background: var(--_accent-hover); }
+.primary:disabled { opacity: .5; cursor: default; }
+.err { color: var(--_danger); font-size: 13px; margin-top: 10px; min-height: 1em; }
+
+/* chat */
+.chat { display: flex; flex-direction: column; height: 100%; min-height: 0; }
+.bar { display: flex; align-items: center; gap: 10px; padding: 8px 12px; border-bottom: 1px solid var(--_line); background: var(--_panel); flex: 0 0 auto; }
+.bar .title { font-weight: 600; font-size: 14px; }
+.bar .spacer { flex: 1; }
+.status { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: var(--_muted); }
+.status .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--_good); flex: 0 0 auto; }
+.status.busy .dot { background: var(--_warn); animation: pulse 1s ease-in-out infinite; }
+.status.error .dot { background: var(--_danger); }
+@keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: .35; } }
+.pill { background: color-mix(in srgb, var(--_good) 12%, transparent); color: var(--_good); border: 1px solid color-mix(in srgb, var(--_good) 30%, transparent); border-radius: 999px; padding: 3px 10px; font-size: 12px; font-weight: 600; cursor: pointer; }
+.pill.low { background: color-mix(in srgb, var(--_danger) 10%, transparent); color: var(--_danger); border-color: color-mix(in srgb, var(--_danger) 30%, transparent); }
+.mem { font-size: 12px; color: var(--_muted); border: 1px solid var(--_line); border-radius: 999px; padding: 2px 8px; }
+.bar select { width: auto; padding: 4px 6px; font-size: 12px; }
+.bar .link { background: none; border: none; color: var(--_accent); font-size: 13px; }
+.who { font-size: 12px; color: var(--_muted); }
+
+.notice { display: flex; align-items: flex-start; gap: 8px; margin: 8px 12px 0; padding: 8px 11px; border-radius: 7px; background: #eef2f7; color: #33415c; font-size: 12.5px; }
+.notice .x { background: none; border: none; color: inherit; font-size: 15px; line-height: 1; margin-left: auto; }
+.banner { margin: 8px 12px 0; padding: 8px 11px; border-radius: var(--_radius); background: color-mix(in srgb, var(--_danger) 10%, transparent); color: var(--_danger); font-size: 13px; display: flex; align-items: center; gap: 10px; }
+.banner a { color: var(--_accent); font-weight: 600; }
+
+.main { flex: 1 1 auto; display: flex; min-height: 0; }
+.thread { flex: 1 1 auto; overflow-y: auto; padding: 16px; display: flex; flex-direction: column; gap: 12px; min-height: 0; }
+.results { flex: 0 0 var(--_results-width); border-left: 1px solid var(--_line); background: var(--_results-bg); overflow-y: auto; padding: 14px; display: flex; flex-direction: column; gap: 12px; min-height: 0; }
+.results h4 { margin: 0 0 4px; font-size: 12px; text-transform: uppercase; letter-spacing: .04em; color: var(--_muted); }
+.results img { max-width: 100%; border: 1px solid var(--_line); border-radius: 6px; cursor: zoom-in; background: var(--_surface); }
+.results .empty { color: var(--_muted); font-size: 13px; }
+@media (max-width: 640px) { .main { flex-direction: column; } .results { flex-basis: auto; border-left: none; border-top: 1px solid var(--_line); } }
+
+.welcome { color: var(--_muted); font-size: 14px; }
+.welcome strong { color: inherit; display: block; margin-bottom: 8px; }
+.chips { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 10px; }
+.chip { border: 1px solid var(--_line); border-radius: 999px; padding: 5px 12px; font-size: 12.5px; cursor: pointer; background: var(--_surface); }
+.chip:hover { border-color: var(--_accent); color: var(--_accent); }
+
+.msg { padding: 10px 13px; border-radius: 10px; font-size: 14.5px; line-height: 1.55; max-width: 90%; word-wrap: break-word; }
+.msg.user { background: var(--_user-bg); align-self: flex-end; white-space: pre-wrap; }
+.msg.assistant { background: var(--_results-bg); border: 1px solid var(--_line); align-self: flex-start; }
+.msg.assistant p { margin: 0 0 8px; } .msg.assistant p:last-child { margin: 0; }
+.msg.assistant h1, .msg.assistant h2, .msg.assistant h3 { margin: 4px 0 6px; line-height: 1.25; }
+.msg.assistant h1 { font-size: 18px; } .msg.assistant h2 { font-size: 16px; } .msg.assistant h3 { font-size: 14.5px; }
+.msg.assistant pre { background: var(--_panel); padding: 10px; border-radius: 7px; overflow-x: auto; font-size: 12.5px; }
+.msg.assistant code { background: var(--_panel); padding: 1px 4px; border-radius: 4px; font-size: 12.5px; }
+.msg.assistant pre code { background: none; padding: 0; }
+.msg.assistant ul, .msg.assistant ol { margin: 0 0 8px; padding-left: 20px; }
+.msg.assistant a { color: var(--_accent); }
+.msg.assistant table { border-collapse: collapse; margin: 4px 0 8px; font-size: 13px; }
+.msg.assistant th, .msg.assistant td { border: 1px solid var(--_line); padding: 4px 8px; text-align: left; }
+.msg.assistant th { background: var(--_panel); }
+.msg.assistant del { opacity: .6; }
+.thinking { color: var(--_muted); font-size: 13px; font-style: italic; align-self: flex-start; }
+
+.tool { align-self: flex-start; max-width: 90%; border: 1px solid var(--_line); border-radius: 8px; background: var(--_panel); font-size: 12.5px; overflow: hidden; }
+.tool summary { cursor: pointer; padding: 7px 11px; list-style: none; display: flex; align-items: center; gap: 8px; }
+.tool summary::-webkit-details-marker { display: none; }
+.tool .badge { font-family: ui-monospace, monospace; background: var(--_accent); color: #fff; border-radius: 5px; padding: 1px 6px; font-size: 11px; }
+.tool .sum { color: var(--_muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
+.tool .glyph { font-weight: 700; } .tool .glyph.ok { color: var(--_good); } .tool .glyph.bad { color: var(--_danger); }
+.tool pre { margin: 0; padding: 10px 11px; border-top: 1px solid var(--_line); background: var(--_surface); overflow-x: auto; font-size: 12px; max-height: 260px; }
+.tool img { max-width: 100%; display: block; border-top: 1px solid var(--_line); }
+.tool .ref { color: var(--_muted); font-style: italic; padding: 8px 11px; border-top: 1px solid var(--_line); background: var(--_surface); }
+
+.attached { display: flex; flex-wrap: wrap; gap: 6px; padding: 6px 12px 0; }
+.attached .a { font-size: 12px; background: var(--_panel); border: 1px solid var(--_line); border-radius: 6px; padding: 2px 8px; display: inline-flex; gap: 6px; align-items: center; }
+.attached .a button { background: none; border: none; color: var(--_muted); cursor: pointer; }
+.composer { display: flex; gap: 8px; padding: 10px 12px; border-top: 1px solid var(--_line); flex: 0 0 auto; align-items: flex-end; }
+.composer .attach { border: 1px solid var(--_line); background: var(--_surface); border-radius: 7px; padding: 8px 10px; }
+.composer textarea { flex: 1; resize: none; min-height: 40px; max-height: 160px; }
+`;
+
+// Escape ALL HTML-significant chars incl. quotes — text from md() flows into attribute
+// contexts (href), so unescaped quotes would allow attribute breakout / event-handler XSS.
+const esc = (s) => String(s)
+  .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+  .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+// Minimal, safe markdown -> HTML. Every text path is escaped BEFORE inline formatting,
+// so model/data output can never inject HTML. Supports headings, tables, fenced/inline code,
+// bold/italic/strikethrough, lists, and http(s) links only.
+function inline(escaped) {
+  return escaped
+    .replace(/`([^`]+)`/g, (_, c) => `<code>${c}</code>`)
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/~~([^~]+)~~/g, "<del>$1</del>")
+    .replace(/(^|[^*])\*([^*]+)\*/g, "$1<em>$2</em>")
+    // http(s) links only; require // and forbid quotes/space in the URL. By the time this
+    // runs the text is already esc()'d (quotes are entities), so this is belt-and-suspenders.
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s"']+)\)/g, '<a href="$2" target="_blank" rel="noopener">$1</a>');
+}
+function tableRow(line, cell) {
+  const cells = line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+  return "<tr>" + cells.map((c) => `<${cell}>${inline(esc(c))}</${cell}>`).join("") + "</tr>";
+}
+function md(raw) {
+  if (!raw) return "";
+  const blocks = String(raw).replace(/\r/g, "").split(/\n{2,}/);
+  return blocks.map((block) => {
+    const fence = block.match(/^```(\w*)\n([\s\S]*?)```$/);
+    if (fence) return `<pre><code>${esc(fence[2])}</code></pre>`;
+    const lines = block.split("\n");
+    // table: every line piped, 2nd line is the header separator
+    if (lines.length >= 2 && lines.every((l) => /^\s*\|.*\|\s*$/.test(l)) && /^\s*\|[\s:|-]+\|\s*$/.test(lines[1])) {
+      const head = tableRow(lines[0], "th");
+      const body = lines.slice(2).map((l) => tableRow(l, "td")).join("");
+      return `<table><thead>${head}</thead><tbody>${body}</tbody></table>`;
+    }
+    const h = block.match(/^(#{1,3})\s+(.+)$/);
+    if (h && lines.length === 1) return `<h${h[1].length}>${inline(esc(h[2]))}</h${h[1].length}>`;
+    if (lines.every((l) => /^\s*[-*]\s+/.test(l))) {
+      return "<ul>" + lines.map((l) => `<li>${inline(esc(l.replace(/^\s*[-*]\s+/, "")))}</li>`).join("") + "</ul>";
+    }
+    if (lines.every((l) => /^\s*\d+\.\s+/.test(l))) {
+      return "<ol>" + lines.map((l) => `<li>${inline(esc(l.replace(/^\s*\d+\.\s+/, "")))}</li>`).join("") + "</ol>";
+    }
+    return `<p>${inline(esc(block)).replace(/\n/g, "<br>")}</p>`;
+  }).join("");
+}
+
+const MODELS = [
+  { id: "anthropic/claude-sonnet-4.6", label: "Sonnet — balanced" },
+  { id: "anthropic/claude-opus-4.8", label: "Opus — most capable" },
+  { id: "anthropic/claude-haiku-4.5", label: "Haiku — fastest" },
+];
+// All current Claude 4.x models accept image input. Deliberately permissive: treat any
+// claude* id (or an unset id) as vision-capable. If a future text-only claude-* ships, switch
+// this to a static allow-list keyed off MODELS to avoid sending image_url to it (would 400).
+const isVisionModel = (id) => !id || /claude/i.test(id);
+
+// Pure: normalize a tool result into the string fed back to the model, the figures to render,
+// and (when showToModel) the multimodal user turn that lets the model see the figure. Exported
+// for tests. `vision` = whether the active model accepts image input.
+function normalizeToolResult(result, vision) {
+  let textOut, images = null, panel = false, showToModel = false, explicitErr = null;
+  if (result && typeof result === "object") {
+    images = result.images ? result.images : (result.image ? [result.image] : null);
+    panel = !!result.panel; showToModel = !!result.showToModel;
+    if (typeof result.isError === "boolean") explicitErr = result.isError;
+    textOut = result.text != null ? String(result.text) : (images ? "[figure rendered]" : JSON.stringify(result));
+  } else {
+    textOut = typeof result === "string" ? result : JSON.stringify(result);
+  }
+  const isError = explicitErr != null
+    ? explicitErr
+    : (/^\s*(tool error|error)[:\n]/i.test(textOut) || /^No such tool:/.test(textOut));
+  let visionTurn = null;
+  if (showToModel && images && images.length) {
+    const last = images[images.length - 1];
+    const url = last.startsWith("data:") ? last : `data:image/png;base64,${last}`;
+    visionTurn = vision
+      ? { role: "user", content: [
+          { type: "text", text: "Here is the figure you produced — inspect it for layout issues (clipped labels, overlap, legends covering data) and fix if needed." },
+          { type: "image_url", image_url: { url } },
+        ] }
+      : { role: "user", content: "A figure was produced, but the current model cannot view images. Proceed without visual inspection." };
+  }
+  return { textOut, isError, images, panel, showToModel, visionTurn };
+}
+
+// Pure: build one OpenAI content part for an attachment. Text cap is measured in BYTES.
+function attachmentPart(name, kind, data, vision) {
+  if (kind === "image") {
+    return vision
+      ? { type: "image_url", image_url: { url: data } }
+      : { type: "text", text: `[Attached image ${name} — current model can't view images]` };
+  }
+  const bytes = typeof Blob !== "undefined" ? new Blob([data]).size : Buffer.byteLength(data, "utf8");
+  if (bytes <= 100000) return { type: "text", text: `Attached ${name}:\n\`\`\`\n${data}\n\`\`\`` };
+  return { type: "text", text: `[Attached ${name} — ${bytes} bytes, too large to inline]` };
+}
+
+// Importable in non-DOM contexts (Node tests) without throwing: fall back to a dummy base
+// and skip customElements registration when the DOM isn't present.
+const Base = typeof HTMLElement !== "undefined" ? HTMLElement : class {};
+
+class SphereAgent extends Base {
+  constructor() {
+    super();
+    this._sphere = null;
+    this._tools = [];
+    this._systemPrompt = "";
+    this._examples = [];
+    this._model = null;
+    this._maxTokens = 4096;
+    this._layout = "chat";
+    this._attachmentsEnabled = false;
+    this._accountUrl = "";
+    this._seed = null;           // () => messages[]  (called per fresh conversation)
+    this._seedMessages = null;   // static array alternative
+    this._memory = null;         // { count() } — drives the badge
+    this._messages = [];         // OpenAI-format conversation (no system; sent separately)
+    this._attached = [];         // pending File attachments
+    this._seeded = false;
+    this._busy = false;
+    this._abort = null;
+    this.attachShadow({ mode: "open" });
+    this.shadowRoot.innerHTML = `<style>${STYLE}</style>${this._skeleton()}`;
+    this._bind();
+  }
+
+  // ---- public API (properties) ----
+  set sphere(s) { this._sphere = s; this._refresh(); }
+  get sphere() { return this._sphere; }
+  set tools(t) { this._tools = Array.isArray(t) ? t : []; }
+  set systemPrompt(s) { this._systemPrompt = s || ""; }
+  set examples(e) { this._examples = Array.isArray(e) ? e : []; this._renderWelcome(); }
+  set model(m) { this._model = m || null; }
+  set maxTokens(n) { this._maxTokens = Number(n) || 4096; }
+  set layout(v) { this._layout = v === "split" ? "split" : "chat"; this._applyLayout(); }
+  set attachments(v) { this._attachmentsEnabled = !!v; this._applyAttachments(); }
+  set accountUrl(v) { this._accountUrl = v || ""; }
+  set seed(fn) { this._seed = typeof fn === "function" ? fn : null; }
+  set seedMessages(arr) { this._seedMessages = Array.isArray(arr) ? arr : null; }
+  set memory(m) { this._memory = m && typeof m.count === "function" ? m : null; this._renderMemBadge(); }
+
+  static get observedAttributes() { return ["layout", "attachments", "account-url"]; }
+  attributeChangedCallback(name, _old, val) {
+    if (name === "layout") this.layout = val;
+    else if (name === "attachments") this.attachments = val !== null && val !== "false";
+    else if (name === "account-url") this.accountUrl = val;
+  }
+
+  connectedCallback() { this._refresh(); }
+
+  // ---- skeleton ----
+  _skeleton() {
+    return `
+    <section class="auth" id="auth">
+      <div class="tabs"><button id="tab-in" class="active">Sign in</button><button id="tab-up">Create account</button></div>
+      <div id="name-wrap" class="hidden"><label>Name</label><input id="name" type="text" autocomplete="name"></div>
+      <label>Email</label><input id="email" type="email" autocomplete="email" placeholder="you@lab.edu">
+      <label>Password</label><input id="password" type="password" autocomplete="current-password" placeholder="••••••••">
+      <div style="margin-top:14px"><button class="primary" id="auth-go">Sign in</button></div>
+      <div class="err" id="auth-err"></div>
+      <p id="up-hint" class="hidden" style="margin-top:12px">New accounts start with <strong>$10</strong> in free credit.</p>
+    </section>
+
+    <section class="chat hidden" id="chat">
+      <div class="bar">
+        <span class="title"><slot name="title">SPHERE Agent</slot></span>
+        <span class="status" id="status"><span class="dot"></span><span id="status-text">Ready</span></span>
+        <span class="who" id="who"></span>
+        <span class="spacer"></span>
+        <span class="mem hidden" id="mem"></span>
+        <span class="pill" id="balance" title="Manage credits">—</span>
+        <select id="model"></select>
+        <button class="link" id="reset" title="New conversation">↺</button>
+        <button class="link" id="signout">Sign out</button>
+      </div>
+      <div class="notice hidden" id="notice"><span><slot name="notice"></slot></span><button class="x" id="notice-x" title="Dismiss">×</button></div>
+      <div class="banner hidden" id="banner"></div>
+      <div class="main">
+        <div class="thread" id="thread"></div>
+        <div class="results hidden" id="results"><h4>Results</h4><div class="empty" id="results-empty">Figures and analysis output appear here.</div></div>
+      </div>
+      <div class="attached hidden" id="attached"></div>
+      <div class="composer">
+        <button class="attach hidden" id="attach" title="Attach files">📎</button>
+        <input type="file" id="file" multiple class="hidden">
+        <textarea id="input" rows="2" placeholder="Ask the agent…  (Enter to send, Shift+Enter for newline)"></textarea>
+        <button class="primary" id="send">Send</button>
+        <button class="link hidden" id="stop">Stop</button>
+      </div>
+    </section>`;
+  }
+
+  _$(id) { return this.shadowRoot.getElementById(id); }
+
+  _bind() {
+    const $ = (id) => this._$(id);
+    this._mode = "signin";
+    $("tab-in").onclick = () => this._setMode("signin");
+    $("tab-up").onclick = () => this._setMode("signup");
+    $("auth-go").onclick = () => this._auth();
+    $("signout").onclick = () => { this._sphere?.signOut(); this._messages = []; this._seeded = false; this._refresh(); };
+    $("reset").onclick = () => this._resetConversation();
+    $("send").onclick = () => this._send();
+    $("stop").onclick = () => this._abort?.abort();
+    $("balance").onclick = () => this._openAccount();
+    $("notice-x").onclick = () => this._dismissNotice();
+    $("attach").onclick = () => $("file").click();
+    $("file").onchange = (e) => this._addAttachments(e.target.files);
+    $("input").addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); this._send(); }
+    });
+    const sel = $("model");
+    sel.innerHTML = MODELS.map((m) => `<option value="${m.id}">${m.label}</option>`).join("");
+    sel.onchange = () => { this._model = sel.value; };
+  }
+
+  _setMode(m) {
+    const $ = (id) => this._$(id);
+    this._mode = m;
+    $("tab-in").classList.toggle("active", m === "signin");
+    $("tab-up").classList.toggle("active", m === "signup");
+    $("name-wrap").classList.toggle("hidden", m !== "signup");
+    $("up-hint").classList.toggle("hidden", m !== "signup");
+    $("auth-go").textContent = m === "signin" ? "Sign in" : "Create account";
+    $("auth-err").textContent = "";
+  }
+
+  _refresh() {
+    const $ = (id) => this._$(id);
+    const signedIn = this._sphere && this._sphere.isSignedIn();
+    $("auth").classList.toggle("hidden", signedIn);
+    $("chat").classList.toggle("hidden", !signedIn);
+    if (signedIn) {
+      this._applyLayout(); this._applyAttachments(); this._applyNotice();
+      this._renderMemBadge(); this._renderWelcome(); this._loadAccount();
+    }
+  }
+
+  _applyLayout() { const r = this._$("results"); if (r) r.classList.toggle("hidden", this._layout !== "split"); }
+  _applyAttachments() { const a = this._$("attach"); if (a) a.classList.toggle("hidden", !this._attachmentsEnabled); }
+
+  // ---- notice banner (dismiss persisted per portal) ----
+  _noticeKey() { return "sphere-agent:notice:" + (this._sphere?.portal || "default"); }
+  _applyNotice() {
+    const notice = this._$("notice"); if (!notice) return;
+    const slot = notice.querySelector("slot[name=notice]");
+    const hasContent = slot && slot.assignedNodes && slot.assignedNodes().length > 0;
+    let dismissed = false;
+    try { dismissed = localStorage.getItem(this._noticeKey()) === "1"; } catch { /* ignore */ }
+    notice.classList.toggle("hidden", !hasContent || dismissed);
+  }
+  _dismissNotice() {
+    try { localStorage.setItem(this._noticeKey(), "1"); } catch { /* ignore */ }
+    this._$("notice").classList.add("hidden");
+  }
+
+  _openAccount() {
+    if (this._accountUrl) window.open(this._accountUrl, "_blank", "noopener");
+  }
+
+  async _auth() {
+    const $ = (id) => this._$(id);
+    const email = $("email").value.trim(), password = $("password").value, name = $("name").value.trim();
+    const btn = $("auth-go"), err = $("auth-err");
+    err.textContent = ""; btn.disabled = true;
+    try {
+      if (this._mode === "signup") await this._sphere.signUp(email, password, name || undefined);
+      await this._sphere.signIn(email, password);
+      this._refresh();
+    } catch (e) {
+      err.textContent = this._mode === "signup" ? "Could not create account. " + (e.message || "") : "Sign in failed — check your email and password.";
+    } finally { btn.disabled = false; }
+  }
+
+  _resetConversation() {
+    this._messages = []; this._seeded = false; this._attached = [];
+    this._$("thread").innerHTML = "";
+    const results = this._$("results");
+    results.querySelectorAll("img,.line").forEach((n) => n.remove());
+    this._$("results-empty").classList.remove("hidden");
+    this._renderAttached(); this._renderWelcome();
+  }
+
+  _renderWelcome() {
+    const thread = this._$("thread");
+    if (!thread || thread.childElementCount) return;
+    const chips = this._examples.map((x) => `<span class="chip">${esc(x)}</span>`).join("");
+    thread.innerHTML = `<div class="welcome"><strong>Ask the agent</strong>${this._examples.length ? `Try one:<div class="chips">${chips}</div>` : ""}</div>`;
+    thread.querySelectorAll(".chip").forEach((c) => (c.onclick = () => { this._$("input").value = c.textContent; this._send(); }));
+  }
+
+  _renderMemBadge() {
+    const mem = this._$("mem"); if (!mem) return;
+    const n = this._memory ? this._memory.count() : 0;
+    mem.textContent = n ? `Memory: ${n}` : "";
+    mem.classList.toggle("hidden", !n);
+  }
+
+  async _loadAccount() {
+    try {
+      const a = await this._sphere.getAccount();
+      this._setBalance(a.wallet?.balance_usd);
+      const bits = [a.user?.email, a.portal?.name].filter(Boolean);
+      this._$("who").textContent = bits.join(" · ");
+    } catch (_) {}
+  }
+
+  _setBalance(v) {
+    const pill = this._$("balance");
+    if (v == null) { pill.textContent = "—"; return; }
+    pill.textContent = `$${Number(v).toFixed(4)}`;
+    const low = Number(v) <= 0;
+    pill.classList.toggle("low", low);
+    this._$("send").disabled = low;
+    const banner = this._$("banner");
+    banner.classList.toggle("hidden", !low);
+    if (low) {
+      const link = this._accountUrl ? ` <a href="${esc(this._accountUrl)}" target="_blank" rel="noopener">Add credits ↗</a>` : "";
+      banner.innerHTML = `You're out of SPHERE credit.${link}`;
+    }
+  }
+
+  _setStatus(text, state) {
+    const s = this._$("status"); if (!s) return;
+    s.classList.remove("busy", "error");
+    if (state) s.classList.add(state);
+    this._$("status-text").textContent = text || "Ready";
+  }
+
+  // ---- attachments ----
+  _addAttachments(fileList) {
+    for (const f of fileList || []) this._attached.push(f);
+    this._$("file").value = "";
+    this._renderAttached();
+  }
+  _renderAttached() {
+    const wrap = this._$("attached"); if (!wrap) return;
+    wrap.classList.toggle("hidden", this._attached.length === 0);
+    wrap.innerHTML = this._attached.map((f, i) =>
+      `<span class="a">${esc(f.name)} <button data-i="${i}" title="Remove">×</button></span>`).join("");
+    wrap.querySelectorAll("button").forEach((b) => (b.onclick = () => {
+      this._attached.splice(Number(b.dataset.i), 1); this._renderAttached();
+    }));
+  }
+  _readFile(file) {
+    return new Promise((res, rej) => {
+      const fr = new FileReader();
+      fr.onerror = () => rej(new Error("read failed"));
+      if (/^image\//.test(file.type)) { fr.onload = () => res({ kind: "image", data: fr.result }); fr.readAsDataURL(file); }
+      else { fr.onload = () => res({ kind: "text", data: fr.result }); fr.readAsText(file); }
+    });
+  }
+  // Build OpenAI-shaped content for the user turn from text + pending attachments.
+  async _composeUserContent(text) {
+    if (!this._attached.length) return text;
+    const parts = [{ type: "text", text }];
+    const vision = isVisionModel(this._model);
+    for (const f of this._attached) {
+      try {
+        const r = await this._readFile(f);
+        parts.push(attachmentPart(f.name, r.kind, r.data, vision));
+      } catch { parts.push({ type: "text", text: `[Attached ${f.name} — could not read]` }); }
+    }
+    this._attached = []; this._renderAttached();
+    return parts;
+  }
+
+  // ---- DOM helpers ----
+  _bubble(role, html, asText) {
+    const div = document.createElement("div");
+    div.className = `msg ${role}`;
+    if (asText) div.textContent = html; else div.innerHTML = html;
+    this._$("thread").appendChild(div);
+    this._scroll();
+    return div;
+  }
+  _scroll() { const t = this._$("thread"); t.scrollTop = t.scrollHeight; }
+  _toolCard(name, input) {
+    const d = document.createElement("details");
+    d.className = "tool"; d.open = false;
+    const summary = (() => { const s = JSON.stringify(input); return s.length > 80 ? s.slice(0, 78) + "…" : s; })();
+    d.innerHTML = `<summary><span class="badge">${esc(name)}</span><span class="sum">${esc(summary)}</span><span class="glyph"></span></summary><pre>running…</pre>`;
+    this._$("thread").appendChild(d);
+    this._scroll();
+    return d;
+  }
+  // Route figure(s) to the results pane (split layout) or inline in the card.
+  _renderFigures(card, images, toPanel) {
+    const imgs = (Array.isArray(images) ? images : [images]).filter(Boolean);
+    if (!imgs.length) return;
+    const toData = (b) => (b.startsWith("data:") ? b : `data:image/png;base64,${b}`);
+    if (toPanel && this._layout === "split") {
+      const pane = this._$("results");
+      this._$("results-empty").classList.add("hidden");
+      for (const b of imgs) {
+        const img = document.createElement("img");
+        img.src = toData(b);
+        img.onclick = () => window.open(img.src, "_blank", "noopener");
+        pane.appendChild(img);
+      }
+      pane.scrollTop = pane.scrollHeight;
+      const ref = document.createElement("div"); ref.className = "ref";
+      ref.textContent = imgs.length > 1 ? `→ ${imgs.length} figures in results` : "→ figure in results";
+      card.appendChild(ref); card.open = true;
+    } else {
+      for (const b of imgs) {
+        const img = document.createElement("img");
+        img.src = toData(b); card.appendChild(img);
+      }
+      card.open = true;
+    }
+    this._scroll();
+  }
+
+  // ---- send + agent loop ----
+  async _send() {
+    if (this._busy || !this._sphere) return;
+    const input = this._$("input");
+    const text = input.value.trim();
+    if (!text && !this._attached.length) return;
+    input.value = "";
+    const welcome = this.shadowRoot.querySelector(".welcome"); if (welcome) welcome.remove();
+    this._bubble("user", text || "(attachment)", true);
+    // Seed prior context once per fresh conversation, before the first user message.
+    if (!this._seeded) {
+      const seeded = this._seed ? this._seed() : (this._seedMessages || []);
+      if (Array.isArray(seeded) && seeded.length) this._messages.push(...seeded);
+      this._seeded = true;
+    }
+    const content = await this._composeUserContent(text);
+    this._messages.push({ role: "user", content });
+    await this._runLoop();
+  }
+
+  async _runLoop() {
+    this._busy = true;
+    this._abort = new AbortController();
+    const $ = (id) => this._$(id);
+    $("send").disabled = true; $("stop").classList.remove("hidden");
+    this._setStatus("Thinking…", "busy");
+    let thinking = this._bubble("thinking", "Thinking…", true); thinking.classList.add("thinking");
+    try {
+      for (let i = 0; i < 16; i++) {
+        const turn = await this._streamTurn(() => { if (thinking) { thinking.remove(); thinking = null; } });
+        const asMsg = { role: "assistant", content: turn.text || "" };
+        if (turn.toolCalls.length) asMsg.tool_calls = turn.toolCalls.map((t) => ({ id: t.id, type: "function", function: { name: t.name, arguments: t.arguments } }));
+        this._messages.push(asMsg);
+
+        if (turn.finish === "tool_calls" && turn.toolCalls.length) {
+          const visionTurns = []; // figures to show the model after this batch of tool results
+          for (const call of turn.toolCalls) {
+            const input = this._safeParse(call.arguments);
+            const card = this._toolCard(call.name, input);
+            this._setStatus(this._toolStatus(call.name, input), "busy");
+            const result = await this._execTool(call.name, input);
+            const { textOut, isError } = this._applyToolResult(card, result, visionTurns);
+            this._messages.push({ role: "tool", tool_call_id: call.id, content: textOut });
+            this._setToolGlyph(card, isError);
+          }
+          // Feed any requested figures back to the model as a user turn (vision).
+          for (const vt of visionTurns) this._messages.push(vt);
+          this._setStatus("Thinking…", "busy");
+          thinking = this._bubble("thinking", "Thinking…", true); thinking.classList.add("thinking");
+          continue;
+        }
+        break;
+      }
+    } catch (e) {
+      if (thinking) { thinking.remove(); thinking = null; }
+      if (e?.message === "insufficient_credits") { this._setBalance(0); this._bubble("assistant", md("💳 You're out of credits.")); }
+      else if (e?.name === "AbortError") this._bubble("assistant", md("⏹ Stopped."));
+      else this._bubble("assistant", md("⚠️ " + (e?.message || "Something went wrong.")));
+    } finally {
+      if (thinking) thinking.remove();
+      this._busy = false; this._abort = null;
+      $("send").disabled = false; $("stop").classList.add("hidden");
+      this._setStatus("Ready");
+      this._renderMemBadge();
+      this._$("input").focus();
+    }
+  }
+
+  _toolStatus(name, input) {
+    const tool = this._tools.find((t) => t.name === name);
+    try { if (tool && typeof tool.status === "function") return tool.status(input) || "Working…"; } catch { /* ignore */ }
+    return name === "run_python" ? "Running Python…" : `Running ${name}…`;
+  }
+  _setToolGlyph(card, isError) {
+    const g = card.querySelector(".glyph");
+    if (g) { g.textContent = isError ? "✗" : "✓"; g.classList.add(isError ? "bad" : "ok"); }
+  }
+
+  // Normalize a tool result into the string fed back to the model, render figures,
+  // and (for showToModel results) queue a multimodal user turn so the model can see them.
+  _applyToolResult(card, result, visionTurns) {
+    const n = normalizeToolResult(result, isVisionModel(this._model));
+    card.querySelector("pre").textContent = n.textOut;
+    if (n.images && n.images.length) this._renderFigures(card, n.images, n.panel);
+    if (n.visionTurn) visionTurns.push(n.visionTurn);
+    return { textOut: n.textOut, isError: n.isError };
+  }
+
+  _safeParse(s) { try { return JSON.parse(s); } catch { return {}; } }
+
+  async _execTool(name, input) {
+    const tool = this._tools.find((t) => t.name === name);
+    if (!tool) return `No such tool: ${name}`;
+    try { return await tool.run(input); }
+    catch (e) { return "Error: " + (e?.message || e); } // "Error:" prefix => flagged as an error glyph
+  }
+
+  // One streaming model turn. Renders assistant text live, assembles tool_calls, updates balance.
+  async _streamTurn(onFirstByte) {
+    const tools = this._tools.length
+      ? this._tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description || "", parameters: t.input_schema || { type: "object", properties: {} } } }))
+      : undefined;
+    const resp = await this._sphere.streamAgent({
+      model: this._model || undefined,
+      system: this._systemPrompt || undefined,
+      messages: this._messages,
+      max_tokens: this._maxTokens,
+      ...(tools ? { tools } : {}),
+    }, this._abort.signal);
+
+    if (!resp.ok) {
+      if (resp.status === 402) throw new Error("insufficient_credits");
+      if (resp.status === 401) { this._sphere.signOut(); this._refresh(); throw new Error("Session expired — sign in again."); }
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(err.error || `API error ${resp.status}`);
+    }
+
+    const reader = resp.body.getReader();
+    const dec = new TextDecoder();
+    let text = "", bubble = null, flushed = false;
+    const toolCalls = []; // {id,name,arguments}
+    let finish = "stop";
+    let buf = "";
+
+    const renderLive = () => { if (bubble) bubble.textContent = text; this._scroll(); };
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() || "";
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue;
+        const payload = line.slice(5).trim();
+        if (payload === "[DONE]" || !payload) continue;
+        let ev; try { ev = JSON.parse(payload); } catch { continue; }
+        if (ev.sphere) { this._setBalance(ev.sphere.balance_usd); continue; }
+        const choice = ev.choices?.[0]; if (!choice) continue;
+        const delta = choice.delta || {};
+        if (delta.content) {
+          if (!flushed) { flushed = true; onFirstByte?.(); bubble = this._bubble("assistant", "", true); }
+          text += delta.content; renderLive();
+        }
+        if (delta.tool_calls) {
+          for (const tc of delta.tool_calls) {
+            const idx = tc.index ?? 0;
+            toolCalls[idx] = toolCalls[idx] || { id: "", name: "", arguments: "" };
+            if (tc.id) toolCalls[idx].id = tc.id;
+            if (tc.function?.name) toolCalls[idx].name = tc.function.name;
+            if (tc.function?.arguments) toolCalls[idx].arguments += tc.function.arguments;
+          }
+        }
+        if (choice.finish_reason) finish = choice.finish_reason;
+      }
+    }
+    if (bubble && text) bubble.innerHTML = md(text); // seal: render markdown
+    return { text, toolCalls: toolCalls.filter(Boolean), finish };
+  }
+}
+
+if (typeof customElements !== "undefined") customElements.define("sphere-agent", SphereAgent);
+export { SphereAgent, md, isVisionModel, normalizeToolResult, attachmentPart };

package/sphere-tools.js

@@ -0,0 +1,343 @@
+// Optional tool packs for <sphere-agent>. A "tool" is { name, description, input_schema, run }.
+// `run(input)` returns a string, or an object describing output:
+//   { text, image }            — text plus a single base64 PNG (rendered in the card / results panel)
+//   { text, images: [b64,…] }  — text plus several figures
+//   { …, panel: true }         — route the figure(s) to the two-pane results panel, not inline
+//   { …, showToModel: true }   — also feed the figure back to the model (vision) as a user turn
+//   { …, isError: true }       — explicitly mark the result as a failure (else inferred from text)
+// An optional `status(input) -> string` lets a tool label its own running state in the status bar.
+//
+// Labs compose the tools they want:
+//   import { pyodideTools, learningStore } from "./sphere-tools.js";
+//   const mem = learningStore(sphere.portal);
+//   el.tools = [ ...pyodideTools({ baseUrl: "/data/", datasets: { demographics: "demographics.csv" } }), mem.tool ];
+//   el.seed  = mem.seed;     // inject prior learnings at the start of each conversation
+//   el.memory = mem;         // drive the memory badge (count())
+
+// ── calculator (no deps; safe arithmetic only) ──────────────────────
+export const calculatorTool = {
+  name: "calculator",
+  description: "Evaluate a basic arithmetic expression (+ - * / parentheses).",
+  input_schema: { type: "object", properties: { expr: { type: "string", description: "e.g. (47*89)/3" } }, required: ["expr"] },
+  run: ({ expr }) => {
+    if (!/^[\d\s+\-*/().,]+$/.test(String(expr || ""))) return "Error: only numbers and + - * / ( ) allowed.";
+    try { return String(Function(`"use strict";return (${expr})`)()); }
+    catch (e) { return "Error: " + (e?.message || "bad expression"); }
+  },
+};
+
+// ── pure helpers (exported for unit tests) ──────────────────────────
+
+// Resolve a dataset name to a fetchable URL. `datasets[name]` may be an absolute
+// URL / data: URI (used as-is) or a path relative to `baseUrl`. One configurable
+// `baseUrl` is the seam that lets a portal point at static files today and a
+// SPHERE data API later with no code change.
+export function resolveDatasetUrl(baseUrl, datasets, name) {
+  const v = datasets?.[name];
+  if (typeof v !== "string" || !v) return null;                     // missing or non-string -> not available
+  if (/^([a-z]+:)?\/\//i.test(v) || v.startsWith("data:")) return v; // absolute or data URI
+  return (baseUrl || "") + v;                                        // relative to baseUrl
+}
+
+const LEARN_PREFIX = "sphere-agent:learnings:";
+const LEARN_MAX = 30;
+
+// localStorage-backed, per-namespace learning store. `storage` is injectable for tests.
+export function learningStore(namespace, storage) {
+  const store = storage || (typeof globalThis !== "undefined" ? globalThis.localStorage : null);
+  const key = LEARN_PREFIX + (namespace || "default");
+
+  const read = () => {
+    try { const v = JSON.parse(store?.getItem(key) || "[]"); return Array.isArray(v) ? v : []; } catch { return []; }
+  };
+  const write = (arr) => { try { store?.setItem(key, JSON.stringify(arr)); } catch { /* quota / unavailable */ } };
+
+  const add = (issue, solution, ts = 0) => {
+    issue = String(issue || "").trim(); solution = String(solution || "").trim();
+    if (!issue || !solution) return { ok: false, note: "Both issue and solution are required." };
+    const arr = read();
+    if (arr.some((l) => l.issue === issue)) return { ok: true, count: arr.length, note: "Already saved." };
+    arr.push({ issue, solution, ts });
+    if (arr.length > LEARN_MAX) arr.splice(0, arr.length - LEARN_MAX);
+    write(arr);
+    return { ok: true, count: arr.length };
+  };
+
+  const tool = {
+    name: "save_learning",
+    description:
+      "Save a lesson to persistent memory for future sessions. Call this when you fix a new error " +
+      "(imports, data-shape surprises, API quirks) or discover something useful about the data " +
+      "(a column's real range, a merge gotcha, a working pattern). Be specific and actionable.",
+    input_schema: {
+      type: "object",
+      required: ["issue", "solution"],
+      properties: {
+        issue: { type: "string", description: 'The problem, e.g. "biomarkers ptau217 has ~40% NaN"' },
+        solution: { type: "string", description: 'The fix/insight, e.g. "dropna() before plotting; n 618→370"' },
+      },
+    },
+    run: ({ issue, solution }) => {
+      const r = add(issue, solution);
+      return r.ok ? `Saved to memory (${r.count ?? read().length} learnings).` : "Error: " + r.note;
+    },
+  };
+
+  // Synthetic [user, assistant] turns that re-inject prior learnings at conversation start.
+  const seed = () => {
+    const arr = read();
+    if (!arr.length) return [];
+    const lines = arr.map((l, i) => `${i + 1}. **Issue**: ${l.issue}\n   **Fix**: ${l.solution}`).join("\n\n");
+    return [
+      { role: "user", content: `[Persistent memory from previous sessions — apply proactively]\n\n${lines}` },
+      { role: "assistant", content: `Understood. I'll apply these ${arr.length} learned fix${arr.length > 1 ? "es" : ""}.` },
+    ];
+  };
+
+  return { tool, seed, count: () => read().length, clear: () => write([]), _add: add };
+}
+
+// ── Pyodide pack: run Python in the browser; data never leaves the page ──
+const PYODIDE_CDN = "https://cdn.jsdelivr.net/pyodide/v0.27.5/full/pyodide.js";
+const DEFAULT_PACKAGES = ["pandas", "numpy", "scipy", "matplotlib", "scikit-learn", "statsmodels", "micropip"];
+let _pyReady = null;
+
+async function ensurePyodide(packages) {
+  if (_pyReady) return _pyReady;
+  _pyReady = (async () => {
+    if (!globalThis.loadPyodide) {
+      await new Promise((res, rej) => {
+        const s = document.createElement("script");
+        s.src = PYODIDE_CDN; s.onload = res; s.onerror = () => rej(new Error("failed to load Pyodide"));
+        document.head.appendChild(s);
+      });
+    }
+    const py = await globalThis.loadPyodide();
+    await py.loadPackage(packages && packages.length ? packages : DEFAULT_PACKAGES);
+    py.runPython(`
+import io, os, sys, math, json, base64, warnings
+import numpy as np, pandas as pd
+import matplotlib
+matplotlib.use('AGG')
+import matplotlib.pyplot as plt
+try:
+    import scipy, scipy.stats as stats
+except Exception:
+    scipy = None; stats = None
+try:
+    import statsmodels.api as sm
+except Exception:
+    sm = None
+try:
+    import sklearn
+except Exception:
+    sklearn = None
+sns = None  # seaborn loaded lazily via micropip below
+os.makedirs('/sandbox', exist_ok=True)
+data = {}                 # data['name'] -> DataFrame
+_sphere_datasets = {}     # same, for iteration: for n, df in _sphere_datasets.items()
+dd = {}                   # data dictionary: col -> label, injected by the host
+_agent_figures = []       # base64 PNGs captured since last clear
+def _capture_fig():
+    figs = [plt.figure(n) for n in plt.get_fignums()]
+    if not figs: return
+    for f in figs:
+        buf = io.BytesIO(); f.savefig(buf, format='png', bbox_inches='tight', dpi=150)
+        buf.seek(0); _agent_figures.append(base64.b64encode(buf.read()).decode())
+    plt.close('all')
+`);
+    // seaborn is optional — try via micropip, leave sns=None if it fails.
+    try {
+      await py.runPythonAsync(`import micropip\nawait micropip.install('seaborn')\nimport seaborn as sns`);
+    } catch { /* sns stays None */ }
+    return py;
+  })();
+  return _pyReady;
+}
+
+export function pyodideTools({ datasets = {}, dataDictionary = null, packages = null, baseUrl = "" } = {}) {
+  const loaded = new Set();
+  let ddInjected = false;
+
+  const injectDd = (py) => {
+    if (ddInjected || !dataDictionary) return;
+    // Accept either {col: label} or {modality: [{col,label}, …]} (portal shape).
+    const flat = {};
+    for (const v of Object.values(dataDictionary)) {
+      if (Array.isArray(v)) for (const e of v) { if (e && e.col) flat[e.col] = e.label ?? e.col; }
+    }
+    const merged = Array.isArray(Object.values(dataDictionary)[0]) ? flat : dataDictionary;
+    py.globals.set("_dd_json", JSON.stringify(merged));
+    py.runPython("import json as _json\ndd.clear(); dd.update(_json.loads(_dd_json))");
+    ddInjected = true;
+  };
+
+  const load_dataset = {
+    name: "load_dataset",
+    description:
+      "Load one or more named datasets into Python as pandas DataFrames (available as `data['<name>']` " +
+      "AND as a variable named after the dataset). Available: " + (Object.keys(datasets).join(", ") || "(none configured)") +
+      ". Call before run_python; you can load several at once.",
+    input_schema: {
+      type: "object",
+      properties: { datasets: { type: "array", items: { type: "string" }, description: "names to load" } },
+      required: ["datasets"],
+    },
+    status: ({ datasets: names }) => `Loading ${(names || []).join(", ") || "data"}…`,
+    run: async ({ datasets: names }) => {
+      const py = await ensurePyodide(packages);
+      injectDd(py);
+      const out = [];
+      let ok = 0, fail = 0;
+      for (const name of names || []) {
+        if (loaded.has(name)) { out.push(`${name}: already loaded`); ok++; continue; }
+        const url = resolveDatasetUrl(baseUrl, datasets, name);
+        if (!url) { out.push(`${name}: not available`); fail++; continue; }
+        try {
+          const resp = await fetch(url);
+          if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+          const csv = await resp.text();
+          py.globals.set("_csv_text", csv); py.globals.set("_csv_name", name);
+          py.runPython(
+            "import pandas as pd, io as _io\n" +
+            "_df = pd.read_csv(_io.StringIO(_csv_text))\n" +
+            "data[_csv_name] = _df\n_sphere_datasets[_csv_name] = _df\n" +
+            "globals()[_csv_name] = _df\n_shape = _df.shape\n_cols = list(_df.columns)"
+          );
+          const shape = py.globals.get("_shape").toJs();
+          const cols = Array.from(py.globals.get("_cols").toJs());
+          loaded.add(name);
+          out.push(`${name}: ${shape[0]} rows × ${shape[1]} cols\nColumns: ${cols.join(", ")}`);
+          ok++;
+        } catch (e) { out.push(`${name}: error ${e?.message || e}`); fail++; }
+      }
+      return { text: "Loaded:\n" + out.join("\n"), isError: ok === 0 && fail > 0 };
+    },
+  };
+
+  const run_python = {
+    name: "run_python",
+    description:
+      "Run Python in the browser sandbox. Pre-imported: os, sys, math, json, warnings, numpy as np, " +
+      "pandas as pd, matplotlib (Agg) + plt, seaborn as sns (may be None), scipy, scipy.stats as stats, " +
+      "statsmodels.api as sm, sklearn. Variables PERSIST across calls — build on previous results. Loaded " +
+      "datasets are DataFrames by name; the data dictionary is `dd` (col -> label). Use print() for output " +
+      "and plt.show()/savefig() for figures.",
+    input_schema: { type: "object", properties: { code: { type: "string" } }, required: ["code"] },
+    status: () => "Running Python…",
+    run: async ({ code }) => {
+      const py = await ensurePyodide(packages);
+      injectDd(py);
+      py.runPython("import sys, io as _io\n_agent_figures.clear()\n_stdout = sys.stdout\nsys.stdout = _io.StringIO()");
+      let err = null;
+      try { await py.runPythonAsync(code); }
+      catch (e) { err = e?.message || String(e); }
+      // Always restore stdout first; figure capture is best-effort and must not lose output.
+      py.runPython("_v = sys.stdout.getvalue(); sys.stdout = _stdout");
+      try { py.runPython("_capture_fig()"); } catch { /* ignore figure-capture errors */ }
+      const stdout = py.globals.get("_v");
+      const figs = Array.from(py.globals.get("_agent_figures").toJs());
+      const text = (err ? "Error:\n" + err + "\n" : "") + (stdout || (figs.length ? "(figure produced)" : "(no output)"));
+      if (figs.length > 1) return { text, images: figs };
+      if (figs.length === 1) return { text, image: figs[0] };
+      return text;
+    },
+  };
+
+  const write_file = {
+    name: "write_file",
+    description: "Write a text file to /sandbox/. Overwrites; content must be non-empty. Use to maintain analysis.py.",
+    input_schema: {
+      type: "object",
+      properties: { path: { type: "string" }, content: { type: "string" } },
+      required: ["path", "content"],
+    },
+    run: async ({ path, content }) => {
+      if (!content) return "Error: content is empty.";
+      const py = await ensurePyodide(packages);
+      const full = "/sandbox/" + String(path || "").replace(/^\/+/, "");
+      try { py.FS.writeFile(full, content); return `Wrote ${full} (${content.length} chars).`; }
+      catch (e) { return "Error: " + (e?.message || e); }
+    },
+  };
+
+  const read_file = {
+    name: "read_file",
+    description: "Read a text file from /sandbox/ (up to 50 KB).",
+    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+    run: async ({ path }) => {
+      const py = await ensurePyodide(packages);
+      const full = "/sandbox/" + String(path || "").replace(/^\/+/, "");
+      try { return py.FS.readFile(full, { encoding: "utf8" }).slice(0, 50000); }
+      catch { return `Error: ${full} not found.`; }
+    },
+  };
+
+  const list_files = {
+    name: "list_files",
+    description: "List files in /sandbox/.",
+    input_schema: { type: "object", properties: {}, required: [] },
+    run: async () => {
+      const py = await ensurePyodide(packages);
+      try { const f = Array.from(py.FS.readdir("/sandbox")).filter((n) => n !== "." && n !== ".."); return f.length ? f.join("\n") : "(empty)"; }
+      catch (e) { return "Error: " + (e?.message || e); }
+    },
+  };
+
+  const pip_install = {
+    name: "pip_install",
+    description: "Install extra Python packages via micropip. Common scientific packages are already available — only use for less common ones. Try import first.",
+    input_schema: { type: "object", properties: { packages: { type: "array", items: { type: "string" } } }, required: ["packages"] },
+    status: ({ packages: pk }) => `Installing ${(pk || []).join(" ")}…`,
+    run: async ({ packages: pk }) => {
+      const py = await ensurePyodide(packages);
+      const names = (pk || []).filter(Boolean);
+      if (!names.length) return "Error: no packages given.";
+      try {
+        py.globals.set("_pip_list", names);
+        await py.runPythonAsync("import micropip\nawait micropip.install(list(_pip_list))");
+        return "Installed: " + names.join(", ");
+      } catch (e) { return "Error: " + (e?.message || e); }
+    },
+  };
+
+  const run_analysis_py = {
+    name: "run_analysis_py",
+    description: "Run /sandbox/analysis.py against the loaded data as a final verification step. Its stdout/stderr and figures are shown in the results panel.",
+    input_schema: { type: "object", properties: {}, required: [] },
+    status: () => "Running analysis.py…",
+    run: async () => {
+      const py = await ensurePyodide(packages);
+      let code;
+      try { code = py.FS.readFile("/sandbox/analysis.py", { encoding: "utf8" }); }
+      catch { return "Error: /sandbox/analysis.py not found. Write it first with write_file."; }
+      py.globals.set("_analysis_code", code);
+      py.runPython("import sys, io as _io\n_agent_figures.clear()\n_stdout = sys.stdout\nsys.stdout = _io.StringIO()");
+      let err = null;
+      try { await py.runPythonAsync("exec(_analysis_code, globals())"); }
+      catch (e) { err = e?.message || String(e); }
+      py.runPython("_v = sys.stdout.getvalue(); sys.stdout = _stdout");
+      try { py.runPython("_capture_fig()"); } catch { /* ignore figure-capture errors */ }
+      const stdout = py.globals.get("_v");
+      const figs = Array.from(py.globals.get("_agent_figures").toJs());
+      const text = `exit ${err ? 1 : 0}\n` + (stdout || "") + (err ? "\n[stderr] " + err : "");
+      return { text, images: figs, panel: true, isError: !!err };
+    },
+  };
+
+  const view_figure = {
+    name: "view_figure",
+    description: "View the most recently produced figure with vision to check layout (clipped labels, overlap, legends covering data). Call after a figure is made; fix issues with another run_python.",
+    input_schema: { type: "object", properties: {}, required: [] },
+    status: () => "Inspecting figure…",
+    run: async () => {
+      const py = await ensurePyodide(packages);
+      const figs = Array.from(py.globals.get("_agent_figures").toJs());
+      const last = figs[figs.length - 1];
+      if (!last) return "No figure available yet. Run code that calls plt.show()/savefig() first.";
+      return { text: "Inspecting the figure for layout issues.", image: last, panel: true, showToModel: true };
+    },
+  };
+
+  return [load_dataset, run_python, write_file, read_file, list_files, pip_install, run_analysis_py, view_figure];
+}