@objectstack/service-ai 6.3.0 → 6.5.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AIToolDefinition, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, ProposePendingActionInput, PendingActionStatus, PendingActionRow, AIConversation, IMetadataService, IAutomationService } from '@objectstack/spec/contracts';
+import { AIToolDefinition, ToolExecutionContext, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, ProposePendingActionInput, PendingActionStatus, PendingActionRow, AIConversation, IMetadataService, IKnowledgeService, IAutomationService } from '@objectstack/spec/contracts';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as AI from '@objectstack/spec/ai';
@@ -13,9 +13,12 @@ import * as _objectstack_spec_data from '@objectstack/spec/data';
 /**
  * Handler function for a registered tool.
  *
- * Receives parsed arguments and returns the tool output as a string.
+ * Receives parsed arguments and an optional per-call execution context.
+ * Returns the tool output as a string (typically JSON). Tools that
+ * require permission enforcement should use `ctx.actor` and propagate
+ * it into the underlying engine call.
  */
-type ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
+type ToolHandler = (args: Record<string, unknown>, ctx?: ToolExecutionContext) => Promise<string> | string;
 /**
  * Extended ToolResultPart that carries an `isError` flag for internal
  * error-tracking in the tool-call loop.
@@ -61,12 +64,20 @@ declare class ToolRegistry {
     names(): string[];
     /**
      * 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.
      */
-    execute(toolCall: ToolCallPart): Promise<ToolExecutionResult>;
+    execute(toolCall: ToolCallPart, ctx?: ToolExecutionContext): Promise<ToolExecutionResult>;
     /**
-     * Execute multiple tool calls in parallel.
+     * Execute multiple tool calls in parallel, threading the same
+     * execution context to each handler.
      */
-    executeAll(toolCalls: ToolCallPart[]): Promise<ToolExecutionResult[]>;
+    executeAll(toolCalls: ToolCallPart[], ctx?: ToolExecutionContext): Promise<ToolExecutionResult[]>;
     /**
      * Clear all registered tools.
      */
