@objectstack/service-ai 5.2.0 → 6.0.0

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"
           },
@@ -850,14 +853,20 @@ __export(index_exports, {
   AgentRuntime: () => AgentRuntime,
   AiConversationObject: () => AiConversationObject,
   AiMessageObject: () => AiMessageObject,
+  AiTraceObject: () => AiTraceObject,
   DATA_CHAT_AGENT: () => DATA_CHAT_AGENT,
   DATA_TOOL_DEFINITIONS: () => DATA_TOOL_DEFINITIONS,
   InMemoryConversationService: () => InMemoryConversationService,
   METADATA_ASSISTANT_AGENT: () => METADATA_ASSISTANT_AGENT,
   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,
@@ -866,8 +875,11 @@ __export(index_exports, {
   buildAgentRoutes: () => buildAgentRoutes,
   buildAssistantRoutes: () => buildAssistantRoutes,
   buildToolRoutes: () => buildToolRoutes,
+  buildTraceEvent: () => buildTraceEvent,
+  computeCost: () => computeCost,
   createObjectTool: () => createObjectTool,
   createPackageTool: () => createPackageTool,
+  createQueryDataHandler: () => createQueryDataHandler,
   deleteFieldTool: () => deleteFieldTool,
   describeObjectTool: () => describeObjectTool,
   encodeStreamPart: () => encodeStreamPart,
@@ -880,6 +892,7 @@ __export(index_exports, {
   registerDataTools: () => registerDataTools,
   registerMetadataTools: () => registerMetadataTools,
   registerPackageTools: () => registerPackageTools,
+  registerQueryDataTool: () => registerQueryDataTool,
   setActivePackageTool: () => setActivePackageTool
 });
 module.exports = __toCommonJS(index_exports);
@@ -931,6 +944,59 @@ 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_]+)\b/gim;
+    const candidates = [];
+    for (const match of sys.matchAll(headerRe)) {
+      if (match[1]) candidates.push(match[1]);
+    }
+    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];
+    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);
+      if (score > bestScore) {
+        bestScore = score;
+        chosen = 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."
+    );
+  }
 };
 
 // src/tools/tool-registry.ts
@@ -1097,6 +1163,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 +1245,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 });
@@ -2212,7 +2403,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 +2420,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 +2493,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 +2738,395 @@ 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/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 label = obj.label ? ` \u2014 ${obj.label}` : "";
+      lines.push(`### ${obj.name}${label}`);
+      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/agent-runtime.ts
 var import_ai7 = require("@objectstack/spec/ai");
 var AgentRuntime = class {
@@ -3148,11 +3724,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 +3941,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 +3983,7 @@ var AIServicePlugin = class {
       type: "plugin",
       scope: "project",
       namespace: "ai",
-      objects: [AiConversationObject, AiMessageObject]
+      objects: [AiConversationObject, AiMessageObject, AiTraceObject]
     });
     if (this.options.debug) {
       ctx.hook("ai:beforeChat", async (messages) => {
@@ -3324,6 +4015,14 @@ 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");
+        }
         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) {
@@ -3839,14 +4538,20 @@ function registerPackageTools(registry, context) {
   AgentRuntime,
   AiConversationObject,
   AiMessageObject,
+  AiTraceObject,
   DATA_CHAT_AGENT,
   DATA_TOOL_DEFINITIONS,
   InMemoryConversationService,
   METADATA_ASSISTANT_AGENT,
   METADATA_TOOL_DEFINITIONS,
   MemoryLLMAdapter,
+  ModelRegistry,
+  NullTraceRecorder,
   ObjectQLConversationService,
+  ObjectQLTraceRecorder,
   PACKAGE_TOOL_DEFINITIONS,
+  QUERY_DATA_TOOL,
+  SchemaRetriever,
   SkillRegistry,
   ToolRegistry,
   VercelLLMAdapter,
@@ -3855,8 +4560,11 @@ function registerPackageTools(registry, context) {
   buildAgentRoutes,
   buildAssistantRoutes,
   buildToolRoutes,
+  buildTraceEvent,
+  computeCost,
   createObjectTool,
   createPackageTool,
+  createQueryDataHandler,
   deleteFieldTool,
   describeObjectTool,
   encodeStreamPart,
@@ -3869,6 +4577,7 @@ function registerPackageTools(registry, context) {
   registerDataTools,
   registerMetadataTools,
   registerPackageTools,
+  registerQueryDataTool,
   setActivePackageTool
 });
 //# sourceMappingURL=index.cjs.map