@oyehello/chat 0.5.1 → 0.6.0

package/LICENSE

@@ -56,4 +56,4 @@ otherwise using the Software, You agree to be bound by this Agreement.
    subject matter. If any provision is held unenforceable, the remaining
    provisions remain in full force.
 
-For licensing enquiries, contact: legal@hotreloads.com
+For licensing enquiries, contact: legal@oyehello.ai

package/README.md

@@ -2,7 +2,7 @@
 
 Framework-agnostic embeddable chat for oyehello agents — a `<oyehello-chat>` web component that renders a **floating chat launcher** (bottom-right; click to open a chat window), plus a headless `createChatClient()` for custom UIs. Zero framework dependencies.
 
-The widget connects lazily (a session opens the first time the visitor opens the panel), renders assistant replies as **markdown** (sanitized), and has a full launcher → panel experience: an unread badge, expand/maximize, an emoji picker, file attach, a jump-to-latest control, smart auto-scroll, an optional teaser nudge, quick-reply suggestions, and a privacy footer. It follows the visitor's OS light/dark theme by default. Theme the accent with the `--oc-accent` CSS variable. Just drop the tag anywhere on the page; it positions itself as a floating launcher.
+The widget connects lazily (a session opens the first time the visitor opens the panel), renders assistant replies as **markdown** (sanitized), and has a full launcher → panel experience: an unread badge, expand/maximize, an emoji picker, file attach, a jump-to-latest control, smart auto-scroll, an optional teaser nudge, quick-reply suggestions, and a privacy footer. By default it follows your page's own light/dark theme (live, as your theme toggle changes it), and the visitor's OS theme when your page doesn't declare one. Theme the accent with the `--oc-accent` CSS variable. Just drop the tag anywhere on the page; it positions itself as a floating launcher.
 
 ### Attributes
 
