@objectstack/service-ai 4.0.0 → 4.0.1

package/src/ai-service.ts

@@ -131,8 +131,8 @@ export class AIService implements IAIService {
     messages: AIMessage[],
     options?: ChatWithToolsOptions,
   ): Promise<AIResult> {
-    // Destructure maxIterations out so it is never forwarded to the adapter
-    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    // Destructure loop-specific options so they are never forwarded to the adapter
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
     const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
 
@@ -152,12 +152,17 @@ export class AIService implements IAIService {
     // Working copy of the conversation
     const conversation = [...messages];
 
+    // Track errors across iterations for diagnostics
+    const toolErrors: Array<{ iteration: number; toolName: string; error: string }> = [];
+
     this.logger.debug('[AI] chatWithTools start', {
       messageCount: conversation.length,
       toolCount: mergedTools.length,
       maxIterations,
     });
 
+    let abortedByCallback = false;
+
     for (let iteration = 0; iteration < maxIterations; iteration++) {
       const result = await this.adapter.chat(conversation, chatOptions);
 
@@ -182,19 +187,47 @@ export class AIService implements IAIService {
       // Execute all tool calls in parallel
       const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
 
-      // Append each tool result as a `role: 'tool'` message
+      // Process results: track errors and honour onToolError callback
       for (const tr of toolResults) {
+        if (tr.isError) {
+          // Match tool call by toolCallId for robust attribution
+          const matchedCall = result.toolCalls!.find(tc => tc.id === tr.toolCallId);
+          const toolName = matchedCall?.name ?? 'unknown';
+          const errorEntry = { iteration, toolName, error: tr.content };
+          toolErrors.push(errorEntry);
+          this.logger.warn('[AI] chatWithTools tool error', errorEntry);
+
+          if (onToolError && matchedCall) {
+            const action = onToolError(matchedCall, tr.content);
+            if (action === 'abort') {
+              abortedByCallback = true;
+            }
+          }
+        }
+
+        // Append each tool result as a `role: 'tool'` message
         conversation.push({
           role: 'tool',
           content: tr.content,
           toolCallId: tr.toolCallId,
         });
       }
+
+      if (abortedByCallback) {
+        break;
+      }
+    }
+
+    // Distinguish user-driven abort from max-iterations exhaustion in logs
+    if (abortedByCallback) {
+      this.logger.warn('[AI] chatWithTools aborted by onToolError callback', { toolErrors });
+    } else {
+      this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response', {
+        toolErrors: toolErrors.length > 0 ? toolErrors : undefined,
+      });
     }
 
-    // If we exhausted the loop without a final response, make one last
-    // call *without* tools so the model is forced to produce text.
-    this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response');
+    // Make one last call *without* tools so the model is forced to produce text.
     const finalResult = await this.adapter.chat(conversation, {
       ...chatOptions,
       tools: undefined,
@@ -202,4 +235,91 @@ export class AIService implements IAIService {
     });
     return finalResult;
   }
+
+  /**
+   * 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.
+   */
+  async *streamChatWithTools(
+    messages: AIMessage[],
+    options?: ChatWithToolsOptions,
+  ): AsyncIterable<AIStreamEvent> {
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
+    const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
+    const registeredTools = this.toolRegistry.getAll();
+
+    const mergedTools = [
+      ...registeredTools,
+      ...(restOptions.tools ?? []),
+    ];
+
+    const chatOptions: AIRequestOptions = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : undefined,
+      toolChoice: mergedTools.length > 0 ? (restOptions.toolChoice ?? 'auto') : undefined,
+    };
+
+    const conversation = [...messages];
+    let abortedByCallback = false;
+
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      // Use non-streaming chat for intermediate tool-call rounds
+      const result = await this.adapter.chat(conversation, chatOptions);
+
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        // Final round — return the probed result without an extra model call
+        yield { type: 'text-delta', textDelta: result.content };
+        yield { type: 'finish', result };
+        return;
+      }
+
+      // Emit tool-call events so the client can see tool execution progress
+      for (const tc of result.toolCalls) {
+        yield { type: 'tool-call', toolCall: tc };
+      }
+
+      conversation.push({
+        role: 'assistant',
+        content: result.content ?? '',
+        toolCalls: result.toolCalls,
+      });
+
+      const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
+
+      for (const tr of toolResults) {
+        if (tr.isError && onToolError) {
+          const matchedCall = result.toolCalls!.find(tc => tc.id === tr.toolCallId);
+          if (matchedCall) {
+            const action = onToolError(matchedCall, tr.content);
+            if (action === 'abort') {
+              abortedByCallback = true;
+            }
+          }
+        }
+        conversation.push({
+          role: 'tool',
+          content: tr.content,
+          toolCallId: tr.toolCallId,
+        });
+      }
+
+      if (abortedByCallback) {
+        break;
+      }
+    }
+
+    // Forced final response (no tools) — either aborted or max iterations
+    if (abortedByCallback) {
+      this.logger.warn('[AI] streamChatWithTools aborted by onToolError callback');
+    } else {
+      this.logger.warn('[AI] streamChatWithTools max iterations reached');
+    }
+    const finalOptions = { ...chatOptions, tools: undefined, toolChoice: undefined };
+    const result = await this.adapter.chat(conversation, finalOptions);
+    yield { type: 'text-delta', textDelta: result.content };
+    yield { type: 'finish', result };
+  }
 }

package/src/index.ts

@@ -37,4 +37,4 @@ export { AiConversationObject, AiMessageObject } from './objects/index.js';
 // Routes
 export { buildAIRoutes } from './routes/ai-routes.js';
 export { buildAgentRoutes } from './routes/agent-routes.js';
-export type { RouteDefinition, RouteRequest, RouteResponse } from './routes/ai-routes.js';
+export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './routes/ai-routes.js';

package/src/routes/agent-routes.ts

@@ -48,6 +48,8 @@ export function buildAgentRoutes(
       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) {

package/src/routes/ai-routes.ts

@@ -16,6 +16,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 +27,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 +50,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 {
@@ -94,6 +116,8 @@ export function buildAIRoutes(
       method: 'POST',
       path: '/api/v1/ai/chat',
       description: 'Synchronous chat completion',
+      auth: true,
+      permissions: ['ai:chat'],
       handler: async (req) => {
         const { messages, options } = (req.body ?? {}) as {
           messages?: unknown[];
@@ -124,6 +148,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[];
@@ -157,6 +183,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 +210,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 +228,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 +254,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 +269,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 +286,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,6 +301,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' } };
+            }
+          }
+
           const conversation = await conversationService.addMessage(id, message as AIMessage);
           return { status: 200, body: conversation };
         } catch (err) {
@@ -267,6 +328,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 +337,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) {

package/src/routes/index.ts

@@ -1,4 +1,4 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { buildAIRoutes } from './ai-routes.js';
-export type { RouteDefinition, RouteRequest, RouteResponse } from './ai-routes.js';
+export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './ai-routes.js';