ttp-agent-sdk 2.45.4 → 2.45.7

package/dist/index.html

@@ -56,6 +56,8 @@
             <li><a href="#vanilla-js" class="nav-link">Vanilla JavaScript</a></li>
             <li><a href="#react" class="nav-link">React Integration</a></li>
             <li><a href="#voice-button" class="nav-link">VoiceButton Component</a></li>
+            <li><a href="#client-script-tools" class="nav-link">Client-Script Tools</a></li>
+            <li><a href="#chain-tools" class="nav-link">Chain Tools</a></li>
           </ul>
         </div>
 
@@ -2642,6 +2644,154 @@ function App() {
           </table>
         </section>
 
+        <!-- Client-Script Tools -->
+        <section id="client-script-tools" class="doc-section">
+          <h1>Client-Script Tools</h1>
+          <p>Client-script tools let you attach <strong>backend-authored JavaScript</strong> to a client tool (<code>tool_type: 'client'</code>) that runs in the visitor's browser when the LLM calls the tool — <strong>no host-page <code>registerToolHandler()</code> code required</strong>. The script is configured in the dashboard (tool form → "Agent scripts"), stored with the tool, and delivered to the widget automatically at session start. Available since SDK <strong>v2.45.3</strong>.</p>
+
+          <div class="info-box">
+            <strong>When to use which:</strong> use <code>registerToolHandler()</code> when the host page owns the logic and ships its own JS. Use a client-script tool when the agent owner wants browser-side behavior (DOM reads, page API calls, UI nudges) configurable from the dashboard without touching the embedding site.
+          </div>
+
+          <h2>How it works</h2>
+          <ol>
+            <li><strong>Session init</strong> — the backend pushes a <code>partner_bundle</code> message with the reserved partner id <code>__client_tools__</code>, carrying every scripted tool attached to the agent (plus auto-run library scripts). The bundle is pushed on both the voice and text-chat channels, works with or without a widget flavor, and is re-pushed on reconnect (a new bundle replaces the previous one).</li>
+            <li><strong>Compile on load</strong> — each entry compiles into a strict-mode async function immediately when the bundle lands. A syntax error poisons only that entry (logged at load time); the rest of the bundle still works.</li>
+            <li><strong>Invocation</strong> — when the LLM calls the tool, the SDK runs the compiled script and returns its result to the backend.</li>
+            <li><strong>Auto-run</strong> — library scripts flagged <code>auto_run</code> execute exactly once when the bundle arrives (e.g. to set up page listeners).</li>
+          </ol>
+
+          <h2>Authoring styles</h2>
+          <p>Two styles compile — the SDK detects the shape and picks the right wrapping:</p>
+          <pre><code>// 1. Raw statement body (typical in the dashboard UI; `ctx` is in scope)
+alert("hi");
+return { ok: true, clicked: true };
+
+// 2. Function expression
+async (ctx) => {
+  const res = await ctx.fetch('/api/something');
+  return { ok: true, data: await res.json() };
+}</code></pre>
+          <p>Both run inside an async function, so <code>await</code> is always allowed. A script that returns nothing resolves to <code>{ ok: true }</code>.</p>
+
+          <h2>The <code>ctx</code> object</h2>
+          <table class="properties-table">
+            <thead>
+              <tr><th>Property</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>ctx.args</code></td><td>Parameters from the LLM tool call.</td></tr>
+              <tr><td><code>ctx.host</code></td><td><code>window.location.hostname</code>.</td></tr>
+              <tr><td><code>ctx.fetch</code></td><td>Bound <code>window.fetch</code>.</td></tr>
+              <tr><td><code>ctx.log(...)</code></td><td><code>console.log</code> prefixed with <code>[adapter:&lt;tool&gt;]</code>.</td></tr>
+              <tr><td><code>ctx.runAdapter(action, args)</code></td><td>Invoke another script in the same bundle (max nesting depth 16).</td></tr>
+              <tr><td><code>ctx.emit(msg)</code></td><td>Send an unsolicited JSON message back to the backend over the active channel.</td></tr>
+            </tbody>
+          </table>
+          <p>Client-tool scripts run with a <strong>generic context</strong> — the ecommerce-only helpers (<code>ctx.platform</code>, <code>ctx.normalizeCart</code>, <code>ctx.refreshUI</code>) are not available; those exist only in ecommerce partner-adapter bundles.</p>
+
+          <h2>Pre / main / post steps</h2>
+          <p>A scripted tool may carry up to three steps, executed in order: <strong>pre → main → post</strong>.</p>
+          <ul>
+            <li><strong>Pre</strong> is best-effort — if it throws, the error is logged and main still runs.</li>
+            <li><strong>Main</strong> produces the tool result. A thrown error becomes an <code>ok: false</code> result.</li>
+            <li><strong>Post</strong> runs only when main succeeded; its <code>ctx.args._mainResult</code> holds main's return value.</li>
+          </ul>
+
+          <h2>Sync vs async results</h2>
+          <p>Configured per tool in the dashboard ("Wait for result"):</p>
+          <table class="properties-table">
+            <thead>
+              <tr><th>Mode</th><th>Behavior</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><strong>Wait ON</strong> (sync)</td><td>The backend awaits the script result up to <code>timeoutMs</code> (1000–15000 ms, default 8000) and feeds it to the LLM as the tool result.</td></tr>
+              <tr><td><strong>Wait OFF</strong> (async)</td><td>The LLM immediately receives the configured pending message; the real result is injected later: <code>SPOKEN_EVENT</code> (spoken immediately), <code>SPOKEN_DEFERRED</code> (next natural turn, default), or <code>SILENT_CONTEXT</code> (silent context update).</td></tr>
+            </tbody>
+          </table>
+
+          <h2>Limits</h2>
+          <table class="properties-table">
+            <thead>
+              <tr><th>Limit</th><th>Value</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>Per-step code size</td><td>32 KB</td></tr>
+              <tr><td>Result size</td><td>50 KB serialized (oversize → <code>ok: false, error: "RESULT_TOO_LARGE"</code>)</td></tr>
+              <tr><td>Sync timeout</td><td>1000–15000 ms (default 8000)</td></tr>
+              <tr><td>Pending message</td><td>500 chars</td></tr>
+            </tbody>
+          </table>
+
+          <h2>Wire protocol (reference)</h2>
+          <p>Script invocations arrive on two wire forms, both handled by the SDK on both channels:</p>
+          <pre><code>// Bundle (session init / reconnect)
+{ "t": "partner_bundle", "partner_id": "__client_tools__",
+  "adapters": { "my_tool": { "code_js": "...", "pre_code_js": "...", "post_code_js": "..." } },
+  "autoRun":  { "my_script": { "code_js": "..." } } }
+
+// Form A — dedicated envelope (async path / chain steps)
+→ { "t": "run_partner_script", "requestId": "...", "partnerId": "__client_tools__",
+    "action": "my_tool", "args": { ... } }
+← { "t": "run_partner_script_result", "requestId": "...", "ok": true, "result": { ... } }
+
+// Form B — client_tool_call piggyback (backend sync-await path)
+→ { "t": "client_tool_call", "toolCallId": "...", "toolName": "run_partner_script",
+    "parameters": { "action": "my_tool", "args": { ... }, "partner_id": "__client_tools__" } }
+← { "t": "client_tool_result", "toolCallId": "...", "result": { ... } }</code></pre>
+          <p>Routing rule: <code>partner_id === '__client_tools__'</code> → the flavor-independent <code>ClientScriptManager</code>; any other partner id → the ecommerce flavor's partner-adapter path. The two bundles coexist.</p>
+
+          <h2>Troubleshooting</h2>
+          <table class="properties-table">
+            <thead>
+              <tr><th>Symptom</th><th>Cause / fix</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>compile failed ... SyntaxError</code> at bundle load</td><td>Script doesn't parse. On SDK &lt; 2.45.1, raw statement bodies (e.g. <code>alert("stop");</code>) failed even when valid — check the SDK version banner in the console and hard-refresh if stale.</td></tr>
+              <tr><td><code>NO_HANDLER</code> for <code>run_partner_script</code></td><td>SDK &lt; 2.45.3 didn't route the <code>client_tool_call</code> piggyback form without an ecommerce flavor. Fixed in 2.45.3.</td></tr>
+              <tr><td><code>adapter_not_in_bundle</code></td><td>Tool not attached to the agent, or the bundle hasn't arrived yet. Check the session-start <code>partner_bundle</code> log.</td></tr>
+              <tr><td>Sync result is a timeout</td><td>Script exceeded <code>timeoutMs</code>. Raise it (max 15 s) or switch to async delivery.</td></tr>
+            </tbody>
+          </table>
+          <p>For the full internals reference see <code>CLIENT_SCRIPT_TOOLS_GUIDE.md</code> in the repository root.</p>
+        </section>
+
+        <!-- Chain Tools -->
+        <section id="chain-tools" class="doc-section">
+          <h1>Chain Tools</h1>
+          <p>A chain tool (<code>tool_type: 'chain'</code>) runs a <strong>graph of steps</strong> — server tools, client tools, agent switches, and library scripts — as a single LLM tool call. Chains are edited visually in the dashboard (Chain Editor: nodes are steps, edges are data-flow dependencies) and executed by the backend; the widget participates only when a step targets the browser.</p>
+
+          <h2>Execution model</h2>
+          <ul>
+            <li>Steps with no dependencies run first; steps at the same level run <strong>in parallel</strong>; levels run sequentially.</li>
+            <li>A step's <code>input_from</code> lists the upstream steps whose outputs feed it. Dependent steps receive the original LLM arguments shallow-merged with each upstream result (a non-object result lands under the upstream step's id).</li>
+            <li><strong>Fail-fast</strong>: the first failing step aborts the chain with <code>{ "success": false, "error": ..., "step": ... }</code>.</li>
+            <li>The LLM receives the terminal step's result (multiple terminals merge keyed by step id).</li>
+            <li>Inside a chain, every step is awaited — a referenced client tool's own "wait for result = off" setting is ignored.</li>
+          </ul>
+
+          <h2>Step types and the widget</h2>
+          <table class="properties-table">
+            <thead>
+              <tr><th>Step type</th><th>Runs where</th><th>Widget involvement</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>server_tool</code></td><td>Backend (webhook)</td><td>None.</td></tr>
+              <tr><td><code>switch_agent</code></td><td>Backend</td><td>None.</td></tr>
+              <tr><td><code>client_tool</code> (plain)</td><td>Browser</td><td>Arrives as a normal <code>client_tool_call</code> → your <code>registerToolHandler()</code> handler.</td></tr>
+              <tr><td><code>client_tool</code> (scripted)</td><td>Browser</td><td>Dispatched as a <code>__client_tools__</code> bundle action keyed by <strong>tool name</strong>.</td></tr>
+              <tr><td><code>client_script</code> (library)</td><td>Browser</td><td>Dispatched as a <code>__client_tools__</code> bundle action keyed by <code>script:{scriptId}</code>.</td></tr>
+            </tbody>
+          </table>
+          <p>Scripts and scripted client tools referenced by a chain are resolved into the session bundle automatically — they do <strong>not</strong> need to be attached to the agent.</p>
+
+          <h2>Constraints</h2>
+          <ul>
+            <li>1–30 steps per chain; no cycles; chains cannot reference other chain tools (no recursion).</li>
+            <li>Deleting a tool or library script that a chain references is blocked in the dashboard (the delete dialog lists the referencing chains).</li>
+          </ul>
+        </section>
+
         <!-- VoiceSDK API -->
         <section id="voicesdk" class="doc-section">
           <h1>VoiceSDK Class</h1>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttp-agent-sdk",
-  "version": "2.45.4",
+  "version": "2.45.7",
   "description": "Comprehensive Voice Agent SDK with Customizable Widget - Real-time audio, WebSocket communication, React components, and extensive customization options",
   "main": "dist/agent-widget.js",
   "module": "dist/agent-widget.esm.js",