@objectstack/service-ai 6.1.1 → 6.3.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, AIConversation, IMetadataService } from '@objectstack/spec/contracts';
+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';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as AI from '@objectstack/spec/ai';
@@ -258,6 +258,13 @@ interface AIServiceConfig {
     modelRegistry?: ModelRegistry;
     /** Trace recorder for per-call observability. Defaults to no-op. */
     traceRecorder?: TraceRecorder;
+    /**
+     * Data engine used to persist `ai_pending_actions` rows for the
+     * actions-as-tools HITL queue. Optional — when omitted, the
+     * `proposePendingAction` / `approvePendingAction` methods throw if
+     * called. Wired by `AIServicePlugin` after the data driver is up.
+     */
+    dataEngine?: IDataEngine;
 }
 /**
  * AIService — Unified AI capability service.
@@ -281,6 +288,15 @@ declare class AIService implements IAIService {
     readonly conversationService: IAIConversationService;
     readonly modelRegistry?: ModelRegistry;
     readonly traceRecorder: TraceRecorder;
+    /**
+     * Map of tool-name → dispatcher used to re-run an approved pending
+     * action. Populated by `registerActionsAsTools()` when action
+     * approval is enabled. Kept private because callers should go
+     * through `approvePendingAction()`.
+     */
+    private readonly pendingDispatchers;
+    /** Data engine for `ai_pending_actions` persistence. */
+    private readonly dataEngine?;
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
@@ -335,6 +351,29 @@ declare class AIService implements IAIService {
      * fed back until a final text stream is produced.
      */
     streamChatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): AsyncIterable<TextStreamPart<ToolSet>>;
+    /**
+     * Register a dispatcher callback for a tool. Called by
+     * `registerActionsAsTools()` when action approval is enabled so the
+     * approval handler can re-run the exact same code path the LLM
+     * would have triggered.
+     */
+    registerPendingActionDispatcher(toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>): void;
+    proposePendingAction(input: ProposePendingActionInput): Promise<{
+        id: string;
+    }>;
+    approvePendingAction(id: string, actorId: string): Promise<{
+        status: 'executed' | 'failed';
+        result?: unknown;
+        error?: string;
+    }>;
+    rejectPendingAction(id: string, actorId: string, reason?: string): Promise<void>;
+    listPendingActions(filter?: {
+        status?: PendingActionStatus | PendingActionStatus[];
+        conversationId?: string;
+        objectName?: string;
+        limit?: number;
+    }): Promise<PendingActionRow[]>;
+    private loadPendingRow;
 }
 
 /**
@@ -356,6 +395,12 @@ interface AIServicePluginOptions {
     models?: AI.ModelConfig[];
     /** Default model id (must appear in `models`). */
     defaultModelId?: string;
+    /**
+     * Explicit trace recorder override. When set, auto-detection
+     * of {@link ObjectQLTraceRecorder} is skipped.
+     *
+     * Set to `null` to disable tracing entirely.
+     */
     /**
      * Explicit trace recorder override. When set, auto-detection
      * of {@link ObjectQLTraceRecorder} is skipped.
@@ -363,6 +408,31 @@ interface AIServicePluginOptions {
      * Set to `null` to disable tracing entirely.
      */
     traceRecorder?: TraceRecorder | null;
