@proveanything/smartlinks 2.0.26 → 2.0.29

package/dist/types/ai.d.ts

@@ -139,6 +139,17 @@ export interface ResponsesRequest {
     exclude?: AiToolName[];
     /** With `server_tools`: cap model round-trips (1–12, default 8). */
     maxSteps?: number;
+    /**
+     * With `server_tools`: ALSO offer an installed app's AI-exposed server functions (those declaring
+     * `ai.tool: true`) as tools, alongside the built-ins. Their visibility/authority/capabilities are
+     * enforced unchanged — the agent is just another caller surface.
+     */
+    app_functions?: AgentAppFunctionsOption;
+    /**
+     * Unified toolbelt (preferred over server_tools/app_functions): built-ins + app functions (+ reserved
+     * client tools) in one declaration. Providing it opts the request into the agentic loop.
+     */
+    toolbelt?: AgentToolbelt;
 }
 /** Response from the Responses API. */
 export interface ResponsesResult {
@@ -681,12 +692,124 @@ export interface AgentRunRequest {
     only?: string[];
     /** Drop these tool names. */
     exclude?: string[];
+    /** Also offer an installed app's AI-exposed server functions as tools (see AgentAppFunctionsOption). */
+    appFunctions?: AgentAppFunctionsOption;
+    /** Unified toolbelt (preferred): built-ins + app functions (+ reserved client tools) in one place. */
+    toolbelt?: AgentToolbelt;
+}
+/**
+ * Include an installed app's AI-exposed server functions (those declaring `ai.tool: true`) in an
+ * agent run as callable tools, alongside the built-in tools. The function's
+ * visibility/authority/capabilities are enforced unchanged — the agent is just another caller.
+ */
+export interface AgentAppFunctionsOption {
+    /** The app whose functions to expose (the master app id). */
+    appId: string;
+    /** Release channel to resolve the app's functions from (default 'stable'; pass 'dev' to test). */
+    channel?: string;
+    /** Restrict to these function names. */
+    only?: string[];
+}
+/**
+ * The unified TOOLBELT for an agent run — one declaration spanning every tool KIND:
+ *   - `builtins`     — SmartLinks built-in tools (`true` = all, `[names]` = a subset, omit/`false` = none).
+ *   - `appFunctions` — one or more installed apps' AI-exposed server functions.
+ *   - `clientTools`  — front-end tools executed in the caller's page (RESERVED — the client-tool bridge
+ *                      is staged; declaring them has no effect until it ships).
+ * Precedence on a name clash: a built-in wins, then earlier `appFunctions` sources win over later ones.
+ * On the public surface, `builtins: true` is not honoured (built-ins there are an explicit allowlist).
+ */
+export interface AgentToolbelt {
+    builtins?: boolean | AiToolName[];
+    appFunctions?: AgentAppFunctionsOption | AgentAppFunctionsOption[];
+    /** RESERVED — front-end/client tools (executed via the client-tool bridge; not yet active). */
+    clientTools?: ClientToolDeclaration[];
+}
+/** A front-end/client tool the model may call that the caller's page executes (see ai.runWithClientTools). */
+export interface ClientToolDeclaration {
+    name: string;
+    description?: string;
+    /** JSON Schema for the arguments the model supplies. */
+    input?: Record<string, any>;
+}
+/** A pending client-tool invocation the agent loop suspended on — the caller runs it and resubmits. */
+export interface ClientToolCall {
+    callId: string;
+    name: string;
+    args: Record<string, any>;
+}
+/** The suspend response when the model calls a client tool: run each call, then resubmit items+outputs. */
+export interface RequiresActionResult {
+    status: 'requires_action';
+    client_tool_calls: ClientToolCall[];
+    /** The transcript so far — resubmit as `input` with a function_call_output appended per call. */
+    items: any[];
+    steps?: number;
+    toolResults?: AgentToolResult[];
+    availableTools?: string[];
+}
+/** A client tool bound to its browser-side handler (build with ai.defineClientTool). */
+export interface ClientTool {
+    declaration: ClientToolDeclaration;
+    handler: (args: Record<string, any>) => any | Promise<any>;
+}
+/** Options for ai.runWithClientTools — the browser-side loop that resolves client tools automatically. */
+export interface RunWithClientToolsOptions {
+    input: string;
+    tools: ClientTool[];
+    /** Which agent surface to run on: 'admin' (default) or 'public' (consumer). */
+    surface?: 'admin' | 'public';
+    instructions?: string;
+    model?: string;
+    maxSteps?: number;
+    /** Built-ins + app functions to include alongside the client tools. */
+    toolbelt?: AgentToolbelt;
+    /** Safety cap on client round-trips (default 8). */
+    maxRounds?: number;
+}
+/**
+ * Body for the PUBLIC agent loop (`ai.publicClient.agentRun`). The consumer-surface equivalent of
+ * AgentRunRequest: the caller is the signed-in consumer (authKit bearer → 'owner') or anonymous
+ * ('public'), and tools run at that authority. Its main use is exposing an app's PUBLIC functions.
+ * SAFETY: built-in tools are opt-in by EXPLICIT allowlist only — `server_tools` here is an array, not
+ * a boolean (there is no "all built-ins" on the public surface).
+ */
+export interface PublicAgentRunRequest {
+    input?: string;
+    prompt?: string;
+    instructions?: string;
+    model?: string;
+    maxSteps?: number;
+    /** Built-in tools to allow (explicit list; no `true`=all on the public surface). */
+    server_tools?: AiToolName[];
+    /** Alias of server_tools[] — restrict built-ins to these names. */
+    only?: AiToolName[];
+    /** Drop these built-in tool names. */
+    exclude?: AiToolName[];
+    /** Cap blast radius: only built-ins whose capabilities are all granted. */
+    allowCapabilities?: AiToolCapability[];
+    /** Include an installed app's PUBLIC AI functions as tools. */
+    appFunctions?: AgentAppFunctionsOption;
+    /** Unified toolbelt. On the public surface `builtins` is an explicit allowlist (no `true`=all). */
+    toolbelt?: AgentToolbelt;
+    /** Rate-limit key for anonymous callers (else derived from the bearer/IP). */
+    userId?: string;
 }
 export interface AgentToolResult {
     name: string;
     isError: boolean;
     result: any;
 }
+/**
+ * Result of a DIRECT single-tool invocation (`ai.tools.run`) — no model in the loop.
+ * Mirrors one AgentToolResult but typed to the tool's own result. `result` is the tool's
+ * raw output; deterministic tools may still put a tool-level `{ error }` inside it.
+ */
+export interface ToolRunResult<T = any> {
+    name: string;
+    isError: boolean;
+    result: T;
+}
 export interface AgentRunResult {
     finalText: string | null;
     steps: number;
@@ -725,7 +848,7 @@ export interface CatalogResponse {
 /** Capability tags a tool requires; scope a run with `allowCapabilities`. */
 export type AiToolCapability = 'web:read' | 'ai:vision' | 'ai:image' | 'ai:text' | 'media:image' | 'media:pdf' | 'net:http';
 /** The names of the built-in server-side agent tools (run via `server_tools`). */
-export type AiToolName = 'web.fetchPage' | 'web.extractSchema' | 'web.screenshot' | 'web.search' | 'brand.assets' | 'document.read' | 'data.extract' | 'image.describe' | 'image.generate' | 'image.fromReference' | 'image.searchStock' | 'image.transform' | 'pdf.create' | 'pdf.fill' | 'pdf.merge' | 'http.request' | 'translate';
+export type AiToolName = 'web.fetchPage' | 'web.extractSchema' | 'web.screenshot' | 'web.search' | 'brand.assets' | 'document.read' | 'data.extract' | 'image.describe' | 'image.generate' | 'image.fromReference' | 'image.searchStock' | 'image.transform' | 'pdf.create' | 'pdf.fill' | 'pdf.merge' | 'pdf.inspect' | 'pdf.render' | 'pdf.extract' | 'pdf.decodeBarcodes' | 'pdf.inspectGraphics' | 'http.request' | 'translate';
 export interface WebFetchPageArgs {
     url: string;
     type?: string;
@@ -817,6 +940,34 @@ export interface PdfFillArgs {
 export interface PdfMergeArgs {
     urls: string[];
 }
+export interface PdfInspectArgs {
+    url: string;
+    maxPages?: number;
+    minTextChars?: number;
+}
+export interface PdfRenderArgs {
+    url: string;
+    page?: number;
+    dpi?: number;
+}
+export interface PdfExtractArgs {
+    url: string;
+    schema?: Record<string, any>;
+    prompt?: string;
+    maxPages?: number;
+    dpi?: number;
+    includeConfidence?: boolean;
+    includeBoxes?: boolean;
+}
+export interface PdfDecodeBarcodesArgs {
+    url: string;
+    page?: number;
+    dpi?: number;
+}
+export interface PdfInspectGraphicsArgs {
+    url: string;
+    page?: number;
+}
 export interface HttpRequestArgs {
     url: string;
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
@@ -845,6 +996,11 @@ export interface AiToolArgsMap {
     'pdf.create': PdfCreateArgs;
     'pdf.fill': PdfFillArgs;
     'pdf.merge': PdfMergeArgs;
+    'pdf.inspect': PdfInspectArgs;
+    'pdf.render': PdfRenderArgs;
+    'pdf.extract': PdfExtractArgs;
+    'pdf.decodeBarcodes': PdfDecodeBarcodesArgs;
+    'pdf.inspectGraphics': PdfInspectGraphicsArgs;
     'http.request': HttpRequestArgs;
     'translate': TranslateArgs;
 }
@@ -905,6 +1061,86 @@ export interface TranslateResult {
     translations: Record<string, string>;
     sourceLanguage: string;
 }
+/** One page's structure from pdf.inspect. */
+export interface PdfInspectPage {
+    page: number;
+    width: number;
+    height: number;
+    textChars: number;
+    hasText: boolean;
+    imageCount: number;
+    likelyType: 'text-native' | 'text+raster' | 'raster-only' | 'curve-only';
+}
+export interface PdfInspectResult {
+    url: string;
+    pageCount: number;
+    inspectedPages: number;
+    totalTextChars: number;
+    isTextNative: boolean;
+    isCurveOnly: boolean;
+    recommendedPath: 'text' | 'vision';
+    note: string;
+    pages: PdfInspectPage[];
+}
+export interface PdfRenderResult {
+    url: string | null;
+    page: number;
+    pageCount: number;
+    dpi: number;
+    width: number;
+    height: number;
+}
+/** Per-field metadata from pdf.extract when includeConfidence / includeBoxes is set. */
+export interface PdfFieldMeta {
+    confidence?: number | null;
+    source?: 'text' | 'vision' | 'inferred';
+    bbox?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        page: number;
+    };
+}
+export interface PdfExtractResult {
+    url: string;
+    method: 'text' | 'vision';
+    pagesRead: number;
+    fields: Record<string, any>;
+    fieldsMeta?: Record<string, PdfFieldMeta>;
+}
+/** One decoded barcode/QR from pdf.decodeBarcodes. bbox is in PDF points (top-left origin). */
+export interface PdfBarcode {
+    type: string;
+    format: string;
+    value: string;
+    page: number;
+    bbox?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    confidence: number;
+}
+export interface PdfDecodeBarcodesResult {
+    url: string;
+    pagesScanned: number;
+    codes: PdfBarcode[];
+}
+export interface PdfGraphicsPage {
+    page: number;
+    paths: number;
+    images: number;
+    textRuns: number;
+    colourSpaces: string[];
+}
+export interface PdfInspectGraphicsResult {
+    url: string;
+    pages: PdfGraphicsPage[];
+    spotColours: string[];
+    note: string;
+}
 /** The `_agent` trace attached to an agentic Responses result. */
 export interface ResponsesAgentTrace {
     steps: number;

package/dist/types/appManifest.d.ts

@@ -271,6 +271,34 @@ export interface AppFunctionDef {
     apiVersion?: string;
     /** Exported handler name in the functions bundle. Defaults to `name`. */
     handler?: string;
+    /**
+     * Expose this function to the AI agent as a callable tool (an MCP-shaped facade over the function).
+     * Only `http`-trigger functions can be exposed. The agent becomes just another caller surface, so
+     * the function's visibility/authority/capabilities apply UNCHANGED — nothing new is granted. The
+     * agent-supplied arguments arrive as the function's http request `body`. See agent-tools.md.
+     */
+    agent?: AppFunctionAgentExposure;
+}
+/** Opt-in that turns a server function into an agent-callable tool. See agent-tools.md. */
+export interface AppFunctionAgentExposure {
+    /** When true, offer this `http` function to the agent as a tool. */
+    tool: boolean;
+    /** Short human label for the tool (tool pickers / approval prompts). */
+    title?: string;
+    /** Model-facing description — when to use the tool (falls back to the function's `description`). */
+    description?: string;
+    /**
+     * JSON Schema (`{ type: 'object', properties: … }`) for the arguments the agent supplies. They
+     * arrive as the function's http request body. Strongly recommended — without it the agent is told
+     * the tool takes a free-form object.
+     */
+    input?: Record<string, any>;
+    /**
+     * `'auto'` (default) = the agent may call it without confirmation. `'require'` = a human must
+     * confirm before each call. Until the human-approval UX ships, `'require'` tools are NOT offered to
+     * the autonomous server-side loop (they'd otherwise run unconfirmed).
+     */
+    approval?: 'auto' | 'require';
 }
 /** The `functions` block in `app.manifest.json`. Presence means the app ships server functions. */
 export interface AppManifestFunctions {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.26  |  Generated: 2026-09-28T11:34:04.010Z
+Version: 2.0.29  |  Generated: 2026-09-29T10:33:46.286Z
 
 This is a concise summary of all available API functions and types.
 
@@ -594,6 +594,8 @@ interface ResponsesRequest {
   only?: AiToolName[]
   exclude?: AiToolName[]
   maxSteps?: number
+  app_functions?: AgentAppFunctionsOption
+  toolbelt?: AgentToolbelt
 }
 ```
 
@@ -1177,6 +1179,96 @@ interface AgentRunRequest {
   allowCapabilities?: string[]
   only?: string[]
   exclude?: string[]
+  appFunctions?: AgentAppFunctionsOption
+  toolbelt?: AgentToolbelt
+}
+```
+
+**AgentAppFunctionsOption** (interface)
+```typescript
+interface AgentAppFunctionsOption {
+  appId: string
+  channel?: string
+  only?: string[]
+}
+```
+
+**AgentToolbelt** (interface)
+```typescript
+interface AgentToolbelt {
+  builtins?: boolean | AiToolName[]
+  appFunctions?: AgentAppFunctionsOption | AgentAppFunctionsOption[]
+  clientTools?: ClientToolDeclaration[]
+}
+```
+
+**ClientToolDeclaration** (interface)
+```typescript
+interface ClientToolDeclaration {
+  name: string
+  description?: string
+  input?: Record<string, any>
+}
+```
+
+**ClientToolCall** (interface)
+```typescript
+interface ClientToolCall {
+  callId: string
+  name: string
+  args: Record<string, any>
+}
+```
+
+**RequiresActionResult** (interface)
+```typescript
+interface RequiresActionResult {
+  status: 'requires_action'
+  client_tool_calls: ClientToolCall[]
+  items: any[]
+  steps?: number
+  toolResults?: AgentToolResult[]
+  availableTools?: string[]
+}
+```
+
+**ClientTool** (interface)
+```typescript
+interface ClientTool {
+  declaration: ClientToolDeclaration
+  handler: (args: Record<string, any>) => any | Promise<any>
+}
+```
+
+**RunWithClientToolsOptions** (interface)
+```typescript
+interface RunWithClientToolsOptions {
+  input: string
+  tools: ClientTool[]
+  surface?: 'admin' | 'public'
+  instructions?: string
+  model?: string
+  maxSteps?: number
+  toolbelt?: AgentToolbelt
+  maxRounds?: number
+}
+```
+
+**PublicAgentRunRequest** (interface)
+```typescript
+interface PublicAgentRunRequest {
+  input?: string
+  prompt?: string
+  instructions?: string
+  model?: string
+  maxSteps?: number
+  server_tools?: AiToolName[]
+  only?: AiToolName[]
+  exclude?: AiToolName[]
+  allowCapabilities?: AiToolCapability[]
+  appFunctions?: AgentAppFunctionsOption
+  toolbelt?: AgentToolbelt
+  userId?: string
 }
 ```
 
@@ -1189,6 +1281,15 @@ interface AgentToolResult {
 }
 ```
 
+**ToolRunResult<T = any>** (interface)
+```typescript
+interface ToolRunResult<T = any> {
+  name: string
+  isError: boolean
+  result: T
+}
+```
+
 **AgentRunResult** (interface)
 ```typescript
 interface AgentRunResult {
@@ -1367,6 +1468,41 @@ interface PdfMergeArgs {
 }
 ```
 
+**PdfInspectArgs** (interface)
+```typescript
+interface PdfInspectArgs {
+  url: string; maxPages?: number; minTextChars?: number
+}
+```
+
+**PdfRenderArgs** (interface)
+```typescript
+interface PdfRenderArgs {
+  url: string; page?: number; dpi?: number
+}
+```
+
+**PdfExtractArgs** (interface)
+```typescript
+interface PdfExtractArgs {
+  url: string; schema?: Record<string, any>; prompt?: string; maxPages?: number; dpi?: number; includeConfidence?: boolean; includeBoxes?: boolean
+}
+```
+
+**PdfDecodeBarcodesArgs** (interface)
+```typescript
+interface PdfDecodeBarcodesArgs {
+  url: string; page?: number; dpi?: number
+}
+```
+
+**PdfInspectGraphicsArgs** (interface)
+```typescript
+interface PdfInspectGraphicsArgs {
+  url: string; page?: number
+}
+```
+
 **HttpRequestArgs** (interface)
 ```typescript
 interface HttpRequestArgs {
@@ -1399,6 +1535,11 @@ interface AiToolArgsMap {
   'pdf.create': PdfCreateArgs
   'pdf.fill': PdfFillArgs
   'pdf.merge': PdfMergeArgs
+  'pdf.inspect': PdfInspectArgs
+  'pdf.render': PdfRenderArgs
+  'pdf.extract': PdfExtractArgs
+  'pdf.decodeBarcodes': PdfDecodeBarcodesArgs
+  'pdf.inspectGraphics': PdfInspectGraphicsArgs
   'http.request': HttpRequestArgs
   'translate': TranslateArgs
 }
@@ -1467,6 +1608,69 @@ interface TranslateResult {
 }
 ```
 
+**PdfInspectPage** (interface)
+```typescript
+interface PdfInspectPage {
+  page: number; width: number; height: number; textChars: number; hasText: boolean; imageCount: number; likelyType: 'text-native' | 'text+raster' | 'raster-only' | 'curve-only'
+}
+```
+
+**PdfInspectResult** (interface)
+```typescript
+interface PdfInspectResult {
+  url: string; pageCount: number; inspectedPages: number; totalTextChars: number; isTextNative: boolean; isCurveOnly: boolean; recommendedPath: 'text' | 'vision'; note: string; pages: PdfInspectPage[]
+}
+```
+
+**PdfRenderResult** (interface)
+```typescript
+interface PdfRenderResult {
+  url: string | null; page: number; pageCount: number; dpi: number; width: number; height: number
+}
+```
+
+**PdfFieldMeta** (interface)
+```typescript
+interface PdfFieldMeta {
+  confidence?: number | null; source?: 'text' | 'vision' | 'inferred'; bbox?: { x: number; y: number; w: number; h: number; page: number }
+}
+```
+
+**PdfExtractResult** (interface)
+```typescript
+interface PdfExtractResult {
+  url: string; method: 'text' | 'vision'; pagesRead: number; fields: Record<string, any>; fieldsMeta?: Record<string, PdfFieldMeta>
+}
+```
+
+**PdfBarcode** (interface)
+```typescript
+interface PdfBarcode {
+  type: string; format: string; value: string; page: number; bbox?: { x: number; y: number; w: number; h: number }; confidence: number
+}
+```
+
+**PdfDecodeBarcodesResult** (interface)
+```typescript
+interface PdfDecodeBarcodesResult {
+  url: string; pagesScanned: number; codes: PdfBarcode[]
+}
+```
+
+**PdfGraphicsPage** (interface)
+```typescript
+interface PdfGraphicsPage {
+  page: number; paths: number; images: number; textRuns: number; colourSpaces: string[]
+}
+```
+
+**PdfInspectGraphicsResult** (interface)
+```typescript
+interface PdfInspectGraphicsResult {
+  url: string; pages: PdfGraphicsPage[]; spotColours: string[]; note: string
+}
+```
+
 **ResponsesAgentTrace** (interface)
 ```typescript
 interface ResponsesAgentTrace {
@@ -2135,6 +2339,18 @@ interface AppFunctionDef {
   dataScope?: 'collection' | 'global';
   apiVersion?: string;
   handler?: string;
+  agent?: AppFunctionAgentExposure;
+}
+```
+
+**AppFunctionAgentExposure** (interface)
+```typescript
+interface AppFunctionAgentExposure {
+  tool: boolean;
+  title?: string;
+  description?: string;
+  input?: Record<string, any>;
+  approval?: 'auto' | 'require';
 }
 ```
 
@@ -11250,6 +11466,10 @@ Get the active transfer/status for a proof (owner, collection admin, or the name
       request: PublicChatRequest) → `Promise<PublicChatResponse>`
 Chat with product assistant (RAG)
 
+**agentRun**(collectionId: string,
+      body: PublicAgentRunRequest) → `Promise<AgentRunResult>`
+Public agent loop — run the orchestration-neutral tool loop on the consumer surface. Exposes an app's PUBLIC server functions (`agent.tool:true`, `visibility:'public'`) to a consumer assistant; built-in tools are opt-in by explicit `server_tools[]` allowlist only. The caller runs as the signed-in consumer ('owner', send the authKit bearer) or anonymous ('public'). POST /public/collection/:collectionId/ai/agent/run
+
 **getSession**(collectionId: string, sessionId: string) → `Promise<Session>`
 Get session history
 
@@ -11483,6 +11703,22 @@ Reverse lookup by ref via POST (public). `POST /public/collection/:collectionId/
 **renderSource**(collectionId: string,
     body: TemplateRenderSourceRequest) → `Promise<TemplateRenderSourceResponse>`
 
+### tools
+
+**run**(collectionId: string,
+      name: K,
+      args: AiToolArgsMap[K],) → `Promise<ToolRunResult>
+    export async function run<T = any>(
+      collectionId: string,
+      name: string,
+      args?: Record<string, any>,
+    ): Promise<ToolRunResult<T>>
+    export async function run(
+      collectionId: string,
+      name: string,
+      args: Record<string, any> =`
+Invoke ONE built-in server tool directly — no model in the loop. This is the "direct code" caller of the orchestration-neutral tool registry: the SAME tools the agent loop and the Responses `server_tools` path run, but called as a plain, typed, deterministic API. A front end can use it two ways: (1) call a tool straight as an API (e.g. `pdf.render` / `pdf.extract` behind a PDF UX), or (2) drive its OWN agent loop and execute each model tool-call here. Capability-gated server-side to the caller's grants (same blast-radius rules as the agent loop). POST /admin/collection/:collectionId/ai/tools/:name/run
+
 ### translations
 
 **hashText**(text: string, options?: TranslationHashOptions) → `Promise<string>`

package/docs/agent-tools.md

@@ -69,6 +69,34 @@ The platform derives an **MCP tool list** from your manifest and drives the stan
 → `tools/call` → structured result — with streaming, cancellation, and approval layered on. You don't
 implement the wire protocol; you declare tools and write handlers. (The live loop is the staged part.)
 
+## Client tools (front-end)
+
+For genuinely UI-coupled actions — read a field the user is editing, open a picker, update on-page
+state — declare a **client tool**: the model calls it, but it runs in your page, not on the server.
+Build each with `ai.defineClientTool` and drive the loop with `ai.runWithClientTools`, which resolves
+every client call automatically (suspend → run handler → resubmit) until the assistant answers:
+
+```ts
+const pickDate = SL.ai.defineClientTool(
+  'ui.pickDate',
+  { description: 'Open the date picker and return the chosen ISO date.',
+    input: { type: 'object', properties: { min: { type: 'string' } } } },
+  async ({ min }) => ({ date: await openDatePicker({ min }) })   // runs in the browser
+)
+
+const result = await SL.ai.runWithClientTools(collectionId, {
+  input: 'Book me the earliest slot next week',
+  tools: [pickDate],
+  toolbelt: { builtins: ['web.search'], appFunctions: [{ appId: 'booking' }] }, // mix all three kinds
+  // surface: 'public'  // for a consumer assistant
+})
+```
+
+The handler runs with the user's own session (auto-scoped), and only tools you declared can be called
+(a call for anything else throws). A client-tool name can never collide with a built-in or a server
+function — those always win. This is the third tool **kind**, alongside built-in tools and app
+functions, all declared together in one `toolbelt`.
+
 ## Security
 
 Identical to server functions — nothing new to reason about: