@objectstack/service-ai 4.0.0 → 4.0.2

package/src/plugin.ts

@@ -9,8 +9,11 @@ import { buildAgentRoutes } from './routes/agent-routes.js';
 import { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
 import { AiConversationObject, AiMessageObject } from './objects/index.js';
 import { registerDataTools } from './tools/data-tools.js';
+import { registerMetadataTools } from './tools/metadata-tools.js';
 import { AgentRuntime } from './agent-runtime.js';
-import { DATA_CHAT_AGENT } from './agents/index.js';
+import { DATA_CHAT_AGENT, METADATA_ASSISTANT_AGENT } from './agents/index.js';
+import { VercelLLMAdapter } from './adapters/vercel-adapter.js';
+import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
 
 /**
  * Configuration options for the AIServicePlugin.
@@ -51,7 +54,7 @@ export class AIServicePlugin implements Plugin {
   name = 'com.objectstack.service-ai';
   version = '1.0.0';
   type = 'standard' as const;
-  dependencies: string[] = [];
+  dependencies: string[] = ['com.objectstack.engine.objectql']; // manifest service required
 
   private service?: AIService;
   private readonly options: AIServicePluginOptions;
@@ -60,6 +63,90 @@ export class AIServicePlugin implements Plugin {
     this.options = options;
   }
 
+  /**
+   * 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 async detectAdapter(ctx: PluginContext): Promise<{ adapter: LLMAdapter; description: string }> {
+    // 1. Vercel AI Gateway — works with any provider via gateway('provider/model')
+    const gatewayModel = process.env.AI_GATEWAY_MODEL;
+    if (gatewayModel) {
+      try {
+        const gatewayPkg = '@ai-sdk/gateway';
+        const { gateway } = await import(/* webpackIgnore: true */ gatewayPkg);
+        const adapter = new VercelLLMAdapter({ model: gateway(gatewayModel) });
+        return { adapter, description: `Vercel AI Gateway (model: ${gatewayModel})` };
+      } catch (err) {
+        ctx.logger.warn(
+          `[AI] Failed to load @ai-sdk/gateway for AI_GATEWAY_MODEL=${gatewayModel}, trying next provider`,
+          err instanceof Error ? { error: err.message } : undefined
+        );
+      }
+    }
+
+    // 2. Direct provider SDKs
+    const providerConfigs: Array<{
+      envKey: string;
+      pkg: string;
+      factory: string;
+      defaultModel: string;
+      displayName: string;
+    }> = [
+      {
+        envKey: 'OPENAI_API_KEY',
+        pkg: '@ai-sdk/openai',
+        factory: 'openai',
+        defaultModel: 'gpt-4o',
+        displayName: 'OpenAI'
+      },
+      {
+        envKey: 'ANTHROPIC_API_KEY',
+        pkg: '@ai-sdk/anthropic',
+        factory: 'anthropic',
+        defaultModel: 'claude-sonnet-4-20250514',
+        displayName: 'Anthropic'
+      },
+      {
+        envKey: 'GOOGLE_GENERATIVE_AI_API_KEY',
+        pkg: '@ai-sdk/google',
+        factory: 'google',
+        defaultModel: 'gemini-2.0-flash',
+        displayName: 'Google'
+      },
+    ];
+
+    for (const { envKey, pkg, factory, defaultModel, displayName } of providerConfigs) {
+      if (process.env[envKey]) {
+        try {
+          const mod = await import(/* webpackIgnore: true */ pkg);
+          const createModel = mod[factory] ?? mod.default;
+          if (typeof createModel === 'function') {
+            const modelId = process.env.AI_MODEL ?? defaultModel;
+            const adapter = new VercelLLMAdapter({ model: createModel(modelId) });
+            return { adapter, description: `${displayName} (model: ${modelId})` };
+          }
+        } catch (err) {
+          ctx.logger.warn(
+            `[AI] Failed to load ${pkg} for ${envKey}, trying next provider`,
+            err instanceof Error ? { error: err.message } : undefined
+          );
+        }
+      }
+    }
+
+    // 3. Fallback to MemoryLLMAdapter
+    ctx.logger.warn('[AI] No LLM provider configured via environment variables. Falling back to MemoryLLMAdapter (echo mode). Set AI_GATEWAY_MODEL, OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY to use a real LLM.');
+    return { adapter: new MemoryLLMAdapter(), description: 'MemoryLLMAdapter (echo mode - for testing only)' };
+  }
+
   async init(ctx: PluginContext): Promise<void> {
     // Check if there is an existing AI service (e.g. from dev-plugin)
     let hasExisting = false;
@@ -87,8 +174,26 @@ export class AIServicePlugin implements Plugin {
       }
     }
 