+    /**
+     * Base URL prepended to relative `target` paths for `type:'api'`
+     * actions invoked by the AI tool runtime. When unset, falls back to
+     * `process.env.OS_AI_ACTION_API_BASE_URL`. If neither is set, api
+     * actions are skipped at registration with a clear reason.
+     */
+    apiActionBaseUrl?: string;
+    /**
+     * Extra HTTP headers (e.g. `{ Authorization: 'Bearer ...' }`) applied
+     * to every `type:'api'` action dispatch. Useful for forwarding the
+     * caller's session token so server-side authorization still applies.
+     */
+    apiActionHeaders?: Record<string, string>;
+    /**
+     * Opt into Human-In-The-Loop approval for dangerous actions exposed
+     * as AI tools. When `true`, actions with `confirmText`, `mode:'delete'`,
+     * or `variant:'danger'` are still registered as tools — but invoking
+     * them enqueues an `ai_pending_actions` row and returns
+     * `{ status: 'pending_approval' }` instead of running. A human
+     * operator approves via Studio's pending-actions inbox to execute.
+     *
+     * Defaults to `false` (safer: dangerous actions stay invisible to LLM
+     * until an operator explicitly enables this routing).
+     */
+    enableActionApproval?: boolean;
 }
 /**
  * AIServicePlugin — Kernel plugin for the unified AI capability service.
@@ -988,6 +1058,16 @@ interface ObjectDef {
  * subject record when a `recordIdParam` is configured and (b) dispatch
  * to the registered handler via `executeAction`.
  *
+ * `automation` enables `type:'flow'` actions to dispatch into the
+ * automation service's flow runner. When omitted, flow actions are
+ * skipped at registration time with a clear reason.
+ *
+ * `apiClient` (or `apiBaseUrl`) enables `type:'api'` actions to perform
+ * an HTTP call to the action's `target` URL. The default client uses
+ * the global `fetch` and prepends `apiBaseUrl` to relative `target`s.
+ * Supply a custom client when you need bespoke auth, in-process
+ * routing, or stubbing in tests.
+ *
  * `principal` lets callers attribute AI-initiated mutations to a known
  * user id; it defaults to a synthetic `'ai_agent'` user so traces /
  * audit always have *some* actor.
@@ -995,6 +1075,14 @@ interface ObjectDef {
 interface ActionToolsContext {
     metadata: IMetadataService;
     dataEngine: IDataEngine;
+    /** Automation service for `type:'flow'` action dispatch. Optional. */
+    automation?: IAutomationService;
+    /** Custom API client for `type:'api'` actions. Defaults to a fetch-based client. */
+    apiClient?: ApiActionClient;
+    /** Base URL prepended to relative `target` paths for `type:'api'` actions. */
+    apiBaseUrl?: string;
+    /** Extra HTTP headers (e.g. auth bearer) applied to every `type:'api'` call. */
+    apiHeaders?: Record<string, string>;
     /** Synthetic user attribution for AI-initiated calls. */
     principal?: {
         id: string;
@@ -1002,14 +1090,57 @@ interface ActionToolsContext {
     };
     /** Tool-name prefix (default: `action_`). Keeps namespace separate from data tools. */
     toolPrefix?: string;
+    /**
+     * AI service used to enqueue HITL approvals for dangerous actions.
+     * When supplied together with `enableActionApproval: true`, actions
+     * that would otherwise be skipped on safety grounds (`confirmText`,
+     * `mode:'delete'`, `variant:'danger'`) are registered as tools whose
+     * handler proposes a pending action and returns
+     * `{ status: 'pending_approval' }` instead of executing.
+     */
+    aiService?: {
+        proposePendingAction?: (input: {
+            objectName: string;
+            actionName: string;
+            toolName: string;
+            toolInput: Record<string, unknown>;
+            conversationId?: string;
+            messageId?: string;
+            proposedBy?: string;
+        }) => Promise<{
+            id: string;
+        }>;
+        registerPendingActionDispatcher?: (toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>) => void;
+    };
+    /**
+     * Opt into the HITL approval queue for dangerous actions. Default
+     * is `false` (safer: dangerous actions stay invisible to the LLM
+     * until an operator explicitly enables approval routing).
+     */
+    enableActionApproval?: boolean;
 }
 /**
- * Decide whether an action should be auto-exposed as a tool.
+ * Minimal HTTP client shape used by `type:'api'` action dispatch.
  *
- * Returns `null` when exposed, or a string reason when skipped.
- * Exported for tests and Studio "AI exposure" diagnostics.
+ * Implementations are expected to return a JSON-deserialised body (or
+ * `null` for empty responses) on 2xx, and throw on non-2xx so the tool
+ * surfaces the failure to the LLM as a tool error.
  */
