@proveanything/smartlinks 2.0.25 → 2.0.28

package/dist/ai-tools.d.ts

@@ -26,6 +26,9 @@ export declare const AI_TOOL_NAMES: {
     readonly PDF_CREATE: "pdf.create";
     readonly PDF_FILL: "pdf.fill";
     readonly PDF_MERGE: "pdf.merge";
+    readonly PDF_INSPECT: "pdf.inspect";
+    readonly PDF_RENDER: "pdf.render";
+    readonly PDF_EXTRACT: "pdf.extract";
     readonly HTTP_REQUEST: "http.request";
     readonly TRANSLATE: "translate";
 };

package/dist/ai-tools.js

@@ -23,6 +23,9 @@ export const AI_TOOL_NAMES = {
     PDF_CREATE: 'pdf.create',
     PDF_FILL: 'pdf.fill',
     PDF_MERGE: 'pdf.merge',
+    PDF_INSPECT: 'pdf.inspect',
+    PDF_RENDER: 'pdf.render',
+    PDF_EXTRACT: 'pdf.extract',
     HTTP_REQUEST: 'http.request',
     TRANSLATE: 'translate',
 };
@@ -58,6 +61,12 @@ export const BUILTIN_AI_TOOLS = [
         description: 'Fill an AcroForm PDF\'s fields from a { field: value } map → hosted URL.' },
     { name: 'pdf.merge', group: 'media', capabilities: ['media:pdf'],
         description: 'Merge several PDFs (by URL) into one → hosted URL.' },
