@objectstack/service-ai 4.0.0 → 4.0.1

package/dist/index.d.ts

@@ -116,6 +116,14 @@ declare class AIService implements IAIService {
      *    maximum number of iterations (`maxIterations`) is reached.
      */
     chatWithTools(messages: AIMessage[], 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: AIMessage[], options?: ChatWithToolsOptions): AsyncIterable<AIStreamEvent>;
 }
 
 /**
@@ -3349,12 +3357,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 +3389,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 */
@@ -3403,4 +3432,4 @@ declare function buildAIRoutes(aiService: IAIService, conversationService: IAICo
  */
 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, MemoryLLMAdapter, ObjectQLConversationService, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type ToolHandler, ToolRegistry, buildAIRoutes, buildAgentRoutes, registerDataTools };

package/dist/index.js

@@ -249,7 +249,7 @@ var _AIService = class _AIService {
    *    maximum number of iterations (`maxIterations`) is reached.
    */
   async chatWithTools(messages, options) {
-    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
     const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
     const mergedTools = [
@@ -262,11 +262,13 @@ var _AIService = class _AIService {
       toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
     };
     const conversation = [...messages];
+    const toolErrors = [];
     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);
       if (!result.toolCalls || result.toolCalls.length === 0) {
@@ -284,14 +286,36 @@ var _AIService = class _AIService {
       });
       const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
       for (const tr of toolResults) {
+        if (tr.isError) {
+          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;
+            }
+          }
+        }
         conversation.push({
           role: "tool",
           content: tr.content,
           toolCallId: tr.toolCallId
         });
       }
+      if (abortedByCallback) {
+        break;
+      }
+    }
+    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 : void 0
+      });
     }
-    this.logger.warn("[AI] chatWithTools max iterations reached, forcing final response");
     const finalResult = await this.adapter.chat(conversation, {
       ...chatOptions,
       tools: void 0,
@@ -299,6 +323,74 @@ var _AIService = class _AIService {
     });
     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, options) {
+    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 = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : void 0,
+      toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
+    };
+    const conversation = [...messages];
+    let abortedByCallback = false;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      const result2 = await this.adapter.chat(conversation, chatOptions);
+      if (!result2.toolCalls || result2.toolCalls.length === 0) {
+        yield { type: "text-delta", textDelta: result2.content };
+        yield { type: "finish", result: result2 };
+        return;
+      }
+      for (const tc of result2.toolCalls) {
+        yield { type: "tool-call", toolCall: tc };
+      }
+      conversation.push({
+        role: "assistant",
+        content: result2.content ?? "",
+        toolCalls: result2.toolCalls
+      });
+      const toolResults = await this.toolRegistry.executeAll(result2.toolCalls);
+      for (const tr of toolResults) {
+        if (tr.isError && onToolError) {
+          const matchedCall = result2.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;
+      }
+    }
+    if (abortedByCallback) {
+      this.logger.warn("[AI] streamChatWithTools aborted by onToolError callback");
+    } else {
+      this.logger.warn("[AI] streamChatWithTools max iterations reached");
+    }
+    const finalOptions = { ...chatOptions, tools: void 0, toolChoice: void 0 };
+    const result = await this.adapter.chat(conversation, finalOptions);
+    yield { type: "text-delta", textDelta: result.content };
+    yield { type: "finish", result };
+  }
 };
 // ── Tool Call Loop ────────────────────────────────────────────
 /** Default maximum iterations for the tool call loop. */
@@ -327,6 +419,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/chat",
       description: "Synchronous chat completion",
+      auth: true,
+      permissions: ["ai:chat"],
       handler: async (req) => {
         const { messages, options } = req.body ?? {};
         if (!Array.isArray(messages) || messages.length === 0) {
@@ -350,6 +444,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       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 ?? {};
         if (!Array.isArray(messages) || messages.length === 0) {
@@ -376,6 +472,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/complete",
       description: "Text completion",
+      auth: true,
+      permissions: ["ai:complete"],
       handler: async (req) => {
         const { prompt, options } = req.body ?? {};
         if (!prompt || typeof prompt !== "string") {
@@ -395,6 +493,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       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() : [];
@@ -410,9 +510,17 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "POST",
       path: "/api/v1/ai/conversations",
       description: "Create a conversation",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         try {
-          const options = req.body ?? {};
+          if (req.body !== void 0 && req.body !== null && (typeof req.body !== "object" || Array.isArray(req.body))) {
+            return { status: 400, body: { error: "Invalid request payload" } };
+          }
+          const options = { ...req.body ?? {} };
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
           const conversation = await conversationService.create(options);
           return { status: 201, body: conversation };
         } catch (err) {
@@ -425,6 +533,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       method: "GET",
       path: "/api/v1/ai/conversations",
       description: "List conversations",
+      auth: true,
+      permissions: ["ai:conversations"],
       handler: async (req) => {
         try {
           const rawQuery = req.query ?? {};
@@ -436,6 +546,9 @@ function buildAIRoutes(aiService, conversationService, logger) {
             }
             options.limit = parsedLimit;
           }
+          if (req.user?.userId) {
+            options.userId = req.user.userId;
+          }
           const conversations = await conversationService.list(options);
           return { status: 200, body: { conversations } };
         } catch (err) {
@@ -448,6 +561,8 @@ function buildAIRoutes(aiService, conversationService, logger) {
       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) {
@@ -459,6 +574,15 @@ function buildAIRoutes(aiService, conversationService, logger) {
           return { status: 400, body: { error: validationError } };
         }
         try {
+          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);
           return { status: 200, body: conversation };
         } catch (err) {
@@ -475,12 +599,23 @@ function buildAIRoutes(aiService, conversationService, logger) {
       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) {
           return { status: 400, body: { error: "conversation id is required" } };
         }
         try {
+          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) {
@@ -513,6 +648,8 @@ function buildAgentRoutes(aiService, agentRuntime, logger) {
       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) {