-declare function actionSkipReason(action: Action): string | null;
+interface ApiActionClient {
+    request(input: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+}
+declare function actionSkipReason(action: Action, ctx?: {
+    automation?: IAutomationService;
+    apiClient?: ApiActionClient;
+    apiBaseUrl?: string;
+    enableActionApproval?: boolean;
+    aiService?: ActionToolsContext['aiService'];
+}): string | null;
 /** Compute the AI tool name for a given action (prefixed for namespacing). */
 declare function actionToolName(action: Action, prefix?: string): string;
 /**
@@ -1433,7 +1564,7 @@ declare const AiConversationObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -1572,7 +1703,7 @@ declare const AiConversationObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -2005,7 +2136,7 @@ declare const AiConversationObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -3358,7 +3489,7 @@ declare const AiMessageObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -3497,7 +3628,7 @@ declare const AiMessageObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -3930,7 +4061,7 @@ declare const AiMessageObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -5285,7 +5416,7 @@ declare const AiTraceObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -5424,7 +5555,7 @@ declare const AiTraceObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -5857,7 +5988,7 @@ declare const AiTraceObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -9970,19 +10101,26 @@ interface QueryDataToolContext {
  * Kept small and strict — every property is documented so providers like
  * OpenAI Structured Outputs and Anthropic Tool Use can render high-quality
  * prompts from the schema metadata.
+ *
+ * NOTE: `where` is intentionally typed as a JSON string rather than a free-form
+ * record. OpenAI's Structured Outputs surface rejects `propertyNames`
+ * (which Zod's `z.record(z.string(), ...)` emits), and Anthropic's tool-use
+ * surface dislikes open-ended object schemas without `additionalProperties`.
+ * Having the model emit a JSON-encoded filter sidesteps both restrictions and
+ * keeps the tool portable across providers.
  */
 declare const QueryPlanSchema: z.ZodObject<{
     objectName: z.ZodString;
-    where: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    whereJson: z.ZodNullable<z.ZodString>;
+    fields: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    orderBy: z.ZodNullable<z.ZodArray<z.ZodObject<{
         field: z.ZodString;
         order: z.ZodEnum<{
             asc: "asc";
             desc: "desc";
         }>;
     }, z.core.$strip>>>;
-    limit: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 /** Strongly-typed query plan inferred from the LLM. */
 type QueryPlan = z.infer<typeof QueryPlanSchema>;

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, AIConversation, IMetadataService } from '@objectstack/spec/contracts';
+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';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as AI from '@objectstack/spec/ai';
@@ -258,6 +258,13 @@ interface AIServiceConfig {
     modelRegistry?: ModelRegistry;
     /** Trace recorder for per-call observability. Defaults to no-op. */
     traceRecorder?: TraceRecorder;
+    /**
+     * Data engine used to persist `ai_pending_actions` rows for the
+     * actions-as-tools HITL queue. Optional — when omitted, the
+     * `proposePendingAction` / `approvePendingAction` methods throw if
+     * called. Wired by `AIServicePlugin` after the data driver is up.
+     */
+    dataEngine?: IDataEngine;
 }
 /**
  * AIService — Unified AI capability service.
@@ -281,6 +288,15 @@ declare class AIService implements IAIService {
     readonly conversationService: IAIConversationService;
     readonly modelRegistry?: ModelRegistry;
     readonly traceRecorder: TraceRecorder;
+    /**
+     * Map of tool-name → dispatcher used to re-run an approved pending
+     * action. Populated by `registerActionsAsTools()` when action
+     * approval is enabled. Kept private because callers should go
+     * through `approvePendingAction()`.
+     */
+    private readonly pendingDispatchers;
+    /** Data engine for `ai_pending_actions` persistence. */
+    private readonly dataEngine?;
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
@@ -335,6 +351,29 @@ declare class AIService implements IAIService {
      * fed back until a final text stream is produced.
      */
     streamChatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): AsyncIterable<TextStreamPart<ToolSet>>;
+    /**
+     * Register a dispatcher callback for a tool. Called by
+     * `registerActionsAsTools()` when action approval is enabled so the
+     * approval handler can re-run the exact same code path the LLM
+     * would have triggered.
+     */
+    registerPendingActionDispatcher(toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>): void;
+    proposePendingAction(input: ProposePendingActionInput): Promise<{
+        id: string;
+    }>;
+    approvePendingAction(id: string, actorId: string): Promise<{
+        status: 'executed' | 'failed';
+        result?: unknown;
+        error?: string;
+    }>;
+    rejectPendingAction(id: string, actorId: string, reason?: string): Promise<void>;
+    listPendingActions(filter?: {
+        status?: PendingActionStatus | PendingActionStatus[];
+        conversationId?: string;
+        objectName?: string;
+        limit?: number;
+    }): Promise<PendingActionRow[]>;
+    private loadPendingRow;
 }
 
 /**
@@ -356,6 +395,12 @@ interface AIServicePluginOptions {
     models?: AI.ModelConfig[];
     /** Default model id (must appear in `models`). */
     defaultModelId?: string;
