@proveanything/smartlinks 2.0.25 → 2.0.28

package/dist/openapi.yaml

@@ -16,6 +16,8 @@ tags:
     description: Chat completion generation.
   - name: agent
     description: Agent orchestration and tool-calling.
+  - name: tools
+    description: tools API
   - name: skills
     description: Reusable agent skills.
   - name: models
@@ -1239,6 +1241,45 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/ai/tools/{name}/run:
+    post:
+      tags:
+        - tools
+      summary: tools.run
+      operationId: tools_run
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ToolRunResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /admin/collection/{collectionId}/ai/tts:
     post:
       tags:
@@ -10390,6 +10431,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/ai/agent/run:
+    post:
+      tags:
+        - publicClient
+      summary: Public agent loop — run the orchestration-neutral tool loop on the consumer surface.
+      operationId: publicClient_agentRun
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentRunResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PublicAgentRunRequest"
   /public/collection/{collectionId}/ai/chat:
     post:
       tags:
@@ -15499,6 +15572,10 @@ components:
             $ref: "#/components/schemas/AiToolName"
         maxSteps:
           type: number
+        app_functions:
+          $ref: "#/components/schemas/AgentAppFunctionsOption"
+        toolbelt:
+          $ref: "#/components/schemas/AgentToolbelt"
       required:
         - enabled
     ResponsesResult:
@@ -16530,6 +16607,162 @@ components:
           type: array
           items:
             type: string
+        appFunctions:
+          $ref: "#/components/schemas/AgentAppFunctionsOption"
+        toolbelt:
+          $ref: "#/components/schemas/AgentToolbelt"
+    AgentAppFunctionsOption:
+      type: object
+      properties:
+        appId:
+          type: string
+        channel:
+          type: string
+        only:
+          type: array
+          items:
+            type: string
+      required:
+        - appId
+    AgentToolbelt:
+      type: object
+      properties:
+        builtins:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        appFunctions:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentAppFunctionsOption"
+        clientTools:
+          type: array
+          items:
+            $ref: "#/components/schemas/ClientToolDeclaration"
+    ClientToolDeclaration:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        input:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+    ClientToolCall:
+      type: object
+      properties:
+        callId:
+          type: string
+        name:
+          type: string
+        args:
+          type: object
+          additionalProperties: true
+      required:
+        - callId
+        - name
+        - args
+    RequiresActionResult:
+      type: object
+      properties:
+        status:
+          type: string
+          enum:
+            - requires_action
+        client_tool_calls:
+          type: array
+          items:
+            $ref: "#/components/schemas/ClientToolCall"
+        items:
+          type: array
+          items: {}
+        steps:
+          type: number
+        toolResults:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentToolResult"
+        availableTools:
+          type: array
+          items:
+            type: string
+      required:
+        - status
+        - client_tool_calls
+        - items
+    ClientTool:
+      type: object
+      properties:
+        declaration:
+          $ref: "#/components/schemas/ClientToolDeclaration"
+      required:
+        - declaration
+    RunWithClientToolsOptions:
+      type: object
+      properties:
+        input:
+          type: string
+        tools:
+          type: array
+          items:
+            $ref: "#/components/schemas/ClientTool"
+        surface:
+          type: string
+          enum:
+            - admin
+            - public
+        instructions:
+          type: string
+        model:
+          type: string
+        maxSteps:
+          type: number
+        toolbelt:
+          $ref: "#/components/schemas/AgentToolbelt"
+        maxRounds:
+          type: number
+      required:
+        - input
+        - tools
+    PublicAgentRunRequest:
+      type: object
+      properties:
+        input:
+          type: string
+        prompt:
+          type: string
+        instructions:
+          type: string
+        model:
+          type: string
+        maxSteps:
+          type: number
+        server_tools:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolName"
+        only:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolName"
+        exclude:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolName"
+        allowCapabilities:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolCapability"
+        appFunctions:
+          $ref: "#/components/schemas/AgentAppFunctionsOption"
+        toolbelt:
+          $ref: "#/components/schemas/AgentToolbelt"
+        userId:
+          type: string
     AgentToolResult:
       type: object
       properties:
