@proveanything/smartlinks 2.0.9 → 2.0.11

package/dist/ai-tools.d.ts

@@ -0,0 +1,35 @@
+import type { AiToolName, AiToolCapability } from './types/ai.js';
+export interface BuiltinAiToolDescriptor {
+    /** Canonical tool name, e.g. 'web.search'. */
+    name: AiToolName;
+    /** One-line summary of what the tool does (mirrors the server registry). */
+    description: string;
+    /** Capability tags the tool requires. */
+    capabilities: AiToolCapability[];
+    /** Grouping for tool-picker UIs. */
+    group: 'web' | 'vision' | 'image' | 'media' | 'net' | 'text';
+}
+/** Stable name constants — reference tools without stringly-typed literals. */
+export declare const AI_TOOL_NAMES: {
+    readonly WEB_FETCH_PAGE: "web.fetchPage";
+    readonly WEB_EXTRACT_SCHEMA: "web.extractSchema";
+    readonly WEB_SCREENSHOT: "web.screenshot";
+    readonly WEB_SEARCH: "web.search";
+    readonly BRAND_ASSETS: "brand.assets";
+    readonly DOCUMENT_READ: "document.read";
+    readonly DATA_EXTRACT: "data.extract";
+    readonly IMAGE_DESCRIBE: "image.describe";
+    readonly IMAGE_GENERATE: "image.generate";
+    readonly IMAGE_FROM_REFERENCE: "image.fromReference";
+    readonly IMAGE_SEARCH_STOCK: "image.searchStock";
+    readonly IMAGE_TRANSFORM: "image.transform";
+    readonly PDF_CREATE: "pdf.create";
+    readonly PDF_FILL: "pdf.fill";
+    readonly PDF_MERGE: "pdf.merge";
+    readonly HTTP_REQUEST: "http.request";
+    readonly TRANSLATE: "translate";
+};
+/** The curated core toolset shipped with the SDK. */
+export declare const BUILTIN_AI_TOOLS: BuiltinAiToolDescriptor[];
+/** Look up a core tool descriptor by name. */
+export declare function getBuiltinAiTool(name: AiToolName): BuiltinAiToolDescriptor | undefined;

package/dist/ai-tools.js

