@objectstack/service-ai 4.0.0 → 4.0.2

package/dist/index.d.cts

@@ -1,6 +1,9 @@
-import { AIToolDefinition, AIToolCall, AIToolResult, IAIService, IAIConversationService, LLMAdapter, Logger, AIMessage, AIRequestOptions, AIResult, AIStreamEvent, ChatWithToolsOptions, AIConversation, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
+import { AIToolDefinition, ToolCallPart, ToolResultPart, IAIService, IAIConversationService, LLMAdapter, Logger, ModelMessage, AIRequestOptions, AIResult, TextStreamPart, ToolSet, ChatWithToolsOptions, AIConversation, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { Plugin, PluginContext } from '@objectstack/core';
+import { LanguageModelV2 } from '@ai-sdk/provider';
+import { TextStreamPart as TextStreamPart$1, ToolSet as ToolSet$1 } from 'ai';
+import { Tool } from '@objectstack/spec/ai';
 import { Agent } from '@objectstack/spec';
 import { z } from 'zod';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
@@ -11,6 +14,13 @@ import * as _objectstack_spec_data from '@objectstack/spec/data';
  * Receives parsed arguments and returns the tool output as a string.
  */
 type ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
+/**
+ * Extended ToolResultPart that carries an `isError` flag for internal
+ * error-tracking in the tool-call loop.
+ */
+interface ToolExecutionResult extends ToolResultPart {
+    isError?: boolean;
+}
 /**
  * ToolRegistry — Central registry for AI-callable tools.
  *
@@ -50,11 +60,11 @@ declare class ToolRegistry {
     /**
      * Execute a tool call and return the result.
      */
-    execute(toolCall: AIToolCall): Promise<AIToolResult>;
+    execute(toolCall: ToolCallPart): Promise<ToolExecutionResult>;
     /**
      * Execute multiple tool calls in parallel.
      */
-    executeAll(toolCalls: AIToolCall[]): Promise<AIToolResult[]>;
+    executeAll(toolCalls: ToolCallPart[]): Promise<ToolExecutionResult[]>;
     /**
      * Clear all registered tools.
      */
@@ -97,13 +107,15 @@ declare class AIService implements IAIService {
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
-    chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult>;
+    chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult>;
     complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
-    streamChat(messages: AIMessage[], options?: AIRequestOptions): AsyncIterable<AIStreamEvent>;
+    streamChat(messages: ModelMessage[], options?: AIRequestOptions): AsyncIterable<TextStreamPart<ToolSet>>;
     embed(input: string | string[], model?: string): Promise<number[][]>;
     listModels(): Promise<string[]>;
     /** Default maximum iterations for the tool call loop. */
     static readonly DEFAULT_MAX_ITERATIONS = 10;
+    /** Extract the text value from a ToolExecutionResult's output. */
+    private static extractOutputText;
     /**
      * Chat with automatic tool call resolution.
      *
@@ -115,7 +127,15 @@ declare class AIService implements IAIService {
      * 4. Repeats until the model produces a final text response or the
      *    maximum number of iterations (`maxIterations`) is reached.
      */
-    chatWithTools(messages: AIMessage[], options?: ChatWithToolsOptions): Promise<AIResult>;
+    chatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): Promise<AIResult>;
+    /**
+     * Stream chat with automatic tool call resolution.
+     *
+     * Works like {@link chatWithTools} but yields SSE events.  When the model
+     * requests tool calls during streaming, they are executed and the results
+     * fed back until a final text stream is produced.
+     */
+    streamChatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): AsyncIterable<TextStreamPart<ToolSet>>;
 }
 
 /**
@@ -160,6 +180,19 @@ declare class AIServicePlugin implements Plugin {
     private service?;
     private readonly options;
     constructor(options?: AIServicePluginOptions);
+    /**
+     * Auto-detect LLM provider from environment variables.
+     *
+     * Priority order:
+     * 1. AI_GATEWAY_MODEL → Vercel AI Gateway
+     * 2. OPENAI_API_KEY → OpenAI
+     * 3. ANTHROPIC_API_KEY → Anthropic
+     * 4. GOOGLE_GENERATIVE_AI_API_KEY → Google
+     * 5. Fallback → MemoryLLMAdapter
+     *
+     * Returns the adapter and a description for logging.
+     */
+    private detectAdapter;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     destroy(): Promise<void>;
@@ -173,13 +206,81 @@ declare class AIServicePlugin implements Plugin {
  */
 declare class MemoryLLMAdapter implements LLMAdapter {
     readonly name = "memory";
-    chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult>;
+    chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult>;
     complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
-    streamChat(messages: AIMessage[], _options?: AIRequestOptions): AsyncIterable<AIStreamEvent>;
+    streamChat(messages: ModelMessage[], _options?: AIRequestOptions): AsyncIterable<TextStreamPart<ToolSet>>;
     embed(input: string | string[]): Promise<number[][]>;
     listModels(): Promise<string[]>;
 }
 
+/**
+ * VercelLLMAdapter — Production LLM adapter powered by the Vercel AI SDK.
+ *
+ * Wraps `generateText` / `streamText` from the `ai` package, delegating to
+ * any Vercel AI SDK–compatible model provider (OpenAI, Anthropic, Google,
+ * Ollama, etc.).
+ *
+ * @example
+ * ```typescript
+ * import { openai } from '@ai-sdk/openai';
+ * import { VercelLLMAdapter } from '@objectstack/service-ai';
+ *
+ * const adapter = new VercelLLMAdapter({ model: openai('gpt-4o') });
+ * ```
+ */
+declare class VercelLLMAdapter implements LLMAdapter {
+    readonly name = "vercel";
+    private readonly model;
+    constructor(config: VercelLLMAdapterConfig);
+    chat(messages: ModelMessage[], options?: AIRequestOptions): Promise<AIResult>;
+    complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
+    streamChat(messages: ModelMessage[], options?: AIRequestOptions): AsyncIterable<TextStreamPart<ToolSet>>;
+    embed(_input: string | string[]): Promise<number[][]>;
+    listModels(): Promise<string[]>;
+}
+/**
+ * Configuration for the Vercel LLM adapter.
+ */
+interface VercelLLMAdapterConfig {
+    /**
+     * A Vercel AI SDK–compatible language model instance.
+     *
+     * @example `openai('gpt-4o')` or `anthropic('claude-sonnet-4-20250514')`
+     */
+    model: LanguageModelV2;
+}
+
+/**
+ * Vercel AI SDK v6 — UI Message Stream Encoder
+ *
+ * Converts `AsyncIterable<TextStreamPart<ToolSet>>` (the internal ObjectStack
+ * streaming format) into the Vercel AI SDK v6 **UI Message Stream Protocol**.
+ *
+ * Wire format: Server-Sent Events (SSE) with JSON payloads.
+ *   `data: {"type":"text-delta","id":"0","delta":"Hello"}\n\n`
+ *
+ * The client-side `DefaultChatTransport` from `ai` v6 uses
+ * `parseJsonEventStream` to parse these SSE events.
+ *
+ * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+ */
+
+/**
+ * Encode a single `TextStreamPart` event into SSE-formatted UI Message
+ * Stream chunk(s).
+ *
+ * Returns an empty string for event types that have no wire-format mapping.
+ */
+declare function encodeStreamPart(part: TextStreamPart$1<ToolSet$1>): string;
+/**
+ * Transform an `AsyncIterable<TextStreamPart>` into an `AsyncIterable<string>`
+ * where each yielded string is an SSE-formatted UI Message Stream chunk.
+ *
+ * Lifecycle order required by the client:
+ *   start → start-step → text-start → text-delta* → text-end → finish-step → finish → [DONE]
+ */
+declare function encodeVercelDataStream(events: AsyncIterable<TextStreamPart$1<ToolSet$1>>): AsyncIterable<string>;
+
 /**
  * InMemoryConversationService — Reference implementation of IAIConversationService.
  *
@@ -203,7 +304,7 @@ declare class InMemoryConversationService implements IAIConversationService {
         limit?: number;
         cursor?: string;
     }): Promise<AIConversation[]>;
-    addMessage(conversationId: string, message: AIMessage): Promise<AIConversation>;
+    addMessage(conversationId: string, message: ModelMessage): Promise<AIConversation>;
     delete(conversationId: string): Promise<void>;
     /** Total number of stored conversations. */
     get size(): number;
@@ -237,7 +338,7 @@ declare class ObjectQLConversationService implements IAIConversationService {
         limit?: number;
         cursor?: string;
     }): Promise<AIConversation[]>;