@@ -300,6 +311,13 @@ declare class AIService implements IAIService {
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
+    /**
+     * 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`.
+     */
+    private persistMessage;
     /**
      * Run an adapter call and emit a trace event.
      *
@@ -850,6 +868,27 @@ interface MetadataToolContext {
  */
 declare function registerMetadataTools(registry: ToolRegistry, context: MetadataToolContext): void;
 
+/**
+ * Services required by the knowledge tool family.
+ */
+interface KnowledgeToolContext {
+    /** Orchestrator that resolves adapters and applies permission filtering. */
+    knowledgeService: IKnowledgeService;
+}
+declare const SEARCH_KNOWLEDGE_TOOL: AIToolDefinition;
+/**
+ * Register knowledge-related tools on the AI tool registry.
+ *
+ * @example
+ * ```ts
+ * ctx.hook('ai:ready', async (aiService) => {
+ *   const knowledgeService = ctx.getService<IKnowledgeService>('knowledge');
+ *   registerKnowledgeTools(aiService.toolRegistry, { knowledgeService });
+ * });
+ * ```
+ */
+declare function registerKnowledgeTools(registry: ToolRegistry, context: KnowledgeToolContext): void;
+
 /**
  * list_packages — AI Tool Metadata
  *
@@ -10279,4 +10318,4 @@ declare function buildAssistantRoutes(aiService: AIService, agentRuntime: AgentR
  */
 declare function buildToolRoutes(aiService: AIService, logger: Logger): RouteDefinition[];
 
-export { ACTIONS_EXECUTOR_SKILL, AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type ActionToolsContext, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, AiTraceView, type CostEstimate, DATA_CHAT_AGENT, DATA_EXPLORER_SKILL, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, METADATA_ASSISTANT_AGENT, METADATA_AUTHORING_SKILL, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, actionSkipReason, actionToToolDefinition, actionToolName, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerActionsAsTools, registerDataTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };
+export { ACTIONS_EXECUTOR_SKILL, AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type ActionToolsContext, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, AiTraceView, type CostEstimate, DATA_CHAT_AGENT, DATA_EXPLORER_SKILL, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, type KnowledgeToolContext, METADATA_ASSISTANT_AGENT, METADATA_AUTHORING_SKILL, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, SEARCH_KNOWLEDGE_TOOL, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, actionSkipReason, actionToToolDefinition, actionToolName, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerActionsAsTools, registerDataTools, registerKnowledgeTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AIToolDefinition, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, ProposePendingActionInput, PendingActionStatus, PendingActionRow, AIConversation, IMetadataService, IAutomationService } from '@objectstack/spec/contracts';
+import { AIToolDefinition, ToolExecutionContext, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, ProposePendingActionInput, PendingActionStatus, PendingActionRow, AIConversation, IMetadataService, IKnowledgeService, IAutomationService } from '@objectstack/spec/contracts';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as AI from '@objectstack/spec/ai';
@@ -13,9 +13,12 @@ import * as _objectstack_spec_data from '@objectstack/spec/data';
 /**
  * Handler function for a registered tool.
  *
- * Receives parsed arguments and returns the tool output as a string.
+ * Receives parsed arguments and an optional per-call execution context.
+ * Returns the tool output as a string (typically JSON). Tools that
+ * require permission enforcement should use `ctx.actor` and propagate
+ * it into the underlying engine call.
  */
-type ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
+type ToolHandler = (args: Record<string, unknown>, ctx?: ToolExecutionContext) => Promise<string> | string;
 /**
  * Extended ToolResultPart that carries an `isError` flag for internal
  * error-tracking in the tool-call loop.
@@ -61,12 +64,20 @@ declare class ToolRegistry {
     names(): string[];
     /**
      * 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.
      */
-    execute(toolCall: ToolCallPart): Promise<ToolExecutionResult>;
+    execute(toolCall: ToolCallPart, ctx?: ToolExecutionContext): Promise<ToolExecutionResult>;
     /**
-     * Execute multiple tool calls in parallel.
+     * Execute multiple tool calls in parallel, threading the same
+     * execution context to each handler.
      */
-    executeAll(toolCalls: ToolCallPart[]): Promise<ToolExecutionResult[]>;
+    executeAll(toolCalls: ToolCallPart[], ctx?: ToolExecutionContext): Promise<ToolExecutionResult[]>;
     /**
      * Clear all registered tools.
      */
@@ -300,6 +311,13 @@ declare class AIService implements IAIService {
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
+    /**
+     * 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`.
+     */
+    private persistMessage;
     /**
      * Run an adapter call and emit a trace event.
      *
@@ -850,6 +868,27 @@ interface MetadataToolContext {
  */
 declare function registerMetadataTools(registry: ToolRegistry, context: MetadataToolContext): void;
 
+/**
+ * Services required by the knowledge tool family.
+ */
+interface KnowledgeToolContext {
+    /** Orchestrator that resolves adapters and applies permission filtering. */
+    knowledgeService: IKnowledgeService;
+}
+declare const SEARCH_KNOWLEDGE_TOOL: AIToolDefinition;
+/**
+ * Register knowledge-related tools on the AI tool registry.
+ *
+ * @example
+ * ```ts
+ * ctx.hook('ai:ready', async (aiService) => {
+ *   const knowledgeService = ctx.getService<IKnowledgeService>('knowledge');
+ *   registerKnowledgeTools(aiService.toolRegistry, { knowledgeService });
+ * });
+ * ```
+ */
+declare function registerKnowledgeTools(registry: ToolRegistry, context: KnowledgeToolContext): void;
+
 /**
  * list_packages — AI Tool Metadata
  *
@@ -10279,4 +10318,4 @@ declare function buildAssistantRoutes(aiService: AIService, agentRuntime: AgentR
  */
 declare function buildToolRoutes(aiService: AIService, logger: Logger): RouteDefinition[];
 
-export { ACTIONS_EXECUTOR_SKILL, AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type ActionToolsContext, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, AiTraceView, type CostEstimate, DATA_CHAT_AGENT, DATA_EXPLORER_SKILL, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, METADATA_ASSISTANT_AGENT, METADATA_AUTHORING_SKILL, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, actionSkipReason, actionToToolDefinition, actionToolName, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerActionsAsTools, registerDataTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };
+export { ACTIONS_EXECUTOR_SKILL, AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type ActionToolsContext, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, AiTraceView, type CostEstimate, DATA_CHAT_AGENT, DATA_EXPLORER_SKILL, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, type KnowledgeToolContext, METADATA_ASSISTANT_AGENT, METADATA_AUTHORING_SKILL, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, SEARCH_KNOWLEDGE_TOOL, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, actionSkipReason, actionToToolDefinition, actionToolName, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerActionsAsTools, registerDataTools, registerKnowledgeTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };