@objectstack/service-ai 6.1.1 → 6.3.0

package/dist/index.js

@@ -1087,7 +1087,12 @@ function pickActionTool(userText, actionTools) {
     "notify",
     "publish",
     "unpublish",
-    "mark"
+    "mark",
+    "delete",
+    "remove",
+    "purge",
+    "destroy",
+    "erase"
   ]);
   const hasActionVerb = [...userTokens].some((t) => ACTION_VERBS.has(t));
   if (!hasActionVerb) return null;
@@ -1392,12 +1397,20 @@ function finishPart(result) {
 }
 var _AIService = class _AIService {
   constructor(config = {}) {
+    /**
+     * 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()`.
+     */
+    this.pendingDispatchers = /* @__PURE__ */ new Map();
     this.adapter = config.adapter ?? new MemoryLLMAdapter();
     this.logger = config.logger ?? createLogger({ level: "info", format: "pretty" });
     this.toolRegistry = config.toolRegistry ?? new ToolRegistry();
     this.conversationService = config.conversationService ?? new InMemoryConversationService();
     this.modelRegistry = config.modelRegistry;
     this.traceRecorder = config.traceRecorder ?? new NullTraceRecorder();
+    this.dataEngine = config.dataEngine;
     this.logger.info(
       `[AI] Service initialized with adapter="${this.adapter.name}", tools=${this.toolRegistry.size}, models=${this.modelRegistry?.size ?? 0}`
     );
@@ -1671,11 +1684,144 @@ var _AIService = class _AIService {
     yield textDeltaPart("stream", result.content);
     yield finishPart(result);
   }
+  // ── HITL: pending-action queue ─────────────────────────────────
+  /**
+   * 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, dispatch) {
+    this.pendingDispatchers.set(toolName, dispatch);
+  }
+  async proposePendingAction(input) {
+    if (!this.dataEngine) {
+      throw new Error("proposePendingAction requires a dataEngine \u2014 wire it via AIServiceConfig.");
+    }
+    const id = `pa_${cryptoRandomId()}`;
+    const row = {
+      id,
+      conversation_id: input.conversationId ?? null,
+      message_id: input.messageId ?? null,
+      object_name: input.objectName,
+      action_name: input.actionName,
+      tool_name: input.toolName,
+      tool_input: JSON.stringify(input.toolInput ?? {}),
+      status: "pending",
+      proposed_by: input.proposedBy ?? "ai_agent",
+      proposed_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.dataEngine.insert("ai_pending_actions", row);
+    this.logger.info(
+      `[AI] pending action proposed: ${id} (${input.toolName} on ${input.objectName})`
+    );
+    return { id };
+  }
+  async approvePendingAction(id, actorId) {
+    if (!this.dataEngine) {
+      throw new Error("approvePendingAction requires a dataEngine.");
+    }
+    const row = await this.loadPendingRow(id);
+    if (row.status !== "pending") {
+      throw new Error(`pending action ${id} is already ${row.status}`);
+    }
+    const dispatch = this.pendingDispatchers.get(row.tool_name);
+    if (!dispatch) {
+      throw new Error(
+        `no dispatcher registered for tool '${row.tool_name}' \u2014 was the AI plugin restarted without re-registering actions?`
+      );
+    }
+    await this.dataEngine.update(
+      "ai_pending_actions",
+      {
+        id,
+        status: "approved",
+        decided_by: actorId,
+        decided_at: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      { where: { id } }
+    );
+    let parsed = {};
+    try {
+      parsed = row.tool_input ? JSON.parse(row.tool_input) : {};
+    } catch {
+      parsed = {};
+    }
+    try {
+      const out = await dispatch(parsed);
+      await this.dataEngine.update(
+        "ai_pending_actions",
+        { id, status: "executed", result: JSON.stringify(out ?? null) },
+        { where: { id } }
+      );
+      this.logger.info(`[AI] pending action ${id} executed by ${actorId}`);
+      return { status: "executed", result: out };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      await this.dataEngine.update(
+        "ai_pending_actions",
+        { id, status: "failed", error: msg },
+        { where: { id } }
+      );
+      this.logger.warn(`[AI] pending action ${id} failed after approval: ${msg}`);
+      return { status: "failed", error: msg };
+    }
+  }
+  async rejectPendingAction(id, actorId, reason) {
+    if (!this.dataEngine) {
+      throw new Error("rejectPendingAction requires a dataEngine.");
+    }
+    const row = await this.loadPendingRow(id);
+    if (row.status !== "pending") {
+      throw new Error(`pending action ${id} is already ${row.status}`);
+    }
+    await this.dataEngine.update(
+      "ai_pending_actions",
+      {
+        id,
+        status: "rejected",
+        decided_by: actorId,
+        decided_at: (/* @__PURE__ */ new Date()).toISOString(),
+        rejection_reason: reason ?? null
+      },
+      { where: { id } }
+    );
+    this.logger.info(`[AI] pending action ${id} rejected by ${actorId}`);
+  }
+  async listPendingActions(filter) {
+    if (!this.dataEngine) return [];
+    const where = {};
+    if (filter?.status) {
+      where.status = Array.isArray(filter.status) ? { in: filter.status } : filter.status;
+    }
+    if (filter?.conversationId) where.conversation_id = filter.conversationId;
+    if (filter?.objectName) where.object_name = filter.objectName;
+    const rows = await this.dataEngine.find("ai_pending_actions", {
+      where,
+      limit: filter?.limit ?? 100,
+      orderBy: [{ field: "proposed_at", order: "desc" }]
+    });
+    return rows;
+  }
+  async loadPendingRow(id) {
+    const rows = await this.dataEngine.find("ai_pending_actions", {
+      where: { id },
+      limit: 1
+    });
+    const row = rows[0];
+    if (!row) throw new Error(`pending action ${id} not found`);
+    return row;
+  }
 };
 // ── Tool Call Loop ────────────────────────────────────────────
 /** Default maximum iterations for the tool call loop. */
 _AIService.DEFAULT_MAX_ITERATIONS = 10;
 var AIService = _AIService;