-    addMessage(conversationId: string, message: AIMessage): Promise<AIConversation>;
+    addMessage(conversationId: string, message: ModelMessage): Promise<AIConversation>;
     delete(conversationId: string): Promise<void>;
     /**
      * Safely parse a JSON string, returning `undefined` on failure.
@@ -248,7 +349,7 @@ declare class ObjectQLConversationService implements IAIConversationService {
      */
     private toConversation;
     /**
-     * Map a database row to an AIMessage.
+     * Map a database row to a ModelMessage.
      */
     private toMessage;
 }
@@ -284,6 +385,158 @@ declare const DATA_TOOL_DEFINITIONS: AIToolDefinition[];
  */
 declare function registerDataTools(registry: ToolRegistry, context: DataToolContext): void;
 
+/**
+ * create_object — AI Tool Metadata
+ *
+ * Creates a new data object (table) with schema validation.
+ * Validates snake_case naming for object and initial fields,
+ * checks for duplicates, and registers the object definition.
+ */
+declare const createObjectTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/**
+ * add_field — AI Tool Metadata
+ *
+ * Adds a new field (column) to an existing data object.
+ * Validates snake_case for objectName, field name, reference,
+ * and select option values before merging into the definition.
+ */
+declare const addFieldTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/**
+ * modify_field — AI Tool Metadata
+ *
+ * Modifies an existing field definition (label, type, required, default value, etc.)
+ * on a data object. Does not support renaming the field.
+ */
+declare const modifyFieldTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/**
+ * delete_field — AI Tool Metadata
+ *
+ * Removes a field (column) from an existing data object.
+ * This is a destructive operation.
+ */
+declare const deleteFieldTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/**
+ * list_metadata_objects — AI Tool Metadata
+ *
+ * Lists all registered metadata objects (tables) with optional filtering.
+ * Uses a unique name (`list_metadata_objects`) to avoid collision with
+ * the data-tools `list_objects` tool.
+ */
+declare const listMetadataObjectsTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/**
+ * describe_metadata_object — AI Tool Metadata
+ *
+ * Returns the full metadata schema of a data object including all
+ * fields, types, relationships, and configuration. Uses a unique name
+ * (`describe_metadata_object`) to avoid collision with the data-tools
+ * `describe_object` tool.
+ */
+declare const describeMetadataObjectTool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    requiresConfirmation: boolean;
+    active: boolean;
+    builtIn: boolean;
+    category?: "flow" | "action" | "vector_search" | "data" | "utility" | "integration" | "analytics" | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
+    objectName?: string | undefined;
+    permissions?: string[] | undefined;
+};
+
+/** All built-in metadata management tool definitions (Tool metadata). */
+declare const METADATA_TOOL_DEFINITIONS: Tool[];
+/**
+ * Services required by the metadata management tools.
+ *
+ * Provided by the kernel at `ai:ready` time and closed over
+ * by the handler functions so they stay framework-agnostic.
+ */
+interface MetadataToolContext {
+    /** Metadata service for schema CRUD operations. */
+    metadataService: IMetadataService;
+}
+/**
+ * Register all built-in metadata management tools on the given {@link ToolRegistry}.
+ *
+ * Typically called from the `ai:ready` hook after the metadata service is available.
+ *
+ * @example
+ * ```ts
+ * ctx.hook('ai:ready', async (aiService) => {
+ *   const metadataService = ctx.getService<IMetadataService>('metadata');
+ *   registerMetadataTools(aiService.toolRegistry, { metadataService });
+ * });
+ * ```
+ */
+declare function registerMetadataTools(registry: ToolRegistry, context: MetadataToolContext): void;
+
 /**
  * Context passed alongside a user message when chatting with an agent.
  *
@@ -312,6 +565,17 @@ interface AgentChatContext {
 declare class AgentRuntime {
     private readonly metadataService;
     constructor(metadataService: IMetadataService);
+    /**
+     * List all active agents registered in the metadata service.
+     *
+     * Returns a summary for each agent (name, label, role) suitable
+     * for populating an agent selector dropdown in the UI.
+     */
+    listAgents(): Promise<Array<{
+        name: string;
+        label: string;
+        role: string;
+    }>>;
     /**
      * Load and validate an agent definition by name.
      *
@@ -325,7 +589,7 @@ declare class AgentRuntime {
      * Build the system message(s) that should be prepended to the
      * conversation when chatting with the given agent.
      */
