@useago/sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,97 +1,115 @@
 # @useago/sdk
 
 [![npm version](https://img.shields.io/npm/v/@useago/sdk.svg)](https://www.npmjs.com/package/@useago/sdk)
-[![license](https://img.shields.io/npm/l/@useago/sdk.svg)](./LICENSE)
 [![types](https://img.shields.io/npm/types/@useago/sdk.svg)](https://www.npmjs.com/package/@useago/sdk)
 
-Official JavaScript/TypeScript SDK for [AGO](https://useago.com) — embed AGO's AI
-agents directly inside your own app. Stream answers, let the agent call **your**
-client-side functions, navigate users around your UI, and feed it live context
-about what the user is doing.
+**The agent layer for your frontend stack.** AGO's agents plug into React, Vue,
+Angular or plain TypeScript like any other dependency: send a message, stream
+the reply, and let the agent call **your** code and navigate **your** UI.
 
-Works with **plain JS/TS, React, Vue and Angular**. The core is framework-agnostic;
-each framework gets idiomatic bindings (hooks, composables, services) on top of the
-same `AgoClient`.
+In two minutes you'll have a working chat on your page and an agent that can
+navigate your app. The quickstart below uses **React**; every other stack gets
+the same two steps through its own guide:
+
+| Stack | Guide |
+| --- | --- |
+| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/react/react-original.svg" width="14" /> React | **you're reading it**, just scroll down |
+| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/vuejs/vuejs-original.svg" width="14" /> Vue 3 | [Vue guide](docs/frameworks/vue.md) |
+| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/angular/angular-original.svg" width="14" /> Angular | [Angular guide](docs/frameworks/angular.md) |
+| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/typescript/typescript-original.svg" width="14" /> Plain JavaScript / TypeScript | [Core guide](docs/general/core.md) |
+| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/html5/html5-original.svg" width="14" /> Any website, no build step (`<script>`) | [Widget guide](docs/general/widget.md) |
+
+## <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/react/react-original.svg" width="22" /> Try it in 30 seconds
 
 ```bash
 npm install @useago/sdk
 ```
 
-📚 **Full documentation:** [docs.useago.com](https://docs.useago.com) · the
-framework guides below are also published there.
+The SDK has no framework dependency of its own. The React bindings need `react`
+and `react-dom` (>=17): already there in an existing React app, otherwise
+install them too.
+
+```tsx
+// App.tsx
+import { AgoProvider, ChatWidget } from "@useago/sdk/react";
+
+export default function App() {
+  return (
+    <AgoProvider baseUrl="https://ago.api.useago.com" agent="generic-guide">
+      <ChatWidget title="AGO" welcomeMessage="Ask me anything!" height={500} />
+    </AgoProvider>
+  );
+}
+```
 
----
+Start your dev server. A chat panel renders on the page; type a message and
+watch the reply stream in. That's a complete integration. (`generic-guide` is a
+public demo agent; swap `baseUrl` and `agent` for your own once you have a tenant.)
 
-## Quick start
+## Let the agent drive your existing routes
 
-Pick your stack — each guide is self-contained.
+This is the part existing apps care about. You already have a router and pages;
+describe them to the agent and *"show me my invoices"* actually navigates there.
+One hook in the layout you already have, nothing to restructure:
 
-| Stack | Guide |
-| --- | --- |
-| Plain JavaScript / TypeScript | [docs/general/core.md](docs/general/core.md) |
-| React | [docs/frameworks/react.md](docs/frameworks/react.md) |
-| Vue 3 | [docs/frameworks/vue.md](docs/frameworks/vue.md) |
-| Angular | [docs/frameworks/angular.md](docs/frameworks/angular.md) |
-| Embeddable widget (`<script>`) | [docs/general/widget.md](docs/general/widget.md) |
+```tsx
+import { Outlet, useNavigate } from "react-router-dom";
+import { useAgoNavigation } from "@useago/sdk/react";
 
-Cross-cutting topics (apply to every framework):
+// Your existing layout component. Only the hook is new.
+function AppLayout() {
+  const navigate = useNavigate();
 
-- [**Client-side functions & helpers**](docs/general/functions-and-context.md#client-side-functions) — let the agent run code in the browser
-- [**Client context**](docs/general/functions-and-context.md#client-context) — tell the agent what the user is looking at
-- [**Events & streaming**](docs/general/events-and-streaming.md) — low-level hooks into the message stream
-- [**Testing**](docs/general/testing.md) — a mock client for unit tests
-- [**Configuration & auth**](docs/general/configuration.md) — every `AgoConfig` option, headers, errors
+  useAgoNavigation(navigate, [
+    { name: "dashboard", path: "/dashboard", description: "KPIs and recent activity" },
+    { name: "invoices", path: "/invoices", description: "List, search and download invoices" },
+    { name: "settings", path: "/settings", description: "Account, billing and team settings" },
+  ]);
 
-The 30-second version (vanilla):
+  return <Outlet />; // your existing routes render as before
+}
+```
 
-```ts
-import { AgoClient } from "@useago/sdk";
+Each route needs a `name`, its existing `path`, and a `description` the agent
+uses to pick the right page. It calls **your** `navigate` function, so route
+guards, auth and layouts keep working exactly as they do today.
+`react-router-dom` here is *your* router, not an SDK dependency:
+`useAgoNavigation` accepts any `(path: string) => void` function.
 
-const ago = new AgoClient({ baseUrl: "https://YOUR-DOMAIN.useago.com" });
+**Next: the [Getting started guide](docs/general/getting-started.md)** has both
+examples assembled into a running app, plus everything else the SDK can do, in
+about 5 minutes.
 
-ago.on("message:chunk", ({ content }) => process.stdout.write(content));
+## Or clone a running example
 
-const reply = await ago.sendMessage("What can you do?");
-console.log("\nDone:", reply.status);
+```bash
+git clone https://github.com/useago/ago-sdk.git
+cd ago-sdk && npm install && npm run build   # build the SDK once
+cd examples/simple-react
+npm install && npm run dev
 ```
 
+The examples ship pre-configured against the demo backend, so they answer
+immediately. [`examples/`](examples/) has one per stack: React (with
+react-router navigation), Vue, Angular, plain TypeScript, and no-build HTML.
+
 ---
 
-## Feature matrix
-
-What ships out of the box for each entry point. The **core** (`@useago/sdk`)
-APIs are usable from *any* framework — the framework columns mark where a more
-idiomatic binding (hook / composable / service / component) is also provided.
-
-| Feature | Core (vanilla) | React | Vue | Angular |
-| --- | :---: | :---: | :---: | :---: |
-| Create client | `new AgoClient()` | `useAgo` / `<AgoProvider>` | `AgoPlugin` / `useAgo` | `provideAgo` / `AgoService` |
-| Zero-config auto-detect | ✅ `createAgo()` | ✅ | ✅ | ✅ |
-| Send message (streaming) | ✅ | ✅ `useChat`/`useMessages` | ✅ `useChat`/`useMessages` | ✅ `AgoService.sendMessage` |
-| File attachments | ✅ | ✅ | ✅ | ✅ |
-| List / load conversations | ✅ | ✅ `useConversation` | ✅ `useConversation` | ✅ `AgoService` |
-| All-in-one chat state | — | ✅ `useChat` | ✅ `useChat` | ➖ compose manually |
-| Pre-built `<ChatWidget>` UI | — | ✅ | ➖ see example | — |
-| Markdown / `<Message>` / `<ChatInput>` | — | ✅ | — | — |
-| Client-side functions | ✅ `registerFunction` | ✅ `useAgoFunction` | ✅ `useAgoFunction` | ✅ `AgoService` |
-| `defineFunction` / `withHandler` | ✅ | ✅ | ✅ | ✅ |
-| Pre-built helpers (`showToast`, …) | ✅ | ✅ `helpers` prop | ✅ | ✅ |
-| Navigation function | ✅ `registerNavigationFunction` | ✅ `useAgoNavigation` | ✅ `useAgoNavigation` | ✅ `AgoService` |
-| Client context | ✅ `setContext` / `addDynamicContext` | ✅ `useAgoContext` | ✅ core API | ✅ core API |
-| Auto page context | ✅ `enableAutoPageContext()` | ✅ `pageContext="auto"` | ✅ core API | ✅ core API |
-| Events (`on`/`off`/`once`/`waitFor`) | ✅ | ✅ (via client) | ✅ `useAgoEvents` | ✅ `messages$` Observables |
-| Streaming helpers / async generator | ✅ | ✅ | ✅ | ✅ |
-| Tool calls (form/confirm/reject) | ✅ | ✅ | ✅ | ✅ `AgoService` |
-| Message feedback | ✅ `submitFeedback` | ✅ | ✅ | ✅ `AgoService` |
-| Observable store | ✅ `createStore` | ✅ `useAgoStore` | ✅ `useAgoStore` | ➖ core API |
-| Dev panel / devtools | ✅ `initDevPanel` (`/devtools`) | ✅ | ✅ | ✅ |
-| Testing mock client | ✅ `createMockClient` | ✅ | ✅ | ✅ |
-
-Legend: ✅ first-class binding · ➖ supported via the core API, no dedicated sugar · — not applicable.
+## Docs
+
+- [**Getting started**](docs/general/getting-started.md): send a message, wire the router, see the feature map
+- [**Feature matrix**](docs/general/feature-matrix.md): everything that ships, per stack
+- [**Functions & context**](docs/general/functions-and-context.md): let the agent run your code and see what the user sees
+- [**Events & streaming**](docs/general/events-and-streaming.md): low-level hooks into the message stream
+- [**Testing**](docs/general/testing.md): mock client for unit tests
+- [**Configuration & auth**](docs/general/configuration.md): every `AgoConfig` option, headers, errors
+
+Full documentation: [ago.mintlify.app](https://ago.mintlify.app/)
 
 ---
 
-## Package entry points
+<details>
+<summary><strong>Package entry points</strong> (subpath exports)</summary>
 
 The package is published with several subpath exports so bundlers only pull in
 what you use:
@@ -104,20 +122,31 @@ what you use:
 | `@useago/sdk/angular` | Angular service and provider |
 | `@useago/sdk/helpers` | Pre-built client functions only |
 | `@useago/sdk/widget` | `window.AGO` widget config types |
-| `@useago/sdk/devtools` | `initDevPanel` — in-browser debug overlay (DOM/CSS) |
-| `@useago/sdk/testing` | `createMockClient` — mock client for tests |
+| `@useago/sdk/devtools` | `initDevPanel`, an in-browser debug overlay (DOM/CSS) |
+| `@useago/sdk/testing` | `createMockClient`, a mock client for tests |
 
 ESM and CJS builds are both shipped, with full TypeScript declarations.
 
----
+</details>
 
-## Requirements
+## Dependencies
 
-- A modern browser environment (uses `fetch` + `ReadableStream` for SSE) or Node 18+.
-- `react` / `react-dom` `>=17` for the React bindings (peer dependency, optional).
-- `vue` `>=3.3` for the Vue bindings (peer dependency, optional).
-- Angular bindings have **no** hard Angular dependency — they work with any DI container.
+The core SDK depends on nothing but the platform: `fetch` and `ReadableStream`,
+so any modern browser or Node 18+. Framework packages are **optional peer
+dependencies**; you only need the one whose bindings you import:
+
+| You import | Needs | Notes |
+| --- | --- | --- |
+| `@useago/sdk` (core, widget, helpers, testing) | nothing | works everywhere |
+| `@useago/sdk/react` | `react` + `react-dom` `>=17` | already present in any React app |
+| `@useago/sdk/vue` | `vue` `>=3.3` | already present in any Vue 3 app |
+| `@useago/sdk/angular` | nothing | no hard Angular dependency, works with any DI container |
+
+Your router (`react-router-dom`, `vue-router`, Angular Router) is **never** an
+SDK dependency: the navigation helpers just take your navigate function.
+
+---
 
 ## License
 
-[Apache 2.0](./LICENSE) · [Documentation](https://docs.useago.com) · [Website](https://useago.com)
+[Apache 2.0](./LICENSE) · [Documentation](https://ago.mintlify.app/) · [Website](https://useago.com)

package/dist/{AgoClient-CPqPT5s6.cjs → AgoClient-0x2Du_62.cjs}

@@ -1,6 +1,6 @@
 var u=class extends Error{constructor(e,t,s){super(e),this.code=t,this.statusCode=s,this.name="AgoError"}},h=class p extends u{constructor(t,s,r,n,o,a){super(t,s,r),this.type=n,this.param=o,this.docUrl=a,this.name="AgoApiError"}static fromResponse(t,s){const r=t.error;return new p(r.message,r.code,s,r.type,r.param,r.doc_url)}},d=class extends u{constructor(e,t){super(e,"network_error"),this.originalError=t,this.name="AgoNetworkError"}},g=class extends u{constructor(e){super(e,"stream_error"),this.name="AgoStreamError"}},m=class extends u{constructor(e,t,s){super(e,"function_error"),this.functionName=t,this.originalError=s,this.name="AgoFunctionError"}},_=class{constructor(e=!1){this.enabled=e}enable(){this.enabled=!0}disable(){this.enabled=!1}log(...e){this.enabled&&console.log("[AGO SDK]",...e)}warn(...e){this.enabled&&console.warn("[AGO SDK]",...e)}error(...e){console.error("[AGO SDK]",...e)}debug(...e){this.enabled&&console.debug("[AGO SDK]",...e)}},i=new _,f="ago_widget_id";function S(){if(typeof localStorage<"u"){const t=localStorage.getItem(f);if(t)return t}const e=crypto.randomUUID();if(typeof localStorage<"u")try{localStorage.setItem(f,e)}catch{}return e}var k=class{constructor(e){this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"X-Widget-Id":e.widgetId||S()},e.userEmail&&(this.headers["X-User-Email"]=e.userEmail),e.userJwt&&(this.headers.Authorization=`Bearer ${e.userJwt}`),e.permission&&(this.headers["X-Widget-Permission"]=e.permission)}updateConfig(e){e.baseUrl&&(this.baseUrl=e.baseUrl.replace(/\/$/,"")),e.widgetId&&(this.headers["X-Widget-Id"]=e.widgetId),e.userEmail&&(this.headers["X-User-Email"]=e.userEmail),e.userJwt&&(this.headers.Authorization=`Bearer ${e.userJwt}`),e.permission!==void 0&&(e.permission?this.headers["X-Widget-Permission"]=e.permission:delete this.headers["X-Widget-Permission"])}async get(e){return this.request("GET",e)}async post(e,t){return this.request("POST",e,t)}async postStream(e,t){const s=`${this.baseUrl}${e}`;i.debug("POST (stream)",s,t);try{const r=await fetch(s,{method:"POST",headers:{...this.headers,"Content-Type":"application/json"},body:t?JSON.stringify(t):void 0});return r.ok||await this.handleErrorResponse(r),r}catch(r){throw r instanceof h?r:new d(`Network error: ${r instanceof Error?r.message:"Unknown error"}`,r instanceof Error?r:void 0)}}async postFormData(e,t){const s=`${this.baseUrl}${e}`;i.debug("POST (formData)",s);const r={...this.headers};try{const n=await fetch(s,{method:"POST",headers:r,body:t});return n.ok||await this.handleErrorResponse(n),n}catch(n){throw n instanceof h?n:new d(`Network error: ${n instanceof Error?n.message:"Unknown error"}`,n instanceof Error?n:void 0)}}async request(e,t,s){const r=`${this.baseUrl}${t}`;i.debug(e,r,s);try{const n=await fetch(r,{method:e,headers:{...this.headers,"Content-Type":"application/json"},body:s?JSON.stringify(s):void 0});return n.ok||await this.handleErrorResponse(n),n.status===204?void 0:n.json()}catch(n){throw n instanceof h?n:new d(`Network error: ${n instanceof Error?n.message:"Unknown error"}`,n instanceof Error?n:void 0)}}async handleErrorResponse(e){let t;try{t=await e.json()}catch{}throw t?.error?h.fromResponse(t,e.status):new h(`HTTP ${e.status}: ${e.statusText}`,"http_error",e.status,"api_error")}},y=class{constructor(){this.functions=new Map}register(e,t,s){if(typeof e=="object"){const{name:n,handler:o,description:a,parameters:c}=e;return this.register(n,o,{description:a,parameters:c})}const r=e;if(!t||!s)throw new Error("handler and schema are required");this.functions.has(r)&&i.warn(`Function "${r}" is being overwritten`),this.functions.set(r,{schema:{...s,name:r},handler:t}),i.log(`Registered function: ${r}`)}unregister(e){const t=this.functions.delete(e);return t&&i.log(`Unregistered function: ${e}`),t}get(e){return this.functions.get(e)}has(e){return this.functions.has(e)}getSchemas(){return Array.from(this.functions.values()).map(e=>e.schema)}async execute(e,t){const s=this.functions.get(e);if(!s)throw new m(`Function "${e}" is not registered`,e);i.log(`Executing function: ${e}`,t);try{const r=await s.handler(t);return i.log(`Function ${e} completed:`,r),r}catch(r){throw i.error(`Function ${e} failed:`,r),new m(`Function "${e}" execution failed: ${r instanceof Error?r.message:"Unknown error"}`,e,r instanceof Error?r:void 0)}}clear(){this.functions.clear(),i.log("Cleared all registered functions")}get size(){return this.functions.size}},w=class{constructor(){this.entries=new Map,this.dynamicProviders=new Map}set(e,t){this.entries.set(e,t),i.log(`ClientContext set: ${e}`)}remove(e){const t=this.entries.delete(e);return t&&i.log(`ClientContext removed: ${e}`),t}addDynamicProvider(e,t){this.dynamicProviders.set(e,t),i.log(`DynamicContext provider added: ${e}`)}removeDynamicProvider(e){const t=this.dynamicProviders.delete(e);return t&&i.log(`DynamicContext provider removed: ${e}`),t}getSnapshot(){if(this.entries.size===0&&this.dynamicProviders.size===0)return null;const e={};for(const[t,s]of this.entries)e[t]=s;for(const[t,s]of this.dynamicProviders)try{const r=s();r&&(e[t]=r)}catch(r){i.error(`DynamicContext provider "${t}" threw:`,r)}return Object.keys(e).length===0?null:{entries:e}}clear(){this.entries.clear(),this.dynamicProviders.clear(),i.log("ClientContext cleared")}},v=class{constructor(e){this.callbacks=e,this.buffer="",this.message={},this.toolCalls=[],this.sources=[],this.followUpReplies=[],this.isFirstChunk=!0,this.answerCompleteEmitted=!1}async processStream(e){if(!e.body)throw new g("Response has no body");const t=e.body.getReader(),s=new TextDecoder;try{for(;;){const{done:r,value:n}=await t.read();if(r)break;const o=s.decode(n,{stream:!0});this.buffer+=o,this.processBuffer()}return this.buffer.trim()&&this.processBuffer(),this.buildFinalMessage()}catch(r){const n=r instanceof Error?r:new g("Stream processing failed");throw this.callbacks.onError?.(n),n}finally{t.releaseLock()}}processBuffer(){const e=this.buffer.split(`
 
 `);this.buffer=e.pop()||"";for(const t of e){if(!t.trim())continue;const s=t.split(`
-`);for(const r of s)if(!r.startsWith(": ")&&r.startsWith("data: ")){const n=r.slice(6);try{const o=JSON.parse(n);this.handleChunk(o)}catch(o){i.warn("Failed to parse SSE data:",n,o)}}}}handleChunk(e){if(e.message_id&&!this.message.id&&(this.message.id=e.message_id),e.thread?.id&&(this.message.conversationId=e.thread.id,this.isFirstChunk&&this.message.id&&(this.isFirstChunk=!1,this.callbacks.onStart?.({conversationId:this.message.conversationId,messageId:this.message.id}))),e.content!==void 0&&(this.message.content=(this.message.content||"")+e.content,this.message.conversationId&&this.message.id&&this.callbacks.onChunk?.({content:e.content,conversationId:this.message.conversationId,messageId:this.message.id})),e.full_content!==void 0&&(this.message.content=e.full_content),e.status&&(this.message.status=e.status),e.agent&&(this.message.agent={id:e.agent.id,name:e.agent.name,displayName:e.agent.display_name}),e.knowledge_sources&&(this.sources=e.knowledge_sources.map(t=>{const s=t.knowledge_document;return{id:s.id,title:s.title,url:s.use_external_link?s.external_link_url:s.internal_link_url}})),e.type==="client_function"&&e.function_name&&this.callbacks.onClientFunction?.({invocationId:e.id||"",functionName:e.function_name,arguments:e.arguments||{},conversationId:this.message.conversationId||""}),e.tool_call_data&&e.type&&e.type!=="client_function"){const t=this.parseToolCall(e);this.callbacks.onToolCall?.(t);const s=this.toolCalls.findIndex(r=>r.id===t.id);s>=0?this.toolCalls[s]=t:this.toolCalls.push(t)}e.follow_up_replies&&(this.followUpReplies=e.follow_up_replies),this.message.status==="DONE"&&!this.answerCompleteEmitted&&this.message.id&&(this.answerCompleteEmitted=!0,this.callbacks.onAnswerComplete?.(this.buildMessage()))}parseToolCall(e){return{id:e.id||"",type:e.type||"status_message",status:e.status||"unknown",toolName:e.tool_name||"",toolDisplayName:e.tool_display_name,message:e.message,formSchema:e.form_schema,data:e.data,functionName:e.function_name,arguments:e.arguments}}buildMessage(){return{id:this.message.id||"",conversationId:this.message.conversationId||"",content:this.message.content||"",role:"assistant",status:this.message.status||"DONE",agent:this.message.agent,sources:this.sources.length>0?this.sources:void 0,toolCalls:this.toolCalls.length>0?this.toolCalls:void 0,followUpReplies:this.followUpReplies.length>0?this.followUpReplies:void 0,createdAt:new Date}}buildFinalMessage(){const e=this.buildMessage();return this.callbacks.onComplete?.(e),e}};function x(e){const t=e.message.toLowerCase();return t.includes("load failed")||t.includes("failed to fetch")||t.includes("network")||t.includes("abort")}var C=class{constructor(){this.handlers=new Map}on(e,t){this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t)}off(e,t){const s=this.handlers.get(e);s&&s.delete(t)}emit(e,t){const s=this.handlers.get(e);s&&s.forEach(r=>{try{r(t)}catch(n){console.error(`Error in event handler for ${String(e)}:`,n)}})}once(e,t){const s=(r=>{this.off(e,s),t(r)});this.on(e,s)}waitFor(e,t){return new Promise((s,r)=>{let n;const o=(a=>{n&&clearTimeout(n),s(a)});this.once(e,o),t?.timeout&&(n=setTimeout(()=>{this.off(e,o),r(new Error(`waitFor("${String(e)}") timed out after ${t.timeout}ms`))},t.timeout))})}removeAllListeners(e){e?this.handlers.delete(e):this.handlers.clear()}},A=class b{constructor(t){this.config=t,this.httpClient=new k(t),this.functionRegistry=new y,this.contextRegistry=new w,this.eventEmitter=new C,t.debug&&i.enable(),i.log("AgoClient initialized")}async sendMessage(t,s){const r=this.functionRegistry.getSchemas(),n=this.contextRegistry.getSnapshot(),o=this.config.agent||this.config.defaultAgentId,a={content:t,conversation_id:s?.conversationId,agent_id:s?.agentId||o};r.length>0&&(a.client_functions=r),n&&(a.client_context=n);let c;if(s?.files&&s.files.length>0){const l=new FormData;l.append("content",t),s.conversationId&&l.append("conversation_id",s.conversationId),(s.agentId||o)&&l.append("agent_id",s.agentId||o||""),r.length>0&&l.append("client_functions",JSON.stringify(r)),n&&l.append("client_context",JSON.stringify(n));for(const E of s.files)l.append("files",E);c=await this.httpClient.postFormData("/api/sdk/v1/messages",l)}else c=await this.httpClient.postStream("/api/sdk/v1/messages",a);return this.processSSEResponse(c)}async processSSEResponse(t){return new v({onStart:s=>{this.eventEmitter.emit("message:start",s)},onChunk:s=>{this.eventEmitter.emit("message:chunk",s)},onToolCall:s=>{this.eventEmitter.emit("toolCall:received",s),s.type==="form"&&this.eventEmitter.emit("toolCall:form",s)},onClientFunction:async s=>{this.eventEmitter.emit("function:invoke",s),await this.handleClientFunctionInvocation(s)},onAnswerComplete:s=>{this.eventEmitter.emit("message:answer-complete",s)},onComplete:s=>{this.eventEmitter.emit("message:complete",s)},onError:s=>{this.eventEmitter.emit("message:error",{error:s.message})}}).processStream(t)}async handleClientFunctionInvocation(t){let s,r;try{s=await this.functionRegistry.execute(t.functionName,t.arguments)}catch(n){r=n instanceof Error?n.message:"Unknown error",i.error("Client function execution failed:",n)}if(t.invocationId)try{await this.submitToolCallForm(t.invocationId,{result:s,error:r,_type:"client_function_result"})}catch(n){i.error("Failed to submit function result:",n)}this.eventEmitter.emit("function:result",{invocationId:t.invocationId,result:s,error:r})}async getConversations(){return(await this.httpClient.get("/api/sdk/v1/conversations")).items.map(t=>({id:t.id,title:t.title,lastMessageDate:new Date(t.last_message_date)}))}async getConversation(t){const s=await this.httpClient.get(`/api/sdk/v1/conversations/${t}`),r={id:s.id,title:s.title,lastMessageDate:new Date(s.last_message_date),messages:s.messages.map(n=>({id:n.id,conversationId:s.id,content:n.content,role:n.role,status:n.status,createdAt:new Date(n.created_at),toolCalls:b.mapPersistedToolCalls(n.tool_call_data)}))};return this.eventEmitter.emit("conversation:loaded",r),r}static mapPersistedToolCalls(t){if(!(!t||t.length===0))return t.map(s=>({id:String(s.id??""),type:s.type??"status_message",status:String(s.status??"unknown"),toolName:s.tool_name??"",toolDisplayName:s.tool_display_name,message:s.message,formSchema:s.form_schema,data:s.data,functionName:s.function_name,arguments:s.arguments}))}async getMessages(t){return(await this.getConversation(t)).messages||[]}async submitToolCallForm(t,s){await this.httpClient.post(`/api/sdk/v1/tool-calls/${t}/submit`,{formData:s})}async confirmToolCall(t){await this.httpClient.post(`/api/tool-calls/${t}/confirm/`)}async rejectToolCall(t){await this.httpClient.post(`/api/tool-calls/${t}/reject/`)}async submitFormCollector(t,s){return this.httpClient.post("/api/sdk/v1/forms/submit",{destination:t,values:s})}async submitFeedback(t,s){await this.httpClient.post(`/api/sdk/v1/messages/${t}/feedback`,{rating:s})}registerFunction(t,s,r){typeof t=="object"?this.functionRegistry.register(t):this.functionRegistry.register(t,s,r)}register(t){if(Array.isArray(t))for(const s of t)this.functionRegistry.register(s);else this.functionRegistry.register(t)}unregisterFunction(t){return this.functionRegistry.unregister(t)}getRegisteredFunctions(){return this.functionRegistry.getSchemas()}registerNavigationFunction(t,s){const r=s.map(o=>o.name),n=s.map(o=>`- "${o.name}": ${o.description}`).join(`
+`);for(const r of s)if(!r.startsWith(": ")&&r.startsWith("data: ")){const n=r.slice(6);try{const o=JSON.parse(n);this.handleChunk(o)}catch(o){i.warn("Failed to parse SSE data:",n,o)}}}}handleChunk(e){if(e.message_id&&!this.message.id&&(this.message.id=e.message_id),e.thread?.id&&(this.message.conversationId=e.thread.id,this.isFirstChunk&&this.message.id&&(this.isFirstChunk=!1,this.callbacks.onStart?.({conversationId:this.message.conversationId,messageId:this.message.id}))),e.content!==void 0&&(this.message.content=(this.message.content||"")+e.content,this.message.conversationId&&this.message.id&&this.callbacks.onChunk?.({content:e.content,conversationId:this.message.conversationId,messageId:this.message.id})),e.full_content!==void 0&&(this.message.content=e.full_content),e.status&&(this.message.status=e.status),e.agent&&(this.message.agent={id:e.agent.id,name:e.agent.name,displayName:e.agent.display_name}),e.knowledge_sources&&(this.sources=e.knowledge_sources.map(t=>{const s=t.knowledge_document;return{id:s.id,title:s.title,url:s.use_external_link?s.external_link_url:s.internal_link_url}})),e.type==="client_function"&&e.function_name&&this.callbacks.onClientFunction?.({invocationId:e.id||"",functionName:e.function_name,arguments:e.arguments||{},conversationId:this.message.conversationId||""}),e.tool_call_data&&e.type&&e.type!=="client_function"){const t=this.parseToolCall(e);this.callbacks.onToolCall?.(t);const s=this.toolCalls.findIndex(r=>r.id===t.id);s>=0?this.toolCalls[s]=t:this.toolCalls.push(t)}e.follow_up_replies&&(this.followUpReplies=e.follow_up_replies),this.message.status==="DONE"&&!this.answerCompleteEmitted&&this.message.id&&(this.answerCompleteEmitted=!0,this.callbacks.onAnswerComplete?.(this.buildMessage()))}parseToolCall(e){return{id:e.id||"",type:e.type||"status_message",status:e.status||"unknown",toolName:e.tool_name||"",toolDisplayName:e.tool_display_name,message:e.message,formSchema:e.form_schema,data:e.data,functionName:e.function_name,arguments:e.arguments}}buildMessage(){return{id:this.message.id||"",conversationId:this.message.conversationId||"",content:this.message.content||"",role:"assistant",status:this.message.status||"DONE",agent:this.message.agent,sources:this.sources.length>0?this.sources:void 0,toolCalls:this.toolCalls.length>0?this.toolCalls:void 0,followUpReplies:this.followUpReplies.length>0?this.followUpReplies:void 0,createdAt:new Date}}buildFinalMessage(){const e=this.buildMessage();return this.callbacks.onComplete?.(e),e}};function x(e){const t=e.message.toLowerCase();return t.includes("load failed")||t.includes("failed to fetch")||t.includes("network")||t.includes("abort")}var C=class{constructor(){this.handlers=new Map}on(e,t){this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t)}off(e,t){const s=this.handlers.get(e);s&&s.delete(t)}emit(e,t){const s=this.handlers.get(e);s&&s.forEach(r=>{try{r(t)}catch(n){console.error(`Error in event handler for ${String(e)}:`,n)}})}once(e,t){const s=(r=>{this.off(e,s),t(r)});this.on(e,s)}waitFor(e,t){return new Promise((s,r)=>{let n;const o=(a=>{n&&clearTimeout(n),s(a)});this.once(e,o),t?.timeout&&(n=setTimeout(()=>{this.off(e,o),r(new Error(`waitFor("${String(e)}") timed out after ${t.timeout}ms`))},t.timeout))})}removeAllListeners(e){e?this.handlers.delete(e):this.handlers.clear()}},A=class b{constructor(t){this.config=t,this.httpClient=new k(t),this.functionRegistry=new y,this.contextRegistry=new w,this.eventEmitter=new C,t.debug&&i.enable(),i.log("AgoClient initialized")}async sendMessage(t,s){const r=this.functionRegistry.getSchemas(),n=this.contextRegistry.getSnapshot(),o=this.config.agent||this.config.defaultAgentId,a={content:t,conversation_id:s?.conversationId,agent_id:s?.agentId||o};r.length>0&&(a.client_functions=r),n&&(a.client_context=n);let c;if(s?.files&&s.files.length>0){const l=new FormData;l.append("content",t),s.conversationId&&l.append("conversation_id",s.conversationId),(s.agentId||o)&&l.append("agent_id",s.agentId||o||""),r.length>0&&l.append("client_functions",JSON.stringify(r)),n&&l.append("client_context",JSON.stringify(n));for(const E of s.files)l.append("files",E);c=await this.httpClient.postFormData("/api/sdk/v1/messages",l)}else c=await this.httpClient.postStream("/api/sdk/v1/messages",a);return this.processSSEResponse(c)}async processSSEResponse(t){return new v({onStart:s=>{this.eventEmitter.emit("message:start",s)},onChunk:s=>{this.eventEmitter.emit("message:chunk",s)},onToolCall:s=>{this.eventEmitter.emit("toolCall:received",s),s.type==="form"&&this.eventEmitter.emit("toolCall:form",s)},onClientFunction:async s=>{this.eventEmitter.emit("function:invoke",s),await this.handleClientFunctionInvocation(s)},onAnswerComplete:s=>{this.eventEmitter.emit("message:answer-complete",s)},onComplete:s=>{this.eventEmitter.emit("message:complete",s)},onError:s=>{this.eventEmitter.emit("message:error",{error:s.message})}}).processStream(t)}async handleClientFunctionInvocation(t){let s,r;try{s=await this.functionRegistry.execute(t.functionName,t.arguments)}catch(n){r=n instanceof Error?n.message:"Unknown error",i.error("Client function execution failed:",n)}if(t.invocationId)try{await this.submitToolCallForm(t.invocationId,{result:s,error:r,_type:"client_function_result"})}catch(n){i.error("Failed to submit function result:",n)}this.eventEmitter.emit("function:result",{invocationId:t.invocationId,result:s,error:r})}async getConversations(){return(await this.httpClient.get("/api/sdk/v1/conversations")).items.map(t=>({id:t.id,title:t.title,lastMessageDate:new Date(t.last_message_date)}))}async getConversation(t){const s=await this.httpClient.get(`/api/sdk/v1/conversations/${t}`),r={id:s.id,title:s.title,lastMessageDate:new Date(s.last_message_date),messages:s.messages.map(n=>({id:n.id,conversationId:s.id,content:n.content,role:n.role,status:n.status,createdAt:new Date(n.created_at),toolCalls:b.mapPersistedToolCalls(n.tool_call_data)}))};return this.eventEmitter.emit("conversation:loaded",r),r}static mapPersistedToolCalls(t){if(!(!t||t.length===0))return t.map(s=>({id:String(s.id??""),type:s.type??"status_message",status:String(s.status??"unknown"),toolName:s.tool_name??"",toolDisplayName:s.tool_display_name,message:s.message,formSchema:s.form_schema,data:s.data,functionName:s.function_name,arguments:s.arguments}))}async getMessages(t){return(await this.getConversation(t)).messages||[]}async submitToolCallForm(t,s){await this.httpClient.post(`/api/sdk/v1/tool-calls/${t}/submit`,{formData:s})}async confirmToolCall(t){await this.httpClient.post(`/api/tool-calls/${t}/confirm/`)}async rejectToolCall(t){await this.httpClient.post(`/api/tool-calls/${t}/reject/`)}async getFormCollector(t){const s=await this.httpClient.get(`/api/sdk/v1/forms/${encodeURIComponent(t)}`);return{name:s.name,description:s.description,schema:s.schema,submit:s.submit??void 0}}async submitFormCollector(t,s){return this.httpClient.post("/api/sdk/v1/forms/submit",{destination:t,values:s})}async submitFeedback(t,s){await this.httpClient.post(`/api/sdk/v1/messages/${t}/feedback`,{rating:s})}registerFunction(t,s,r){typeof t=="object"?this.functionRegistry.register(t):this.functionRegistry.register(t,s,r)}register(t){if(Array.isArray(t))for(const s of t)this.functionRegistry.register(s);else this.functionRegistry.register(t)}unregisterFunction(t){return this.functionRegistry.unregister(t)}getRegisteredFunctions(){return this.functionRegistry.getSchemas()}registerNavigationFunction(t,s){const r=s.map(o=>o.name),n=s.map(o=>`- "${o.name}": ${o.description}`).join(`
 `);this.registerFunction("navigateToPage",async o=>{const a=o.page,c=s.find(l=>l.name===a);return c?(t(c.path),{success:!0,navigatedTo:c.path}):{success:!1,error:`Unknown page: ${a}`}},{description:`Navigate the user to a page in the application. Available pages:
 ${n}`,parameters:{type:"object",properties:{page:{type:"string",description:"The page to navigate to",enum:r}},required:["page"]}})}setContext(t,s){this.contextRegistry.set(t,s),this.notifyContextChanged()}removeContext(t){const s=this.contextRegistry.remove(t);return s&&this.notifyContextChanged(),s}addDynamicContext(t,s){this.contextRegistry.addDynamicProvider(t,s),this.notifyContextChanged()}removeDynamicContext(t){const s=this.contextRegistry.removeDynamicProvider(t);return s&&this.notifyContextChanged(),s}notifyContextChanged(){this.eventEmitter.emit("context:changed",this.contextRegistry.getSnapshot())}enableAutoPageContext(){this.addDynamicContext("browser-page",()=>{const t=typeof window<"u"?window.location.href:void 0,s=typeof document<"u"?document.title:void 0;return!t&&!s?null:{name:"Browser page",description:"Current page the user is viewing",data:{url:t,title:s}}})}getContextSnapshot(){return this.contextRegistry.getSnapshot()}on(t,s){this.eventEmitter.on(t,s)}off(t,s){this.eventEmitter.off(t,s)}once(t,s){this.eventEmitter.once(t,s)}waitFor(t,s){return this.eventEmitter.waitFor(t,s)}updateConfig(t){this.config={...this.config,...t},this.httpClient.updateConfig(t),t.debug!==void 0&&(t.debug?i.enable():i.disable())}destroy(){this.eventEmitter.removeAllListeners(),this.functionRegistry.clear(),this.contextRegistry.clear(),i.log("AgoClient destroyed")}};Object.defineProperty(exports,"AgoApiError",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"AgoClient",{enumerable:!0,get:function(){return A}});Object.defineProperty(exports,"AgoError",{enumerable:!0,get:function(){return u}});Object.defineProperty(exports,"AgoFunctionError",{enumerable:!0,get:function(){return m}});Object.defineProperty(exports,"AgoNetworkError",{enumerable:!0,get:function(){return d}});Object.defineProperty(exports,"AgoStreamError",{enumerable:!0,get:function(){return g}});Object.defineProperty(exports,"ClientContextRegistry",{enumerable:!0,get:function(){return w}});Object.defineProperty(exports,"EventEmitter",{enumerable:!0,get:function(){return C}});Object.defineProperty(exports,"FunctionRegistry",{enumerable:!0,get:function(){return y}});Object.defineProperty(exports,"SSEHandler",{enumerable:!0,get:function(){return v}});Object.defineProperty(exports,"isStreamNetworkError",{enumerable:!0,get:function(){return x}});Object.defineProperty(exports,"logger",{enumerable:!0,get:function(){return i}});

package/dist/{AgoClient-BrYhSO5M.js → AgoClient-CZYNL25R.js}

@@ -14,11 +14,11 @@ var d = class extends Error {
   constructor(e, t) {
     super(e, "network_error"), this.originalError = t, this.name = "AgoNetworkError";
   }
-}, g = class extends d {
+}, m = class extends d {
   constructor(e) {
     super(e, "stream_error"), this.name = "AgoStreamError";
   }
-}, m = class extends d {
+}, g = class extends d {
   constructor(e, t, s) {
     super(e, "function_error"), this.functionName = t, this.originalError = s, this.name = "AgoFunctionError";
   }
@@ -133,10 +133,10 @@ var E = class {
   }
   register(e, t, s) {
     if (typeof e == "object") {
-      const { name: i, handler: o, description: a, parameters: l } = e;
+      const { name: i, handler: o, description: a, parameters: c } = e;
       return this.register(i, o, {
         description: a,
-        parameters: l
+        parameters: c
       });
     }
     const r = e;
@@ -164,13 +164,13 @@ var E = class {
   }
   async execute(e, t) {
     const s = this.functions.get(e);
-    if (!s) throw new m(`Function "${e}" is not registered`, e);
+    if (!s) throw new g(`Function "${e}" is not registered`, e);
     n.log(`Executing function: ${e}`, t);
     try {
       const r = await s.handler(t);
       return n.log(`Function ${e} completed:`, r), r;
     } catch (r) {
-      throw n.error(`Function ${e} failed:`, r), new m(`Function "${e}" execution failed: ${r instanceof Error ? r.message : "Unknown error"}`, e, r instanceof Error ? r : void 0);
+      throw n.error(`Function ${e} failed:`, r), new g(`Function "${e}" execution failed: ${r instanceof Error ? r.message : "Unknown error"}`, e, r instanceof Error ? r : void 0);
     }
   }
   clear() {
@@ -217,7 +217,7 @@ var E = class {
     this.callbacks = e, this.buffer = "", this.message = {}, this.toolCalls = [], this.sources = [], this.followUpReplies = [], this.isFirstChunk = !0, this.answerCompleteEmitted = !1;
   }
   async processStream(e) {
-    if (!e.body) throw new g("Response has no body");
+    if (!e.body) throw new m("Response has no body");
     const t = e.body.getReader(), s = new TextDecoder();
     try {
       for (; ; ) {
@@ -228,7 +228,7 @@ var E = class {
       }
       return this.buffer.trim() && this.processBuffer(), this.buildFinalMessage();
     } catch (r) {
-      const i = r instanceof Error ? r : new g("Stream processing failed");
+      const i = r instanceof Error ? r : new m("Stream processing failed");
       throw this.callbacks.onError?.(i), i;
     } finally {
       t.releaseLock();
@@ -376,14 +376,14 @@ var S = class {
       agent_id: s?.agentId || o
     };
     r.length > 0 && (a.client_functions = r), i && (a.client_context = i);
-    let l;
+    let c;
     if (s?.files && s.files.length > 0) {
-      const c = new FormData();
-      c.append("content", t), s.conversationId && c.append("conversation_id", s.conversationId), (s.agentId || o) && c.append("agent_id", s.agentId || o || ""), r.length > 0 && c.append("client_functions", JSON.stringify(r)), i && c.append("client_context", JSON.stringify(i));
-      for (const v of s.files) c.append("files", v);
-      l = await this.httpClient.postFormData("/api/sdk/v1/messages", c);
-    } else l = await this.httpClient.postStream("/api/sdk/v1/messages", a);
-    return this.processSSEResponse(l);
+      const l = new FormData();
+      l.append("content", t), s.conversationId && l.append("conversation_id", s.conversationId), (s.agentId || o) && l.append("agent_id", s.agentId || o || ""), r.length > 0 && l.append("client_functions", JSON.stringify(r)), i && l.append("client_context", JSON.stringify(i));
+      for (const v of s.files) l.append("files", v);
+      c = await this.httpClient.postFormData("/api/sdk/v1/messages", l);
+    } else c = await this.httpClient.postStream("/api/sdk/v1/messages", a);
+    return this.processSSEResponse(c);
   }
   async processSSEResponse(t) {
     return new k({
@@ -483,6 +483,15 @@ var S = class {
   async rejectToolCall(t) {
     await this.httpClient.post(`/api/tool-calls/${t}/reject/`);
   }
+  async getFormCollector(t) {
+    const s = await this.httpClient.get(`/api/sdk/v1/forms/${encodeURIComponent(t)}`);
+    return {
+      name: s.name,
+      description: s.description,
+      schema: s.schema,
+      submit: s.submit ?? void 0
+    };
+  }
   async submitFormCollector(t, s) {
     return this.httpClient.post("/api/sdk/v1/forms/submit", {
       destination: t,
@@ -509,10 +518,10 @@ var S = class {
     const r = s.map((o) => o.name), i = s.map((o) => `- "${o.name}": ${o.description}`).join(`
 `);
     this.registerFunction("navigateToPage", async (o) => {
-      const a = o.page, l = s.find((c) => c.name === a);
-      return l ? (t(l.path), {
+      const a = o.page, c = s.find((l) => l.name === a);
+      return c ? (t(c.path), {
         success: !0,
-        navigatedTo: l.path
+        navigatedTo: c.path
       }) : {
         success: !1,
         error: `Unknown page: ${a}`
@@ -590,7 +599,7 @@ export {
   _ as a,
   h as c,
   u as d,
-  g as f,
+  m as f,
   x as i,
   d as l,
   S as n,
@@ -598,5 +607,5 @@ export {
   k as r,
   n as s,
   $ as t,
-  m as u
+  g as u
 };

package/dist/angular.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./AgoClient-CPqPT5s6.cjs");var n=class{constructor(e){this.client=new o.AgoClient(e),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(e){const t=this.client;return{subscribe(i){const s=r=>{i.next?.(r)};return t.on(e,s),{unsubscribe:()=>t.off(e,s)}}}}sendMessage(e,t){return this.client.sendMessage(e,t)}getConversations(){return this.client.getConversations()}getConversation(e){return this.client.getConversation(e)}getMessages(e){return this.client.getMessages(e)}submitToolCallForm(e,t){return this.client.submitToolCallForm(e,t)}confirmToolCall(e){return this.client.confirmToolCall(e)}rejectToolCall(e){return this.client.rejectToolCall(e)}submitFeedback(e,t){return this.client.submitFeedback(e,t)}registerFunction(e,t,i){typeof e=="object"?this.client.registerFunction(e):this.client.registerFunction(e,t,i)}unregisterFunction(e){return this.client.unregisterFunction(e)}registerNavigationFunction(e,t){this.client.registerNavigationFunction(e,t)}on(e,t){this.client.on(e,t)}off(e,t){this.client.off(e,t)}updateConfig(e){this.client.updateConfig(e)}getClient(){return this.client}destroy(){this.client.destroy()}};function c(e){return{provide:n,useValue:new n(e)}}exports.AgoService=n;exports.provideAgo=c;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./AgoClient-0x2Du_62.cjs");var n=class{constructor(e){this.client=new o.AgoClient(e),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(e){const t=this.client;return{subscribe(i){const s=r=>{i.next?.(r)};return t.on(e,s),{unsubscribe:()=>t.off(e,s)}}}}sendMessage(e,t){return this.client.sendMessage(e,t)}getConversations(){return this.client.getConversations()}getConversation(e){return this.client.getConversation(e)}getMessages(e){return this.client.getMessages(e)}submitToolCallForm(e,t){return this.client.submitToolCallForm(e,t)}confirmToolCall(e){return this.client.confirmToolCall(e)}rejectToolCall(e){return this.client.rejectToolCall(e)}submitFeedback(e,t){return this.client.submitFeedback(e,t)}registerFunction(e,t,i){typeof e=="object"?this.client.registerFunction(e):this.client.registerFunction(e,t,i)}unregisterFunction(e){return this.client.unregisterFunction(e)}registerNavigationFunction(e,t){this.client.registerNavigationFunction(e,t)}on(e,t){this.client.on(e,t)}off(e,t){this.client.off(e,t)}updateConfig(e){this.client.updateConfig(e)}getClient(){return this.client}destroy(){this.client.destroy()}};function c(e){return{provide:n,useValue:new n(e)}}exports.AgoService=n;exports.provideAgo=c;

package/dist/angular.d.cts

@@ -53,6 +53,13 @@ declare class AgoClient {
      * Reject a tool call
      */
     rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Fetch a backend-stored form collector definition by name (the single source
+     * of truth for the form's description, schema, and submit target). Used by
+     * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
+     * lives in the backend instead of being hardcoded in client code.
+     */
+    getFormCollector(name: string): Promise<FormCollectorDefinition>;
     /**
      * Relay a completed form collector's values to a server-configured destination.
      *
@@ -477,6 +484,30 @@ export declare interface Conversation {
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
+/**
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
+ * `handler` variant (a function can't be stored server-side).
+ */
+declare interface FormCollectorDefinition<V = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: FormCollectorSchema;
+    /** Server-stored submit target, if any. Absent means collect-only. */
+    submit?: SubmitConfig<V>;
+}
+
+/**
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
+ */
+declare interface FormCollectorSchema {
+    type: "object";
+    properties: Record<string, FormFieldSchema>;
+    required?: string[];
+}
+
 declare interface FormField {
     type: "string" | "number" | "boolean" | "array";
     title?: string;
@@ -485,6 +516,43 @@ declare interface FormField {
     default?: unknown;
 }
 
+/**
+ * A field's conditional-requiredness rule. The field becomes required exactly
+ * when the controlling `property` matches `value` against the answers collected
+ * so far:
+ * - a single `value`, no `op` — equality (compared as strings);
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
+ * - an array `value`, no `op` — "one of": matches when the property equals any
+ *   listed value.
+ *
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
+ */
+declare interface FormFieldCondition {
+    /** The controlling field whose value the rule tests. */
+    property: string;
+    /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
+    op?: ">=" | "<=" | ">" | "<";
+    /**
+     * The value(s) to test the controlling field against. A single value is an
+     * equality (or, with `op`, a numeric comparison); an array is an "is one of"
+     * membership test, e.g. `value: ["1", "2", "3"]`.
+     */
+    value: string | number | Array<string | number>;
+}
+
+/** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
+declare interface FormFieldSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /**
+     * Makes the field required only while this condition holds. Drives the dynamic
+     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     */
+    requiredWhen?: FormFieldCondition;
+}
+
 /**
  * Form schema for tool calls requiring user input
  */
@@ -541,6 +609,27 @@ declare interface SendMessageOptions {
     files?: File[];
 }
 
+/**
+ * Where a completed form is sent.
+ * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser
+ *   POSTs the values to that URL.
+ * - `{ via: "client", url }` — same, written out.
+ * - `{ via: "client", handler }` — the browser runs your own submit logic.
+ * - `{ via: "backend", destination }` — the browser relays the values to the backend,
+ *   which forwards them to the server-configured destination (URL + secret stay server-side).
+ * - `false` — collect only, no submit function.
+ */
+declare type SubmitConfig<V = Record<string, unknown>> = string | {
+    via: "client";
+    url: string;
+} | {
+    via: "client";
+    handler: (values: V) => Promise<unknown> | unknown;
+} | {
+    via: "backend";
+    destination: string;
+} | false;
+
 /**
  * Tool call data from SSE stream
  */