+function cryptoRandomId() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
 
 // src/stream/vercel-stream-encoder.ts
 function sse(data) {
@@ -2560,6 +2706,132 @@ function buildToolRoutes(aiService, logger) {
   ];
 }
 
+// src/routes/pending-action-routes.ts
+function buildPendingActionRoutes(aiService, logger) {
+  const supported = typeof aiService.listPendingActions === "function" && typeof aiService.approvePendingAction === "function" && typeof aiService.rejectPendingAction === "function";
+  if (!supported) {
+    logger.warn(
+      "[AI] HITL pending-action methods not implemented on AI service \u2014 routes return 501."
+    );
+  }
+  const notImpl = () => ({
+    status: 501,
+    body: { error: "Pending-action queue not available (dataEngine not wired)" }
+  });
+  return [
+    // ── List pending actions ───────────────────────────────────────
+    {
+      method: "GET",
+      path: "/api/v1/ai/pending-actions",
+      description: "List pending actions in the HITL approval queue",
+      auth: true,
+      permissions: ["ai:read"],
+      handler: async (req) => {
+        if (!supported) return notImpl();
+        try {
+          const query = req.query ?? {};
+          const status = typeof query.status === "string" ? query.status : void 0;
+          const conversationId = typeof query.conversationId === "string" ? query.conversationId : void 0;
+          const limitRaw = query.limit;
+          const limit = typeof limitRaw === "string" ? Number(limitRaw) : void 0;
+          const rows = await aiService.listPendingActions({
+            status,
+            conversationId,
+            limit: Number.isFinite(limit) ? limit : void 0
+          });
+          return { status: 200, body: { items: rows, total: rows.length } };
+        } catch (err) {
+          logger.error(
+            "[AI Route] /pending-actions list error",
+            err instanceof Error ? err : void 0
+          );
+          return { status: 500, body: { error: "Failed to list pending actions" } };
+        }
+      }
+    },
+    // ── Get a single pending action ────────────────────────────────
+    {
+      method: "GET",
+      path: "/api/v1/ai/pending-actions/:id",
+      description: "Get a single pending action by id",
+      auth: true,
+      permissions: ["ai:read"],
+      handler: async (req) => {
+        if (!supported) return notImpl();
+        const id = req.params?.id;
+        if (!id) return { status: 400, body: { error: "id is required" } };
+        try {
+          const rows = await aiService.listPendingActions({});
+          const found = rows.find((r) => r.id === id);
+          if (!found) return { status: 404, body: { error: `Pending action ${id} not found` } };
+          return { status: 200, body: found };
+        } catch (err) {
+          logger.error(
+            "[AI Route] /pending-actions/:id error",
+            err instanceof Error ? err : void 0
+          );
+          return { status: 500, body: { error: "Failed to load pending action" } };
+        }
+      }
+    },
+    // ── Approve & execute ──────────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/pending-actions/:id/approve",
+      description: "Approve a pending action and execute it immediately",
+      auth: true,
+      permissions: ["ai:approve"],
+      handler: async (req) => {
+        if (!supported) return notImpl();
+        const id = req.params?.id;
+        if (!id) return { status: 400, body: { error: "id is required" } };
+        const actorId = req.user?.id ?? "system";
+        try {
+          const outcome = await aiService.approvePendingAction(id, actorId);
+          const httpStatus = outcome.status === "executed" ? 200 : 500;
+          return { status: httpStatus, body: outcome };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          logger.error("[AI Route] /pending-actions/:id/approve error", err instanceof Error ? err : void 0);
+          if (/not found/i.test(msg)) return { status: 404, body: { error: msg } };
+          if (/already|not pending|no dispatcher/i.test(msg)) {
+            return { status: 409, body: { error: msg } };
+          }
+          return { status: 500, body: { error: msg } };
+        }
+      }
+    },
+    // ── Reject ─────────────────────────────────────────────────────
+    {
+      method: "POST",
+      path: "/api/v1/ai/pending-actions/:id/reject",
+      description: "Reject a pending action (will not be executed)",
+      auth: true,
+      permissions: ["ai:approve"],
+      handler: async (req) => {
+        if (!supported) return notImpl();
+        const id = req.params?.id;
+        if (!id) return { status: 400, body: { error: "id is required" } };
+        const actorId = req.user?.id ?? "system";
+        const body = req.body ?? {};
+        const reason = typeof body.reason === "string" ? body.reason : void 0;
+        try {
+          await aiService.rejectPendingAction(id, actorId, reason);
+          return { status: 200, body: { status: "rejected", id } };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          logger.error("[AI Route] /pending-actions/:id/reject error", err instanceof Error ? err : void 0);
+          if (/not found/i.test(msg)) return { status: 404, body: { error: msg } };
+          if (/already|not pending/i.test(msg)) {
+            return { status: 409, body: { error: msg } };
+          }
+          return { status: 500, body: { error: msg } };
+        }
+      }
+    }
+  ];
+}
+
 // src/conversation/objectql-conversation-service.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var CONVERSATIONS_OBJECT = "ai_conversations";