@@ -14,7 +14,7 @@ The **accent/logo/name** (workspace brand), the **teaser** (a chat-agent setting
 | `agent-id` | yes | The chat agent (`agt_…`) |
 | `base-url` | yes | API origin, e.g. `https://api.oyehello.ai` |
 | `title` | no | Header title (defaults to the agent's name) |
-| `theme` | no | `auto` (default, follows the OS), `light`, or `dark` |
+| `theme` | no | `auto` (default: follows your page's theme - a `data-theme` or `data-mode` of `dark`/`light`, a `dark`/`light` class on `<html>`, `<body>` or any parent of the widget, or `color-scheme` - and the visitor's OS when the page declares none), `light`, or `dark` |
 | `teaser` | no | Text for a one-time nudge bubble; omit to disable |
 | `suggestions` | no | Comma-separated quick-reply chips, e.g. `"Book a demo, Pricing"` |
 | `privacy-url` | no | Shows a Privacy-Policy footer linking here |
@@ -36,7 +36,7 @@ npm install @oyehello/chat
 ```
 Or via a plain script tag (no bundler):
 ```html
-<script src="https://unpkg.com/@oyehello/chat@0.5.0"></script>
+<script src="https://unpkg.com/@oyehello/chat@0.6.0"></script>
 <oyehello-chat api-key="ohk_pub_…" agent-id="agt_…" base-url="https://api.oyehello.ai"></oyehello-chat>
 ```
 Pin a specific version (`@0.5.0` above) rather than the bare package name, so a customer's site loads the exact widget it was tested against instead of silently auto-upgrading on every publish.
@@ -74,23 +74,35 @@ await chat.sendMessage('Hello');
 
 ## Client tools (browser actions)
 
-An agent can call browser-side tools your page executes. Register a handler per tool; a tool
-reaches the agent only when it is (a) enabled for that agent in the console AND (b) registered here:
+The SDK supports two browser-side tools: `navigate` (go to a path on the current site) and `openUrl`
+(open a URL, by default in a new tab). Once a tool is enabled for the agent in the console **and** the
+target passes the agent's navigate allowlist (also set in the console), the SDK executes it itself —
+**no host integration required**:
+```html
+<script type="module">import '@oyehello/chat';</script>
+<oyehello-chat api-key="ohk_pub_…" agent-id="agt_…" base-url="https://api.oyehello.ai"></oyehello-chat>
+```
+That's it — a plain embed with no JS wiring can navigate the visitor or open a link when the agent calls
+the tool. `navigate` calls `window.location.assign(path)` (in-app path). `openUrl` opens the URL — which
+is restricted server-side to the agent's allowlisted base domain(s) and their subdomains — choosing the
+tab itself: the exact same host as the embedding page opens in the same tab, any allowed subdomain opens
+in a new tab (`window.open(url, …, 'noopener,noreferrer')`). The agent has no say over the tab target.
+
+A host page MAY still register its own `navigate`/`openUrl` handler to override the default behavior
+(e.g. push through a client-side router instead of a full navigation):
 ```js
 const chat = createChatClient({ apiKey, agentId, baseUrl });
 chat.registerTools({
   navigate: ({ path }) => router.push(path),
-  fillField: ({ selector, value }) => { /* your DOM logic */ },
 });
 // or on the web component: document.querySelector('oyehello-chat').registerTools({ … })
 ```
-Register handlers BEFORE `start()` — only tools registered at open are offered to the agent that session.
+Register handlers BEFORE `start()`. A host-registered handler always takes priority over the SDK's
+built-in; any other tool name has no handler and fails cleanly.
 
-> **Security.** `navigate`/`openUrl` targets can be constrained to an allowlist in the agent's console
-> settings. The other tools (`click`, `fillField`, `readPageContext`, `custom`) receive
-> model-generated arguments with no server-side restriction: **your handler is the trust boundary.**
-> Because a visitor can influence the conversation, treat these as capable of arbitrary DOM action —
-> validate selectors/values and scope what each handler can do before enabling them.
+> **Security.** Navigation targets (both the SDK's built-in execution and a host-overridden handler)
+> are validated against the agent's navigate allowlist **server-side** before the tool call ever
+> reaches the browser — the SDK/host is not the trust boundary for where a visitor can be sent.
 
 ## Requirements
 - `api-key` is a **publishable** key (`ohk_pub_…`) created in the oyehello console.

package/dist/index.cjs

@@ -67,6 +67,16 @@ async function postMessage(opts) {
   });
   if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
 }
+async function getHistory(opts) {
+  const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/messages`, {
+    method: "GET",
+    credentials: "omit",
+    headers: { Authorization: `Bearer ${opts.sessionToken}` }
+  });
+  if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
+  const body = await res.json();
+  return body.messages;
+}
 async function postPageViews(opts) {
   const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/page-views`, {
     method: "POST",
@@ -314,6 +324,33 @@ function installSpaHooks(onNav) {
 // src/client.ts
 var seq = 0;
 var uid = (p) => `${p}_${Date.now().toString(36)}_${(seq++).toString(36)}`;
+var isSafeRelativePath = (p) => p.startsWith("/") && !p.startsWith("//");
+var isSafeHttpUrl = (u) => {
+  try {
+    const parsed = new URL(u, window.location.origin);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+var AFTER_RESULT = "__ohAfterResult";
+var BUILTIN_TOOL_HANDLERS = {
+  navigate: (args) => {
+    const path = String(args.path ?? "");
+    if (!isSafeRelativePath(path)) return { ok: false, error: "unsafe navigate path" };
+    const here = window.location.pathname + window.location.search + window.location.hash;
+    const target = new URL(path, window.location.href);
+    if (target.pathname + target.search + target.hash === here) return { ok: true, note: "already on this page" };
+    return { ok: true, [AFTER_RESULT]: () => window.location.assign(path) };
+  },
+  openUrl: (args) => {
+    const url = String(args.url ?? "");
+    if (!isSafeHttpUrl(url)) return { ok: false, error: "unsafe url" };
+    const sameHost = new URL(url, window.location.origin).hostname === window.location.hostname;
+    window.open(url, sameHost ? "_self" : "_blank", "noopener,noreferrer");
+    return { ok: true };
+  }
+};
 function createChatClient(options) {
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
   const ES = options.eventSource ?? globalThis.EventSource;
@@ -422,6 +459,23 @@ function createChatClient(options) {
     } catch {
     }
   };
+  const callsKey = `oyehello-chat-calls:${options.agentId}`;
+  const handledCallIds = () => {
+    try {
+      const raw = store2?.getItem(callsKey);
+      const v = raw ? JSON.parse(raw) : null;
+      return v && session && v.sessionId === session.sessionId && Array.isArray(v.ids) ? v.ids : [];
+    } catch {
+      return [];
+    }
+  };
+  const rememberHandledCall = (callId) => {
+    if (!session) return;
+    try {
+      store2?.setItem(callsKey, JSON.stringify({ sessionId: session.sessionId, ids: [...handledCallIds(), callId].slice(-50) }));
+    } catch {
+    }
+  };
   const emit = (e) => {
     for (const l of listeners) l(e);
   };
@@ -470,9 +524,10 @@ function createChatClient(options) {
     } else if (ev.type === "error") {
       emit({ type: "error", error: new Error(ev.message) });
     } else if (ev.type === "tool_call") {
-      if (seenCallIds.has(ev.callId)) return;
+      if (seenCallIds.has(ev.callId) || handledCallIds().includes(ev.callId)) return;
       seenCallIds.add(ev.callId);
-      const handler = toolHandlers.get(ev.name);
+      rememberHandledCall(ev.callId);
+      const handler = toolHandlers.get(ev.name) ?? BUILTIN_TOOL_HANDLERS[ev.name];
       void (async () => {
         if (!session) return;
         const base = { baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, callId: ev.callId, fetchImpl };
@@ -481,8 +536,16 @@ function createChatClient(options) {
           return;
         }
         try {
-          const out = await handler(ev.args);
+          const raw = await handler(ev.args);
+          let after = null;
+          let out = raw;
+          if (raw && typeof raw === "object" && typeof raw[AFTER_RESULT] === "function") {
+            const { [AFTER_RESULT]: run, ...rest } = raw;
+            after = run;
+            out = rest;
+          }
           await postToolResult({ ...base, ok: true, result: typeof out === "string" ? out : JSON.stringify(out ?? { ok: true }) });
+          after?.();
         } catch (err) {
           await postToolResult({ ...base, ok: false, result: err.message });
         }
@@ -564,13 +627,24 @@ function createChatClient(options) {
     if (resumed) {
       session = resumed;
       emit({ type: "agent", agent: resumed.agent });
+      try {
+        const history2 = await getHistory({ baseUrl: options.baseUrl, sessionId: resumed.sessionId, sessionToken: resumed.sessionToken, fetchImpl });
+        for (const h of history2) {
+          const turnId = h.role === "assistant" || h.role === "human" ? h.turnId : void 0;
+          messages.push({ id: uid("m"), role: h.role, text: h.text, streaming: false, turnId });
+          if (h.turnId) seenTurnIds.add(h.turnId);
+        }
+        emitMessages();
+      } catch {
+      }
       await openStream();
       scheduleRefresh();
       flushJourney();
       return;
     }
     if (deviceFingerprint === void 0) deviceFingerprint = await computeDeviceFingerprint().catch(() => null);
-    session = await openSession({ baseUrl: options.baseUrl, apiKey: options.apiKey, agentId: options.agentId, user: options.user, clientTools: Array.from(toolHandlers.keys()), fingerprint: deviceFingerprint ?? void 0, fetchImpl });
+    const advertisedTools = /* @__PURE__ */ new Set([...toolHandlers.keys(), ...Object.keys(BUILTIN_TOOL_HANDLERS)]);
+    session = await openSession({ baseUrl: options.baseUrl, apiKey: options.apiKey, agentId: options.agentId, user: options.user, clientTools: Array.from(advertisedTools), fingerprint: deviceFingerprint ?? void 0, fetchImpl });
     persistSession(session);
     if (!warnedProtocol && typeof session.protocol === "number" && session.protocol !== CHAT_PROTOCOL_VERSION) {
       warnedProtocol = true;
@@ -703,6 +777,44 @@ function createChatClient(options) {
     }
   };
 }
+
+// src/page-theme.ts
+var WATCHED = ["class", "data-theme", "data-mode", "style"];
+function themeOf(node) {
+  for (const attr of ["data-theme", "data-mode"]) {
+    const v = node.getAttribute(attr);
+    if (v === "dark" || v === "light") return v;
+  }
+  if (node.classList.contains("dark")) return "dark";
+  if (node.classList.contains("light")) return "light";
+  return null;
+}
+function resolvePageTheme(el) {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    const t = themeOf(node);
+    if (t) return t;
+  }
+  const scheme = (document.documentElement.style.colorScheme || getComputedStyle(document.documentElement).colorScheme || "").trim();
+  return scheme === "dark" || scheme === "light" ? scheme : null;
+}
+function watchPageTheme(el, onChange) {
+  let last;
+  const check = () => {
+    const t = resolvePageTheme(el);
+    if (t !== last) {
+      last = t;
+      onChange(t);
+    }
+  };
+  check();
+  if (typeof MutationObserver === "undefined") return () => {
+  };
+  const mo = new MutationObserver(check);
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    mo.observe(node, { attributes: true, attributeFilter: WATCHED });
+  }
+  return () => mo.disconnect();
+}
 marked.marked.setOptions({ gfm: true, breaks: true });
 var hookInstalled = false;
 function installLinkHook() {
@@ -785,11 +897,15 @@ var STYLES = `
      * body children (oyehello-chat { display:none }) can't silently kill the widget. Also pinned
      * inline with !important at mount (see element.ts) to beat an external !important rule. */
     display: block; visibility: visible; opacity: 1;
+    /* The closed panel still takes up its full size in the layout (it fades, it is not removed), so
+     * the host box covers ~384x620px of the page. The host and its wrapper must not catch clicks;
+     * only the visible parts opt back in (launcher, teaser while shown, panel while open). */
+    pointer-events: none;
     font-family: 'Geist', system-ui, -apple-system, 'Helvetica Neue', sans-serif;
     -webkit-font-smoothing: antialiased;
   }
   @media (prefers-color-scheme: dark) {
-    :host(:not([theme="light"])) {
+    :host(:not([theme="light"]):not([data-oc-page-theme="light"])) {
       --oc-bg: #000000; --oc-bg-sunk: #000000;
       --oc-fg: #FFFFFF; --oc-fg-muted: rgba(255,255,255,0.68); --oc-fg-dim: rgba(255,255,255,0.42);
       --oc-border: rgba(255,255,255,0.09);
@@ -799,7 +915,9 @@ var STYLES = `
       --oc-glass-border: rgba(255,255,255,0.12);
     }
   }
-  :host([theme="dark"]) {
+  /* Explicit dark, or auto on a page that declares dark (data-oc-page-theme, set by page-theme.ts). The OS rule above
+   * only applies when the page declares nothing; a page that declares light keeps the light base. */
+  :host([theme="dark"]), :host(:not([theme="light"])[data-oc-page-theme="dark"]) {
     --oc-bg: #000000; --oc-bg-sunk: #000000;
     --oc-fg: #FFFFFF; --oc-fg-muted: rgba(255,255,255,0.68); --oc-fg-dim: rgba(255,255,255,0.42);
     --oc-border: rgba(255,255,255,0.09);
@@ -811,7 +929,7 @@ var STYLES = `
   * { box-sizing: border-box; }
   button { font-family: inherit; }
 
-  .oc { display: flex; flex-direction: column; align-items: flex-end; gap: 14px; }
+  .oc { display: flex; flex-direction: column; align-items: flex-end; gap: 14px; pointer-events: none; }
 
   /* \u2500\u2500 Launcher \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
   .launcher {
@@ -820,6 +938,7 @@ var STYLES = `
     box-shadow: 0 8px 22px -8px color-mix(in oklab, var(--oc-ac) 70%, transparent), 0 18px 48px -18px rgba(0,0,0,0.6);
     color: #fff; display: flex; align-items: center; justify-content: center; cursor: pointer;
     transition: transform .26s var(--oc-bounce), filter .2s var(--oc-ease); align-self: flex-end;
+    pointer-events: auto;
   }
   .launcher:hover { transform: scale(1.06); }
   .launcher:active { transform: scale(0.93); }
@@ -1187,6 +1306,7 @@ var OyehelloChatElement = class extends HTMLElement {
   // Uninstaller for the SPA history-navigation hooks (journey tracking), installed in
   // connectedCallback and torn down in disconnectedCallback alongside everything else.
   uninstallSpaHooks = null;
+  unwatchPageTheme = null;
   // ── shadow refs ──
   oc;
   bodyEl;
@@ -1220,6 +1340,11 @@ var OyehelloChatElement = class extends HTMLElement {
       this.uninstallSpaHooks = null;
     }
     this.renderShell();
+    this.unwatchPageTheme?.();
+    this.unwatchPageTheme = watchPageTheme(this, (t) => {
+      if (t) this.setAttribute("data-oc-page-theme", t);
+      else this.removeAttribute("data-oc-page-theme");
+    });
     this.style.setProperty("display", "block", "important");
     this.style.setProperty("visibility", "visible", "important");
     this.style.setProperty("opacity", "1", "important");
@@ -1330,6 +1455,8 @@ var OyehelloChatElement = class extends HTMLElement {
     this.teardownIdle();
     this.uninstallSpaHooks?.();
     this.uninstallSpaHooks = null;
+    this.unwatchPageTheme?.();
+    this.unwatchPageTheme = null;
     for (const t of this.timers) clearTimeout(t);
     for (const url of this.imagePreviewCache.values()) {
       if (typeof URL.revokeObjectURL === "function") URL.revokeObjectURL(url);
@@ -1340,6 +1467,11 @@ var OyehelloChatElement = class extends HTMLElement {
     if (this.client) this.client.registerTools(handlers);
     else Object.assign(this.pendingTools, handlers);
   }
+  /** Open the chat window, exactly as a launcher click does. No-op if already open or not rendered. */
+  open() {
+    if (!this.oc || this.uiOpen) return;
+    this.openPanel();
+  }
   key(k) {
     return `oyehello-chat:${k}:${this.getAttribute("agent-id") ?? ""}`;
   }