-    buildSystemMessages(agent: Agent, context?: AgentChatContext): AIMessage[];
+    buildSystemMessages(agent: Agent, context?: AgentChatContext): ModelMessage[];
     /**
      * Derive {@link AIRequestOptions} from an agent definition.
      *
@@ -360,6 +624,27 @@ declare class AgentRuntime {
  */
 declare const DATA_CHAT_AGENT: Agent;
 
+/**
+ * Built-in `metadata_assistant` agent definition.
+ *
+ * This agent powers AI-driven metadata management — users can create objects,
+ * add/modify/delete fields, and inspect schema definitions through natural
+ * language conversation.
+ *
+ * It is registered automatically by the AI service plugin alongside the
+ * `data_chat` agent when the metadata service is available.
+ *
+ * @example
+ * ```
+ * POST /api/v1/ai/agents/metadata_assistant/chat
+ * {
+ *   "messages": [{ "role": "user", "content": "Create a contracts table with name, value, and status fields" }],
+ *   "context": {}
+ * }
+ * ```
+ */
+declare const METADATA_ASSISTANT_AGENT: Agent;
+
 /**
  * XState-inspired State Machine Protocol
  * Used to define strict business logic constraints and lifecycle management.
@@ -423,7 +708,7 @@ declare const AiConversationObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "json" | "text" | "avatar" | "vector" | "date" | "tags" | "lookup" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress";
+        type: "number" | "boolean" | "file" | "text" | "json" | "code" | "avatar" | "vector" | "date" | "tags" | "lookup" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -607,7 +892,7 @@ declare const AiConversationObject: Omit<{
     } | undefined;
     versioning?: {
         enabled: boolean;
-        strategy: "snapshot" | "delta" | "event-sourcing";
+        strategy: "delta" | "snapshot" | "event-sourcing";
         versionField: string;
         retentionDays?: number | undefined;
     } | undefined;
@@ -683,11 +968,7 @@ declare const AiConversationObject: Omit<{
     keyPrefix?: string | undefined;
     actions?: {
         name: string;
-        label: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        };
+        label: string;
         type: "url" | "script" | "modal" | "flow" | "api";
         refreshAfter: boolean;
         objectName?: string | undefined;
@@ -698,44 +979,24 @@ declare const AiConversationObject: Omit<{
         execute?: string | undefined;
         params?: {
             name: string;
-            label: string | {
-                key: string;
-                defaultValue?: string | undefined;
-                params?: Record<string, string | number | boolean> | undefined;
-            };
+            label: string;
             type: "number" | "boolean" | "date" | "lookup" | "file" | "url" | "json" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
             required: boolean;
             options?: {
-                label: string | {
-                    key: string;
-                    defaultValue?: string | undefined;
-                    params?: Record<string, string | number | boolean> | undefined;
-                };
+                label: string;
                 value: string;
             }[] | undefined;
         }[] | undefined;
         variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
-        confirmText?: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        } | undefined;
-        successMessage?: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        } | undefined;
+        confirmText?: string | undefined;
+        successMessage?: string | undefined;
         visible?: string | undefined;
         disabled?: string | boolean | undefined;
         shortcut?: string | undefined;
         bulkEnabled?: boolean | undefined;
         timeout?: number | undefined;
         aria?: {
-            ariaLabel?: string | {
-                key: string;
-                defaultValue?: string | undefined;
-                params?: Record<string, string | number | boolean> | undefined;
-            } | undefined;
+            ariaLabel?: string | undefined;
             ariaDescribedBy?: string | undefined;
             role?: string | undefined;
         } | undefined;
@@ -1888,7 +2149,7 @@ declare const AiMessageObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "json" | "text" | "avatar" | "vector" | "date" | "tags" | "lookup" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress";
+        type: "number" | "boolean" | "file" | "text" | "json" | "code" | "avatar" | "vector" | "date" | "tags" | "lookup" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -2072,7 +2333,7 @@ declare const AiMessageObject: Omit<{
     } | undefined;
     versioning?: {
         enabled: boolean;
-        strategy: "snapshot" | "delta" | "event-sourcing";
+        strategy: "delta" | "snapshot" | "event-sourcing";
         versionField: string;
         retentionDays?: number | undefined;
     } | undefined;
@@ -2148,11 +2409,7 @@ declare const AiMessageObject: Omit<{
     keyPrefix?: string | undefined;
     actions?: {
         name: string;
-        label: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        };
+        label: string;
         type: "url" | "script" | "modal" | "flow" | "api";
         refreshAfter: boolean;
         objectName?: string | undefined;
@@ -2163,44 +2420,24 @@ declare const AiMessageObject: Omit<{
         execute?: string | undefined;
         params?: {
             name: string;
-            label: string | {
-                key: string;
-                defaultValue?: string | undefined;
-                params?: Record<string, string | number | boolean> | undefined;
-            };
+            label: string;
             type: "number" | "boolean" | "date" | "lookup" | "file" | "url" | "json" | "text" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
             required: boolean;
             options?: {
-                label: string | {
-                    key: string;
-                    defaultValue?: string | undefined;
-                    params?: Record<string, string | number | boolean> | undefined;
-                };
+                label: string;
                 value: string;
             }[] | undefined;
         }[] | undefined;
         variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
-        confirmText?: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        } | undefined;
-        successMessage?: string | {
-            key: string;
-            defaultValue?: string | undefined;
-            params?: Record<string, string | number | boolean> | undefined;
-        } | undefined;
+        confirmText?: string | undefined;
+        successMessage?: string | undefined;
         visible?: string | undefined;
         disabled?: string | boolean | undefined;
         shortcut?: string | undefined;
         bulkEnabled?: boolean | undefined;
         timeout?: number | undefined;
         aria?: {
-            ariaLabel?: string | {
-                key: string;
-                defaultValue?: string | undefined;
-                params?: Record<string, string | number | boolean> | undefined;
-            } | undefined;
+            ariaLabel?: string | undefined;
             ariaDescribedBy?: string | undefined;
             role?: string | undefined;
         } | undefined;
@@ -3349,12 +3586,31 @@ interface RouteDefinition {
     path: string;
     /** Human-readable description */
     description: string;
