@objectstack/service-ai 6.0.0 → 6.2.0

package/dist/index.js

@@ -844,8 +844,112 @@ var MemoryLLMAdapter = class {
   async chat(messages, options) {
     const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
     const userContent = lastUserMessage?.content;
-    const text = typeof userContent === "string" ? userContent : "(complex content)";
-    const content = lastUserMessage ? `[memory] ${text}` : "[memory] (no user message)";
+    const userText = typeof userContent === "string" ? userContent : "(complex content)";
+    const tools = options?.tools;
+    const hasQueryDataTool = Array.isArray(tools) && tools.some((t) => t?.name === "query_data");
+    const alreadyCalledQueryData = messages.some(
+      (m) => m.role === "tool" && Array.isArray(m.content) && m.content.some((c) => c?.toolName === "query_data")
+    );
+    const alreadyCalledAction = messages.some(
+      (m) => m.role === "tool" && Array.isArray(m.content) && m.content.some(
+        (c) => typeof c?.toolName === "string" && c.toolName.startsWith("action_")
+      )
+    );
+    if (Array.isArray(tools) && !alreadyCalledAction && lastUserMessage) {
+      const actionTools = tools.filter((t) => typeof t?.name === "string" && t.name.startsWith("action_"));
+      const chosen = pickActionTool(userText, actionTools);
+      if (chosen) {
+        const recordId = extractRecordIdFromMessages(messages, userText);
+        if (recordId) {
+          const toolCallId = `memory_tc_${Date.now().toString(36)}`;
+          return {
+            content: "",
+            model: options?.model ?? "memory",
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            toolCalls: [
+              {
+                type: "tool-call",
+                toolCallId,
+                toolName: chosen.name,
+                input: { recordId }
+              }
+            ]
+          };
+        }
+      }
+    }
+    if (hasQueryDataTool && !alreadyCalledQueryData && lastUserMessage) {
+      const toolCallId = `memory_tc_${Date.now().toString(36)}`;
+      return {
+        content: "",
+        model: options?.model ?? "memory",
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        toolCalls: [
+          {
+            type: "tool-call",
+            toolCallId,
+            toolName: "query_data",
+            input: { request: userText }
+          }
+        ]
+      };
+    }
+    if (alreadyCalledAction) {
+      const lastTool = [...messages].reverse().find((m) => m.role === "tool");
+      const part = Array.isArray(lastTool?.content) ? lastTool.content.find((c) => typeof c?.toolName === "string" && c.toolName.startsWith("action_")) : void 0;
+      const raw = part?.output && typeof part.output === "object" && "value" in part.output ? part.output.value : part?.result;
+      let payload = {};
+      if (typeof raw === "string") {
+        try {
+          payload = JSON.parse(raw);
+        } catch {
+        }
+      } else if (raw && typeof raw === "object") {
+        payload = raw;
+      }
+      if (payload.error) {
+        return {
+          content: `[memory] action ${payload.action ?? ""} failed: ${payload.error}`,
+          model: options?.model ?? "memory",
+          usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+        };
+      }
+      return {
+        content: `[memory] ${payload.message ?? "Action executed."} (${payload.action ?? "action"})`,
+        model: options?.model ?? "memory",
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      };
+    }
+    if (alreadyCalledQueryData) {
+      const lastTool = [...messages].reverse().find((m) => m.role === "tool");
+      const part = Array.isArray(lastTool?.content) ? lastTool.content.find((c) => c?.toolName === "query_data") : void 0;
+      let payload = {};
+      const raw = part?.output && typeof part.output === "object" && "value" in part.output ? part.output.value : part?.result;
+      if (typeof raw === "string") {
+        try {
+          payload = JSON.parse(raw);
+        } catch {
+          payload = {};
+        }
+      } else if (raw && typeof raw === "object") {
+        payload = raw;
+      }
+      if (payload.error) {
+        return {
+          content: `[memory] query_data failed: ${payload.error}`,
+          model: options?.model ?? "memory",
+          usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+        };
+      }
+      const records = payload.records ?? [];
+      const count = payload.count ?? records.length;
+      return {
+        content: `[memory] Found ${count} record${count === 1 ? "" : "s"} for "${userText}".`,
+        model: options?.model ?? "memory",
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      };
+    }
+    const content = lastUserMessage ? `[memory] ${userText}` : "[memory] (no user message)";
     return {
       content,
       model: options?.model ?? "memory",
@@ -897,23 +1001,42 @@ var MemoryLLMAdapter = class {
    */
   async generateObject(messages, schema, options) {
     const sys = messages.filter((m) => m.role === "system").map((m) => typeof m.content === "string" ? m.content : "").join("\n");
-    const headerRe = /^###\s+([a-z0-9_]+)\b/gim;
+    const headerRe = /^###\s+([a-z0-9_]+)(?:\s+—\s+([^\n]+))?/gim;
     const candidates = [];
     for (const match of sys.matchAll(headerRe)) {
-      if (match[1]) candidates.push(match[1]);
+      const machineName = match[1];
+      if (!machineName) continue;
+      const aliasText = match[2] ?? "";
+      const aliasTokens = /* @__PURE__ */ new Set();
+      for (const t of machineName.split(/[^a-z0-9]+/)) {
+        if (t) aliasTokens.add(t);
+      }
+      for (const t of aliasText.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (t) aliasTokens.add(t);
+      }
+      for (const t of [...aliasTokens]) {
+        if (t.length > 3 && t.endsWith("s")) aliasTokens.add(t.slice(0, -1));
+      }
+      candidates.push({ name: machineName, aliasTokens });
     }
     const lastUser = [...messages].reverse().find((m) => m.role === "user");
     const userText = typeof lastUser?.content === "string" ? lastUser.content.toLowerCase() : "";
     const userTokens = new Set(
       userText.split(/[^a-z0-9_]+/).filter((t) => t.length > 1)
     );
-    let chosen = candidates[0];
+    for (const t of [...userTokens]) {
+      if (t.length > 3 && t.endsWith("s")) userTokens.add(t.slice(0, -1));
+    }
+    let chosen = candidates[0]?.name;
     let bestScore = -1;
-    for (const name of candidates) {
-      const score = name.split(/[^a-z0-9]+/).reduce((acc, tok) => acc + (tok && userTokens.has(tok) ? 1 : 0), 0);
+    for (const cand of candidates) {
+      let score = 0;
+      for (const tok of cand.aliasTokens) {
+        if (userTokens.has(tok)) score += 1;
+      }
       if (score > bestScore) {
         bestScore = score;
-        chosen = name;
+        chosen = cand.name;
       }
     }
     const attempts = [];
@@ -934,6 +1057,103 @@ var MemoryLLMAdapter = class {
     );
   }
 };
+function pickActionTool(userText, actionTools) {
+  if (actionTools.length === 0 || !userText) return null;
+  const userTokens = new Set(
+    userText.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2)
+  );
+  const ACTION_VERBS = /* @__PURE__ */ new Set([
+    "complete",
+    "finish",
+    "done",
+    "close",
+    "start",
+    "begin",
+    "resume",
+    "clone",
+    "copy",
+    "duplicate",
+    "cancel",
+    "abort",
+    "archive",
+    "restore",
+    "approve",
+    "reject",
+    "assign",
+    "unassign",
+    "export",
+    "import",
+    "send",
+    "notify",
+    "publish",
+    "unpublish",
+    "mark",
+    "delete",
+    "remove",
+    "purge",
+    "destroy",
+    "erase"
+  ]);
+  const hasActionVerb = [...userTokens].some((t) => ACTION_VERBS.has(t));
+  if (!hasActionVerb) return null;
+  let best = null;
+  let bestScore = 0;
+  for (const tool of actionTools) {
+    const nameTokens = tool.name.replace(/^action_/, "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2);
+    let score = 0;
+    for (const tok of nameTokens) {
+      if (!userTokens.has(tok)) continue;
+      score += ACTION_VERBS.has(tok) ? 3 : 1;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      best = tool;
+    }
+  }
+  return bestScore >= 3 ? best : null;
+}
+function extractRecordIdFromMessages(messages, userText) {
+  const userTokens = userText.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2);
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== "tool" || !Array.isArray(m.content)) continue;
+    const parts = m.content;
+    for (const part of parts) {
+      if (part?.toolName !== "query_data") continue;
+      const raw = part.output && typeof part.output === "object" && "value" in part.output ? part.output.value : part.result;
+      let payload = {};
+      if (typeof raw === "string") {
+        try {
+          payload = JSON.parse(raw);
+        } catch {
+        }
+      } else if (raw && typeof raw === "object") {
+        payload = raw;
+      }
+      const records = payload.records ?? [];
+      if (records.length === 0) continue;
+      let bestId;
+      let bestScore = -1;
+      for (const rec of records) {
+        if (!rec || typeof rec !== "object") continue;
+        const id = rec.id;
+        if (typeof id !== "string" && typeof id !== "number") continue;
+        const hay = Object.values(rec).filter((v) => typeof v === "string").join(" ").toLowerCase();
+        const hayTokens = hay.split(/[^a-z0-9]+/).filter(Boolean);
+        let score = 0;
+        for (const ut of userTokens) {
+          if (hayTokens.includes(ut)) score += 1;
+        }
+        if (score > bestScore) {
+          bestScore = score;
+          bestId = String(id);
+        }
+      }
+      return bestId ?? String(records[0].id);
+    }
+  }
+  return void 0;
+}
 
 // src/tools/tool-registry.ts
 var ToolRegistry = class {
@@ -1177,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}`
     );
@@ -1297,6 +1525,13 @@ var _AIService = class _AIService {
    *    maximum number of iterations (`maxIterations`) is reached.
    */
   async chatWithTools(messages, options) {
+    return this.instrument(
+      "chat_with_tools",
+      options,
+      () => this.chatWithToolsImpl(messages, options)
+    );
+  }
+  async chatWithToolsImpl(messages, options) {
     const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
     const maxIterations = maxIter ?? _AIService.DEFAULT_MAX_ITERATIONS;
     const registeredTools = this.toolRegistry.getAll();
@@ -1449,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) {
@@ -2338,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";
@@ -2808,6 +3302,438 @@ 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({
+  list: {
+    type: "grid",
+    data: { provider: "object", object: "ai_traces" },
+    columns: [
+      { field: "created_at", label: "Time" },
+      { field: "operation" },
+      { field: "model" },
+      { field: "agent_id", label: "Agent" },
+      { field: "latency_ms", label: "Latency (ms)" },
+      { field: "total_tokens", label: "Tokens" },
+      { field: "cost_total", label: "Cost" },
+      { field: "status" }
+    ],
+    sort: [{ field: "created_at", order: "desc" }],
+    pagination: { pageSize: 50 },
+    searchableFields: ["conversation_id", "agent_id", "model", "error"],
+    filterableFields: ["operation", "model", "status"]
+  },
+  listViews: {
+    errors: {
+      label: "Errors",
+      type: "grid",
+      data: { provider: "object", object: "ai_traces" },
+      columns: [
+        { field: "created_at", label: "Time" },
+        { field: "operation" },
+        { field: "model" },
+        { field: "latency_ms", label: "Latency (ms)" },
+        { field: "error" }
+      ],
+      filter: [
+        { field: "status", operator: "=", value: "error" }
+      ],
+      sort: [{ field: "created_at", order: "desc" }]
+    },
+    by_model: {
+      label: "By Model",
+      type: "grid",
+      data: { provider: "object", object: "ai_traces" },
+      columns: [
+        { field: "model" },
+        { field: "operation" },
+        { field: "latency_ms", label: "Latency (ms)" },
+        { field: "total_tokens", label: "Tokens" },
+        { field: "cost_total", label: "Cost" },
+        { field: "status" },
+        { field: "created_at", label: "Time" }
+      ],
+      grouping: { fields: [{ field: "model" }] },
+      sort: [{ field: "created_at", order: "desc" }]
+    }
+  }
+});
+
+// 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();
@@ -2860,8 +3786,11 @@ var SchemaRetriever = class {
     const lines = ["## Schema context (auto-injected)"];
     for (const hit of hits) {
       const obj = hit.object;
-      const label = obj.label ? ` \u2014 ${obj.label}` : "";
-      lines.push(`### ${obj.name}${label}`);
+      const parts = [];
+      if (obj.label) parts.push(obj.label);
+      if (obj.pluralLabel && obj.pluralLabel !== obj.label) parts.push(`(${obj.pluralLabel})`);
+      const header = parts.length > 0 ? ` \u2014 ${parts.join(" ")}` : "";
+      lines.push(`### ${obj.name}${header}`);
       const fields = Object.entries(obj.fields ?? {}).slice(0, maxFieldsPerObject);
       for (const [name, field] of fields) {
         lines.push(`  - ${name}: ${describeField(field)}`);
@@ -2961,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",
@@ -2982,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"],
@@ -2996,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" });
     }
@@ -3015,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."
       });
