@proveanything/smartlinks 2.0.26 → 2.0.29

package/dist/ai-tools.d.ts

@@ -26,6 +26,11 @@ 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 PDF_DECODE_BARCODES: "pdf.decodeBarcodes";
+    readonly PDF_INSPECT_GRAPHICS: "pdf.inspectGraphics";
     readonly HTTP_REQUEST: "http.request";
     readonly TRANSLATE: "translate";
 };

package/dist/ai-tools.js

@@ -23,6 +23,11 @@ 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',
+    PDF_DECODE_BARCODES: 'pdf.decodeBarcodes',
+    PDF_INSPECT_GRAPHICS: 'pdf.inspectGraphics',
     HTTP_REQUEST: 'http.request',
     TRANSLATE: 'translate',
 };
@@ -58,6 +63,16 @@ 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. Optional per-field confidence/source (includeConfidence) and bounding boxes (includeBoxes).' },
+    { name: 'pdf.decodeBarcodes', group: 'media', capabilities: ['web:read'],
+        description: 'Deterministically decode 1D/2D barcodes (EAN/UPC/QR/Code128/DataMatrix/…) on a PDF page by rasterizing and running a WASM decoder — reliable barcode/QR values where vision hallucinates. Returns value, symbology, page, bbox, confidence. No AI.' },
+    { name: 'pdf.inspectGraphics', group: 'media', capabilities: ['web:read'],
+        description: 'Prepress structural inspection: per-page vector-path/image/outlined-text counts + colour spaces used, plus document-level named SPOT colours (e.g. "PANTONE 871 C"). Answers whether spot/foil plates survived. Deterministic, no AI.' },
     { 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.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/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/ai.md

@@ -324,15 +324,40 @@ in `input`.
 | `image.searchStock` | Search real stock photos (Unsplash). |
 | `image.transform` | Resize / crop / rotate / grayscale / format-convert / compress → hosted URL. |
 | `pdf.create` | Render HTML → PDF → hosted URL. |
-| `pdf.fill` | Fill an AcroForm PDF's fields → hosted URL. |
-| `pdf.merge` | Merge several PDFs into one → hosted URL. |
+| `pdf.fill` | Fill an AcroForm PDF's fields (`{ field: value }`) → hosted URL. |
+| `pdf.merge` | Merge several PDFs into one, in order → hosted URL. |
+| `pdf.inspect` | Cheap, no-AI introspection: page count/sizes, which pages have a real text layer, raster present, and a routing hint (`text` vs `vision`). |
+| `pdf.render` | Rasterize one page to a PNG at a chosen DPI → hosted image URL (feed to vision, or screenshot a page). |
+| `pdf.extract` | PDF → typed JSON in one call (schema and/or prompt). Auto-routes text vs vision. Optional per-field `confidence`/`source` (`includeConfidence`) and `bbox` (`includeBoxes`) in `fieldsMeta`. |
+| `pdf.decodeBarcodes` | Deterministically decode barcodes/QR on a page (WASM, no AI) → value + symbology + page + bbox + confidence. Use this for barcode digits, never vision. |
+| `pdf.inspectGraphics` | Prepress inspection: per-page path/image/outlined-text counts + colour spaces, plus named SPOT colours (e.g. "PANTONE 871 C"). No AI. |
 | `http.request` | SSRF-guarded outbound HTTP(S) to a public URL (call a REST API). |
 | `translate` | Translate text into one or more languages (generic, model-based). |
 
+**Working with PDFs.** The PDF tools split into *read/analyse* and *produce*:
+
+- **Read a whole PDF as text** → `document.read` (Firecrawl; good for prose/decks).
+- **Turn a PDF into structured fields** → `pdf.extract` (give it a JSON schema and/or a prompt; it
+  returns typed JSON). It routes itself, but you can drive the route yourself: call `pdf.inspect`
+  first (deterministic, no AI) to see whether each page has a real text layer, then `pdf.extract`
+  (cheap text path) or `pdf.render` → `image.describe`/vision for curve-only or raster artwork.
+- **Zoom in on small print** (INCI/allergen lists) → `pdf.render` at a high DPI (e.g. 300), then read
+  the PNG with vision.
+- **Barcodes / QR** → `pdf.decodeBarcodes` (deterministic WASM decode) — never trust vision for barcode
+  digits; it hallucinates them.
+- **Prepress / print QA** (spot colours, colour spaces, vector vs raster) → `pdf.inspectGraphics`.
+- **A review UI that flags guessed fields** → `pdf.extract` with `includeConfidence` (per-field
+  confidence + source) and `includeBoxes` (per-field bbox on text-native pages) in `fieldsMeta`.
+- **Produce a PDF** → `pdf.create` (HTML → PDF), `pdf.fill` (populate an AcroForm's fields),
+  `pdf.merge` (combine several). These return a hosted `hostedUrl`.
+
+Every tool is also directly callable without the model loop via `ai.tools.run(collectionId, name,
+args)` — e.g. render a page or extract fields straight from a UI, no agent round-trip.
+
 Discover tools two ways:
 - **Design time (typed):** import `BUILTIN_AI_TOOLS`, `AI_TOOL_NAMES`, and the per-tool arg types
-  (`WebSearchArgs`, `DataExtractArgs`, …) from the SDK. This is the core set — stable, versioned,
-  documented here.
+  (`WebSearchArgs`, `DataExtractArgs`, `PdfExtractArgs`, …) from the SDK. This is the core set —
+  stable, versioned, documented here.
 - **Runtime (live):** `await ai.catalog(collectionId)` returns the registry as the server sees it,
   including any future app-contributed tools. The built-in set above is always present.