+    // Determine LLM adapter: explicit > auto-detect from env > MemoryLLMAdapter fallback
+    let adapter: LLMAdapter;
+    let adapterDescription: string;
+
+    if (this.options.adapter) {
+      // User provided an explicit adapter
+      adapter = this.options.adapter;
+      adapterDescription = `${adapter.name} (explicitly configured)`;
+    } else {
+      // Auto-detect from environment variables
+      const detected = await this.detectAdapter(ctx);
+      adapter = detected.adapter;
+      adapterDescription = detected.description;
+    }
+
+    // Log the selected adapter
+    ctx.logger.info(`[AI] Using LLM adapter: ${adapterDescription}`);
+
     const config: AIServiceConfig = {
-      adapter: this.options.adapter,
+      adapter,
       logger: ctx.logger,
       conversationService,
     };
@@ -102,8 +207,8 @@ export class AIServicePlugin implements Plugin {
       ctx.registerService('ai', this.service);
     }
 
-    // Register AI system objects so ObjectQLPlugin auto-discovers them
-    ctx.registerService('app.com.objectstack.service-ai', {
+    // Register AI system objects via the manifest service.
+    ctx.getService<{ register(m: any): void }>('manifest').register({
       id: 'com.objectstack.service-ai',
       name: 'AI Service',
       version: '1.0.0',
@@ -118,16 +223,40 @@ export class AIServicePlugin implements Plugin {
       });
     }
 
+    // Contribute navigation items to the Setup App (if SetupPlugin is loaded).
+    try {
+      const setupNav = ctx.getService<{ contribute(c: any): void }>('setupNav');
+      if (setupNav) {
+        setupNav.contribute({
+          areaId: 'area_ai',
+          items: [
+            { id: 'nav_ai_conversations', type: 'object', label: { key: 'setup.nav.ai_conversations', defaultValue: 'Conversations' }, objectName: 'conversations', icon: 'message-square', order: 10 },
+            { id: 'nav_ai_messages', type: 'object', label: { key: 'setup.nav.ai_messages', defaultValue: 'Messages' }, objectName: 'messages', icon: 'messages-square', order: 20 },
+          ],
+        });
+        ctx.logger.info('[AI] Navigation items contributed to Setup App');
+      }
+    } catch {
+      // SetupPlugin not loaded — skip silently
+    }
+
     ctx.logger.info('[AI] Service initialized');
   }
 
   async start(ctx: PluginContext): Promise<void> {
     if (!this.service) return;
 
-    // ── Auto-register built-in data tools if data engine + metadata are available ──
+    // ── Auto-register built-in tools & agents when services are available ──
+    let metadataService: IMetadataService | undefined;
+    try {
+      metadataService = ctx.getService<IMetadataService>('metadata');
+    } catch {
+      ctx.logger.debug('[AI] Metadata service not available');
+    }
+
+    // Data tools require both data engine and metadata service
     try {
       const dataEngine = ctx.getService<IDataEngine>('data');
-      const metadataService = ctx.getService<IMetadataService>('metadata');
       if (dataEngine && metadataService) {
         registerDataTools(this.service.toolRegistry, { dataEngine, metadataService });
         ctx.logger.info('[AI] Built-in data tools registered');
@@ -146,8 +275,30 @@ export class AIServicePlugin implements Plugin {
         }
       }
     } catch {
-      // Data engine or metadata service not available — skip data tools
-      ctx.logger.debug('[AI] Data engine or metadata service not available, skipping data tools');
+      ctx.logger.debug('[AI] Data engine not available, skipping data tools');
+    }
+
+    // Metadata tools require only the metadata service
+    if (metadataService) {
+      try {
+        registerMetadataTools(this.service.toolRegistry, { metadataService });
+        ctx.logger.info('[AI] Built-in metadata tools registered');
+
+        // Register the built-in metadata_assistant agent
+        const agentExists =
+          typeof metadataService.exists === 'function'
+            ? await metadataService.exists('agent', METADATA_ASSISTANT_AGENT.name)
+            : false;
+
+        if (!agentExists) {
+          await metadataService.register('agent', METADATA_ASSISTANT_AGENT.name, METADATA_ASSISTANT_AGENT);
+          ctx.logger.info('[AI] metadata_assistant agent registered');
+        } else {
+          ctx.logger.debug('[AI] metadata_assistant agent already exists, skipping auto-registration');
+        }
+      } catch (err) {
+        ctx.logger.debug('[AI] Failed to register metadata tools', err instanceof Error ? err : undefined);
+      }
     }
 
     // Trigger hook to notify AI service is ready — other plugins can register tools
@@ -171,6 +322,12 @@ export class AIServicePlugin implements Plugin {
     // Trigger hook so HTTP server plugins can mount these routes
     await ctx.trigger('ai:routes', routes);
 
+    // Cache routes on the kernel so HttpDispatcher can find them
+    const kernel = ctx.getKernel();
+    if (kernel) {
+      (kernel as any).__aiRoutes = routes;
+    }
+
     ctx.logger.info(
       `[AI] Service started — adapter="${this.service.adapterName}", ` +
       `tools=${this.service.toolRegistry.size}, ` +

package/src/routes/agent-routes.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { AIMessage } from '@objectstack/spec/contracts';
+import type { ModelMessage } from '@objectstack/spec/contracts';
 import type { Logger } from '@objectstack/spec/contracts';
 import type { AIService } from '../ai-service.js';
 import type { AgentRuntime, AgentChatContext } from '../agent-runtime.js';
@@ -36,6 +36,7 @@ function validateAgentMessage(raw: unknown): string | null {
  *
  * | Method | Path | Description |
  * |:---|:---|:---|
+ * | GET  | /api/v1/ai/agents | List all active agents |
  * | POST | /api/v1/ai/agents/:agentName/chat | Chat with a specific agent |
  */
 export function buildAgentRoutes(
@@ -44,10 +45,34 @@ export function buildAgentRoutes(
   logger: Logger,
 ): RouteDefinition[] {
   return [
+    // ── List active agents ──────────────────────────────────────
+    {
+      method: 'GET',
+      path: '/api/v1/ai/agents',
+      description: 'List all active AI agents',
+      auth: true,
+      permissions: ['ai:chat'],
+      handler: async () => {
+        try {
+          const agents = await agentRuntime.listAgents();
+          return { status: 200, body: { agents } };
+        } catch (err) {
+          logger.error(
+            '[AI Route] /agents list error',
+            err instanceof Error ? err : undefined,
+          );
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Chat with a specific agent ──────────────────────────────
     {
       method: 'POST',
       path: '/api/v1/ai/agents/:agentName/chat',
       description: 'Chat with a specific AI agent',
+      auth: true,
+      permissions: ['ai:chat', 'ai:agents'],
       handler: async (req) => {
         const agentName = req.params?.agentName;
         if (!agentName) {
@@ -107,9 +132,9 @@ export function buildAgentRoutes(
           const mergedOptions = { ...agentOptions, ...safeOverrides };
 
           // Prepend system messages then user conversation
-          const fullMessages: AIMessage[] = [
+          const fullMessages: ModelMessage[] = [
             ...systemMessages,
-            ...(rawMessages as AIMessage[]),
+            ...(rawMessages as ModelMessage[]),
           ];
 
           // Use chatWithTools for automatic tool resolution

package/src/routes/ai-routes.ts

@@ -1,7 +1,8 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { IAIService, IAIConversationService, AIMessage } from '@objectstack/spec/contracts';
+import type { IAIService, IAIConversationService, ModelMessage } from '@objectstack/spec/contracts';
 import type { Logger } from '@objectstack/spec/contracts';
+import { encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
 
 /**
  * Minimal HTTP handler abstraction so routes stay framework-agnostic.
@@ -16,6 +17,10 @@ export 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.
@@ -23,6 +28,22 @@ export interface RouteDefinition {
   handler: (req: RouteRequest) => Promise<RouteResponse>;
 }
 
+/**
+ * Authenticated user context attached to a route request.
+ *
+ * Populated by the auth middleware when `RouteDefinition.auth` is `true`.
+ */
+export 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[];
+}
+
 export interface RouteRequest {
   /** Parsed JSON body (for POST requests) */
   body?: unknown;
@@ -30,6 +51,8 @@ export interface RouteRequest {
   params?: Record<string, string>;
   /** Query string parameters */
   query?: Record<string, string>;
+  /** Authenticated user context (populated by auth middleware). */
+  user?: RouteUserContext;
 }
 
 export interface RouteResponse {
@@ -41,14 +64,58 @@ export 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;
 }
 
 /** Valid message roles accepted by the AI routes. */
 const VALID_ROLES = new Set<string>(['system', 'user', 'assistant', 'tool']);
 
 /**
- * Validate that `raw` is a well-formed AIMessage.
+ * Normalize a Vercel AI SDK v6 message (which may use `parts` instead of
+ * `content`) into a plain `{ role, content }` ModelMessage.
+ */
+function normalizeMessage(raw: Record<string, unknown>): ModelMessage {
+  const role = raw.role as string;
+
+  // If content is already a string, use it directly
+  if (typeof raw.content === 'string') {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // If content is an array (multi-part), pass through
+  if (Array.isArray(raw.content)) {
+    return { role, content: raw.content } as unknown as ModelMessage;
+  }
+
+  // Vercel AI SDK v6: extract text from `parts` array
+  if (Array.isArray(raw.parts)) {
+    const textParts = (raw.parts as Array<Record<string, unknown>>)
+      .filter(p => p.type === 'text' && typeof p.text === 'string')
+      .map(p => p.text as string);
+    if (textParts.length > 0) {
+      return { role, content: textParts.join('') } as unknown as ModelMessage;
+    }
+  }
+
+  // Fallback: empty content (e.g. tool-only assistant messages)
+  return { role, content: '' } as unknown as ModelMessage;
+}
+
+/**
+ * Validate that `raw` is a well-formed message.
  * Returns null on success, or an error string on failure.
+ *
+ * Accepts:
+ *  - Simple string `content` (legacy)
+ *  - Array `content` (e.g. `[{ type: 'text', text: '...' }]`)
+ *  - Vercel AI SDK v6 `parts` format (content may be absent/null)
  */
 function validateMessage(raw: unknown): string | null {
   if (typeof raw !== 'object' || raw === null) {
@@ -58,10 +125,44 @@ function validateMessage(raw: unknown): string | null {
   if (typeof msg.role !== 'string' || !VALID_ROLES.has(msg.role)) {
     return `message.role must be one of ${[...VALID_ROLES].map(r => `"${r}"`).join(', ')}`;
   }
-  if (typeof msg.content !== 'string') {
-    return 'message.content must be a string';
+  const content = msg.content;
+
+  // Vercel AI SDK v6 sends `parts` instead of (or alongside) `content`.
+  // Accept any message that carries a `parts` array, even when `content` is absent.
+  if (Array.isArray(msg.parts)) {
+    return null;
   }
-  return null;
+
+  // content is a plain string — OK
+  if (typeof content === 'string') {
+    return null;
+  }
+
+  // content is an array of typed parts (legacy multi-part format)
+  if (Array.isArray(content)) {
+    for (const part of content as unknown[]) {
+      if (typeof part !== 'object' || part === null) {
+        return 'message.content array elements must be non-null objects';
+      }
+      const partObj = part as Record<string, unknown>;
+      if (typeof partObj.type !== 'string') {
+        return 'each message.content array element must have a string "type" property';
+      }
+      if (partObj.type === 'text' && typeof partObj.text !== 'string') {
+        return 'message.content elements with type "text" must have a string "text" property';
+      }
+    }
+    return null;
+  }
+
+  // Assistant / tool messages may legitimately have null or missing content
+  if (content === null || content === undefined) {
+    if (msg.role === 'assistant' || msg.role === 'tool') {
+      return null;
+    }
+  }
+
+  return 'message.content must be a string, an array, or include parts';
 }
 
 /**
@@ -90,16 +191,26 @@ export function buildAIRoutes(
 ): RouteDefinition[] {
   return [
     // ── Chat ────────────────────────────────────────────────────
+    //
+    // Dual-mode endpoint compatible with both the legacy ObjectStack
+    // format (`{ messages, options }`) and the Vercel AI SDK useChat
+    // flat format (`{ messages, system, model, stream, … }`).
+    //
+    // Behaviour:
+    //   • `stream !== false` → Vercel Data Stream Protocol (SSE)
+    //   • `stream === false`  → JSON response (legacy)
+    //
     {
       method: 'POST',
       path: '/api/v1/ai/chat',
-      description: 'Synchronous chat completion',
+      description: 'Chat completion (supports Vercel AI Data Stream Protocol)',
+      auth: true,
+      permissions: ['ai:chat'],
       handler: async (req) => {
-        const { messages, options } = (req.body ?? {}) as {
-          messages?: unknown[];
-          options?: Record<string, unknown>;
-        };
+        const body = (req.body ?? {}) as Record<string, unknown>;
 
+        // ── Parse messages ───────────────────────────────────
+        const messages = body.messages as unknown[] | undefined;
         if (!Array.isArray(messages) || messages.length === 0) {
           return { status: 400, body: { error: 'messages array is required' } };
         }
@@ -109,8 +220,64 @@ export function buildAIRoutes(
           if (err) return { status: 400, body: { error: err } };
         }
 
+        // ── Resolve options ──────────────────────────────────
+        // Accept legacy nested `options` object **or** Vercel-style
+        // flat fields (`model`, `temperature`, `maxTokens`).
+        const nested = (body.options ?? {}) as Record<string, unknown>;
+        const resolvedOptions: Record<string, unknown> = {
+          ...nested,
+          ...(body.model != null && { model: body.model }),
+          ...(body.temperature != null && { temperature: body.temperature }),
+          ...(body.maxTokens != null && { maxTokens: body.maxTokens }),
+        };
+
+        // ── Prepend system prompt ────────────────────────────
+        // Vercel useChat sends `system` (or the deprecated `systemPrompt`)
+        // as a top-level field.  We prepend it as a system message.
+        const rawSystemPrompt = body.system ?? body.systemPrompt;
+        if (rawSystemPrompt != null && typeof rawSystemPrompt !== 'string') {
+          return { status: 400, body: { error: 'system/systemPrompt must be a string' } };
+        }
+        const systemPrompt = rawSystemPrompt as string | undefined;
+        const finalMessages: ModelMessage[] = [
+          ...(systemPrompt
+            ? [{ role: 'system' as const, content: systemPrompt }]
+            : []),
+          ...messages.map(m => normalizeMessage(m as Record<string, unknown>)),
+        ];
+
+        // ── Choose response mode ─────────────────────────────
+        const wantStream = body.stream !== false;
+
+        if (wantStream) {
+          // UI Message Stream Protocol (SSE with JSON payloads)
+          try {
+            if (!(aiService as any).streamChatWithTools) {
+              return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
+            }
+            const events = (aiService as any).streamChatWithTools(finalMessages, resolvedOptions as any);
+            return {
+              status: 200,
+              stream: true,
+              vercelDataStream: true,
+              contentType: 'text/event-stream',
+              headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'x-vercel-ai-ui-message-stream': 'v1',
+              },
+              events: encodeVercelDataStream(events),
+            };
+          } catch (err) {
+            logger.error('[AI Route] /chat stream error', err instanceof Error ? err : undefined);
+            return { status: 500, body: { error: 'Internal AI service error' } };
+          }
+        }
+
+        // JSON response (non-streaming)
         try {
-          const result = await aiService.chat(messages as AIMessage[], options as any);
+          const result = await (aiService as any).chatWithTools(finalMessages, resolvedOptions as any);
           return { status: 200, body: result };
         } catch (err) {
           logger.error('[AI Route] /chat error', err instanceof Error ? err : undefined);
@@ -124,6 +291,8 @@ export function buildAIRoutes(
       method: 'POST',
       path: '/api/v1/ai/chat/stream',
       description: 'SSE streaming chat completion',
+      auth: true,
+      permissions: ['ai:chat'],
       handler: async (req) => {
         const { messages, options } = (req.body ?? {}) as {
           messages?: unknown[];
@@ -143,7 +312,7 @@ export function buildAIRoutes(
           if (!aiService.streamChat) {
             return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
           }
-          const events = aiService.streamChat(messages as AIMessage[], options as any);
+          const events = aiService.streamChat(messages.map(m => normalizeMessage(m as Record<string, unknown>)), options as any);
           return { status: 200, stream: true, events };
         } catch (err) {
           logger.error('[AI Route] /chat/stream error', err instanceof Error ? err : undefined);
@@ -157,6 +326,8 @@ export function buildAIRoutes(
       method: 'POST',
       path: '/api/v1/ai/complete',
       description: 'Text completion',
+      auth: true,
+      permissions: ['ai:complete'],
       handler: async (req) => {
         const { prompt, options } = (req.body ?? {}) as {
           prompt?: string;
@@ -182,6 +353,8 @@ export function buildAIRoutes(
       method: 'GET',
       path: '/api/v1/ai/models',
       description: 'List available models',
+      auth: true,
+      permissions: ['ai:read'],
       handler: async () => {
         try {
           const models = aiService.listModels ? await aiService.listModels() : [];
@@ -198,9 +371,20 @@ export function buildAIRoutes(
       method: 'POST',
       path: '/api/v1/ai/conversations',
       description: 'Create a conversation',
+      auth: true,
+      permissions: ['ai:conversations'],
       handler: async (req) => {
         try {
-          const options = (req.body ?? {}) as Record<string, unknown>;
+          // Ensure the request body is a non-null object before mutating it
+          if (req.body !== undefined && req.body !== null && (typeof req.body !== 'object' || Array.isArray(req.body))) {
+            return { status: 400, body: { error: 'Invalid request payload' } };
+          }
+
+          const options: Record<string, unknown> = { ...((req.body ?? {}) as Record<string, unknown>) };
+          // Bind the conversation to the authenticated user
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
           const conversation = await conversationService.create(options as any);
           return { status: 201, body: conversation };
         } catch (err) {
@@ -213,6 +397,8 @@ export function buildAIRoutes(
       method: 'GET',
       path: '/api/v1/ai/conversations',
       description: 'List conversations',
+      auth: true,
+      permissions: ['ai:conversations'],
       handler: async (req) => {
         try {
           const rawQuery = req.query ?? {};
@@ -226,6 +412,11 @@ export function buildAIRoutes(
             options.limit = parsedLimit;
           }
 
+          // Scope to the authenticated user's conversations
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
+
           const conversations = await conversationService.list(options as any);
           return { status: 200, body: { conversations } };
         } catch (err) {
@@ -238,6 +429,8 @@ export function buildAIRoutes(
       method: 'POST',
       path: '/api/v1/ai/conversations/:id/messages',
       description: 'Add message to a conversation',
+      auth: true,
+      permissions: ['ai:conversations'],
       handler: async (req) => {
         const id = req.params?.id;
         if (!id) {
@@ -251,7 +444,18 @@ export function buildAIRoutes(
         }
 
         try {
-          const conversation = await conversationService.addMessage(id, message as AIMessage);
+          // Ownership check: verify the conversation belongs to the current user
+          if (req.user?.userId) {
+            const existing = await conversationService.get(id);
+            if (!existing) {
+              return { status: 404, body: { error: `Conversation "${id}" not found` } };
+            }
+            if (existing.userId && existing.userId !== req.user.userId) {
+              return { status: 403, body: { error: 'You do not have access to this conversation' } };
+            }
+          }
+
+          const conversation = await conversationService.addMessage(id, message as ModelMessage);
           return { status: 200, body: conversation };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -267,6 +471,8 @@ export function buildAIRoutes(
       method: 'DELETE',
       path: '/api/v1/ai/conversations/:id',
       description: 'Delete a conversation',
+      auth: true,
+      permissions: ['ai:conversations'],
       handler: async (req) => {
         const id = req.params?.id;
         if (!id) {
@@ -274,6 +480,17 @@ export function buildAIRoutes(
         }
 
         try {
+          // Ownership check: verify the conversation belongs to the current user
+          if (req.user?.userId) {
+            const existing = await conversationService.get(id);
+            if (!existing) {
+              return { status: 404, body: { error: `Conversation "${id}" not found` } };
+            }
+            if (existing.userId && existing.userId !== req.user.userId) {
+              return { status: 403, body: { error: 'You do not have access to this conversation' } };
+            }
+          }
+
           await conversationService.delete(id);
           return { status: 204 };
         } catch (err) {