+    /**
+     * Explicit trace recorder override. When set, auto-detection
+     * of {@link ObjectQLTraceRecorder} is skipped.
+     *
+     * Set to `null` to disable tracing entirely.
+     */
     /**
      * Explicit trace recorder override. When set, auto-detection
      * of {@link ObjectQLTraceRecorder} is skipped.
@@ -363,6 +408,31 @@ interface AIServicePluginOptions {
      * Set to `null` to disable tracing entirely.
      */
     traceRecorder?: TraceRecorder | null;
+    /**
+     * Base URL prepended to relative `target` paths for `type:'api'`
+     * actions invoked by the AI tool runtime. When unset, falls back to
+     * `process.env.OS_AI_ACTION_API_BASE_URL`. If neither is set, api
+     * actions are skipped at registration with a clear reason.
+     */
+    apiActionBaseUrl?: string;
+    /**
+     * Extra HTTP headers (e.g. `{ Authorization: 'Bearer ...' }`) applied
+     * to every `type:'api'` action dispatch. Useful for forwarding the
+     * caller's session token so server-side authorization still applies.
+     */
+    apiActionHeaders?: Record<string, string>;
+    /**
+     * Opt into Human-In-The-Loop approval for dangerous actions exposed
+     * as AI tools. When `true`, actions with `confirmText`, `mode:'delete'`,
+     * or `variant:'danger'` are still registered as tools — but invoking
+     * them enqueues an `ai_pending_actions` row and returns
+     * `{ status: 'pending_approval' }` instead of running. A human
+     * operator approves via Studio's pending-actions inbox to execute.
+     *
+     * Defaults to `false` (safer: dangerous actions stay invisible to LLM
+     * until an operator explicitly enables this routing).
+     */
+    enableActionApproval?: boolean;
 }
 /**
  * AIServicePlugin — Kernel plugin for the unified AI capability service.
@@ -988,6 +1058,16 @@ interface ObjectDef {
  * subject record when a `recordIdParam` is configured and (b) dispatch
  * to the registered handler via `executeAction`.
  *
+ * `automation` enables `type:'flow'` actions to dispatch into the
+ * automation service's flow runner. When omitted, flow actions are
+ * skipped at registration time with a clear reason.
+ *
+ * `apiClient` (or `apiBaseUrl`) enables `type:'api'` actions to perform
+ * an HTTP call to the action's `target` URL. The default client uses
+ * the global `fetch` and prepends `apiBaseUrl` to relative `target`s.
+ * Supply a custom client when you need bespoke auth, in-process
+ * routing, or stubbing in tests.
+ *
  * `principal` lets callers attribute AI-initiated mutations to a known
  * user id; it defaults to a synthetic `'ai_agent'` user so traces /
  * audit always have *some* actor.
@@ -995,6 +1075,14 @@ interface ObjectDef {
 interface ActionToolsContext {
     metadata: IMetadataService;
     dataEngine: IDataEngine;
+    /** Automation service for `type:'flow'` action dispatch. Optional. */
+    automation?: IAutomationService;
+    /** Custom API client for `type:'api'` actions. Defaults to a fetch-based client. */
+    apiClient?: ApiActionClient;
+    /** Base URL prepended to relative `target` paths for `type:'api'` actions. */
+    apiBaseUrl?: string;
+    /** Extra HTTP headers (e.g. auth bearer) applied to every `type:'api'` call. */
+    apiHeaders?: Record<string, string>;
     /** Synthetic user attribution for AI-initiated calls. */
     principal?: {
         id: string;
@@ -1002,14 +1090,57 @@ interface ActionToolsContext {
     };
     /** Tool-name prefix (default: `action_`). Keeps namespace separate from data tools. */
     toolPrefix?: string;
+    /**
+     * AI service used to enqueue HITL approvals for dangerous actions.
+     * When supplied together with `enableActionApproval: true`, actions
+     * that would otherwise be skipped on safety grounds (`confirmText`,
+     * `mode:'delete'`, `variant:'danger'`) are registered as tools whose
+     * handler proposes a pending action and returns
+     * `{ status: 'pending_approval' }` instead of executing.
+     */
+    aiService?: {
+        proposePendingAction?: (input: {
+            objectName: string;
+            actionName: string;
+            toolName: string;
+            toolInput: Record<string, unknown>;
+            conversationId?: string;
+            messageId?: string;
+            proposedBy?: string;
+        }) => Promise<{
+            id: string;
+        }>;
+        registerPendingActionDispatcher?: (toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>) => void;
+    };
+    /**
+     * Opt into the HITL approval queue for dangerous actions. Default
+     * is `false` (safer: dangerous actions stay invisible to the LLM
+     * until an operator explicitly enables approval routing).
+     */
+    enableActionApproval?: boolean;
 }
 /**
- * Decide whether an action should be auto-exposed as a tool.
+ * Minimal HTTP client shape used by `type:'api'` action dispatch.
  *
- * Returns `null` when exposed, or a string reason when skipped.
- * Exported for tests and Studio "AI exposure" diagnostics.
+ * Implementations are expected to return a JSON-deserialised body (or
+ * `null` for empty responses) on 2xx, and throw on non-2xx so the tool
+ * surfaces the failure to the LLM as a tool error.
  */
