@objectstack/service-ai 4.0.0 → 4.0.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/service-ai@4.0.0 build /home/runner/work/spec/spec/packages/services/service-ai
+> @objectstack/service-ai@4.0.1 build /home/runner/work/spec/spec/packages/services/service-ai
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs     45.63 KB
-CJS dist/index.cjs.map 97.28 KB
-CJS ⚡️ Build success in 153ms
-ESM dist/index.js     43.82 KB
-ESM dist/index.js.map 95.70 KB
-ESM ⚡️ Build success in 153ms
+ESM dist/index.js     49.00 KB
+ESM dist/index.js.map 106.10 KB
+ESM ⚡️ Build success in 168ms
+CJS dist/index.cjs     50.82 KB
+CJS dist/index.cjs.map 107.70 KB
+CJS ⚡️ Build success in 178ms
 DTS Build start
-DTS ⚡️ Build success in 20835ms
-DTS dist/index.d.ts  148.67 KB
-DTS dist/index.d.cts 148.67 KB
+DTS ⚡️ Build success in 18643ms
+DTS dist/index.d.ts  149.83 KB
+DTS dist/index.d.cts 149.83 KB

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @objectstack/service-ai
 
+## 4.1.0
+
+### Minor Changes
+
+- **Route auth/permissions metadata**: Every route definition (`RouteDefinition`) now declares `auth` and `permissions` fields, enabling HTTP server adapters to enforce authentication and authorization automatically.
+- **User context on RouteRequest**: `RouteRequest` now carries an optional `user: RouteUserContext` object populated by the auth middleware, providing `userId`, `displayName`, `roles`, and `permissions`.
+- **Conversation ownership enforcement**: Conversation routes (create, list, add message, delete) are scoped to the authenticated user when a user context is present and the conversation has a `userId`. For backward compatibility, requests without user context and conversations created without a `userId` remain accessible under the existing behavior.
+- **Enhanced tool-call loop error handling**: `chatWithTools` now tracks tool execution errors across iterations and supports an `onToolError` callback (`'continue'` | `'abort'`) for fine-grained error control.
+- **`streamChatWithTools`**: New streaming tool-call loop that yields SSE events while automatically resolving intermediate tool calls.
+- **New `RouteUserContext` type**: Exported from the package for use by HTTP adapters and middleware.
+
 ## 4.0.0
 
 ### Major Changes

package/dist/index.cjs

@@ -288,7 +288,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 = [
@@ -301,11 +301,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) {
@@ -323,14 +325,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,
@@ -338,6 +362,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. */
@@ -366,6 +458,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) {
@@ -389,6 +483,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) {
@@ -415,6 +511,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") {
@@ -434,6 +532,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() : [];
@@ -449,9 +549,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) {
@@ -464,6 +572,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 ?? {};
@@ -475,6 +585,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) {
@@ -487,6 +600,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) {
@@ -498,6 +613,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) {
@@ -514,12 +638,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) {
@@ -552,6 +687,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) {