@objectstack/service-ai 5.2.0 → 6.1.1

package/dist/index.cjs

@@ -124,7 +124,9 @@ var init_data_tools = __esm({
               properties: {
                 field: { type: "string" },
                 order: { type: "string", enum: ["asc", "desc"] }
-              }
+              },
+              required: ["field", "order"],
+              additionalProperties: false
             },
             description: 'Sort order (e.g. [{ "field": "created_at", "order": "desc" }])'
           },
@@ -194,7 +196,8 @@ var init_data_tools = __esm({
                   description: "Result column alias"
                 }
               },
-              required: ["function", "alias"]
+              required: ["function", "alias"],
+              additionalProperties: false
             },
             description: "Aggregation definitions"
           },
@@ -845,29 +848,45 @@ var init_metadata_tools = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ACTIONS_EXECUTOR_SKILL: () => ACTIONS_EXECUTOR_SKILL,
   AIService: () => AIService,
   AIServicePlugin: () => AIServicePlugin,
   AgentRuntime: () => AgentRuntime,
   AiConversationObject: () => AiConversationObject,
   AiMessageObject: () => AiMessageObject,
+  AiTraceObject: () => AiTraceObject,
+  AiTraceView: () => AiTraceView,
   DATA_CHAT_AGENT: () => DATA_CHAT_AGENT,
+  DATA_EXPLORER_SKILL: () => DATA_EXPLORER_SKILL,
   DATA_TOOL_DEFINITIONS: () => DATA_TOOL_DEFINITIONS,
   InMemoryConversationService: () => InMemoryConversationService,
   METADATA_ASSISTANT_AGENT: () => METADATA_ASSISTANT_AGENT,
+  METADATA_AUTHORING_SKILL: () => METADATA_AUTHORING_SKILL,
   METADATA_TOOL_DEFINITIONS: () => METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter: () => MemoryLLMAdapter,
+  ModelRegistry: () => ModelRegistry,
+  NullTraceRecorder: () => NullTraceRecorder,
   ObjectQLConversationService: () => ObjectQLConversationService,
+  ObjectQLTraceRecorder: () => ObjectQLTraceRecorder,
   PACKAGE_TOOL_DEFINITIONS: () => PACKAGE_TOOL_DEFINITIONS,
+  QUERY_DATA_TOOL: () => QUERY_DATA_TOOL,
+  SchemaRetriever: () => SchemaRetriever,
   SkillRegistry: () => SkillRegistry,
   ToolRegistry: () => ToolRegistry,
   VercelLLMAdapter: () => VercelLLMAdapter,
+  actionSkipReason: () => actionSkipReason,
+  actionToToolDefinition: () => actionToToolDefinition,
+  actionToolName: () => actionToolName,
   addFieldTool: () => addFieldTool,
   buildAIRoutes: () => buildAIRoutes,
   buildAgentRoutes: () => buildAgentRoutes,
   buildAssistantRoutes: () => buildAssistantRoutes,
   buildToolRoutes: () => buildToolRoutes,
+  buildTraceEvent: () => buildTraceEvent,
+  computeCost: () => computeCost,
   createObjectTool: () => createObjectTool,
   createPackageTool: () => createPackageTool,
+  createQueryDataHandler: () => createQueryDataHandler,
   deleteFieldTool: () => deleteFieldTool,
   describeObjectTool: () => describeObjectTool,
   encodeStreamPart: () => encodeStreamPart,
@@ -877,9 +896,11 @@ __export(index_exports, {
   listObjectsTool: () => listObjectsTool,
   listPackagesTool: () => listPackagesTool,
   modifyFieldTool: () => modifyFieldTool,
+  registerActionsAsTools: () => registerActionsAsTools,
   registerDataTools: () => registerDataTools,
   registerMetadataTools: () => registerMetadataTools,
   registerPackageTools: () => registerPackageTools,
+  registerQueryDataTool: () => registerQueryDataTool,
   setActivePackageTool: () => setActivePackageTool
 });
 module.exports = __toCommonJS(index_exports);
