@proveanything/smartlinks 2.0.25 → 2.0.28

package/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/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/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