@@ -0,0 +1,69 @@
+// src/ai-tools.ts
+//
+// The core built-in AI tools, as a typed, design-time catalog. Apps learn the core
+// tools from HERE (autocomplete + docs), not by probing an endpoint — so they know
+// what exists and how to call it at build time. The server-side registry
+// (GET /ai/catalog) remains the runtime source of truth and is where future
+// app-contributed tools appear; this list is the curated, tested core set that ships
+// with the SDK. Adding a core tool is a deliberate change here plus a version bump.
+/** Stable name constants — reference tools without stringly-typed literals. */
+export const AI_TOOL_NAMES = {
+    WEB_FETCH_PAGE: 'web.fetchPage',
+    WEB_EXTRACT_SCHEMA: 'web.extractSchema',
+    WEB_SCREENSHOT: 'web.screenshot',
+    WEB_SEARCH: 'web.search',
+    BRAND_ASSETS: 'brand.assets',
+    DOCUMENT_READ: 'document.read',
+    DATA_EXTRACT: 'data.extract',
+    IMAGE_DESCRIBE: 'image.describe',
+    IMAGE_GENERATE: 'image.generate',
+    IMAGE_FROM_REFERENCE: 'image.fromReference',
+    IMAGE_SEARCH_STOCK: 'image.searchStock',
+    IMAGE_TRANSFORM: 'image.transform',
+    PDF_CREATE: 'pdf.create',
+    PDF_FILL: 'pdf.fill',
+    PDF_MERGE: 'pdf.merge',
+    HTTP_REQUEST: 'http.request',
+    TRANSLATE: 'translate',
+};
+/** The curated core toolset shipped with the SDK. */
+export const BUILTIN_AI_TOOLS = [
+    { name: 'web.search', group: 'web', capabilities: ['web:read'],
+        description: 'Search the live web; returns candidate results (url/title/description) to then read.' },
+    { name: 'web.fetchPage', group: 'web', capabilities: ['web:read'],
+        description: 'Fetch a web page and return clean markdown, metadata, and any schema.org JSON-LD.' },
+    { name: 'web.extractSchema', group: 'web', capabilities: ['web:read'],
+        description: 'Fetch a URL and return only its schema.org structured data of a given @type (deterministic).' },
+    { name: 'document.read', group: 'web', capabilities: ['web:read'],
+        description: 'Read a document at a URL — PDF, deck, doc, or article — into clean markdown text.' },
+    { name: 'data.extract', group: 'web', capabilities: ['web:read'],
+        description: 'Extract typed JSON from a page given a schema and/or prompt — turn a page into UI data.' },
+    { name: 'brand.assets', group: 'web', capabilities: ['web:read'],
+        description: "Extract a site's brand elements — logo, colours, design — plus page metadata." },
+    { name: 'web.screenshot', group: 'web', capabilities: ['web:read'],
+        description: 'Capture a page screenshot; returns a hosted image URL you can read with image.describe.' },
+    { name: 'image.describe', group: 'vision', capabilities: ['ai:vision'],
+        description: 'Describe an image or read its text (vision / image-to-text).' },
+    { name: 'image.generate', group: 'image', capabilities: ['ai:image'],
+        description: 'Generate a new image from a text prompt; returns a hosted image URL.' },
+    { name: 'image.fromReference', group: 'image', capabilities: ['ai:image'],
+        description: 'Generate an image guided by reference image(s) plus a prompt (image-to-image).' },
+    { name: 'image.searchStock', group: 'image', capabilities: ['ai:image'],
+        description: 'Search stock photography (Unsplash) for real photos matching a query.' },
+    { name: 'image.transform', group: 'media', capabilities: ['media:image'],
+        description: 'Transform an image: resize/crop/rotate/flip/grayscale/tint/format-convert/compress → hosted URL.' },
+    { name: 'pdf.create', group: 'media', capabilities: ['media:pdf'],
+        description: 'Render HTML to a PDF and return a hosted URL.' },
+    { name: 'pdf.fill', group: 'media', capabilities: ['media:pdf'],
+        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: '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'],
+        description: 'Translate text into one or more target languages (generic, model-based).' },
+];
+/** Look up a core tool descriptor by name. */
+export function getBuiltinAiTool(name) {
+    return BUILTIN_AI_TOOLS.find((t) => t.name === name);
+}

package/dist/api/ai.d.ts

