@proveanything/smartlinks 2.0.5 → 2.0.9

package/dist/docs/agent-tools.md

@@ -0,0 +1,111 @@
+# Agent tools — exposing your app's actions to the SmartLinks agent
+
+> **SmartLinks SDK 2.x.** Redraft of the earlier "Agent Skills & Tools" RFC, now built on
+> [server functions](server-functions.md). **Staged rollout:** the *declaration + discovery* ship in
+> V2 (do them now); the *live agent loop* (a parent chat agent calling your tools) lights up when the
+> platform agent can consume them. Everything you declare is useful before then — a tool is a server
+> function, already invocable via http/event.
+
+## The model: app-authored capabilities
+
+An app declares **capabilities** — app-authored logic the platform runs, each with a declared
+security envelope (`visibility` / `authority` / `capabilities`). There is **one engine** (the
+server-functions runtime) and several **triggers** into it: `http`, `event`, `cron`, and **`agent`**.
+
+**An agent tool is not a new runtime — it's an MCP-shaped facade over a capability.** By default a
+tool *is a server function*: the agent's `tools/call` routes into the same `(ctx, event) => result`
+with the same capability envelope. You author the logic once; the agent is just another caller.
+
+Use a **client tool** (a `postMessage` handler in your live admin iframe) only for genuinely
+UI-coupled actions that must run in the open app. It is **not** the default — headless server
+functions are, because they work whether or not your UI is mounted.
+
+## Declaring a tool
+
+You already declare server functions in `app.manifest.json` (see
+[server-functions.md](server-functions.md)). Mark one **agent-invocable** and give the agent what it
+needs to call it — a description and an input schema:
+
+```jsonc
+{
+  "functions": {
+    "files": { "js": { "umd": "dist/functions.umd.js" } },
+    "definitions": [
+      {
+        "name": "createFaq",
+        "trigger": { "type": "http", "methods": ["POST"] },
+        "visibility": "admin",
+        "authority": "collection",
+        "capabilities": ["sl:records:write"],
+
+        // ── makes it an agent tool ──
+        "agent": {
+          "tool": true,
+          "title": "Create an FAQ entry",
+          "description": "Add a question/answer to this collection's FAQ. Use when the user asks to add or draft an FAQ.",
+          "input": { /* JSON Schema for the arguments the agent supplies as event.body */ },
+          "approval": "auto"        // auto | require  (require = human confirmation before the call)
+        }
+      }
+    ]
+  }
+}
+```
+
+The handler is an ordinary server function — the agent-supplied arguments arrive as `event.body`:
+
+```js
+export async function createFaq(ctx, event) {
+  const { question, answer } = event.body || {}
+  // validate, then act with your declared authority/capabilities:
+  const rec = await ctx.sl.appRecords.create({ recordType: 'faq', data: { question, answer } })
+  return { id: rec.id }
+}
+```
+
+## What the agent sees (MCP shape)
+
+The platform derives an **MCP tool list** from your manifest and drives the standard flow — `tools/list`
+→ `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.)
+
+## Security
+
+Identical to server functions — nothing new to reason about:
+- **`visibility`** — who may call (admin/public).
+- **`authority`** — whose identity `ctx.sl` carries (`caller` vs `collection`).
+- **`capabilities`** — least-privilege, capped even when elevated.
+- **`agent.approval: "require"`** — the agent must get human confirmation before invoking (use for
+  destructive or public-facing actions).
+
+Untrusted third-party tools run in the platform's isolated runner — the same boundary as untrusted
+server functions.
+
+## Replacing `app.admin.json` AI setup
+
+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).
+
+## What ships now vs staged
+
+| Now (V2) | Staged (on the platform agent) |
+|---|---|
+| The `agent` declaration in the manifest | The live agent conversation calling your tools |
+| 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
+
+Do it in order — each step is a drop-in migration prompt (see the migration steps that ship with the
+SDK). Roughly:
+
+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).
+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.
+
+Steps 1–2 are safe to ship now; step 3 as you migrate each app off the old AI path.

package/dist/docs/ai.md

@@ -14,8 +14,7 @@ Build AI-powered SmartLinks experiences with a practical SDK guide for responses
 - [RAG: Product Assistants](#rag-product-assistants)
 - [Voice Integration](#voice-integration)
 - [Podcast Generation](#podcast-generation)
-- [Type Definitions](#type-definitions)
-- [API Reference](#api-reference)
+- [Types & API reference](#types--api-reference)
 - [Usage Examples](#usage-examples)
 - [Error Handling](#error-handling)
 - [Rate Limiting](#rate-limiting)
@@ -38,6 +37,13 @@ This guide is written for SDK users building real products, not backend operator
 | Add spoken input/output | Use [Voice Integration](#voice-integration) |
 | Add progressive rendering | Use [Streaming Responses](#streaming-responses) or [Streaming Chat](#streaming-chat) |
 
+> **Which AI chat API? Three surfaces, three jobs — don't confuse them:**
+> - **`ai.chat.responses`** — the **default for new work**. Structured input, tool use, multi-agent, streaming; you manage any history. Reach for this first.
+> - **`ai.chat.completions`** — **OpenAI-compatible** (`messages[]`). Use it *only* to drop into existing OpenAI-style code; prefer Responses for anything new.
+> - **`ai.public.chat`** (+ `getSession` / `clearSession`) — the **public product assistant** with **server-managed conversation sessions** (RAG-grounded). This is the "ongoing conversation" surface, and it's public-facing.
+>
+> Responses and Completions are *generation* APIs (not single-shot vs conversation — both take history); `ai.public.chat` is the one that keeps a conversation for you.
+
 ### Recommended starting points
 
 - New AI features: start with `ai.chat.responses.create(...)`
@@ -845,426 +851,16 @@ const audioUrl = URL.createObjectURL(audioBlob);
 
 ---
 
-## Type Definitions
-
-### Core Types
-
-```typescript
-/**
- * Chat message with role and content
- */
-interface ChatMessage {
-  role: 'system' | 'user' | 'assistant' | 'function' | 'tool';
-  content: string | ContentPart[];
-  name?: string;
-  function_call?: FunctionCall;
-  tool_calls?: ToolCall[];
-  tool_call_id?: string;
-}
-
-/**
- * Chat completion request
- */
-interface ChatCompletionRequest {
-  messages: ChatMessage[];
-  model?: string;
-  stream?: boolean;
-  tools?: ToolDefinition[];
-  tool_choice?: 'none' | 'auto' | 'required' | { type: 'function'; function: { name: string } };
-  temperature?: number;       // 0-2, default: 0.7
-  max_tokens?: number;
-  top_p?: number;
-  frequency_penalty?: number;
-  presence_penalty?: number;
-  response_format?: { type: 'text' | 'json_object' };
-  user?: string;
-}
-
-/**
- * Chat completion response
- */
-interface ChatCompletionResponse {
-  id: string;
-  object: 'chat.completion';
-  created: number;
-  model: string;
-  choices: ChatCompletionChoice[];
-  usage: {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-  };
-}
-
-/**
- * Streaming chunk
- */
-interface ChatCompletionChunk {
-  id: string;
-  object: 'chat.completion.chunk';
-  created: number;
-  model: string;
-  choices: Array<{
-    index: number;
-    delta: Partial<ChatMessage>;
-    finish_reason: string | null;
-  }>;
-}
-```
-
-### RAG Types
-
-```typescript
-/**
- * Index document request
- */
-interface IndexDocumentRequest {
-  productId: string;
-  text?: string;              // Either text or documentUrl required
-  documentUrl?: string;
-  metadata?: Record<string, any>;
-  chunkSize?: number;         // Default: 500
-  overlap?: number;           // Default: 50
-  provider?: 'openai' | 'gemini';
-}
-
-/**
- * Configure assistant request
- */
-interface ConfigureAssistantRequest {
-  productId: string;
-  systemPrompt?: string;
-  model?: string;
-  maxTokensPerResponse?: number;
-  temperature?: number;
-  rateLimitPerUser?: number;
-  allowedTopics?: string[];
-  customInstructions?: Record<string, any>;
-}
-
-/**
- * Public chat request
- */
-interface PublicChatRequest {
-  productId: string;
-  userId: string;
-  message: string;
-  sessionId?: string;
-  stream?: boolean;
-}
-
-/**
- * Public chat response
- */
-interface PublicChatResponse {
-  message: string;
-  sessionId: string;
-  usage: {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-  };
-  context?: {
-    chunksUsed: number;
-    topSimilarity: number;
-  };
-}
-```
-
-### Podcast Types
-
-```typescript
-/**
- * Podcast generation request
- */
-interface GeneratePodcastRequest {
-  productId: string;
-  documentText?: string;      // Optional if document already indexed
-  duration?: number;          // Target duration in minutes (default: 10)
-  style?: 'casual' | 'professional' | 'educational' | 'entertaining';
-  voices?: {
-    host1?: string;           // Voice name for first host
-    host2?: string;           // Voice name for second host
-  };
-  includeAudio?: boolean;     // Generate audio files (default: false)
-  language?: string;          // Default: 'en-US'
-  customInstructions?: string;
-}
-
-/**
- * Podcast script segment
- */
-interface PodcastSegment {
-  speaker: 'host1' | 'host2';
-  text: string;
-  timestamp?: number;         // Start time in seconds
-  duration?: number;          // Segment duration
-}
-
-/**
- * Podcast script
- */
-interface PodcastScript {
-  title: string;
-  description: string;
-  segments: PodcastSegment[];
-}
-
-/**
- * Podcast generation response
- */
-interface GeneratePodcastResponse {
-  success: boolean;
-  podcastId: string;
-  script: PodcastScript;
-  audio?: {
-    host1Url?: string;        // URL to download host 1 audio
-    host2Url?: string;        // URL to download host 2 audio
-    mixedUrl?: string;        // URL to download mixed podcast
-  };
-  metadata: {
-    duration: number;         // Actual duration in seconds
-    wordCount: number;
-    generatedAt: string;
-  };
-}
-
-/**
- * Podcast status
- */
-interface PodcastStatus {
-  podcastId: string;
-  status: 'generating_script' | 'generating_audio' | 'mixing' | 'completed' | 'failed';
-  progress: number;           // 0-100
-  estimatedTimeRemaining?: number;  // Seconds
-  error?: string;
-  result?: GeneratePodcastResponse; // Available when completed
-}
-
-/**
- * TTS request
- */
-interface TTSRequest {
-  text: string;
-  voice?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
-  speed?: number;             // 0.25 - 4.0, default: 1.0
-  format?: 'mp3' | 'opus' | 'aac' | 'flac';  // Default: mp3
-}
-```
-
-### Error Types
-
-```typescript
-/**
- * API Error response
- */
-interface AIError {
-  error: {
-    message: string;
-    type: string;
-    code: string;
-    param?: string;
-    resetAt?: string;  // ISO 8601 timestamp (for rate limits)
-  };
-}
-
-/**
- * Custom error class
- */
-class SmartLinksAIError extends Error {
-  type: string;
-  code: string;
-  statusCode: number;
-  resetAt?: string;
-
-  isRateLimitError(): boolean;
-  isAuthError(): boolean;
-  isNotFoundError(): boolean;
-}
-```
-
----
-
-## API Reference
-
-### Admin Endpoints
-
-#### `ai.chat.completions.create(collectionId, request)`
-
-Create a chat completion (OpenAI-compatible).
-
-**Parameters:**
-- `collectionId` (string) - Collection ID
-- `request` (ChatCompletionRequest) - Request parameters
-
-**Returns:** `Promise<ChatCompletionResponse | AsyncIterable<ChatCompletionChunk>>`
-
-**Example:**
-```typescript
-const response = await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [{ role: 'user', content: 'Hello!' }]
-});
-```
-
----
-
-#### `ai.models.list(collectionId)`
-
-List available AI models.
-
-**Returns:** `Promise<ModelList>`
-
----
-
-#### `ai.models.get(collectionId, modelId)`
 
-Get specific model information.
-
-**Parameters:**
-- `modelId` (string) - Model identifier (e.g., 'google/gemini-2.5-flash')
-
-**Returns:** `Promise<AIModel>`
-
----
-
-#### `ai.rag.indexDocument(collectionId, request)`
-
-Index a document for RAG.
-
-**Parameters:**
-- `request` (IndexDocumentRequest) - Document and indexing parameters
-
-**Returns:** `Promise<IndexDocumentResponse>`
-
----
-
-#### `ai.rag.configureAssistant(collectionId, request)`
-
-Configure AI assistant behavior.
-
-**Parameters:**
-- `request` (ConfigureAssistantRequest) - Assistant configuration
-
-**Returns:** `Promise<ConfigureAssistantResponse>`
-
----
-
-#### `ai.sessions.stats(collectionId)`
-
-Get session statistics.
-
-**Returns:** `Promise<SessionStatistics>`
-
----
-
-#### `ai.rateLimit.reset(collectionId, userId)`
-
-Reset rate limit for a user.
-
-**Returns:** `Promise<{ success: boolean; userId: string }>`
-
----
+## Types & API reference
 
-#### `ai.podcast.generate(collectionId, request)`
+Full TypeScript types and the per-endpoint HTTP reference for every `SL.ai.*` method live in the
+**generated** references — they're not duplicated here so they can't drift:
 
-Generate a NotebookLM-style conversational podcast.
+- **[`API_SUMMARY.md`](API_SUMMARY.md)** — every function signature + type (search `ai.`).
+- **[`openapi.yaml`](../openapi.yaml)** — the raw HTTP endpoints.
 
-**Parameters:**
-- `request` (GeneratePodcastRequest) - Podcast generation parameters
-
-**Returns:** `Promise<GeneratePodcastResponse>`
-
-**Example:**
-```typescript
-const podcast = await ai.podcast.generate('my-collection', {
-  productId: 'coffee-maker-deluxe',
-  duration: 5,
-  style: 'casual',
-  voices: { host1: 'nova', host2: 'onyx' },
-  includeAudio: true
-});
-```
-
----
-
-#### `ai.podcast.getStatus(collectionId, podcastId)`
-
-Get podcast generation status.
-
-**Parameters:**
-- `podcastId` (string) - Podcast identifier
-
-**Returns:** `Promise<PodcastStatus>`
-
----
-
-#### `ai.tts.generate(collectionId, request)`
-
-Generate text-to-speech audio.
-
-**Parameters:**
-- `request` (TTSRequest) - TTS parameters
-
-**Returns:** `Promise<Blob>`
-
-**Example:**
-```typescript
-const audioBlob = await ai.tts.generate('my-collection', {
-  text: 'Welcome to our podcast!',
-  voice: 'nova',
-  speed: 1.0
-});
-```
-
----
-
-### Public Endpoints
-
-#### `ai.public.chat(collectionId, request)`
-
-Chat with product assistant (no auth required).
-
-**Parameters:**
-- `request` (PublicChatRequest) - Chat parameters
-
-**Returns:** `Promise<PublicChatResponse>`
-
-**Rate Limited:** Yes (20 requests/hour per userId by default)
-
----
-
-#### `ai.public.getSession(collectionId, sessionId)`
-
-Get conversation history.
-
-**Returns:** `Promise<Session>`
-
----
-
-#### `ai.public.clearSession(collectionId, sessionId)`
-
-Clear conversation history.
-
-**Returns:** `Promise<{ success: boolean }>`
-
----
-
-#### `ai.public.getRateLimit(collectionId, userId)`
-
-Check rate limit status.
-
-**Returns:** `Promise<RateLimitStatus>`
-
----
-
-#### `ai.public.getToken(collectionId, request)`
-
-Generate ephemeral token for Gemini Live.
-
-**Returns:** `Promise<EphemeralTokenResponse>`
-
----
+For inline types, use LSP hover / go-to-definition on `SL.ai.*`.
 
 ## Usage Examples
 
@@ -1428,108 +1024,6 @@ function ProductHelp() {
 }
 ```
 