@@ -3030,6 +3302,149 @@ var AiTraceObject = ObjectSchema3.create({
   }
 });
 
+// src/objects/ai-pending-action.object.ts
+import { ObjectSchema as ObjectSchema4, Field as Field4 } from "@objectstack/spec/data";
+var AiPendingActionObject = ObjectSchema4.create({
+  name: "ai_pending_actions",
+  label: "AI Pending Action",
+  pluralLabel: "AI Pending Actions",
+  icon: "shield-check",
+  isSystem: true,
+  description: "Queue of AI-proposed action invocations awaiting human approval",
+  fields: {
+    id: Field4.text({
+      label: "Request ID",
+      required: true,
+      readonly: true
+    }),
+    conversation_id: Field4.lookup("ai_conversations", {
+      label: "Conversation",
+      required: false,
+      description: "Conversation that produced this proposal, if any"
+    }),
+    message_id: Field4.lookup("ai_messages", {
+      label: "Message",
+      required: false,
+      description: "Assistant message containing the proposed tool call"
+    }),
+    object_name: Field4.text({
+      label: "Object",
+      required: true,
+      maxLength: 128,
+      description: 'Target object name (e.g. "task")'
+    }),
+    action_name: Field4.text({
+      label: "Action",
+      required: true,
+      maxLength: 128,
+      description: 'Declarative action name (e.g. "delete_task")'
+    }),
+    tool_name: Field4.text({
+      label: "Tool",
+      required: true,
+      maxLength: 128,
+      description: 'AI tool name exposed to the LLM (e.g. "action_delete_task")'
+    }),
+    tool_input: Field4.textarea({
+      label: "Tool Input",
+      required: true,
+      description: "JSON-serialised tool arguments the LLM passed"
+    }),
+    status: Field4.select({
+      label: "Status",
+      required: true,
+      defaultValue: "pending",
+      options: [
+        { label: "Pending Approval", value: "pending" },
+        { label: "Approved (queued)", value: "approved" },
+        { label: "Executed", value: "executed" },
+        { label: "Failed", value: "failed" },
+        { label: "Rejected", value: "rejected" }
+      ]
+    }),
+    result: Field4.textarea({
+      label: "Execution Result",
+      required: false,
+      description: "JSON-serialised result from the action when executed"
+    }),
+    error: Field4.textarea({
+      label: "Error",
+      required: false,
+      description: "Error message when status=failed"
+    }),
+    rejection_reason: Field4.textarea({
+      label: "Rejection Reason",
+      required: false,
+      description: "Why the reviewer rejected (shown back to the LLM)"
+    }),
+    proposed_by: Field4.text({
+      label: "Proposed By",
+      required: false,
+      maxLength: 128,
+      description: "Principal id of the AI agent that proposed the action"
+    }),
+    decided_by: Field4.text({
+      label: "Decided By",
+      required: false,
+      maxLength: 128,
+      description: "User id of the human who approved/rejected"
+    }),
+    proposed_at: Field4.datetime({
+      label: "Proposed At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true
+    }),
+    decided_at: Field4.datetime({
+      label: "Decided At",
+      required: false,
+      description: "When approve/reject happened"
+    })
+  },
+  indexes: [
+    { fields: ["status"] },
+    { fields: ["conversation_id"] },
+    { fields: ["object_name"] },
+    { fields: ["proposed_at"] }
+  ],
+  actions: [
+    {
+      name: "approve_pending_action",
+      label: "Approve",
+      type: "api",
+      target: "/api/v1/ai/pending-actions/{recordId}/approve",
+      method: "POST",
+      locations: ["list_item", "record_header"],
+      variant: "primary",
+      confirmText: "Approve and execute this action now?",
+      successMessage: "Action approved and executed.",
+      // The approval click is the operator's authorisation gesture —
+      // the LLM must not be allowed to bypass HITL by approving itself.
+      aiExposed: false
+    },
+    {
+      name: "reject_pending_action",
+      label: "Reject",
+      type: "api",
+      target: "/api/v1/ai/pending-actions/{recordId}/reject",
+      method: "POST",
+      locations: ["list_item", "record_header"],
+      variant: "danger",
+      confirmText: "Reject this pending action? It will not be executed.",
+      successMessage: "Action rejected.",
+      aiExposed: false
+    }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list"],
+    trash: false,
+    mru: false
+  }
+});
+
 // src/views/ai-trace.view.ts
 import { defineView } from "@objectstack/spec";
 var AiTraceView = defineView({
@@ -3087,6 +3502,238 @@ var AiTraceView = defineView({
   }
 });
 
+// src/views/ai-pending-action.view.ts
+import { defineView as defineView2 } from "@objectstack/spec";
+var AiPendingActionView = defineView2({
+  list: {
+    type: "grid",
+    data: { provider: "object", object: "ai_pending_actions" },
+    columns: [
+      { field: "proposed_at", label: "Proposed", type: "datetime-relative", width: 140 },
+      { field: "status", width: 130 },
+      { field: "object_name", label: "Object", width: 140 },
+      { field: "action_name", label: "Action", width: 180 },
+      { field: "proposed_by", label: "Proposed by", width: 160 },
+      { field: "decided_by", label: "Decided by", width: 160 },
+      { field: "decided_at", label: "Decided", type: "datetime-relative", width: 140 }
+    ],
+    sort: [{ field: "proposed_at", order: "desc" }],
+    pagination: { pageSize: 50 },
+    searchableFields: ["action_name", "object_name", "tool_name", "proposed_by"],
+    filterableFields: ["status", "object_name", "action_name"],
+    rowActions: ["approve_pending_action", "reject_pending_action"],
+    // Click a row → open the detail drawer instead of navigating to a page.
+    navigation: { mode: "drawer", view: "detail", width: "640px" },
+    rowColor: {
+      field: "status",
+      mapping: {
+        pending: "amber",
+        approved: "blue",
+        executed: "green",
+        failed: "red",
+        rejected: "gray"
+      }
+    }
+  },
+  form: {
+    type: "drawer",
+    data: { provider: "object", object: "ai_pending_actions" },
+    sections: [
+      {
+        label: "Proposal",
+        columns: 2,
+        fields: [
+          { field: "status", readonly: true },
+          { field: "proposed_at", readonly: true, widget: "datetime-relative" },
+          { field: "object_name", label: "Target object", readonly: true },
+          { field: "action_name", label: "Action", readonly: true },
+          { field: "tool_name", label: "Tool exposed to LLM", readonly: true, colSpan: 2 },
+          { field: "proposed_by", label: "Proposed by (AI agent)", readonly: true, colSpan: 2 }
+        ]
+      },
+      {
+        label: "Tool input",
+        collapsible: true,
+        columns: 1,
+        fields: [
+          {
+            field: "tool_input",
+            label: "Arguments the LLM sent",
+            readonly: true,
+            widget: "json",
+            colSpan: 1,
+            helpText: "Pretty-printed JSON. Review carefully before approving \u2014 this is the exact payload that will be re-played against the handler."
+          }
+        ]
+      },
+      {
+        label: "Conversation context",
+        collapsible: true,
+        collapsed: true,
+        columns: 2,
+        fields: [
+          // Both are lookups — Studio renders them as links to the related
+          // ai_conversations / ai_messages record so operators can jump to
+          // the full transcript for context.
+          { field: "conversation_id", label: "Conversation", readonly: true },
+          { field: "message_id", label: "Assistant message", readonly: true }
+        ]
+      },
+      {
+        label: "Decision",
+        collapsible: true,
+        // Only meaningful once the row has been actioned; left collapsed
+        // by default for pending rows so the eye lands on the proposal.
+        collapsed: true,
+        columns: 2,
+        fields: [
+          { field: "decided_by", label: "Decided by", readonly: true },
+          { field: "decided_at", label: "Decided", readonly: true, widget: "datetime-relative" },
+          {
+            field: "rejection_reason",
+            label: "Rejection reason",
+            readonly: true,
+            colSpan: 2,
+            visibleOn: 'record.status == "rejected"'
+          },
+          {
+            field: "result",
+            label: "Execution result",
+            readonly: true,
+            widget: "json",
+            colSpan: 2,
+            visibleOn: 'record.status == "executed"'
+          },
+          {
+            field: "error",
+            label: "Error",
+            readonly: true,
+            colSpan: 2,
+            visibleOn: 'record.status == "failed"'
+          }
+        ]
+      }
+    ]
+  },
+  formViews: {
+    detail: {
+      type: "drawer",
+      data: { provider: "object", object: "ai_pending_actions" },
+      // Mirror of the default form. Named separately so the list's
+      // `navigation.view: 'detail'` resolves explicitly — Studio falls back
+      // to `form` if a named view isn't registered, but being explicit
+      // makes the wiring legible to readers of the metadata.
+      sections: [
+        {
+          label: "Proposal",
+          columns: 2,
+          fields: [
+            { field: "status", readonly: true },
+            { field: "proposed_at", readonly: true, widget: "datetime-relative" },
+            { field: "object_name", label: "Target object", readonly: true },
+            { field: "action_name", label: "Action", readonly: true },
+            { field: "tool_name", label: "Tool exposed to LLM", readonly: true, colSpan: 2 },
+            { field: "proposed_by", label: "Proposed by (AI agent)", readonly: true, colSpan: 2 }
+          ]
+        },
+        {
+          label: "Tool input",
+          collapsible: true,
+          columns: 1,
+          fields: [
+            { field: "tool_input", label: "Arguments the LLM sent", readonly: true, widget: "json" }
+          ]
+        },
+        {
+          label: "Conversation context",
+          collapsible: true,
+          collapsed: true,
+          columns: 2,
+          fields: [
+            { field: "conversation_id", label: "Conversation", readonly: true },
+            { field: "message_id", label: "Assistant message", readonly: true }
+          ]
+        },
+        {
+          label: "Decision",
+          collapsible: true,
+          collapsed: true,
+          columns: 2,
+          fields: [
+            { field: "decided_by", label: "Decided by", readonly: true },
+            { field: "decided_at", label: "Decided", readonly: true, widget: "datetime-relative" },
+            { field: "rejection_reason", label: "Rejection reason", readonly: true, colSpan: 2, visibleOn: 'record.status == "rejected"' },
+            { field: "result", label: "Execution result", readonly: true, widget: "json", colSpan: 2, visibleOn: 'record.status == "executed"' },
+            { field: "error", label: "Error", readonly: true, colSpan: 2, visibleOn: 'record.status == "failed"' }
+          ]
+        }
+      ]
+    }
+  },
+  listViews: {
+    pending: {
+      label: "Pending",
+      type: "grid",
+      data: { provider: "object", object: "ai_pending_actions" },
+      columns: [
+        { field: "proposed_at", label: "Proposed", type: "datetime-relative", width: 140 },
+        { field: "object_name", label: "Object", width: 140 },
+        { field: "action_name", label: "Action", width: 180 },
+        { field: "proposed_by", label: "Proposed by", width: 160 },
+        { field: "tool_name", label: "Tool", width: 200 }
+      ],
+      filter: [{ field: "status", operator: "=", value: "pending" }],
+      sort: [{ field: "proposed_at", order: "desc" }],
+      rowActions: ["approve_pending_action", "reject_pending_action"],
+      navigation: { mode: "drawer", view: "detail", width: "640px" }
+    },
+    executed: {
+      label: "Executed",
+      type: "grid",
+      data: { provider: "object", object: "ai_pending_actions" },
+      columns: [
+        { field: "decided_at", label: "Approved", type: "datetime-relative", width: 140 },
+        { field: "object_name", label: "Object", width: 140 },
+        { field: "action_name", label: "Action", width: 180 },
+        { field: "decided_by", label: "Approved by", width: 160 },
+        { field: "proposed_by", label: "Proposed by", width: 160 }
+      ],
+      filter: [{ field: "status", operator: "=", value: "executed" }],
+      sort: [{ field: "decided_at", order: "desc" }],
+      navigation: { mode: "drawer", view: "detail", width: "640px" }
+    },
+    rejected: {
+      label: "Rejected",
+      type: "grid",
+      data: { provider: "object", object: "ai_pending_actions" },
+      columns: [
+        { field: "decided_at", label: "Rejected", type: "datetime-relative", width: 140 },
+        { field: "object_name", label: "Object", width: 140 },
+        { field: "action_name", label: "Action", width: 180 },
+        { field: "decided_by", label: "Rejected by", width: 160 },
+        { field: "rejection_reason", label: "Reason", wrap: true }
+      ],
+      filter: [{ field: "status", operator: "=", value: "rejected" }],
+      sort: [{ field: "decided_at", order: "desc" }],
+      navigation: { mode: "drawer", view: "detail", width: "640px" }
+    },
+    failed: {
+      label: "Failed",
+      type: "grid",
+      data: { provider: "object", object: "ai_pending_actions" },
+      columns: [
+        { field: "decided_at", label: "When", type: "datetime-relative", width: 140 },
+        { field: "object_name", label: "Object", width: 140 },
+        { field: "action_name", label: "Action", width: 180 },
+        { field: "error", wrap: true }
+      ],
+      filter: [{ field: "status", operator: "=", value: "failed" }],
+      sort: [{ field: "decided_at", order: "desc" }],
+      navigation: { mode: "drawer", view: "detail", width: "640px" }
+    }
+  }
+});
+
 // src/plugin.ts
 init_data_tools();
 init_metadata_tools();
@@ -3243,17 +3890,17 @@ function describeField(field) {
 // src/tools/query-data.tool.ts
 var QueryPlanSchema = z.object({
   objectName: z.string().min(1).describe('The snake_case object name to query (e.g. "task", "account").'),
-  where: z.record(z.string(), z.unknown()).optional().describe(
-    'Filter conditions as key-value pairs. Use MongoDB-style operators for ranges, e.g. {"amount": {"$gt": 100}}.'
+  whereJson: z.string().nullable().describe(
+    'Filter conditions encoded as a JSON object string. Examples: `{"status":"completed"}`, `{"subject":{"$contains":"Build"}}`, `{"amount":{"$gt":100}}`. Pass null to match all records.'
   ),
-  fields: z.array(z.string()).optional().describe("Field names to return. Omit to return all fields."),
+  fields: z.array(z.string()).nullable().describe("Field names to return. Pass null to return all fields."),
   orderBy: z.array(
     z.object({
       field: z.string(),
       order: z.enum(["asc", "desc"])
     })
-  ).optional().describe("Sort order. First entry is primary sort key."),
-  limit: z.number().int().min(1).max(200).optional().describe("Maximum number of records (default 20, max 200).")
+  ).nullable().describe("Sort order. First entry is primary sort key. Pass null for no sort."),
+  limit: z.number().int().min(1).max(200).nullable().describe("Maximum number of records (default 20, max 200). Pass null for default.")
 });
 var QUERY_DATA_TOOL = {
   name: "query_data",
@@ -3264,10 +3911,6 @@ var QUERY_DATA_TOOL = {
       request: {
         type: "string",
         description: "The natural-language question to answer (paraphrase the user's request if needed for clarity)."
-      },
-      model: {
-        type: "string",
-        description: "Optional model id to use for query planning. Defaults to the AI service's default model."
       }
     },
     required: ["request"],
@@ -3278,7 +3921,7 @@ function createQueryDataHandler(ctx) {
   const retriever = new SchemaRetriever(ctx.metadata);
   const maxLimit = ctx.maxLimit ?? 100;
   return async (args) => {
-    const { request, model } = args;
+    const { request } = args;
     if (!request || typeof request !== "string") {
       return JSON.stringify({ error: "query_data: `request` is required" });
     }
@@ -3297,14 +3940,13 @@ function createQueryDataHandler(ctx) {
     const planMessages = [
       {
         role: "system",
-        content: "You translate user data questions into a single ObjectQL query plan. Use ONLY the objects and fields listed in the schema context below. Never invent field names. If the question is ambiguous, pick the most likely interpretation and use a reasonable `limit`.\n\n" + snippet
+        content: 'You translate user data questions into a single ObjectQL query plan. Use ONLY the objects and fields listed in the schema context below. Never invent field names. If the question is ambiguous, pick the most likely interpretation and use a reasonable `limit`.\n\nFilter operator hints:\n  \u2022 For partial string matches (e.g. "task named Foo", "find X"), use case-insensitive substring matching with `$contains`: `{"subject": {"$contains": "Foo"}}`. Do NOT use equality unless the user clearly supplied the exact full value.\n  \u2022 For numeric/date ranges use `$gt` / `$gte` / `$lt` / `$lte`.\n  \u2022 For "is one of" use `$in: [...]`.\n  \u2022 For exact equality just write the value: `{"status": "completed"}`.\n\n' + snippet
       },
       { role: "user", content: request }
     ];
     let plan;
     try {
       const generated = await ctx.ai.generateObject(planMessages, QueryPlanSchema, {
-        model,
         schemaName: "ObjectQLQueryPlan",
         schemaDescription: "A single ObjectQL find() query to answer the user request."
       });
@@ -3321,15 +3963,34 @@ function createQueryDataHandler(ctx) {
       });
     }
     const limit = Math.min(plan.limit ?? 20, maxLimit);
+    let where;
+    if (plan.whereJson) {
+      try {
+        const parsed = JSON.parse(plan.whereJson);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          where = parsed;
+        } else {
+          return JSON.stringify({
+            plan,
+            error: `whereJson must encode a JSON object, got: ${plan.whereJson}`
+          });
+        }
+      } catch (err) {
+        return JSON.stringify({
+          plan,
+          error: `whereJson is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
     try {
       const records = await ctx.dataEngine.find(plan.objectName, {
-        where: plan.where,
-        fields: plan.fields,
-        orderBy: plan.orderBy,
+        where,
+        fields: plan.fields ?? void 0,
+        orderBy: plan.orderBy ?? void 0,
         limit
       });
       return JSON.stringify({
-        plan,
+        plan: { ...plan, where },
         count: records.length,
         records
       });
@@ -3346,15 +4007,43 @@ function registerQueryDataTool(registry, context) {
 }
 
 // src/tools/action-tools.ts
-function actionSkipReason(action) {
+function actionRequiresApproval(action) {
+  return Boolean(
+    action.confirmText || action.mode === "delete" || action.variant === "danger"
+  );
+}
+function actionSkipReason(action, ctx) {
   if (action.aiExposed === false) {
     return "opted-out via aiExposed:false";
   }
-  if (action.type !== "script") return `type='${action.type}' not yet supported`;
-  if (!action.target && !action.body) return "no target or body";
-  if (action.confirmText) return "requires confirmation (confirmText set)";
-  if (action.mode === "delete") return "mode='delete' \u2014 destructive";
-  if (action.variant === "danger") return "variant='danger' \u2014 destructive";
+  if (action.type === "url" || action.type === "modal" || action.type === "form") {
+    return `type='${action.type}' is UI-only`;
+  }
+  if (action.type !== "script" && action.type !== "api" && action.type !== "flow") {
+    return `type='${action.type}' not supported`;
+  }
+  if (action.type === "script" && !action.target && !action.body) {
+    return "no target or body";
+  }
+  if ((action.type === "api" || action.type === "flow") && !action.target) {
+    return `type='${action.type}' requires a target`;
+  }
+  if (ctx) {
+    if (action.type === "flow" && !ctx.automation) {
+      return "no automation service available";
+    }
+    if (action.type === "api" && !ctx.apiClient && !ctx.apiBaseUrl) {
+      return "no apiClient or apiBaseUrl configured";
+    }
+  }
+  if (actionRequiresApproval(action)) {
+    const approvalReady = ctx?.enableActionApproval === true && Boolean(ctx?.aiService?.proposePendingAction);
+    if (!approvalReady) {
+      if (action.confirmText) return "requires confirmation (confirmText set)";
+      if (action.mode === "delete") return "mode='delete' \u2014 destructive";
+      if (action.variant === "danger") return "variant='danger' \u2014 destructive";
+    }
+  }
   return null;
 }
 function fieldTypeToJsonType(t) {
@@ -3453,7 +4142,8 @@ function describeAction(action, ownerObject) {
   return parts.join(" ");
 }
 function actionToToolDefinition(action, ownerObject, allObjects, toolPrefix = "action_") {
-  if (actionSkipReason(action) !== null) return null;
+  if (action.aiExposed === false) return null;
+  if (action.type === "url" || action.type === "modal" || action.type === "form") return null;
   return {
     name: actionToolName(action, toolPrefix),
     description: describeAction(action, ownerObject),
@@ -3465,12 +4155,19 @@ function buildHandlerEngineAdapter(engine) {
     update: (object, id, data) => engine.update(object, { ...data, id }, { where: { id } }),
     insert: (object, data) => engine.insert(object, data),
     find: (object, where) => engine.find(object, { where }),
-    delete: (object, ids) => engine.delete(object, { where: { id: ids.length === 1 ? ids[0] : { $in: ids } } })
+    delete: async (object, ids) => {
+      if (!Array.isArray(ids) || ids.length === 0) return 0;
+      let count = 0;
+      for (const id of ids) {
+        await engine.delete(object, { where: { id } });
+        count++;
+      }
+      return count;
+    }
   };
 }
 function createActionToolHandler(action, ctx) {
   const principal = ctx.principal ?? { id: "ai_agent", name: "AI Assistant" };
-  const engineAdapter = buildHandlerEngineAdapter(ctx.dataEngine);
   const requiresRecord = Array.isArray(action.locations) && action.locations.some(
     (l) => l === "list_item" || l === "record_header" || l === "record_more" || l === "record_related"
   );
@@ -3486,8 +4183,8 @@ function createActionToolHandler(action, ctx) {
       result.error = "Action has no objectName; cannot dispatch.";
       return JSON.stringify(result);
     }
-    if (!target) {
-      result.error = "Action has no target handler.";
+    if (!target && action.type !== "script") {
+      result.error = "Action has no target.";
       return JSON.stringify(result);
     }
     const recordId = typeof args.recordId === "string" && args.recordId.length > 0 ? args.recordId : void 0;
@@ -3514,14 +4211,40 @@ function createActionToolHandler(action, ctx) {
       }
     }
     const { recordId: _omit, ...userParams } = args;
+    if (ctx.enableActionApproval && actionRequiresApproval(action) && ctx.aiService?.proposePendingAction) {
+      try {
+        const toolName = `${ctx.toolPrefix ?? "action_"}${action.name}`;
+        const { id } = await ctx.aiService.proposePendingAction({
+          objectName,
+          actionName: action.name,
+          toolName,
+          toolInput: args,
+          proposedBy: principal.id
+        });
+        const pending = {
+          ok: true,
+          action: action.name,
+          objectName,
+          recordId,
+          status: "pending_approval",
+          pendingActionId: id,
+          message: `Action '${action.name}' is destructive and requires human approval. Proposal queued as ${id}. An operator must approve via Studio's pending-actions inbox before it runs. Do NOT call this tool again for the same intent \u2014 wait for the operator.`
+        };
+        return JSON.stringify(pending);
+      } catch (err) {
+        result.error = `Failed to enqueue approval: ${err instanceof Error ? err.message : String(err)}`;
+        return JSON.stringify(result);
+      }
+    }
     try {
-      const handlerCtx = {
-        record,
-        user: principal,
-        engine: engineAdapter,
-        params: userParams
-      };
-      const out = await ctx.dataEngine.executeAction?.(objectName, target, handlerCtx);
+      let out;
+      if (action.type === "api") {
+        out = await dispatchApiAction(action, ctx, userParams, record, recordId);
+      } else if (action.type === "flow") {
+        out = await dispatchFlowAction(action, ctx, userParams, record, principal);
+      } else {
+        out = await dispatchScriptAction(action, ctx, userParams, record, principal);
+      }
       result.ok = true;
       result.result = out ?? null;
       const successMsg = typeof action.successMessage === "string" ? action.successMessage : void 0;
@@ -3533,6 +4256,87 @@ function createActionToolHandler(action, ctx) {
     }
   };
 }
+async function dispatchScriptAction(action, ctx, params, record, principal) {
+  const engineAdapter = buildHandlerEngineAdapter(ctx.dataEngine);
+  const handlerCtx = { record, user: principal, engine: engineAdapter, params };
+  return await ctx.dataEngine.executeAction?.(action.objectName, action.target, handlerCtx);
+}
+function buildApiRequestBody(action, args, record, recordId) {
+  const shape = action.bodyShape;
+  const wrapKey = shape && typeof shape === "object" && "wrap" in shape && typeof shape.wrap === "string" ? shape.wrap : void 0;
+  const body = wrapKey ? { [wrapKey]: { ...args } } : { ...args };
+  if (action.recordIdParam) {
+    const idField = action.recordIdField ?? "id";
+    const idValue = record ? record[idField] : recordId;
+    if (idValue !== void 0) body[action.recordIdParam] = idValue;
+  }
+  if (action.bodyExtra && typeof action.bodyExtra === "object") {
+    Object.assign(body, action.bodyExtra);
+  }
+  return body;
+}
+async function dispatchApiAction(action, ctx, params, record, recordId) {
+  const client = ctx.apiClient ?? (ctx.apiBaseUrl ? createFetchApiClient({ baseUrl: ctx.apiBaseUrl, headers: ctx.apiHeaders }) : void 0);
+  if (!client) {
+    throw new Error('No apiClient configured for type:"api" action dispatch.');
+  }
+  const method = action.method ?? "POST";
+  const body = buildApiRequestBody(action, params, record, recordId);
+  return await client.request({
+    url: action.target,
+    method,
+    body: method === "GET" || method === "DELETE" ? void 0 : body,
+    headers: ctx.apiHeaders
+  });
+}
+async function dispatchFlowAction(action, ctx, params, record, principal) {
+  if (!ctx.automation) {
+    throw new Error('No automation service available for type:"flow" action dispatch.');
+  }
+  const result = await ctx.automation.execute(action.target, {
+    triggerData: { record, params, user: principal, action: action.name }
+  });
+  if (result && typeof result === "object" && "success" in result && result.success === false) {
+    throw new Error(
+      `Flow '${action.target}' failed: ${result.error ?? "unknown error"}`
+    );
+  }
+  return result;
+}
+function createFetchApiClient(options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("createFetchApiClient: no global fetch available; pass options.fetch.");
+  }
+  return {
+    async request({ url, method, body, headers }) {
+      const absolute = /^https?:\/\//.test(url) ? url : `${(options.baseUrl ?? "").replace(/\/$/, "")}${url.startsWith("/") ? "" : "/"}${url}`;
+      const res = await fetchImpl(absolute, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...options.headers ?? {},
+          ...headers ?? {}
+        },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      const text = await res.text();
+      const parsed = text ? safeJsonParse(text) : null;
+      if (!res.ok) {
+        const msg = parsed && typeof parsed === "object" && "error" in parsed ? parsed.error : text;
+        throw new Error(`${method} ${absolute} \u2192 ${res.status}: ${typeof msg === "string" ? msg : JSON.stringify(msg)}`);
+      }
+      return parsed;
+    }
+  };
+}
+function safeJsonParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
 async function registerActionsAsTools(registry, context) {
   const objects = await context.metadata.listObjects();
   const objMap = new Map(
@@ -3549,7 +4353,13 @@ async function registerActionsAsTools(registry, context) {
         ...action,
         objectName: action.objectName ?? obj.name
       };
-      const reason = actionSkipReason(normalized);
+      const reason = actionSkipReason(normalized, {
+        automation: context.automation,
+        apiClient: context.apiClient,
+        apiBaseUrl: context.apiBaseUrl,
+        enableActionApproval: context.enableActionApproval,
+        aiService: context.aiService
+      });
       if (reason !== null) {
         skipped.push({ action: normalized.name, reason });
         continue;
@@ -3560,8 +4370,33 @@ async function registerActionsAsTools(registry, context) {
         skipped.push({ action: normalized.name, reason: "tool name already registered" });
         continue;
       }
-      registry.register(definition, createActionToolHandler(normalized, context));
+      const handler = createActionToolHandler(normalized, context);
+      registry.register(definition, handler);
       registered.push(definition.name);
+      if (context.enableActionApproval && actionRequiresApproval(normalized) && context.aiService?.registerPendingActionDispatcher) {
+        const bypassCtx = {
+          ...context,
+          enableActionApproval: false
+        };
+        const directHandler = createActionToolHandler(normalized, bypassCtx);
+        context.aiService.registerPendingActionDispatcher(
+          definition.name,
+          async (input) => {
+            const raw = await directHandler(input);
+            let parsed = raw;
+            try {
+              parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+            } catch {
+              parsed = raw;
+            }
+            if (parsed && typeof parsed === "object" && "ok" in parsed && parsed.ok === false) {
+              const errMsg = parsed.error != null ? String(parsed.error) : "action handler reported failure";
+              throw new Error(errMsg);
+            }
+            return parsed;
+          }
+        );
+      }
     }
   }
   return { registered, skipped };
@@ -4439,26 +5274,29 @@ var AIServicePlugin = class {
       ctx.logger.info(`[AI] ModelRegistry initialised with ${modelRegistry.size} model(s)`);
     }
     let traceRecorder;
+    let dataEngine;
+    try {
+      const engine = ctx.getService("data");
+      if (engine && typeof engine.insert === "function") {
+        dataEngine = engine;
+      }
+    } catch {
+    }
     if (this.options.traceRecorder === null) {
       ctx.logger.debug("[AI] Tracing disabled (traceRecorder=null)");
     } else if (this.options.traceRecorder) {
       traceRecorder = this.options.traceRecorder;
-    } else {
-      try {
-        const engine = ctx.getService("data");
-        if (engine && typeof engine.insert === "function") {
-          traceRecorder = new ObjectQLTraceRecorder(engine, { logger: ctx.logger });
-          ctx.logger.info("[AI] Using ObjectQLTraceRecorder (IDataEngine detected)");
-        }
-      } catch {
-      }
+    } else if (dataEngine) {
+      traceRecorder = new ObjectQLTraceRecorder(dataEngine, { logger: ctx.logger });
+      ctx.logger.info("[AI] Using ObjectQLTraceRecorder (IDataEngine detected)");
     }
     const config = {
       adapter,
       logger: ctx.logger,
       conversationService,
       modelRegistry,
-      traceRecorder
+      traceRecorder,
+      dataEngine
     };
     this.service = new AIService(config);
     if (hasExisting) {
@@ -4473,8 +5311,8 @@ var AIServicePlugin = class {
       type: "plugin",
       scope: "project",
       namespace: "ai",
-      objects: [AiConversationObject, AiMessageObject, AiTraceObject],
-      views: [AiTraceView]
+      objects: [AiConversationObject, AiMessageObject, AiTraceObject, AiPendingActionObject],
+      views: [AiTraceView, AiPendingActionView]
     });
     if (this.options.debug) {
       ctx.hook("ai:beforeChat", async (messages) => {
@@ -4514,11 +5352,24 @@ var AIServicePlugin = class {
           });
           ctx.logger.info("[AI] query_data tool registered");
           try {
+            let automation;
+            try {
+              automation = ctx.getService("automation");
+            } catch {
+              automation = void 0;
+            }
+            const apiBaseUrl = this.options.apiActionBaseUrl ?? process.env.OS_AI_ACTION_API_BASE_URL;
+            const apiHeaders = this.options.apiActionHeaders;
             const { registered, skipped } = await registerActionsAsTools(
               this.service.toolRegistry,
               {
                 metadata: metadataService,
-                dataEngine
+                dataEngine,
+                automation,
+                apiBaseUrl,
+                apiHeaders,
+                enableActionApproval: this.options.enableActionApproval ?? false,
+                aiService: this.service
               }
             );
             if (registered.length > 0) {
@@ -4699,6 +5550,9 @@ var AIServicePlugin = class {
     const toolRoutes = buildToolRoutes(this.service, ctx.logger);
     routes.push(...toolRoutes);
     ctx.logger.info(`[AI] Tool routes registered (${toolRoutes.length} routes)`);
+    const pendingRoutes = buildPendingActionRoutes(this.service, ctx.logger);
+    routes.push(...pendingRoutes);
+    ctx.logger.info(`[AI] Pending-action routes registered (${pendingRoutes.length} routes)`);
     if (metadataService) {
       const skillRegistry = new SkillRegistry(metadataService);
       const agentRuntime = new AgentRuntime(metadataService, skillRegistry);