+    /** Whether this route requires authentication (default: true). */
+    auth?: boolean;
+    /** Required permissions for accessing this route. */
+    permissions?: string[];
     /**
      * Handler receives a plain request-like object and returns a response-like
      * object.  SSE responses set `stream: true` and provide an async iterable.
      */
     handler: (req: RouteRequest) => Promise<RouteResponse>;
 }
+/**
+ * Authenticated user context attached to a route request.
+ *
+ * Populated by the auth middleware when `RouteDefinition.auth` is `true`.
+ */
+interface RouteUserContext {
+    /** Unique user identifier. */
+    userId: string;
+    /** User display name (optional). */
+    displayName?: string;
+    /** Roles assigned to the user (e.g. `['admin', 'user']`). */
+    roles?: string[];
+    /** Fine-grained permissions (e.g. `['ai:chat', 'ai:admin']`). */
+    permissions?: string[];
+}
 interface RouteRequest {
     /** Parsed JSON body (for POST requests) */
     body?: unknown;
@@ -3362,6 +3618,8 @@ interface RouteRequest {
     params?: Record<string, string>;
     /** Query string parameters */
     query?: Record<string, string>;
+    /** Authenticated user context (populated by auth middleware). */
+    user?: RouteUserContext;
 }
 interface RouteResponse {
     /** HTTP status code */
@@ -3372,6 +3630,14 @@ interface RouteResponse {
     stream?: boolean;
     /** Async iterable of SSE events (when stream=true) */
     events?: AsyncIterable<unknown>;
+    /**
+     * When `true`, the HTTP server layer should encode the `events` iterable
+     * using the Vercel AI Data Stream Protocol frame format (`0:`, `9:`, `d:`, …)
+     * instead of generic SSE `data:` lines.
+     *
+     * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+     */
+    vercelDataStream?: boolean;
 }
 /**
  * Build the standard AI REST/SSE routes.
@@ -3399,8 +3665,9 @@ declare function buildAIRoutes(aiService: IAIService, conversationService: IAICo
  *
  * | Method | Path | Description |
  * |:---|:---|:---|
+ * | GET  | /api/v1/ai/agents | List all active agents |
  * | POST | /api/v1/ai/agents/:agentName/chat | Chat with a specific agent |
  */
 declare function buildAgentRoutes(aiService: AIService, agentRuntime: AgentRuntime, logger: Logger): RouteDefinition[];
 
-export { AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, DATA_CHAT_AGENT, DATA_TOOL_DEFINITIONS, type DataToolContext, InMemoryConversationService, MemoryLLMAdapter, ObjectQLConversationService, type RouteDefinition, type RouteRequest, type RouteResponse, type ToolHandler, ToolRegistry, buildAIRoutes, buildAgentRoutes, registerDataTools };
+export { AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, DATA_CHAT_AGENT, DATA_TOOL_DEFINITIONS, type DataToolContext, InMemoryConversationService, METADATA_ASSISTANT_AGENT, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ObjectQLConversationService, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type ToolExecutionResult, type ToolHandler, ToolRegistry, VercelLLMAdapter, type VercelLLMAdapterConfig, addFieldTool, buildAIRoutes, buildAgentRoutes, createObjectTool, deleteFieldTool, describeMetadataObjectTool, encodeStreamPart, encodeVercelDataStream, listMetadataObjectsTool, modifyFieldTool, registerDataTools, registerMetadataTools };