@oyehello/chat 0.5.1 → 0.5.2

package/README.md

@@ -74,23 +74,33 @@ 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)`; `openUrl` calls `window.open(url, '_blank')`
+(pass `newTab: false` from the agent to open in the same tab instead).
+
+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

@@ -314,6 +314,29 @@ 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 BUILTIN_TOOL_HANDLERS = {
+  navigate: (args) => {
+    const path = String(args.path ?? "");
+    if (!isSafeRelativePath(path)) return { ok: false, error: "unsafe navigate path" };
+    window.location.assign(path);
+    return { ok: true };
+  },
+  openUrl: (args) => {
+    const url = String(args.url ?? "");
+    if (!isSafeHttpUrl(url)) return { ok: false, error: "unsafe url" };
+    window.open(url, args.newTab === false ? "_self" : "_blank", "noopener,noreferrer");
+    return { ok: true };
+  }
+};
 function createChatClient(options) {
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
   const ES = options.eventSource ?? globalThis.EventSource;
@@ -472,7 +495,7 @@ function createChatClient(options) {
     } else if (ev.type === "tool_call") {
       if (seenCallIds.has(ev.callId)) return;
       seenCallIds.add(ev.callId);
-      const handler = toolHandlers.get(ev.name);
+      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 };
@@ -570,7 +593,8 @@ function createChatClient(options) {
       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;