+    { name: 'pdf.inspect', group: 'media', capabilities: ['web:read'],
+        description: 'Cheaply introspect a PDF before any AI call: page count/sizes, whether each page has an extractable text layer, whether a raster image is present, and a routing recommendation (text-native → cheap text pass; curve-only/raster → vision/OCR). Deterministic, no AI.' },
+    { name: 'pdf.render', group: 'media', capabilities: ['web:read'],
+        description: 'Rasterize a single PDF page to a PNG at a controllable DPI (e.g. 300 for small print) and return a hosted image URL — feed to a vision call or screenshot a page.' },
+    { name: 'pdf.extract', group: 'media', capabilities: ['web:read', 'ai:vision'],
+        description: 'Extract typed JSON from a PDF in one call given a schema and/or prompt. Auto-routes: text-layer pages use cheap text extraction; curve-only/raster pages are rendered and read with vision.' },
     { name: 'http.request', group: 'net', capabilities: ['net:http'],
         description: 'SSRF-guarded outbound HTTP(S) request to a public URL; returns status/headers/body.' },
     { name: 'translate', group: 'text', capabilities: ['ai:text'],

package/dist/api/ai.d.ts

@@ -1,4 +1,4 @@
-import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, AgentRunRequest, AgentRunResult, AgentToolsQuery, AgentToolsResponse, SkillsListResponse, CatalogResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, AiSession, AiSessionCreate, AiUsageReport, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef } from "../types/ai.js";
+import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, AgentRunRequest, AgentRunResult, AgentToolsQuery, AgentToolsResponse, ToolRunResult, AiToolName, AiToolArgsMap, PublicAgentRunRequest, ClientTool, RunWithClientToolsOptions, SkillsListResponse, CatalogResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, AiSession, AiSessionCreate, AiUsageReport, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef } from "../types/ai.js";
 export type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, AiSession, AiSessionCreate, AiUsageReport, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef, };
 declare namespace aiInternal {
     namespace chat {
@@ -34,6 +34,20 @@ declare namespace aiInternal {
          */
         function listTools(collectionId: string, query?: AgentToolsQuery): Promise<AgentToolsResponse>;
     }
+    namespace tools {
+        /**
+         * 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
+         */
+        function run<K extends AiToolName>(collectionId: string, name: K, args: AiToolArgsMap[K]): Promise<ToolRunResult>;
+        function run<T = any>(collectionId: string, name: string, args?: Record<string, any>): Promise<ToolRunResult<T>>;
+    }
     namespace skills {
         /** List the skills apps can invoke (name, description, input/output schema). */
         function list(collectionId: string): Promise<SkillsListResponse>;
@@ -135,6 +149,14 @@ declare namespace aiInternal {
          * Chat with product assistant (RAG)
          */
         function chat(collectionId: string, request: PublicChatRequest): Promise<PublicChatResponse>;
+        /**
+         * 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
+         */
+        function agentRun(collectionId: string, body: PublicAgentRunRequest): Promise<AgentRunResult>;
         /**
          * Get session history
          */
@@ -218,6 +240,23 @@ declare namespace aiInternal {
      * Create or warm a cache for AI (admin)
      */
     function createCache(collectionId: string, params: any): Promise<AICacheRef>;
+    /**
+     * Declare a client tool + its browser-side handler. The `declaration` (name/description/input) is
+     * sent to the model; the `handler` runs in the page when the model calls it — so it can touch the
+     * DOM, the user's session, local state, etc. Pair with `runWithClientTools`.
+     */
+    function defineClientTool(name: string, spec: {
+        description?: string;
+        input?: Record<string, any>;
+    }, handler: (args: Record<string, any>) => any | Promise<any>): ClientTool;
+    /**
+     * Run an agent conversation that can call CLIENT tools, resolving them in the browser automatically.
+     * Drives the suspend/resume loop: call the agent → if it suspends on a client tool
+     * (`status:'requires_action'`), run the matching handler(s), append their outputs, and resubmit —
+     * until a final answer. Built-ins + app functions ride along via `toolbelt`. Only declared tools run
+     * (a call for an unknown tool throws), and each runs with the user's own auth.
+     */
+    function runWithClientTools(collectionId: string, opts: RunWithClientToolsOptions): Promise<AgentRunResult>;
 }
 export declare const ai: {
     chat: {
@@ -251,6 +290,7 @@ export declare const ai: {
     };
     public: {
         chat: typeof aiInternal.publicClient.chat;
+        agentRun: typeof aiInternal.publicClient.agentRun;
         getSession: typeof aiInternal.publicClient.getSession;
         clearSession: typeof aiInternal.publicClient.clearSession;
         getRateLimit: typeof aiInternal.publicClient.getRateLimit;
@@ -265,6 +305,11 @@ export declare const ai: {
         run: typeof aiInternal.agent.run;
         listTools: typeof aiInternal.agent.listTools;
     };
+    tools: {
+        run: typeof aiInternal.tools.run;
+    };
+    defineClientTool: typeof aiInternal.defineClientTool;
+    runWithClientTools: typeof aiInternal.runWithClientTools;
     skills: {
         list: typeof aiInternal.skills.list;
         run: typeof aiInternal.skills.run;

package/dist/api/ai.js

@@ -90,6 +90,17 @@ var aiInternal;
         agent.listTools = listTools;
     })(agent = aiInternal.agent || (aiInternal.agent = {}));
     // ============================================================================
+    // Tools (direct, deterministic single-tool invocation — no model loop)
+    // ============================================================================
+    let tools;
+    (function (tools) {
+        async function run(collectionId, name, args = {}) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/tools/${encodeURIComponent(name)}/run`;
+            return post(path, args);
+        }
+        tools.run = run;
+    })(tools = aiInternal.tools || (aiInternal.tools = {}));
+    // ============================================================================
     // Skills + Catalog (app-facing discovery)
     // ============================================================================
     let skills;
@@ -290,6 +301,18 @@ var aiInternal;
             return post(path, request);
         }
         publicClient.chat = chat;
+        /**
+         * 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
+         */
+        async function agentRun(collectionId, body) {
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/agent/run`;
+            return post(path, body);
+        }
+        publicClient.agentRun = agentRun;
         /**
          * Get session history
          */
@@ -472,6 +495,52 @@ var aiInternal;
         return post(path, params);
     }
     aiInternal.createCache = createCache;
+    // ============================================================================
+    // Client tools (kind c) — front-end tools the model calls, executed in the page
+    // ============================================================================
+    /**
+     * Declare a client tool + its browser-side handler. The `declaration` (name/description/input) is
+     * sent to the model; the `handler` runs in the page when the model calls it — so it can touch the
+     * DOM, the user's session, local state, etc. Pair with `runWithClientTools`.
+     */
+    function defineClientTool(name, spec, handler) {
+        const declaration = { name, description: spec === null || spec === void 0 ? void 0 : spec.description, input: spec === null || spec === void 0 ? void 0 : spec.input };
+        return { declaration, handler };
+    }
+    aiInternal.defineClientTool = defineClientTool;
+    /**
+     * Run an agent conversation that can call CLIENT tools, resolving them in the browser automatically.
+     * Drives the suspend/resume loop: call the agent → if it suspends on a client tool
+     * (`status:'requires_action'`), run the matching handler(s), append their outputs, and resubmit —
+     * until a final answer. Built-ins + app functions ride along via `toolbelt`. Only declared tools run
+     * (a call for an unknown tool throws), and each runs with the user's own auth.
+     */
+    async function runWithClientTools(collectionId, opts) {
+        const { tools, surface = 'admin', maxRounds = 8 } = opts;
+        const byName = new Map(tools.map((t) => [t.declaration.name, t]));
+        const clientTools = tools.map((t) => t.declaration);
+        const toolbelt = Object.assign(Object.assign({}, (opts.toolbelt || {})), { clientTools });
+        let input = opts.input;
+        for (let round = 0; round < maxRounds; round++) {
+            const body = { input, instructions: opts.instructions, model: opts.model, maxSteps: opts.maxSteps, toolbelt };
+            const res = surface === 'public'
+                ? await publicClient.agentRun(collectionId, body)
+                : await agent.run(collectionId, body);
+            if (!res || res.status !== 'requires_action')
+                return res;
+            const outputs = [];
+            for (const call of (res.client_tool_calls || [])) {
+                const tool = byName.get(call.name);
+                if (!tool)
+                    throw new Error(`runWithClientTools: model called undeclared client tool "${call.name}"`);
+                const out = await tool.handler(call.args || {});
+                outputs.push({ type: 'function_call_output', call_id: call.callId, output: typeof out === 'string' ? out : JSON.stringify(out !== null && out !== void 0 ? out : null) });
+            }
+            input = [...(res.items || []), ...outputs];
+        }
+        throw new Error('runWithClientTools: exceeded maxRounds without a final answer');
+    }
+    aiInternal.runWithClientTools = runWithClientTools;
 })(aiInternal || (aiInternal = {}));
 export const ai = {
     chat: {
@@ -505,6 +574,7 @@ export const ai = {
     },
     public: {
         chat: aiInternal.publicClient.chat,
+        agentRun: aiInternal.publicClient.agentRun,
         getSession: aiInternal.publicClient.getSession,
         clearSession: aiInternal.publicClient.clearSession,
         getRateLimit: aiInternal.publicClient.getRateLimit,
@@ -519,6 +589,11 @@ export const ai = {
         run: aiInternal.agent.run,
         listTools: aiInternal.agent.listTools,
     },
+    tools: {
+        run: aiInternal.tools.run,
+    },
+    defineClientTool: aiInternal.defineClientTool,
+    runWithClientTools: aiInternal.runWithClientTools,
     skills: {
         list: aiInternal.skills.list,
         run: aiInternal.skills.run,

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.25  |  Generated: 2026-09-27T12:31:16.701Z
+Version: 2.0.28  |  Generated: 2026-09-28T13:20:09.049Z
 
 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,27 @@ 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
+}
+```
+
 **HttpRequestArgs** (interface)
 ```typescript
 interface HttpRequestArgs {
@@ -1399,6 +1521,9 @@ interface AiToolArgsMap {
   'pdf.create': PdfCreateArgs
   'pdf.fill': PdfFillArgs
   'pdf.merge': PdfMergeArgs
+  'pdf.inspect': PdfInspectArgs
+  'pdf.render': PdfRenderArgs
+  'pdf.extract': PdfExtractArgs
   'http.request': HttpRequestArgs
   'translate': TranslateArgs
 }
@@ -1467,6 +1592,34 @@ 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
+}
+```
+
+**PdfExtractResult** (interface)
+```typescript
+interface PdfExtractResult {
+  url: string; method: 'text' | 'vision'; pagesRead: number; fields: Record<string, any>
+}
+```
+
 **ResponsesAgentTrace** (interface)
 ```typescript
 interface ResponsesAgentTrace {
@@ -2135,6 +2288,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 +11415,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 +11652,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/dist/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:

package/dist/docs/server-functions.md

@@ -271,6 +271,96 @@ name (a first-party builtin still wins). Always prefer an appId.
 
 ---
 
+## Exposing a function to the AI agent
+
+An `http` function can be offered to the AI agent as a **callable tool**, alongside the built-in
+tools. The model calls it, the server runs it, and the result is fed back into the loop. Opt in from
+the manifest with an `agent` block (full reference: [agent-tools.md](agent-tools.md)):
+
+```jsonc
+{
+  "name": "getLoyaltyBalance",
+  "trigger": { "type": "http" },
+  "visibility": "admin",
+  "authority": "caller",
+  "capabilities": ["sl:records:read"],
+  "agent": {
+    "tool": true,
+    "title": "Loyalty balance",
+    "description": "Look up a member's current loyalty points balance.",
+    "input": {
+      "type": "object",
+      "properties": { "memberId": { "type": "string" } },
+      "required": ["memberId"]
+    },
+    "approval": "auto"                       // 'require' = human confirms before each call
+  }
+}
+```
+
+The agent becomes **just another caller surface** — your function's `visibility`, `authority`, and
+`capabilities` are enforced exactly as on the http route. Nothing new is granted. The agent's tool
+arguments arrive as the function's request `body`, and whatever you return becomes the tool result the
+model sees. `approval: "require"` tools are held back from the autonomous server-side loop until the
+human-approval UX ships.
+
+Include your app's functions in an agent run:
+
+```ts
+// Agentic Responses:
+await SL.ai.chat.responses.create(collectionId, {
+  model: 'balanced', input: 'What is member 42's balance?',
+  server_tools: true,                              // built-in tools
+  app_functions: { appId: 'my-loyalty-app' },      // + this app's ai.tool functions
+})
+
+// Or the one-shot agent loop:
+await SL.ai.agent.run(collectionId, {
+  input: '…', appFunctions: { appId: 'my-loyalty-app' },
+})
+```
+
+On the **consumer surface**, a `visibility: "public"` function reaches a public assistant via the
+public agent loop — the caller runs as the signed-in consumer (`'owner'`, send the authKit bearer) or
+anonymous (`'public'`):
+
+```ts
+await SL.ai.publicClient.agentRun(collectionId, {
+  input: '…',
+  appFunctions: { appId: 'my-app' },   // this app's public agent tools
+  server_tools: ['web.search'],         // built-ins are an explicit allowlist on the public surface
+})
+```
+
+`channel` (default `'stable'`, pass `'dev'` to test a dev build) and `only: string[]` narrow which
+functions are exposed. Only `http` functions with `agent.tool: true` are eligible; `event`/`cron`
+functions never are. A built-in tool of the same name wins the clash.
+
+### One unified toolbelt
+
+Rather than juggling `server_tools` + `app_functions`, declare everything in one `toolbelt` — built-in
+tools, one **or several** apps' functions, and (reserved, staged) front-end client tools:
+
+```ts
+await SL.ai.chat.responses.create(collectionId, {
+  input: '…',
+  toolbelt: {
+    builtins: ['web.search', 'document.read'],      // true = all, [names] = subset, omit = none
+    appFunctions: [{ appId: 'loyalty' }, { appId: 'catalog' }],  // several apps at once
+    // clientTools: [ … ]  // reserved — the client-tool bridge is staged
+  },
+})
+```
+
+The same `toolbelt` works on `ai.agent.run` and `ai.publicClient.agentRun` (on the public surface
+`builtins` is an explicit allowlist — `true` is treated as none). Precedence on a name clash: a
+built-in wins, then earlier `appFunctions` sources win over later ones.
+
+> Directly (no model): every function is also callable deterministically — `SL.functions.call` /
+> `callAdmin` (above), the same way the built-in tools are callable via `SL.ai.tools.run`.
+
+---
+
 ## Runtime — what your function can use
 
 Your function runs in a **web-standard sandbox** (think Cloudflare Workers / Deno), **not