@@ -1,5 +1,5 @@
-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, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } 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, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto, };
+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, 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, 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 {
         namespace responses {
@@ -141,27 +141,23 @@ declare namespace aiInternal {
      * Generate text/content via AI (admin)
      * @deprecated Use ai.chat.completions.create() instead
      */
-    function generateContent(collectionId: string, params: AIGenerateContentRequest, admin?: boolean): Promise<any>;
+    function generateContent(collectionId: string, params: AIGenerateContentRequest, admin?: boolean): Promise<AIGenerateContentResponse>;
     /**
      * Generate an image via AI (admin)
      */
-    function generateImage(collectionId: string, params: AIGenerateImageRequest): Promise<any>;
+    function generateImage(collectionId: string, params: AIGenerateImageRequest): Promise<AIGenerateImageResponse>;
     /**
      * Search stock photos or similar via AI (admin)
      */
-    function searchPhotos(collectionId: string, params: AISearchPhotosRequest): Promise<AISearchPhotosPhoto[]>;
+    function searchPhotos(collectionId: string, params: AISearchPhotosRequest): Promise<AISearchPhotosResponse>;
     /**
      * Upload a file for AI usage (admin). Pass FormData for binary uploads.
      */
-    function uploadFile(collectionId: string, params: any): Promise<any>;
+    function uploadFile(collectionId: string, params: any): Promise<AIUploadedFile>;
     /**
      * Create or warm a cache for AI (admin)
      */
-    function createCache(collectionId: string, params: any): Promise<any>;
-    /**
-     * Post a chat message to the AI (admin or public)
-     */
-    function postChat(collectionId: string, params: any, admin?: boolean): Promise<any>;
+    function createCache(collectionId: string, params: any): Promise<AICacheRef>;
 }
 export declare const ai: {
     chat: {
@@ -219,5 +215,4 @@ export declare const ai: {
     searchPhotos: typeof aiInternal.searchPhotos;
     uploadFile: typeof aiInternal.uploadFile;
     createCache: typeof aiInternal.createCache;
-    postChat: typeof aiInternal.postChat;
 };

package/dist/api/ai.js

@@ -345,6 +345,7 @@ var aiInternal;
     async function generateContent(collectionId, params, admin = true) {
         const base = admin ? '/admin' : '/public';
         const path = `${base}/collection/${encodeURIComponent(collectionId)}/ai/generateContent`;
+        // Normalised envelope — text is at candidates[0].content.parts[0].text.
         return post(path, params);
     }
     aiInternal.generateContent = generateContent;
@@ -361,6 +362,7 @@ var aiInternal;
      */
     async function searchPhotos(collectionId, params) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/searchPhotos`;
+        // The API wraps the photos in an envelope — the array is on `.results`.
         return post(path, params);
     }
     aiInternal.searchPhotos = searchPhotos;
@@ -380,15 +382,6 @@ var aiInternal;
         return post(path, params);
     }
     aiInternal.createCache = createCache;
-    /**
-     * Post a chat message to the AI (admin or public)
-     */
-    async function postChat(collectionId, params, admin = true) {
-        const base = admin ? '/admin' : '/public';
-        const path = `${base}/collection/${encodeURIComponent(collectionId)}/ai/postChat`;
-        return post(path, params);
-    }
-    aiInternal.postChat = postChat;
 })(aiInternal || (aiInternal = {}));
 export const ai = {
     chat: {
@@ -446,5 +439,4 @@ export const ai = {
     searchPhotos: aiInternal.searchPhotos,
     uploadFile: aiInternal.uploadFile,
     createCache: aiInternal.createCache,
-    postChat: aiInternal.postChat,
 };

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.9  |  Generated: 2026-09-21T16:23:55.650Z
+Version: 2.0.11  |  Generated: 2026-09-21T19:28:09.956Z
 
 This is a concise summary of all available API functions and types.
 
@@ -580,6 +580,11 @@ interface ResponsesRequest {
   max_concurrent_subagents?: number
   }
   service_tier?: 'auto' | 'standard' | 'flex' | 'priority'
+  server_tools?: boolean | AiToolName[]
+  allowCapabilities?: AiToolCapability[]
+  only?: AiToolName[]
+  exclude?: AiToolName[]
+  maxSteps?: number
 }
 ```
 
@@ -604,6 +609,7 @@ interface ResponsesResult {
   conversation?: unknown
   provider: 'openai'
   responseTime: number
+  _agent?: ResponsesAgentTrace
 }
 ```
 
@@ -1010,14 +1016,98 @@ interface AISearchPhotosRequest {
 **AISearchPhotosPhoto** (interface)
 ```typescript
 interface AISearchPhotosPhoto {
+  id?: string
   url: string
+  thumb?: string
   alt?: string
+  width?: number
+  height?: number
   photographer?: string
   photographerUrl?: string
   [key: string]: any
 }
 ```
 
+**AISearchPhotosResponse** (interface)
+```typescript
+interface AISearchPhotosResponse {
+  provider: string
+  results: AISearchPhotosPhoto[]
+  total?: number
+  total_pages?: number
+  [key: string]: any
+}
+```
+
+**AIGeneratedImage** (interface)
+```typescript
+interface AIGeneratedImage {
+  url: string | null
+  b64_json: string | null
+  revised_prompt?: string
+  [key: string]: any
+}
+```
+
+**AIGenerateImageResponse** (interface)
+```typescript
+interface AIGenerateImageResponse {
+  provider: string
+  model?: string
+  images: AIGeneratedImage[]
+  [key: string]: any
+}
+```
+
+**AIGenerateContentCandidate** (interface)
+```typescript
+interface AIGenerateContentCandidate {
+  content?: { parts?: Array<{ text?: string; [k: string]: any }>; role?: string; [k: string]: any }
+  finishReason?: string
+  [key: string]: any
+}
+```
+
+**AIGenerateContentResponse** (interface)
+```typescript
+interface AIGenerateContentResponse {
+  provider?: string
+  model?: string
+  candidates?: AIGenerateContentCandidate[]
+  usageMetadata?: {
+  promptTokenCount?: number
+  candidatesTokenCount?: number
+  totalTokenCount?: number
+  [k: string]: any
+  }
+  responseTime?: number
+  [key: string]: any
+}
+```
+
+**AIUploadedFile** (interface)
+```typescript
+interface AIUploadedFile {
+  name?: string
+  uri?: string
+  url?: string
+  mimeType?: string
+  sizeBytes?: number | string
+  state?: string
+  [key: string]: any
+}
+```
+
+**AICacheRef** (interface)
+```typescript
+interface AICacheRef {
+  name?: string
+  model?: string
+  expireTime?: string
+  [key: string]: any
+}
+```
+
 **AgentRunRequest** (interface)
 ```typescript
 interface AgentRunRequest {
@@ -1104,6 +1194,258 @@ interface CatalogResponse {
 }
 ```
 
+**WebFetchPageArgs** (interface)
+```typescript
+interface WebFetchPageArgs {
+  url: string; type?: string; forceRefresh?: boolean
+}
+```
+
+**WebExtractSchemaArgs** (interface)
+```typescript
+interface WebExtractSchemaArgs {
+  url: string; schemaType?: string; forceRefresh?: boolean
+}
+```
+
+**WebScreenshotArgs** (interface)
+```typescript
+interface WebScreenshotArgs {
+  url: string
+}
+```
+
+**WebSearchArgs** (interface)
+```typescript
+interface WebSearchArgs {
+  query: string; limit?: number; scrapeContent?: boolean
+}
+```
+
+**BrandAssetsArgs** (interface)
+```typescript
+interface BrandAssetsArgs {
+  url: string
+}
+```
+
+**DocumentReadArgs** (interface)
+```typescript
+interface DocumentReadArgs {
+  url: string; forceRefresh?: boolean
+}
+```
+
+**DataExtractArgs** (interface)
+```typescript
+interface DataExtractArgs {
+  url: string; schema?: Record<string, any>; prompt?: string
+}
+```
+
+**ImageDescribeArgs** (interface)
+```typescript
+interface ImageDescribeArgs {
+  imageUrl: string; prompt?: string
+}
+```
+
+**ImageGenerateArgs** (interface)
+```typescript
+interface ImageGenerateArgs {
+  prompt: string; size?: string; provider?: 'openai' | 'gemini'
+}
+```
+
+**ImageFromReferenceArgs** (interface)
+```typescript
+interface ImageFromReferenceArgs {
+  prompt: string; imageUrls: string[]; size?: string; model?: string
+}
+```
+
+**ImageSearchStockArgs** (interface)
+```typescript
+interface ImageSearchStockArgs {
+  query: string; per_page?: number; orientation?: 'landscape' | 'portrait' | 'squarish'
+}
+```
+
+**ImageTransformArgs** (interface)
+```typescript
+interface ImageTransformArgs {
+  imageUrl: string
+  resize?: { width?: number; height?: number; fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'; allowUpscale?: boolean }
+  crop?: { left: number; top: number; width: number; height: number }
+  rotate?: number
+  flip?: boolean
+  flop?: boolean
+  grayscale?: boolean
+  tint?: string
+  modulate?: { brightness?: number; saturation?: number; hue?: number; lightness?: number }
+  format?: 'jpeg' | 'png' | 'webp' | 'avif'
+  quality?: number
+}
+```
+
+**PdfCreateArgs** (interface)
+```typescript
+interface PdfCreateArgs {
+  html: string; format?: string; landscape?: boolean
+}
+```
+
+**PdfFillArgs** (interface)
+```typescript
+interface PdfFillArgs {
+  url: string; fields: Record<string, string | number | boolean>; flatten?: boolean
+}
+```
+
+**PdfMergeArgs** (interface)
+```typescript
+interface PdfMergeArgs {
+  urls: string[]
+}
+```
+
+**HttpRequestArgs** (interface)
+```typescript
+interface HttpRequestArgs {
+  url: string; method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'; headers?: Record<string, string>; body?: any
+}
+```
+
+**TranslateArgs** (interface)
+```typescript
+interface TranslateArgs {
+  text: string; targetLanguages: string[]; sourceLanguage?: string
+}
+```
+
+**AiToolArgsMap** (interface)
+```typescript
+interface AiToolArgsMap {
+  'web.fetchPage': WebFetchPageArgs
+  'web.extractSchema': WebExtractSchemaArgs
+  'web.screenshot': WebScreenshotArgs
+  'web.search': WebSearchArgs
+  'brand.assets': BrandAssetsArgs
+  'document.read': DocumentReadArgs
+  'data.extract': DataExtractArgs
+  'image.describe': ImageDescribeArgs
+  'image.generate': ImageGenerateArgs
+  'image.fromReference': ImageFromReferenceArgs
+  'image.searchStock': ImageSearchStockArgs
+  'image.transform': ImageTransformArgs
+  'pdf.create': PdfCreateArgs
+  'pdf.fill': PdfFillArgs
+  'pdf.merge': PdfMergeArgs
+  'http.request': HttpRequestArgs
+  'translate': TranslateArgs
+}
+```
+
+**WebSearchResultItem** (interface)
+```typescript
+interface WebSearchResultItem {
+  url: string | null; title: string | null; description: string | null; markdown?: string
+}
+```
+
+**WebSearchResult** (interface)
+```typescript
+interface WebSearchResult {
+  query: string; results: WebSearchResultItem[]
+}
+```
+
+**DocumentReadResult** (interface)
+```typescript
+interface DocumentReadResult {
+  url: string; text: string | null; metadata?: any; provider?: string; cached?: boolean
+}
+```
+
+**DataExtractResult** (interface)
+```typescript
+interface DataExtractResult {
+  url: string; data: Record<string, any>
+}
+```
+
+**WebFetchPageResult** (interface)
+```typescript
+interface WebFetchPageResult {
+  url: string; markdown?: string | null; html?: string | null; metadata?: any; schemas?: any[]; provider?: string; cached?: boolean; status?: number | null
+}
+```
+
+**ImageDescribeResult** (interface)
+```typescript
+interface ImageDescribeResult {
+  imageUrl: string; text: string | null
+}
+```
+
+**HostedAssetResult** (interface)
+```typescript
+interface HostedAssetResult {
+  hostedUrl: string | null; contentType?: string; info?: { width?: number; height?: number; format?: string; size?: number }
+}
+```
+
+**HttpRequestResult** (interface)
+```typescript
+interface HttpRequestResult {
+  status: number; headers: Record<string, any>; body: any; truncated: boolean; finalUrl: string
+}
+```
+
+**TranslateResult** (interface)
+```typescript
+interface TranslateResult {
+  translations: Record<string, string>; sourceLanguage: string
+}
+```
+
+**ResponsesAgentTrace** (interface)
+```typescript
+interface ResponsesAgentTrace {
+  steps: number
+  maxStepsReached: boolean
+  toolResults: AgentToolResult[]
+  availableTools: string[]
+}
+```
+
+**AgentToolCallEvent** (interface)
+```typescript
+interface AgentToolCallEvent {
+  type: 'agent.tool_call'; name: string; args: Record<string, any>
+}
+```
+
+**AgentToolResultEvent** (interface)
+```typescript
+interface AgentToolResultEvent {
+  type: 'agent.tool_result'; name: string; isError: boolean; result: any
+}
+```
+
+**AgentResponseCompletedEvent** (interface)
+```typescript
+interface AgentResponseCompletedEvent {
+  type: 'response.completed'; response: ResponsesResult; _agent: ResponsesAgentTrace
+}
+```
+
+**AiToolCapability** = ``
+
+**AiToolName** = ``
+
+**AgentStreamEvent** = ``
+
 ### analytics
 
 **AnalyticsLocation** (interface)

package/dist/docs/agent-tools.md

@@ -81,12 +81,21 @@ Identical to server functions — nothing new to reason about:
 Untrusted third-party tools run in the platform's isolated runner — the same boundary as untrusted
 server functions.
 
-## Replacing `app.admin.json` AI setup
+## Working with `app.admin.json` (complement, not replacement)
 
-This supersedes the `app.admin.json` "AI setup" schema-extraction model (the outer agent reading a
-schema and handing back JSON blobs). Instead the app owns its domain logic and exposes **real,
-capability-scoped actions** the agent invokes — with multi-turn and streaming. The AI-schema path is
-**deprecated as of V2** (still works through the V2 line; removed later).
+`app.admin.json` stays the **canonical declarative config contract** — setup questions, config schema,
+import fields, tunable settings, content hints. It's inspectable, validatable, deterministic, and
+reused by many consumers at once (the admin form renderer, AI setup, a signup journey asking the same
+questions, bulk import). Agent tools **do not replace it — they serve and adapt it**:
+
+- Keep the declarative schema as the default and source of truth.
+- When you want *dynamic, contextual* behaviour — "which questions for **this** collection?", "the
+  config schema as it stands right now", "apply these answers" — expose a small function/tool that
+  reads the declaration and returns a tailored result. **Static-first; dynamic only where it earns its
+  keep.**
+
+There's no rip-and-replace and nothing to migrate off: an app happy with its `app.admin.json` keeps
+it untouched.
 
 ## What ships now vs staged
 
@@ -96,16 +105,19 @@ capability-scoped actions** the agent invokes — with multi-turn and streaming.
 | SDK types for it; tool descriptors surfaced for discovery | `tools/call` streaming, cancellation, cross-app toolbelt arbitration |
 | Your handlers run today via http/event | Human-approval UX for `approval: "require"` |
 
-## Adopting this in an existing app
+## Adopting this — opt-in, per app, no fleet migration
+
+Agent tools are **purely additive**. There is **no migration pass**, and nothing breaks if you never
+adopt them — an existing app on the V2 SDK simply *gains the ability* to add them whenever you want.
+You do **not** touch every app; you turn it on for one app at a time.
 
-Do it in order — each step is a drop-in migration prompt (see the migration steps that ship with the
-SDK). Roughly:
+To turn them on for a single app (say, an FAQ app), once it's on the V2 SDK:
 
-1. **Server functions** — add the `functions` block + build target + test harness (if the app
-   doesn't have them). See [server-functions.md](server-functions.md).
+1. **Server functions** — add the `functions` block + build target + test harness if the app doesn't
+   already have them. See [server-functions.md](server-functions.md).
 2. **Expose tools** — add the `agent` block to the functions you want the agent to call; give each a
-   title/description/input schema and an approval mode.
-3. **Retire `app.admin.json` AI setup** — move any AI-authoring behaviour to tools; drop the
-   AI-schema block.
+   title / description / input schema and an approval mode.
 
-Steps 1–2 are safe to ship now; step 3 as you migrate each app off the old AI path.
+That's it — declare and build. The live agent loop is staged (see the table above); until it ships,
+your handlers still run via http/event, so declaring tools now is **forward-compatible, not
+speculative breakage**. `app.admin.json` stays as-is throughout — nothing to retire.