@@ -895,8 +916,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",
@@ -931,7 +1056,171 @@ var MemoryLLMAdapter = class {
   async listModels() {
     return ["memory"];
   }
+  /**
+   * Heuristic structured-output for testing & demos — NOT a real LLM.
+   *
+   * Strategy:
+   * 1. Extract candidate object names from the system messages by matching
+   *    schema-context headers (`### name — Label`) emitted by
+   *    {@link SchemaRetriever.renderSnippet}.
+   * 2. Pick the candidate whose tokens overlap most with the last user
+   *    message (falls back to the first candidate).
+   * 3. Try `schema.safeParse({ objectName, limit: 20 })` — this satisfies the
+   *    `QueryPlanSchema` used by the built-in `query_data` tool.
+   * 4. If that fails, fall back to `schema.safeParse({})` for schemas that
+   *    accept defaults.
+   * 5. Otherwise throw with a clear message — the demo needs a real provider.
+   */
+  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_]+)(?:\s+—\s+([^\n]+))?/gim;
+    const candidates = [];
+    for (const match of sys.matchAll(headerRe)) {
+      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)
+    );
+    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 cand of candidates) {
+      let score = 0;
+      for (const tok of cand.aliasTokens) {
+        if (userTokens.has(tok)) score += 1;
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        chosen = cand.name;
+      }
+    }
+    const attempts = [];
+    if (chosen) attempts.push({ objectName: chosen, limit: 20 });
+    attempts.push({});
+    for (const attempt of attempts) {
+      const result = schema.safeParse(attempt);
+      if (result.success) {
+        return {
+          object: result.data,
+          model: options?.model ?? "memory",
+          usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+        };
+      }
+    }
+    throw new Error(
+      "MemoryLLMAdapter.generateObject: unable to synthesise a value for the requested schema. The memory adapter only handles QueryPlan-shaped schemas \u2014 wire a real LLM adapter (OpenAI / Anthropic / Google) for arbitrary structured output."
+    );
+  }
 };
+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"
+  ]);
+  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 {
@@ -1097,6 +1386,70 @@ var InMemoryConversationService = class {
   }
 };
 