@@ -16542,6 +16775,20 @@ components:
         - name
         - isError
         - result
+    ToolRunResult:
+      type: object
+      properties:
+        name:
+          type: string
+        isError:
+          type: boolean
+        result:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+        - isError
+        - result
     AgentRunResult:
       type: object
       properties:
@@ -16793,6 +17040,30 @@ components:
             type: string
       required:
         - urls
+    PdfInspectArgs:
+      type: object
+      properties:
+        url:
+          type: object
+          additionalProperties: true
+      required:
+        - url
+    PdfRenderArgs:
+      type: object
+      properties:
+        url:
+          type: object
+          additionalProperties: true
+      required:
+        - url
+    PdfExtractArgs:
+      type: object
+      properties:
+        url:
+          type: object
+          additionalProperties: true
+      required:
+        - url
     HttpRequestArgs:
       type: object
       properties:
@@ -16848,6 +17119,12 @@ components:
           $ref: "#/components/schemas/PdfFillArgs"
         pdf.merge:
           $ref: "#/components/schemas/PdfMergeArgs"
+        pdf.inspect:
+          $ref: "#/components/schemas/PdfInspectArgs"
+        pdf.render:
+          $ref: "#/components/schemas/PdfRenderArgs"
+        pdf.extract:
+          $ref: "#/components/schemas/PdfExtractArgs"
         http.request:
           $ref: "#/components/schemas/HttpRequestArgs"
         translate:
@@ -16868,6 +17145,9 @@ components:
         - pdf.create
         - pdf.fill
         - pdf.merge
+        - pdf.inspect
+        - pdf.render
+        - pdf.extract
         - http.request
         - translate
     WebSearchResultItem:
@@ -16944,6 +17224,48 @@ components:
           additionalProperties: true
       required:
         - translations
+    PdfInspectPage:
+      type: object
+      properties:
+        page:
+          type: string
+          enum:
+            - text-native
+            - text+raster
+            - raster-only
+            - curve-only
+      required:
+        - page
+    PdfInspectResult:
+      type: object
+      properties:
+        url:
+          type: array
+          items:
+            type: string
+            enum:
+              - text
+              - vision
+      required:
+        - url
+    PdfRenderResult:
+      type: object
+      properties:
+        url:
+          type: object
+          additionalProperties: true
+      required:
+        - url
+    PdfExtractResult:
+      type: object
+      properties:
+        url:
+          type: string
+          enum:
+            - text
+            - vision
+      required:
+        - url
     ResponsesAgentTrace:
       type: object
       properties:
@@ -17022,6 +17344,9 @@ components:
         - pdf.create
         - pdf.fill
         - pdf.merge
+        - pdf.inspect
+        - pdf.render
+        - pdf.extract
         - http.request
         - translate
     AgentStreamEvent:
@@ -18264,9 +18589,30 @@ components:
           type: string
         handler:
           type: string
+        agent:
+          $ref: "#/components/schemas/AppFunctionAgentExposure"
       required:
         - name
         - trigger
+    AppFunctionAgentExposure:
+      type: object
+      properties:
+        tool:
+          type: boolean
+        title:
+          type: string
+        description:
+          type: string
+        input:
+          type: object
+          additionalProperties: true
+        approval:
+          type: string
+          enum:
+            - auto
+            - require
+      required:
+        - tool
     AppManifestFunctions:
       type: object
       properties:

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' | 'http.request' | 'translate';
 export interface WebFetchPageArgs {
     url: string;
     type?: string;
@@ -817,6 +940,23 @@ 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;
+}
 export interface HttpRequestArgs {
     url: string;
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
@@ -845,6 +985,9 @@ export 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;
 }
@@ -905,6 +1048,41 @@ 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;
+}
+export interface PdfExtractResult {
+    url: string;
+    method: 'text' | 'vision';
+    pagesRead: number;
+    fields: Record<string, any>;
+}
 /** 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 {