-### Example 5: Voice Q&A
-
-```typescript
-async function voiceQA() {
-  if (!ai.voice.isSupported()) {
-    console.error('Voice not supported in this browser');
-    return;
-  }
-
-  console.log('Speak your question...');
-  
-  // Listen for voice input
-  const question = await ai.voice.listen('en-US');
-  console.log('You asked:', question);
-
-  // Get answer from AI
-  const response = await ai.public.chat('my-collection', {
-    productId: 'coffee-maker-deluxe',
-    userId: 'user-123',
-    message: question
-  });
-
-  // Display answer
-  console.log('Answer:', response.message);
-
-  // Speak answer
-  await ai.voice.speak(response.message);
-}
-```
-
-### Example 6: Generate Product Podcast
-
-```typescript
-async function generateProductPodcast() {
-  // Generate a casual 5-minute podcast about the coffee maker
-  const podcast = await ai.podcast.generate('my-collection', {
-    productId: 'coffee-maker-deluxe',
-    duration: 5,              // minutes
-    style: 'casual',          // Conversational style
-    voices: {
-      host1: 'nova',          // Female voice
-      host2: 'onyx'           // Male voice
-    },
-    includeAudio: true
-  });
-
-  console.log('Podcast Title:', podcast.script.title);
-  console.log('Duration:', podcast.metadata.duration, 'seconds');
-  
-  // Display script
-  console.log('\nScript:');
-  podcast.script.segments.forEach((segment, i) => {
-    const speaker = segment.speaker === 'host1' ? 'Host 1' : 'Host 2';
-    console.log(`\n${speaker}: ${segment.text}`);
-  });
-
-  // Download audio
-  if (podcast.audio?.mixedUrl) {
-    console.log('\nDownload podcast:', podcast.audio.mixedUrl);
-  }
-}
-```
-
-### Example 7: Podcast with Progress Tracking
-
-```typescript
-async function generatePodcastWithProgress() {
-  // Start podcast generation
-  const podcast = await ai.podcast.generate('my-collection', {
-    productId: 'coffee-maker-deluxe',
-    duration: 10,
-    style: 'professional',
-    includeAudio: true
-  });
-
-  const podcastId = podcast.podcastId;
-
-  // Poll for status
-  const checkStatus = async () => {
-    const status = await ai.podcast.getStatus('my-collection', podcastId);
-    
-    console.log(`Status: ${status.status} (${status.progress}%)`);
-    
-    if (status.status === 'completed' && status.result) {
-      console.log('Podcast ready!');
-      console.log('Listen:', status.result.audio?.mixedUrl);
-      return true;
-    } else if (status.status === 'failed') {
-      console.error('Generation failed:', status.error);
-      return true;
-    }
-    
-    return false;
-  };
-
-  // Check every 5 seconds
-  const interval = setInterval(async () => {
-    const done = await checkStatus();
-    if (done) clearInterval(interval);
-  }, 5000);
-}
-```
 
 ---