+// src/trace-recorder.ts
+var import_node_crypto = require("crypto");
+var TRACE_OBJECT = "ai_traces";
+var NullTraceRecorder = class {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  record(_event) {
+  }
+};
+var ObjectQLTraceRecorder = class {
+  constructor(engine, options = {}) {
+    this.engine = engine;
+    this.logger = options.logger;
+  }
+  async record(event) {
+    const row = {
+      id: `trace_${(0, import_node_crypto.randomUUID)()}`,
+      conversation_id: event.conversationId ?? null,
+      agent_id: event.agentId ?? null,
+      operation: event.operation,
+      model: event.model ?? null,
+      adapter: event.adapter,
+      prompt_tokens: event.promptTokens,
+      completion_tokens: event.completionTokens,
+      total_tokens: event.totalTokens,
+      input_cost: event.cost?.inputCost ?? null,
+      output_cost: event.cost?.outputCost ?? null,
+      total_cost: event.cost?.totalCost ?? null,
+      currency: event.cost?.currency ?? null,
+      latency_ms: event.latencyMs,
+      status: event.status,
+      error: event.error ?? null,
+      metadata: event.metadata ? JSON.stringify(event.metadata) : null,
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    try {
+      await this.engine.insert(TRACE_OBJECT, row);
+    } catch (err) {
+      this.logger?.warn(
+        "[AI] Failed to record trace (non-fatal)",
+        err instanceof Error ? { error: err.message } : { error: String(err) }
+      );
+    }
+  }
+};
+function buildTraceEvent(input) {
+  const usage = input.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  const cost = input.model && input.registry ? input.registry.estimateCost(input.model, usage) : void 0;
+  return {
+    operation: input.operation,
+    adapter: input.adapter,
+    model: input.model,
+    agentId: input.agentId,
+    conversationId: input.conversationId,
+    promptTokens: usage.promptTokens,
+    completionTokens: usage.completionTokens,
+    totalTokens: usage.totalTokens,
+    latencyMs: input.latencyMs,
+    status: input.status,
+    error: input.error,
+    cost,
+    metadata: input.metadata
+  };
+}
+
 // src/ai-service.ts
 function textDeltaPart(id, text) {
   return { type: "text-delta", id, text };
@@ -1115,22 +1468,83 @@ var _AIService = class _AIService {
     this.logger = config.logger ?? (0, import_core.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.logger.info(
-      `[AI] Service initialized with adapter="${this.adapter.name}", tools=${this.toolRegistry.size}`
+      `[AI] Service initialized with adapter="${this.adapter.name}", tools=${this.toolRegistry.size}, models=${this.modelRegistry?.size ?? 0}`
     );
   }
   /** The name of the active LLM adapter. */
   get adapterName() {
     return this.adapter.name;
   }
+  /**
+   * Run an adapter call and emit a trace event.
+   *
+   * Records both success and failure. Tracing failures never escape — the
+   * recorder is expected to be defensive.
+   */
+  async instrument(operation, options, fn) {
+    const started = Date.now();
+    try {
+      const result = await fn();
+      void this.traceRecorder.record(buildTraceEvent({
+        operation,
+        adapter: this.adapter.name,
+        model: result.model ?? options?.model,
+        usage: result.usage,
+        latencyMs: Date.now() - started,
+        status: "success",
+        registry: this.modelRegistry
+      }));
+      return result;
+    } catch (err) {
+      void this.traceRecorder.record(buildTraceEvent({
+        operation,
+        adapter: this.adapter.name,
+        model: options?.model,
+        latencyMs: Date.now() - started,
+        status: "error",
+        error: err instanceof Error ? err.message : String(err),
+        registry: this.modelRegistry
+      }));
+      throw err;
+    }
+  }
   // ── IAIService implementation ──────────────────────────────────
   async chat(messages, options) {
     this.logger.debug("[AI] chat", { messageCount: messages.length, model: options?.model });
-    return this.adapter.chat(messages, options);
+    return this.instrument("chat", options, () => this.adapter.chat(messages, options));
   }
   async complete(prompt, options) {
     this.logger.debug("[AI] complete", { promptLength: prompt.length, model: options?.model });
-    return this.adapter.complete(prompt, options);
+    return this.instrument("complete", options, () => this.adapter.complete(prompt, options));
+  }
+  /**
+   * Generate a strongly-typed object validated against a Zod schema.
+   *
+   * Delegates to the adapter's `generateObject` when supported; throws a
+   * descriptive error when the adapter does not implement structured output.
+   *
+   * @example
+   * ```ts
+   * import { z } from 'zod';
+   * const Schema = z.object({ name: z.string(), priority: z.number().int() });
+   * const { object } = await ai.generateObject(messages, Schema);
+   * ```
+   */
+  async generateObject(messages, schema, options) {
+    this.logger.debug("[AI] generateObject", { messageCount: messages.length, model: options?.model });
+    if (!this.adapter.generateObject) {
+      throw new Error(
+        `[AI] Adapter "${this.adapter.name}" does not support generateObject. Use VercelLLMAdapter with a structured-output-capable model.`
+      );
+    }
+    return this.instrument(
+      "generate_object",
+      options,
+      () => this.adapter.generateObject(messages, schema, options)
+    );
   }
   async *streamChat(messages, options) {
     this.logger.debug("[AI] streamChat", { messageCount: messages.length, model: options?.model });
@@ -1170,6 +1584,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();
@@ -2212,7 +2633,7 @@ function buildToolRoutes(aiService, logger) {
 }
 
 // src/conversation/objectql-conversation-service.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var CONVERSATIONS_OBJECT = "ai_conversations";
 var MESSAGES_OBJECT = "ai_messages";
 var CONVERSATION_ORDER = [
@@ -2229,7 +2650,7 @@ var ObjectQLConversationService = class {
   }
   async create(options = {}) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const id = `conv_${(0, import_node_crypto.randomUUID)()}`;
+    const id = `conv_${(0, import_node_crypto2.randomUUID)()}`;
     const record = {
       id,
       title: options.title ?? null,
@@ -2302,7 +2723,7 @@ var ObjectQLConversationService = class {
       throw new Error(`Conversation "${conversationId}" not found`);
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const msgId = `msg_${(0, import_node_crypto.randomUUID)()}`;
+    const msgId = `msg_${(0, import_node_crypto2.randomUUID)()}`;
     let contentStr;
     let toolCallsJson = null;
     let toolCallId = null;
@@ -2547,10 +2968,677 @@ var AiMessageObject = import_data2.ObjectSchema.create({
   }
 });
 
+// src/objects/ai-trace.object.ts
+var import_data3 = require("@objectstack/spec/data");
+var AiTraceObject = import_data3.ObjectSchema.create({
+  name: "ai_traces",
+  label: "AI Trace",
+  pluralLabel: "AI Traces",
+  icon: "activity",
+  isSystem: true,
+  description: "Per-call LLM invocation trace with token usage and cost",
+  fields: {
+    id: import_data3.Field.text({
+      label: "Trace ID",
+      required: true,
+      readonly: true
+    }),
+    conversation_id: import_data3.Field.lookup("ai_conversations", {
+      label: "Conversation",
+      required: false,
+      description: "Parent conversation, if any"
+    }),
+    agent_id: import_data3.Field.text({
+      label: "Agent",
+      required: false,
+      maxLength: 128,
+      description: "Agent metadata name that originated the call"
+    }),
+    operation: import_data3.Field.select({
+      label: "Operation",
+      required: true,
+      options: [
+        { label: "Chat", value: "chat" },
+        { label: "Complete", value: "complete" },
+        { label: "Stream Chat", value: "stream_chat" },
+        { label: "Chat With Tools", value: "chat_with_tools" },
+        { label: "Generate Object", value: "generate_object" },
+        { label: "Embed", value: "embed" }
+      ]
+    }),
+    model: import_data3.Field.text({
+      label: "Model",
+      required: false,
+      maxLength: 128,
+      description: "Model identifier reported by the adapter"
+    }),
+    adapter: import_data3.Field.text({
+      label: "Adapter",
+      required: false,
+      maxLength: 64,
+      description: 'LLM adapter name (e.g. "vercel", "memory")'
+    }),
+    prompt_tokens: import_data3.Field.number({
+      label: "Prompt Tokens",
+      required: false,
+      defaultValue: 0
+    }),
+    completion_tokens: import_data3.Field.number({
+      label: "Completion Tokens",
+      required: false,
+      defaultValue: 0
+    }),
+    total_tokens: import_data3.Field.number({
+      label: "Total Tokens",
+      required: false,
+      defaultValue: 0
+    }),
+    input_cost: import_data3.Field.number({
+      label: "Input Cost",
+      required: false,
+      description: "Cost attributable to prompt tokens (currency in `currency` field)"
+    }),
+    output_cost: import_data3.Field.number({
+      label: "Output Cost",
+      required: false,
+      description: "Cost attributable to completion tokens"
+    }),
+    total_cost: import_data3.Field.number({
+      label: "Total Cost",
+      required: false,
+      description: "input_cost + output_cost"
+    }),
+    currency: import_data3.Field.text({
+      label: "Currency",
+      required: false,
+      maxLength: 8,
+      defaultValue: "USD"
+    }),
+    latency_ms: import_data3.Field.number({
+      label: "Latency (ms)",
+      required: true,
+      defaultValue: 0,
+      description: "Wall-clock duration of the LLM call"
+    }),
+    status: import_data3.Field.select({
+      label: "Status",
+      required: true,
+      options: [
+        { label: "Success", value: "success" },
+        { label: "Error", value: "error" }
+      ]
+    }),
+    error: import_data3.Field.textarea({
+      label: "Error",
+      required: false,
+      description: "Error message when status=error"
+    }),
+    metadata: import_data3.Field.textarea({
+      label: "Metadata",
+      required: false,
+      description: "JSON-serialized extra fields (request id, user id, \u2026)"
+    }),
+    created_at: import_data3.Field.datetime({
+      label: "Created At",
+      required: true,
+      defaultValue: "NOW()",
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["conversation_id"] },
+    { fields: ["agent_id"] },
+    { fields: ["model"] },
+    { fields: ["status"] },
+    { fields: ["created_at"] }
+  ],
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list"],
+    trash: false,
+    mru: false
+  }
+});
+
+// src/views/ai-trace.view.ts
+var import_spec = require("@objectstack/spec");
+var AiTraceView = (0, import_spec.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/plugin.ts
 init_data_tools();
 init_metadata_tools();
 
+// src/tools/query-data.tool.ts
+var import_zod = require("zod");
+
+// src/schema-retriever.ts
+var SchemaRetriever = class {
+  constructor(metadata, options = {}) {
+    this.metadata = metadata;
+    this.options = {
+      limit: options.limit ?? 3,
+      minScore: options.minScore ?? 1,
+      maxFieldsPerObject: options.maxFieldsPerObject ?? 12
+    };
+  }
+  /**
+   * Find object definitions whose name/label/fields match terms in the query.
+   *
+   * Returns matches sorted by score (descending) capped at `limit`. When
+   * the query yields no matches, returns an empty array — callers may
+   * fall back to a generic "describe what data exists" tool call.
+   */
+  async retrieve(query) {
+    const terms = tokenise(query);
+    if (terms.length === 0) return [];
+    const objects = await this.metadata.listObjects();
+    const hits = [];
+    for (const raw of objects) {
+      const obj = raw;
+      if (!obj?.name) continue;
+      const score = scoreObject(obj, terms);
+      if (score >= this.options.minScore) {
+        hits.push({ object: obj, score });
+      }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, this.options.limit);
+  }
+  /**
+   * Render hits as a compact Markdown schema snippet.
+   *
+   * Designed to be appended to the system message — every line carries
+   * exactly the information a model needs to choose object/field names
+   * for query construction.
+   */
+  static renderSnippet(hits, maxFieldsPerObject = 12) {
+    if (hits.length === 0) return "";
+    const lines = ["## Schema context (auto-injected)"];
+    for (const hit of hits) {
+      const obj = hit.object;
+      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)}`);
+      }
+      const total = Object.keys(obj.fields ?? {}).length;
+      if (total > fields.length) {
+        lines.push(`  - \u2026${total - fields.length} more field(s)`);
+      }
+    }
+    return lines.join("\n");
+  }
+};
+function tokenise(query) {
+  const raw = query.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+  return raw.filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "are",
+  "has",
+  "have",
+  "had",
+  "was",
+  "were",
+  "this",
+  "that",
+  "these",
+  "those",
+  "all",
+  "any",
+  "how",
+  "what",
+  "when",
+  "where",
+  "who",
+  "why",
+  "which",
+  "show",
+  "list",
+  "find",
+  "get",
+  "count",
+  "of",
+  "in",
+  "on",
+  "at",
+  "to",
+  "as",
+  "by",
+  "is",
+  "it",
+  "an",
+  "or",
+  "be",
+  "me"
+]);
+function scoreObject(obj, terms) {
+  let score = 0;
+  const nameTokens = splitSnake(obj.name);
+  const labelTokens = obj.label ? tokenise(obj.label) : [];
+  const pluralTokens = obj.pluralLabel ? tokenise(obj.pluralLabel) : [];
+  const descTokens = obj.description ? tokenise(obj.description) : [];
+  for (const term of terms) {
+    if (nameTokens.includes(term)) score += 3;
+    else if (labelTokens.includes(term) || pluralTokens.includes(term)) score += 2;
+    else if (descTokens.includes(term)) score += 1;
+  }
+  for (const [fieldName, field] of Object.entries(obj.fields ?? {})) {
+    const fnTokens = splitSnake(fieldName);
+    const flTokens = field.label ? tokenise(field.label) : [];
+    for (const term of terms) {
+      if (fnTokens.includes(term)) score += 2;
+      else if (flTokens.includes(term)) score += 1;
+    }
+  }
+  return score;
+}
+function splitSnake(name) {
+  return name.toLowerCase().split("_").filter(Boolean);
+}
+function describeField(field) {
+  const t = field.type ?? "unknown";
+  if (t === "lookup" && field.reference) return `lookup \u2192 ${field.reference}`;
+  if (t === "select" && Array.isArray(field.options)) {
+    const values = field.options.map(
+      (o) => typeof o === "string" ? o : o.value
+    ).filter(Boolean).slice(0, 6);
+    return `select(${values.join("|")})`;
+  }
+  return t;
+}
+
+// src/tools/query-data.tool.ts
+var QueryPlanSchema = import_zod.z.object({
+  objectName: import_zod.z.string().min(1).describe('The snake_case object name to query (e.g. "task", "account").'),
+  where: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional().describe(
+    'Filter conditions as key-value pairs. Use MongoDB-style operators for ranges, e.g. {"amount": {"$gt": 100}}.'
+  ),
+  fields: import_zod.z.array(import_zod.z.string()).optional().describe("Field names to return. Omit to return all fields."),
+  orderBy: import_zod.z.array(
+    import_zod.z.object({
+      field: import_zod.z.string(),
+      order: import_zod.z.enum(["asc", "desc"])
+    })
+  ).optional().describe("Sort order. First entry is primary sort key."),
+  limit: import_zod.z.number().int().min(1).max(200).optional().describe("Maximum number of records (default 20, max 200).")
+});
+var QUERY_DATA_TOOL = {
+  name: "query_data",
+  description: "Answer a natural-language question about the user's data. Internally retrieves the relevant object schema, generates an ObjectQL query, executes it, and returns the matching records. Prefer this tool over `query_records` / `aggregate_data` when the user's intent is expressed in plain language.",
+  parameters: {
+    type: "object",
+    properties: {
+      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"],
+    additionalProperties: false
+  }
+};
+function createQueryDataHandler(ctx) {
+  const retriever = new SchemaRetriever(ctx.metadata);
+  const maxLimit = ctx.maxLimit ?? 100;
+  return async (args) => {
+    const { request, model } = args;
+    if (!request || typeof request !== "string") {
+      return JSON.stringify({ error: "query_data: `request` is required" });
+    }
+    if (!ctx.ai.generateObject) {
+      return JSON.stringify({
+        error: "query_data requires structured-output support. Configure a Vercel-AI-SDK-backed adapter (OpenAI, Anthropic, Google)."
+      });
+    }
+    const hits = await retriever.retrieve(request);
+    if (hits.length === 0) {
+      return JSON.stringify({
+        error: "No matching objects in metadata. Ask the user which object(s) to query, or list available objects via list_objects."
+      });
+    }
+    const snippet = SchemaRetriever.renderSnippet(hits);
+    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
+      },
+      { 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."
+      });
+      plan = generated.object;
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to plan query: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+    const matchedObject = hits.find((h) => h.object.name === plan.objectName)?.object ?? hits[0].object;
+    if (matchedObject.name !== plan.objectName) {
+      return JSON.stringify({
+        error: `Planned object "${plan.objectName}" is not in the retrieved schema. Available: ${hits.map((h) => h.object.name).join(", ")}`
+      });
+    }
+    const limit = Math.min(plan.limit ?? 20, maxLimit);
+    try {
+      const records = await ctx.dataEngine.find(plan.objectName, {
+        where: plan.where,
+        fields: plan.fields,
+        orderBy: plan.orderBy,
+        limit
+      });
+      return JSON.stringify({
+        plan,
+        count: records.length,
+        records
+      });
+    } catch (err) {
+      return JSON.stringify({
+        plan,
+        error: `Query execution failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  };
+}
+function registerQueryDataTool(registry, context) {
+  registry.register(QUERY_DATA_TOOL, createQueryDataHandler(context));
+}
+
+// src/tools/action-tools.ts
+function actionSkipReason(action) {
+  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";
+  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 (actionSkipReason(action) !== null) 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: (object, ids) => engine.delete(object, { where: { id: ids.length === 1 ? ids[0] : { $in: ids } } })
+  };
+}
+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"
+  );
+  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) {
+      result.error = "Action has no target handler.";
+      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;
+    try {
+      const handlerCtx = {
+        record,
+        user: principal,
+        engine: engineAdapter,
+        params: userParams
+      };
+      const out = await ctx.dataEngine.executeAction?.(objectName, target, handlerCtx);
+      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 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);
+      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;
+      }
+      registry.register(definition, createActionToolHandler(normalized, context));
+      registered.push(definition.name);
+    }
+  }
+  return { registered, skipped };
+}
+
 // src/agent-runtime.ts
 var import_ai7 = require("@objectstack/spec/ai");
 var AgentRuntime = class {
@@ -2853,6 +3941,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) {
@@ -2916,7 +4014,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: {
@@ -2996,6 +4095,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",
@@ -3065,6 +4165,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
 var import_ai9 = require("ai");
 function buildVercelOptions(options) {
@@ -3148,11 +4286,102 @@ var VercelLLMAdapter = class {
       "[VercelLLMAdapter] Embeddings require a dedicated EmbeddingModel. Configure an embedding adapter instead."
     );
   }
+  async generateObject(messages, schema, options) {
+    const { schemaName, schemaDescription, ...rest } = options ?? {};
+    const result = await (0, import_ai9.generateObject)({
+      model: this.model,
+      messages,
+      schema,
+      schemaName,
+      schemaDescription,
+      ...buildVercelOptions(rest)
+    });
+    return {
+      object: result.object,
+      model: result.response?.modelId,
+      usage: result.usage ? {
+        promptTokens: result.usage.inputTokens ?? 0,
+        completionTokens: result.usage.outputTokens ?? 0,
+        totalTokens: result.usage.totalTokens ?? 0
+      } : void 0
+    };
+  }
   async listModels() {
     return [];
   }
 };
 
+// src/model-registry.ts
+var ModelRegistry = class {
+  constructor(config = {}) {
+    this.models = /* @__PURE__ */ new Map();
+    for (const model of config.models ?? []) {
+      this.models.set(model.id, model);
+    }
+    this.defaultModelId = config.defaultModelId;
+  }
+  /** Register or replace a model. */
+  register(model) {
+    this.models.set(model.id, model);
+  }
+  /** Look up a model by id. */
+  get(id) {
+    return this.models.get(id);
+  }
+  /** Look up a model by id, throwing if missing. */
+  getOrThrow(id) {
+    const model = this.models.get(id);
+    if (!model) {
+      throw new Error(
+        `[ModelRegistry] Unknown model "${id}". Registered: ${[...this.models.keys()].join(", ") || "(none)"}`
+      );
+    }
+    return model;
+  }
+  /** Resolve the default model (explicit > first registered > undefined). */
+  getDefault() {
+    if (this.defaultModelId) {
+      return this.models.get(this.defaultModelId);
+    }
+    return this.models.values().next().value;
+  }
+  /** Set the default model id (must already be registered). */
+  setDefault(id) {
+    this.getOrThrow(id);
+    this.defaultModelId = id;
+  }
+  /** All registered models. */
+  list() {
+    return [...this.models.values()];
+  }
+  /** Number of registered models. */
+  get size() {
+    return this.models.size;
+  }
+  /**
+   * Estimate cost in the model's currency (defaults to USD).
+   *
+   * Returns `undefined` when the model is unknown or has no pricing data.
+   * Costs are computed as `(tokens / 1000) * pricePer1kTokens` for input and
+   * output independently, then summed.
+   */
+  estimateCost(modelId, usage) {
+    const model = this.models.get(modelId);
+    if (!model?.pricing) return void 0;
+    return computeCost(model.pricing, usage);
+  }
+};
+function computeCost(pricing, usage) {
+  const inputCost = pricing.inputCostPer1kTokens != null ? usage.promptTokens / 1e3 * pricing.inputCostPer1kTokens : 0;
+  const outputCost = pricing.outputCostPer1kTokens != null ? usage.completionTokens / 1e3 * pricing.outputCostPer1kTokens : 0;
+  return {
+    inputCost,
+    outputCost,
+    totalCost: inputCost + outputCost,
+    currency: pricing.currency ?? "USD"
+  };
+}
+
 // src/plugin.ts
 var AIServicePlugin = class {
   constructor(options = {}) {
@@ -3274,10 +4503,34 @@ var AIServicePlugin = class {
       adapterDescription = detected.description;
     }
     ctx.logger.info(`[AI] Using LLM adapter: ${adapterDescription}`);
+    const modelRegistry = new ModelRegistry({
+      models: this.options.models,
+      defaultModelId: this.options.defaultModelId
+    });
+    if (modelRegistry.size > 0) {
+      ctx.logger.info(`[AI] ModelRegistry initialised with ${modelRegistry.size} model(s)`);
+    }
+    let traceRecorder;
+    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 {
+      }
+    }
     const config = {
       adapter,
       logger: ctx.logger,
-      conversationService
+      conversationService,
+      modelRegistry,
+      traceRecorder
     };
     this.service = new AIService(config);
     if (hasExisting) {
@@ -3292,7 +4545,8 @@ var AIServicePlugin = class {
       type: "plugin",
       scope: "project",
       namespace: "ai",
-      objects: [AiConversationObject, AiMessageObject]
+      objects: [AiConversationObject, AiMessageObject, AiTraceObject],
+      views: [AiTraceView]
     });
     if (this.options.debug) {
       ctx.hook("ai:beforeChat", async (messages) => {
@@ -3324,6 +4578,39 @@ var AIServicePlugin = class {
       if (dataEngine) {
         registerDataTools(this.service.toolRegistry, { dataEngine });
         ctx.logger.info("[AI] Built-in data tools registered");
+        if (metadataService) {
+          registerQueryDataTool(this.service.toolRegistry, {
+            ai: this.service,
+            metadata: metadataService,
+            dataEngine
+          });
+          ctx.logger.info("[AI] query_data tool registered");
+          try {
+            const { registered, skipped } = await registerActionsAsTools(
+              this.service.toolRegistry,
+              {
+                metadata: metadataService,
+                dataEngine
+              }
+            );
+            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));
           for (const toolDef of DATA_TOOL_DEFINITIONS2) {
@@ -3374,6 +4661,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 {
@@ -3834,29 +5134,45 @@ function registerPackageTools(registry, context) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  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,
+  NullTraceRecorder,
   ObjectQLConversationService,
+  ObjectQLTraceRecorder,
   PACKAGE_TOOL_DEFINITIONS,
+  QUERY_DATA_TOOL,
+  SchemaRetriever,
   SkillRegistry,
   ToolRegistry,
   VercelLLMAdapter,
+  actionSkipReason,
+  actionToToolDefinition,
+  actionToolName,
   addFieldTool,
   buildAIRoutes,
   buildAgentRoutes,
   buildAssistantRoutes,
   buildToolRoutes,
+  buildTraceEvent,
+  computeCost,
   createObjectTool,
   createPackageTool,
+  createQueryDataHandler,
   deleteFieldTool,
   describeObjectTool,
   encodeStreamPart,
@@ -3866,9 +5182,11 @@ function registerPackageTools(registry, context) {
   listObjectsTool,
   listPackagesTool,
   modifyFieldTool,
+  registerActionsAsTools,
   registerDataTools,
   registerMetadataTools,
   registerPackageTools,
+  registerQueryDataTool,
   setActivePackageTool
 });
 //# sourceMappingURL=index.cjs.map