@objectstack/service-ai 6.3.0 → 6.5.0

package/dist/index.cjs

@@ -29,8 +29,21 @@ __export(data_tools_exports, {
   QUERY_RECORDS_TOOL: () => QUERY_RECORDS_TOOL,
   registerDataTools: () => registerDataTools
 });
+function buildEngineContext(ctx) {
+  if (ctx?.actor) {
+    return {
+      userId: ctx.actor.id,
+      roles: ctx.actor.roles ?? [],
+      permissions: ctx.actor.permissions ?? [],
+      isSystem: false,
+      ...ctx.environmentId ? { tenantId: ctx.environmentId } : {},
+      ...ctx.traceId ? { traceId: ctx.traceId } : {}
+    };
+  }
+  return { roles: [], permissions: [], isSystem: true };
+}
 function createQueryRecordsHandler(ctx) {
-  return async (args) => {
+  return async (args, execCtx) => {
     const {
       objectName,
       where,
@@ -47,17 +60,19 @@ function createQueryRecordsHandler(ctx) {
       fields,
       orderBy,
       limit: safeLimit,
-      offset: safeOffset
+      offset: safeOffset,
+      context: buildEngineContext(execCtx)
     });
     return JSON.stringify({ count: records.length, records });
   };
 }
 function createGetRecordHandler(ctx) {
-  return async (args) => {
+  return async (args, execCtx) => {
     const { objectName, recordId, fields } = args;
     const record = await ctx.dataEngine.findOne(objectName, {
       where: { id: recordId },
-      fields
+      fields,
+      context: buildEngineContext(execCtx)
     });
     if (!record) {
       return JSON.stringify({ error: `Record "${recordId}" not found in "${objectName}"` });
@@ -66,7 +81,7 @@ function createGetRecordHandler(ctx) {
   };
 }
 function createAggregateDataHandler(ctx) {
-  return async (args) => {
+  return async (args, execCtx) => {
     const { objectName, aggregations, groupBy, where } = args;
     for (const a of aggregations) {
       if (!VALID_AGG_FUNCTIONS.has(a.function)) {
@@ -82,7 +97,8 @@ function createAggregateDataHandler(ctx) {
         function: a.function,
         field: a.field,
         alias: a.alias
-      }))
+      })),
+      context: buildEngineContext(execCtx)
     });
     return JSON.stringify(result);
   };
@@ -870,6 +886,7 @@ __export(index_exports, {
   ObjectQLTraceRecorder: () => ObjectQLTraceRecorder,
   PACKAGE_TOOL_DEFINITIONS: () => PACKAGE_TOOL_DEFINITIONS,
   QUERY_DATA_TOOL: () => QUERY_DATA_TOOL,
+  SEARCH_KNOWLEDGE_TOOL: () => SEARCH_KNOWLEDGE_TOOL,
   SchemaRetriever: () => SchemaRetriever,
   SkillRegistry: () => SkillRegistry,
   ToolRegistry: () => ToolRegistry,
@@ -898,6 +915,7 @@ __export(index_exports, {
   modifyFieldTool: () => modifyFieldTool,
   registerActionsAsTools: () => registerActionsAsTools,
   registerDataTools: () => registerDataTools,
+  registerKnowledgeTools: () => registerKnowledgeTools,
   registerMetadataTools: () => registerMetadataTools,
   registerPackageTools: () => registerPackageTools,
   registerQueryDataTool: () => registerQueryDataTool,
@@ -1277,8 +1295,15 @@ var ToolRegistry = class {
   }
   /**
    * Execute a tool call and return the result.
+   *
+   * @param toolCall The decoded tool-call part from the model response.
+   * @param ctx      Optional per-call execution context (actor, conversation,
+   *                 environment). Handlers may use this to enforce RLS,
+   *                 attribute audit entries, or correlate traces. When
+   *                 omitted, handlers should fall back to system-level
+   *                 behaviour for backward compatibility.
    */
-  async execute(toolCall) {
+  async execute(toolCall, ctx) {
     const handler = this.handlers.get(toolCall.toolName);
     if (!handler) {
       return {
@@ -1291,7 +1316,7 @@ var ToolRegistry = class {
     }
     try {
       const args = typeof toolCall.input === "string" ? JSON.parse(toolCall.input) : toolCall.input ?? {};
-      const content = await handler(args);
+      const content = await handler(args, ctx);
       return {
         type: "tool-result",
         toolCallId: toolCall.toolCallId,
@@ -1310,10 +1335,11 @@ var ToolRegistry = class {
     }
   }
   /**
-   * Execute multiple tool calls in parallel.
+   * Execute multiple tool calls in parallel, threading the same
+   * execution context to each handler.
    */
-  async executeAll(toolCalls) {
-    return Promise.all(toolCalls.map((tc) => this.execute(tc)));
+  async executeAll(toolCalls, ctx) {
+    return Promise.all(toolCalls.map((tc) => this.execute(tc, ctx)));
   }
   /**
    * Clear all registered tools.
@@ -1491,6 +1517,23 @@ var _AIService = class _AIService {
   get adapterName() {
     return this.adapter.name;
   }
+  /**
+   * Best-effort persistence of a single chat message to the conversation
+   * store. Failures are logged at warn level and swallowed — chat requests
+   * must never fail because the history write failed. Mirrors the
+   * precedent set by `ObjectQLTraceRecorder.record`.
+   */
+  async persistMessage(conversationId, message) {
+    try {
+      await this.conversationService.addMessage(conversationId, message);
+    } catch (err) {
+      this.logger.warn("[AI] persist message failed", {
+        conversationId,
+        role: message.role,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   /**
    * Run an adapter call and emit a trace event.
    *
@@ -1604,9 +1647,15 @@ var _AIService = class _AIService {
     );
   }
   async chatWithToolsImpl(messages, options) {
-    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
+    const {
+      maxIterations: maxIter,
+      onToolError,
+      toolExecutionContext,
+      ...restOptions
+    } = options ?? {};
     const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
+    const conversationId = toolExecutionContext?.conversationId;
     const mergedTools = [
       ...registeredTools,
       ...restOptions.tools ?? []
@@ -1617,6 +1666,12 @@ var _AIService = class _AIService {
       toolChoice: mergedTools.length > 0 ? restOptions.toolChoice ?? "auto" : void 0
     };
     const conversation = [...messages];
+    if (conversationId && messages.length > 0) {
+      const last = messages[messages.length - 1];
+      if (last && last.role === "user") {
+        await this.persistMessage(conversationId, last);
+      }
+    }
     const toolErrors = [];
     this.logger.debug("[AI] chatWithTools start", {
       messageCount: conversation.length,
@@ -1628,6 +1683,12 @@ var _AIService = class _AIService {
       const result = await this.adapter.chat(conversation, chatOptions);
       if (!result.toolCalls || result.toolCalls.length === 0) {
         this.logger.debug("[AI] chatWithTools finished", { iteration, content: result.content.slice(0, 80) });
+        if (conversationId) {
+          await this.persistMessage(conversationId, {
+            role: "assistant",
+            content: result.content
+          });
+        }
         return result;
       }
       this.logger.debug("[AI] chatWithTools tool calls", {
@@ -1637,11 +1698,18 @@ var _AIService = class _AIService {
       const assistantContent = [];
       if (result.content) assistantContent.push({ type: "text", text: result.content });
       assistantContent.push(...result.toolCalls);
-      conversation.push({
+      const assistantTurn = {
         role: "assistant",
         content: assistantContent
-      });
-      const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
+      };
+      conversation.push(assistantTurn);
+      if (conversationId) {
+        await this.persistMessage(conversationId, assistantTurn);
+      }
+      const toolResults = await this.toolRegistry.executeAll(
+        result.toolCalls,
+        toolExecutionContext
+      );
       for (const tr of toolResults) {
         if (tr.isError) {
           const matchedCall = result.toolCalls.find((tc) => tc.toolCallId === tr.toolCallId);
@@ -1657,10 +1725,14 @@ var _AIService = class _AIService {
             }
           }
         }
-        conversation.push({
+        const toolTurn = {
           role: "tool",
           content: [tr]
-        });
+        };
+        conversation.push(toolTurn);
+        if (conversationId) {
+          await this.persistMessage(conversationId, toolTurn);
+        }
       }
       if (abortedByCallback) {
         break;
@@ -1678,6 +1750,12 @@ var _AIService = class _AIService {
       tools: void 0,
       toolChoice: void 0
     });
+    if (conversationId) {
+      await this.persistMessage(conversationId, {
+        role: "assistant",
+        content: finalResult.content
+      });
+    }
     return finalResult;
   }
   /**
@@ -1688,9 +1766,15 @@ var _AIService = class _AIService {
    * fed back until a final text stream is produced.
    */
   async *streamChatWithTools(messages, options) {
-    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
+    const {
+      maxIterations: maxIter,
+      onToolError,
+      toolExecutionContext,
+      ...restOptions
+    } = options ?? {};
     const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
+    const conversationId = toolExecutionContext?.conversationId;
     const mergedTools = [
       ...registeredTools,
       ...restOptions.tools ?? []
@@ -1702,9 +1786,21 @@ var _AIService = class _AIService {
     };
     const conversation = [...messages];
     let abortedByCallback = false;
+    if (conversationId && messages.length > 0) {
+      const last = messages[messages.length - 1];
+      if (last && last.role === "user") {
+        await this.persistMessage(conversationId, last);
+      }
+    }
     for (let iteration = 0; iteration < maxIterations; iteration++) {
       const result2 = await this.adapter.chat(conversation, chatOptions);
       if (!result2.toolCalls || result2.toolCalls.length === 0) {
+        if (conversationId) {
+          await this.persistMessage(conversationId, {
+            role: "assistant",
+            content: result2.content
+          });
+        }
         yield textDeltaPart("stream", result2.content);
         yield finishPart(result2);
         return;
@@ -1715,11 +1811,18 @@ var _AIService = class _AIService {
       const assistantContent = [];
       if (result2.content) assistantContent.push({ type: "text", text: result2.content });
       assistantContent.push(...result2.toolCalls);
-      conversation.push({
+      const assistantTurn = {
         role: "assistant",
         content: assistantContent
-      });
-      const toolResults = await this.toolRegistry.executeAll(result2.toolCalls);
+      };
+      conversation.push(assistantTurn);
+      if (conversationId) {
+        await this.persistMessage(conversationId, assistantTurn);
+      }
+      const toolResults = await this.toolRegistry.executeAll(
+        result2.toolCalls,
+        toolExecutionContext
+      );
       for (const tr of toolResults) {
         if (tr.isError && onToolError) {
           const matchedCall = result2.toolCalls.find((tc) => tc.toolCallId === tr.toolCallId);
@@ -1737,10 +1840,14 @@ var _AIService = class _AIService {
           toolName: tr.toolName,
           output: tr.output
         };
-        conversation.push({
+        const toolTurn = {
           role: "tool",
           content: [tr]
-        });
+        };
+        conversation.push(toolTurn);
+        if (conversationId) {
+          await this.persistMessage(conversationId, toolTurn);
+        }
       }
       if (abortedByCallback) {
         break;
@@ -1753,6 +1860,12 @@ var _AIService = class _AIService {
     }
     const finalOptions = { ...chatOptions, tools: void 0, toolChoice: void 0 };
     const result = await this.adapter.chat(conversation, finalOptions);
+    if (conversationId) {
+      await this.persistMessage(conversationId, {
+        role: "assistant",
+        content: result.content
+      });
+    }
     yield textDeltaPart("stream", result.content);
     yield finishPart(result);
   }
@@ -2257,6 +2370,32 @@ function buildAIRoutes(aiService, conversationService, logger) {
         }
       }
     },
+    {
+      method: "GET",
+      path: "/api/v1/ai/conversations/:id",
+      description: "Get a conversation with its full message history",
+      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 {
+          const conversation = await conversationService.get(id);
+          if (!conversation) {
+            return { status: 404, body: { error: `Conversation "${id}" not found` } };
+          }
+          if (req.user?.userId && conversation.userId && conversation.userId !== req.user.userId) {
+            return { status: 403, body: { error: "You do not have access to this conversation" } };
+          }
+          return { status: 200, body: conversation };
+        } catch (err) {
+          logger.error("[AI Route] GET /conversations/:id error", err instanceof Error ? err : void 0);
+          return { status: 500, body: { error: "Internal AI service error" } };
+        }
+      }
+    },
     {
       method: "POST",
       path: "/api/v1/ai/conversations/:id/messages",
@@ -2423,7 +2562,19 @@ function buildAgentRoutes(aiService, agentRuntime, logger) {
           ];
           const chatWithToolsOptions = {
             ...mergedOptions,
-            maxIterations: agent.planning?.maxIterations
+            maxIterations: agent.planning?.maxIterations,
+            // Forward authenticated actor → built-in data tools enforce
+            // ObjectQL RLS, action tools attribute audit to the user.
+            toolExecutionContext: req.user ? {
+              actor: {
+                id: req.user.userId,
+                name: req.user.displayName,
+                roles: req.user.roles,
+                permissions: req.user.permissions
+              },
+              conversationId: typeof body.conversationId === "string" ? body.conversationId : void 0,
+              environmentId: typeof chatContext?.environmentId === "string" ? chatContext.environmentId : void 0
+            } : void 0
           };
           const wantStream = body.stream !== false;
           if (wantStream) {
@@ -2612,7 +2763,21 @@ function buildAssistantRoutes(aiService, agentRuntime, skillRegistry, logger) {
           ];
           const chatWithToolsOptions = {
             ...mergedOptions,
-            maxIterations: agent.planning?.maxIterations
+            maxIterations: agent.planning?.maxIterations,
+            // Forward the authenticated actor into every tool the loop
+            // invokes — built-in data tools promote this into the
+            // ObjectQL execution context so row-level security scopes
+            // the LLM to whatever the human user can already see/do.
+            toolExecutionContext: req.user ? {
+              actor: {
+                id: req.user.userId,
+                name: req.user.displayName,
+                roles: req.user.roles,
+                permissions: req.user.permissions
+              },
+              conversationId: typeof body.conversationId === "string" ? body.conversationId : void 0,
+              environmentId: typeof context.environmentId === "string" ? context.environmentId : void 0
+            } : void 0
           };
           const wantStream = body.stream !== false;
           if (wantStream) {
@@ -3960,6 +4125,19 @@ function describeField(field) {
 }
 
 // src/tools/query-data.tool.ts
+function buildAiEngineContext(ctx) {
+  if (ctx?.actor) {
+    return {
+      userId: ctx.actor.id,
+      roles: ctx.actor.roles ?? [],
+      permissions: ctx.actor.permissions ?? [],
+      isSystem: false,
+      ...ctx.environmentId ? { tenantId: ctx.environmentId } : {},
+      ...ctx.traceId ? { traceId: ctx.traceId } : {}
+    };
+  }
+  return { roles: [], permissions: [], isSystem: true };
+}
 var QueryPlanSchema = import_zod.z.object({
   objectName: import_zod.z.string().min(1).describe('The snake_case object name to query (e.g. "task", "account").'),
   whereJson: import_zod.z.string().nullable().describe(
@@ -3992,7 +4170,7 @@ var QUERY_DATA_TOOL = {
 function createQueryDataHandler(ctx) {
   const retriever = new SchemaRetriever(ctx.metadata);
   const maxLimit = ctx.maxLimit ?? 100;
-  return async (args) => {
+  return async (args, execCtx) => {
     const { request } = args;
     if (!request || typeof request !== "string") {
       return JSON.stringify({ error: "query_data: `request` is required" });
@@ -4059,7 +4237,8 @@ function createQueryDataHandler(ctx) {
         where,
         fields: plan.fields ?? void 0,
         orderBy: plan.orderBy ?? void 0,
-        limit
+        limit,
+        context: buildAiEngineContext(execCtx)
       });
       return JSON.stringify({
         plan: { ...plan, where },
@@ -4239,11 +4418,13 @@ function buildHandlerEngineAdapter(engine) {
   };
 }
 function createActionToolHandler(action, ctx) {
-  const principal = ctx.principal ?? { id: "ai_agent", name: "AI Assistant" };
+  const fallbackPrincipal = ctx.principal ?? { id: "ai_agent", name: "AI Assistant" };
   const requiresRecord = Array.isArray(action.locations) && action.locations.some(
     (l) => l === "list_item" || l === "record_header" || l === "record_more" || l === "record_related"
   );
-  return async (args) => {
+  return async (args, execCtx) => {
+    const principal = execCtx?.actor ? { id: execCtx.actor.id, name: execCtx.actor.name } : fallbackPrincipal;
+    const engineCtx = buildActionEngineContext(execCtx);
     const objectName = action.objectName;
     const target = action.target;
     const result = {
@@ -4269,7 +4450,8 @@ function createActionToolHandler(action, ctx) {
       try {
         const found = await ctx.dataEngine.find(objectName, {
           where: { id: recordId },
-          limit: 1
+          limit: 1,
+          context: engineCtx
         });
         record = found[0];
         if (!record) {
@@ -4291,6 +4473,8 @@ function createActionToolHandler(action, ctx) {
           actionName: action.name,
           toolName,
           toolInput: args,
+          conversationId: execCtx?.conversationId,
+          messageId: execCtx?.messageId,
           proposedBy: principal.id
         });
         const pending = {
@@ -4328,6 +4512,19 @@ function createActionToolHandler(action, ctx) {
     }
   };
 }
+function buildActionEngineContext(ctx) {
+  if (ctx?.actor) {
+    return {
+      userId: ctx.actor.id,
+      roles: ctx.actor.roles ?? [],
+      permissions: ctx.actor.permissions ?? [],
+      isSystem: false,
+      ...ctx.environmentId ? { tenantId: ctx.environmentId } : {},
+      ...ctx.traceId ? { traceId: ctx.traceId } : {}
+    };
+  }
+  return { roles: [], permissions: [], isSystem: true };
+}
 async function dispatchScriptAction(action, ctx, params, record, principal) {
   const engineAdapter = buildHandlerEngineAdapter(ctx.dataEngine);
   const handlerCtx = { record, user: principal, engine: engineAdapter, params };
@@ -5654,6 +5851,94 @@ var AIServicePlugin = class {
 // src/index.ts
 init_data_tools();
 init_metadata_tools();
+
+// src/tools/knowledge-tools.ts
+var DEFAULT_TOP_K = 5;
+var MAX_TOP_K = 20;
+function buildEngineContext2(ctx) {
+  if (ctx?.actor) {
+    return {
+      userId: ctx.actor.id,
+      roles: ctx.actor.roles ?? [],
+      permissions: ctx.actor.permissions ?? [],
+      isSystem: false,
+      ...ctx.environmentId ? { tenantId: ctx.environmentId } : {},
+      ...ctx.traceId ? { traceId: ctx.traceId } : {}
+    };
+  }
+  return { roles: [], permissions: [], isSystem: true };
+}
+var SEARCH_KNOWLEDGE_TOOL = {
+  name: "search_knowledge",
+  description: "Search registered knowledge sources (object snapshots, uploaded files, external URLs) and return the most relevant excerpts. Use this when the user asks a question whose answer is in documents, policies, or reference material the LLM does not natively know. Results are already permission-filtered for the current user.",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Free-text question or keywords to search for."
+      },
+      sourceIds: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional list of source ids to restrict the search to. When omitted, every source the caller can see is queried."
+      },
+      topK: {
+        type: "number",
+        description: `Maximum hits to return (default ${DEFAULT_TOP_K}, max ${MAX_TOP_K}).`
+      },
+      filter: {
+        type: "object",
+        description: 'Optional adapter-specific metadata filter (e.g. {"topic":"refunds"}).'
+      }
+    },
+    required: ["query"]
+  }
+};
+function createSearchKnowledgeHandler(context) {
+  return async (args, ctx) => {
+    const query = typeof args.query === "string" ? args.query.trim() : "";
+    if (!query) {
+      return JSON.stringify({ error: "search_knowledge: `query` is required." });
+    }
+    const sourceIds = Array.isArray(args.sourceIds) ? args.sourceIds.filter((x) => typeof x === "string") : void 0;
+    const topKRaw = typeof args.topK === "number" ? args.topK : DEFAULT_TOP_K;
+    const topK = Math.max(1, Math.min(MAX_TOP_K, Math.floor(topKRaw)));
+    const filter = args.filter && typeof args.filter === "object" && !Array.isArray(args.filter) ? args.filter : void 0;
+    const opts = {
+      topK,
+      executionContext: buildEngineContext2(ctx)
+    };
+    if (sourceIds && sourceIds.length > 0) opts.sourceIds = sourceIds;
+    if (filter) opts.filter = filter;
+    try {
+      const hits = await context.knowledgeService.search(query, opts);
+      return JSON.stringify({
+        query,
+        count: hits.length,
+        hits: hits.map((h) => ({
+          documentId: h.documentId,
+          chunkId: h.chunkId,
+          sourceId: h.sourceId,
+          sourceRecordId: h.sourceRecordId,
+          score: Number(h.score?.toFixed?.(4) ?? h.score ?? 0),
+          title: h.title,
+          snippet: h.snippet,
+          metadata: h.metadata
+        }))
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `search_knowledge failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  };
+}
+function registerKnowledgeTools(registry, context) {
+  registry.register(SEARCH_KNOWLEDGE_TOOL, createSearchKnowledgeHandler(context));
+}
+
+// src/index.ts
 init_metadata_tools();
 
 // src/tools/list-packages.tool.ts
@@ -6010,6 +6295,7 @@ function registerPackageTools(registry, context) {
   ObjectQLTraceRecorder,
   PACKAGE_TOOL_DEFINITIONS,
   QUERY_DATA_TOOL,
+  SEARCH_KNOWLEDGE_TOOL,
   SchemaRetriever,
   SkillRegistry,
   ToolRegistry,
@@ -6038,6 +6324,7 @@ function registerPackageTools(registry, context) {
   modifyFieldTool,
   registerActionsAsTools,
   registerDataTools,
+  registerKnowledgeTools,
   registerMetadataTools,
   registerPackageTools,
   registerQueryDataTool,