@@ -3039,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
       });
@@ -3063,6 +4006,402 @@ function registerQueryDataTool(registry, context) {
   registry.register(QUERY_DATA_TOOL, createQueryDataHandler(context));
 }
 
+// src/tools/action-tools.ts
+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 === "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) {
+  switch (t) {
+    case "number":
+    case "currency":
+    case "percent":
+    case "rating":
+    case "slider":
+    case "autonumber":
+      return "number";
+    case "boolean":
+    case "toggle":
+      return "boolean";
+    case "multiselect":
+    case "checkboxes":
+    case "tags":
+      return "array";
+    default:
+      return "string";
+  }
+}
+function resolveParam(param, ownerObject, allObjects) {
+  const fieldRef = param.field;
+  const owner = param.objectOverride && allObjects.get(param.objectOverride) ? allObjects.get(param.objectOverride) : ownerObject;
+  const field = fieldRef ? owner?.fields?.[fieldRef] : void 0;
+  const name = param.name ?? fieldRef;
+  if (!name) return null;
+  const type = param.type ?? field?.type;
+  const jsonType = fieldTypeToJsonType(type);
+  const schema = { type: jsonType };
+  const label = typeof param.label === "string" ? param.label : field?.label;
+  const help = param.helpText ?? field?.description;
+  const description = [label, help].filter(Boolean).join(" \u2014 ") || void 0;
+  if (description) schema.description = description;
+  const optionSource = param.options ?? field?.options;
+  if (Array.isArray(optionSource) && optionSource.length > 0) {
+    const values = optionSource.map((o) => typeof o === "string" ? o : o.value).filter((v) => typeof v === "string");
+    if (values.length > 0) {
+      schema.enum = jsonType === "array" ? void 0 : values;
+      if (jsonType === "array") {
+        schema.items = { type: "string", enum: values };
+      }
+    }
+  } else if (jsonType === "array") {
+    schema.items = { type: "string" };
+  }
+  if (param.defaultValue !== void 0) {
+    schema.default = param.defaultValue;
+  }
+  const required = Boolean(param.required ?? field?.required ?? false);
+  return { name, schema, required };
+}
+function buildParametersSchema(action, ownerObject, allObjects) {
+  const properties = {};
+  const required = [];
+  const isRowContext = Array.isArray(action.locations) && action.locations.some((l) => l === "list_item" || l === "record_header" || l === "record_more" || l === "record_related");
+  if (action.objectName && isRowContext) {
+    properties.recordId = {
+      type: "string",
+      description: `The ${action.objectName} record id to act on.`
+    };
+    if (action.recordIdParam || action.recordIdField) {
+      required.push("recordId");
+    }
+  }
+  for (const param of action.params ?? []) {
+    const resolved = resolveParam(param, ownerObject, allObjects);
+    if (!resolved) continue;
+    properties[resolved.name] = resolved.schema;
+    if (resolved.required) required.push(resolved.name);
+  }
+  return {
+    type: "object",
+    properties,
+    ...required.length > 0 ? { required } : {},
+    additionalProperties: false
+  };
+}
+function actionToolName(action, prefix = "action_") {
+  return `${prefix}${action.name}`;
+}
+function describeAction(action, ownerObject) {
+  const label = typeof action.label === "string" ? action.label : action.name.replace(/_/g, " ");
+  const target = action.objectName ?? ownerObject?.name;
+  const targetLabel = ownerObject?.label ?? target;
+  const parts = [];
+  parts.push(`${label}${targetLabel ? ` \u2014 operates on ${targetLabel}` : ""}.`);
+  if (action.successMessage && typeof action.successMessage === "string") {
+    parts.push(`On success: ${action.successMessage}`);
+  }
+  if (action.mode) parts.push(`Mode: ${action.mode}.`);
+  parts.push(
+    "Use this when the user asks to perform this operation in natural language."
+  );
+  return parts.join(" ");
+}
+function actionToToolDefinition(action, ownerObject, allObjects, toolPrefix = "action_") {
+  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),
+    parameters: buildParametersSchema(action, ownerObject, allObjects)
+  };
+}
+function buildHandlerEngineAdapter(engine) {
+  return {
+    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: 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 requiresRecord = Array.isArray(action.locations) && action.locations.some(
+    (l) => l === "list_item" || l === "record_header" || l === "record_more" || l === "record_related"
+  );
+  return async (args) => {
+    const objectName = action.objectName;
+    const target = action.target;
+    const result = {
+      ok: false,
+      action: action.name,
+      objectName
+    };
+    if (!objectName) {
+      result.error = "Action has no objectName; cannot dispatch.";
+      return JSON.stringify(result);
+    }
+    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;
+    let record;
+    if (requiresRecord) {
+      if (!recordId) {
+        result.error = `recordId is required for this action \u2014 supply the id of the ${objectName} record to act on (use query_data first if you don't have it).`;
+        return JSON.stringify(result);
+      }
+      try {
+        const found = await ctx.dataEngine.find(objectName, {
+          where: { id: recordId },
+          limit: 1
+        });
+        record = found[0];
+        if (!record) {
+          result.error = `Record ${recordId} not found in ${objectName}.`;
+          return JSON.stringify(result);
+        }
+        result.recordId = recordId;
+      } catch (err) {
+        result.error = `Failed to load record: ${err instanceof Error ? err.message : String(err)}`;
+        return JSON.stringify(result);
+      }
+    }
+    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 {
+      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;
+      result.message = successMsg ?? `Action '${action.name}' executed successfully.`;
+      return JSON.stringify(result);
+    } catch (err) {
+      result.error = err instanceof Error ? err.message : String(err);
+      return JSON.stringify(result);
+    }
+  };
+}
+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(
+    objects.filter((o) => Boolean(o?.name)).map((o) => [o.name, o])
+  );
+  const registered = [];
+  const skipped = [];
+  const prefix = context.toolPrefix ?? "action_";
+  for (const obj of objects) {
+    if (!obj?.actions || !Array.isArray(obj.actions)) continue;
+    for (const action of obj.actions) {
+      if (!action || typeof action.name !== "string") continue;
+      const normalized = {
+        ...action,
+        objectName: action.objectName ?? obj.name
+      };
+      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;
+      }
+      const definition = actionToToolDefinition(normalized, obj, objMap, prefix);
+      if (!definition) continue;
+      if (registry.has(definition.name)) {
+        skipped.push({ action: normalized.name, reason: "tool name already registered" });
+        continue;
+      }
+      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 };
+}
+
 // src/agent-runtime.ts
 import { AgentSchema } from "@objectstack/spec/ai";
 var AgentRuntime = class {
@@ -3365,6 +4704,16 @@ var SkillRegistry = class {
     const resolved = [];
     for (const skill of skills) {
       for (const toolName of skill.tools) {
+        if (toolName.endsWith("*")) {
+          const prefix = toolName.slice(0, -1);
+          for (const def2 of availableTools) {
+            if (!def2.name.startsWith(prefix)) continue;
+            if (seen.has(def2.name)) continue;
+            resolved.push(def2);
+            seen.add(def2.name);
+          }
+          continue;
+        }
         if (seen.has(toolName)) continue;
         const def = toolMap.get(toolName);
         if (def) {
@@ -3428,7 +4777,8 @@ Always answer in the same language the user is using. Detailed tool-usage guidan
     maxTokens: 4096
   },
   // Capability bundle lives on the skill; the agent only references it.
-  skills: ["data_explorer"],
+  // `data_explorer` = read side, `actions_executor` = write side.
+  skills: ["data_explorer", "actions_executor"],
   active: true,
   visibility: "global",
   guardrails: {
@@ -3508,6 +4858,7 @@ Guidelines:
 7. Never expose internal IDs unless the user explicitly asks for them.
 8. Always answer in the same language the user is using.`,
   tools: [
+    "query_data",
     "list_objects",
     "describe_object",
     "query_records",
@@ -3577,6 +4928,44 @@ Guidelines:
   active: true
 };
 
+// src/skills/actions-executor-skill.ts
+var ACTIONS_EXECUTOR_SKILL = {
+  name: "actions_executor",
+  label: "Action Executor",
+  description: "Perform business operations on the user's data \u2014 invoke actions like 'mark as complete', 'start task', 'clone record' through natural language.",
+  instructions: `You can perform business operations by invoking the user's registered actions.
+
+Capabilities:
+- Each tool whose name starts with \`action_\` is a business operation declared on an object.
+- Read the tool description carefully \u2014 it tells you what the action does and what record types it applies to.
+- Most actions need a \`recordId\` argument. If you don't already have one from a prior \`query_data\` call, run \`query_data\` first to find the right record, then invoke the action with its id.
+
+Guidelines:
+1. Confirm intent \u2014 when the user says "complete it" / "start that one", make sure you know *which* record they mean. Ask if ambiguous.
+2. Use \`query_data\` to look up records by natural-language description ("the design review task", "tickets assigned to me").
+3. After invoking an action, the tool returns \`{ ok, message, result }\`. Summarise success in plain language; surface errors verbatim.
+4. Never invent recordIds. If \`query_data\` didn't return one, tell the user instead of guessing.
+5. Action tools are pre-filtered for safety \u2014 destructive operations (\`mode: 'delete'\`, \`variant: 'danger'\`, anything with \`confirmText\`) are *not* exposed here and require explicit user confirmation in the UI.
+6. Always answer in the same language the user is using.`,
+  // Dynamically materialised: the runtime registers one tool per Action,
+  // and the skill subscribes to the whole family via the `action_*`
+  // glob (resolved by SkillRegistry.flattenToTools).
+  tools: ["action_*"],
+  triggerPhrases: [
+    "complete",
+    "mark as",
+    "start",
+    "finish",
+    "clone",
+    "duplicate",
+    "do it",
+    "run",
+    "invoke",
+    "execute"
+  ],
+  active: true
+};
+
 // src/adapters/vercel-adapter.ts
 import { generateText, streamText, generateObject, tool as vercelTool, jsonSchema } from "ai";
 function buildVercelOptions(options) {
@@ -3885,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) {
@@ -3919,7 +5311,8 @@ var AIServicePlugin = class {
       type: "plugin",
       scope: "project",
       namespace: "ai",
-      objects: [AiConversationObject, AiMessageObject, AiTraceObject]
+      objects: [AiConversationObject, AiMessageObject, AiTraceObject, AiPendingActionObject],
+      views: [AiTraceView, AiPendingActionView]
     });
     if (this.options.debug) {
       ctx.hook("ai:beforeChat", async (messages) => {
@@ -3958,6 +5351,44 @@ var AIServicePlugin = class {
             dataEngine
           });
           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,
+                automation,
+                apiBaseUrl,
+                apiHeaders,
+                enableActionApproval: this.options.enableActionApproval ?? false,
+                aiService: this.service
+              }
+            );
+            if (registered.length > 0) {
+              ctx.logger.info(
+                `[AI] ${registered.length} action tool(s) registered: ${registered.join(", ")}`
+              );
+            }
+            if (skipped.length > 0) {
+              ctx.logger.debug(
+                `[AI] Skipped ${skipped.length} action(s) for AI exposure`,
+                { skipped }
+              );
+            }
+          } catch (err) {
+            ctx.logger.warn(
+              "[AI] Failed to register action tools",
+              err instanceof Error ? { error: err.message } : { error: String(err) }
+            );
+          }
         }
         if (metadataService) {
           const { DATA_TOOL_DEFINITIONS: DATA_TOOL_DEFINITIONS2 } = await Promise.resolve().then(() => (init_data_tools(), data_tools_exports));
@@ -4009,6 +5440,19 @@ var AIServicePlugin = class {
           } catch (err) {
             ctx.logger.warn("[AI] Failed to register data_explorer skill", err instanceof Error ? { error: err.message } : { error: String(err) });
           }
+          try {
+            const skillExists = typeof metadataService.exists === "function" ? await withTimeout(metadataService.exists("skill", ACTIONS_EXECUTOR_SKILL.name)) : false;
+            if (skillExists === null) {
+              ctx.logger.warn("[AI] Metadata service timed out checking actions_executor skill, skipping");
+            } else if (!skillExists) {
+              await withTimeout(metadataService.register("skill", ACTIONS_EXECUTOR_SKILL.name, ACTIONS_EXECUTOR_SKILL));
+              ctx.logger.info("[AI] actions_executor skill registered");
+            } else {
+              ctx.logger.debug("[AI] actions_executor skill already exists, skipping auto-registration");
+            }
+          } catch (err) {
+            ctx.logger.warn("[AI] Failed to register actions_executor skill", err instanceof Error ? { error: err.message } : { error: String(err) });
+          }
         }
       }
     } catch {
@@ -4106,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);
@@ -4468,16 +5915,20 @@ function registerPackageTools(registry, context) {
   registry.register(setActivePackageTool, createSetActivePackageHandler(context));
 }
 export {
+  ACTIONS_EXECUTOR_SKILL,
   AIService,
   AIServicePlugin,
   AgentRuntime,
   AiConversationObject,
   AiMessageObject,
   AiTraceObject,
+  AiTraceView,
   DATA_CHAT_AGENT,
+  DATA_EXPLORER_SKILL,
   DATA_TOOL_DEFINITIONS,
   InMemoryConversationService,
   METADATA_ASSISTANT_AGENT,
+  METADATA_AUTHORING_SKILL,
   METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter,
   ModelRegistry,
@@ -4490,6 +5941,9 @@ export {
   SkillRegistry,
   ToolRegistry,
   VercelLLMAdapter,
+  actionSkipReason,
+  actionToToolDefinition,
+  actionToolName,
   addFieldTool,
   buildAIRoutes,
   buildAgentRoutes,
@@ -4509,6 +5963,7 @@ export {
   listObjectsTool,
   listPackagesTool,
   modifyFieldTool,
+  registerActionsAsTools,
   registerDataTools,
   registerMetadataTools,
   registerPackageTools,