-declare function actionSkipReason(action: Action): string | null;
+interface ApiActionClient {
+    request(input: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+}
+declare function actionSkipReason(action: Action, ctx?: {
+    automation?: IAutomationService;
+    apiClient?: ApiActionClient;
+    apiBaseUrl?: string;
+    enableActionApproval?: boolean;
+    aiService?: ActionToolsContext['aiService'];
+}): string | null;
 /** Compute the AI tool name for a given action (prefixed for namespacing). */
 declare function actionToolName(action: Action, prefix?: string): string;
 /**
@@ -1433,7 +1564,7 @@ declare const AiConversationObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -1572,7 +1703,7 @@ declare const AiConversationObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -2005,7 +2136,7 @@ declare const AiConversationObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -3358,7 +3489,7 @@ declare const AiMessageObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -3497,7 +3628,7 @@ declare const AiMessageObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -3930,7 +4061,7 @@ declare const AiMessageObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -5285,7 +5416,7 @@ declare const AiTraceObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -5424,7 +5555,7 @@ declare const AiTraceObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -5857,7 +5988,7 @@ declare const AiTraceObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("restore" | "export" | "import" | "search" | "upsert" | "create" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "purge")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -9970,19 +10101,26 @@ interface QueryDataToolContext {
  * Kept small and strict — every property is documented so providers like
  * OpenAI Structured Outputs and Anthropic Tool Use can render high-quality
  * prompts from the schema metadata.
+ *
+ * NOTE: `where` is intentionally typed as a JSON string rather than a free-form
+ * record. OpenAI's Structured Outputs surface rejects `propertyNames`
+ * (which Zod's `z.record(z.string(), ...)` emits), and Anthropic's tool-use
+ * surface dislikes open-ended object schemas without `additionalProperties`.
+ * Having the model emit a JSON-encoded filter sidesteps both restrictions and
+ * keeps the tool portable across providers.
  */
 declare const QueryPlanSchema: z.ZodObject<{
     objectName: z.ZodString;
-    where: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    whereJson: z.ZodNullable<z.ZodString>;
+    fields: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    orderBy: z.ZodNullable<z.ZodArray<z.ZodObject<{
         field: z.ZodString;
         order: z.ZodEnum<{
             asc: "asc";
             desc: "desc";
         }>;
     }, z.core.$strip>>>;
-    limit: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 /** Strongly-typed query plan inferred from the LLM. */
 type QueryPlan = z.infer<typeof QueryPlanSchema>;