@objectstack/service-ai 6.0.0 → 6.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AIToolDefinition, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, AIConversation, IMetadataService } from '@objectstack/spec/contracts';
+import { AIToolDefinition, ToolCallPart, ToolResultPart, IDataEngine, Logger, IAIService, IAIConversationService, LLMAdapter, ModelMessage, AIRequestOptions, AIResult, GenerateObjectOptions, AIObjectResult, TextStreamPart, ToolSet, ChatWithToolsOptions, ProposePendingActionInput, PendingActionStatus, PendingActionRow, AIConversation, IMetadataService, IAutomationService } from '@objectstack/spec/contracts';
 export { LLMAdapter } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 import * as AI from '@objectstack/spec/ai';
@@ -7,6 +7,7 @@ import { Plugin, PluginContext } from '@objectstack/core';
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { TextStreamPart as TextStreamPart$1, ToolSet as ToolSet$1 } from 'ai';
 import { InstalledPackage } from '@objectstack/spec/kernel';
+import { Action } from '@objectstack/spec/ui';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
 
 /**
@@ -257,6 +258,13 @@ interface AIServiceConfig {
     modelRegistry?: ModelRegistry;
     /** Trace recorder for per-call observability. Defaults to no-op. */
     traceRecorder?: TraceRecorder;
+    /**
+     * Data engine used to persist `ai_pending_actions` rows for the
+     * actions-as-tools HITL queue. Optional — when omitted, the
+     * `proposePendingAction` / `approvePendingAction` methods throw if
+     * called. Wired by `AIServicePlugin` after the data driver is up.
+     */
+    dataEngine?: IDataEngine;
 }
 /**
  * AIService — Unified AI capability service.
@@ -280,6 +288,15 @@ declare class AIService implements IAIService {
     readonly conversationService: IAIConversationService;
     readonly modelRegistry?: ModelRegistry;
     readonly traceRecorder: TraceRecorder;
+    /**
+     * Map of tool-name → dispatcher used to re-run an approved pending
+     * action. Populated by `registerActionsAsTools()` when action
+     * approval is enabled. Kept private because callers should go
+     * through `approvePendingAction()`.
+     */
+    private readonly pendingDispatchers;
+    /** Data engine for `ai_pending_actions` persistence. */
+    private readonly dataEngine?;
     constructor(config?: AIServiceConfig);
     /** The name of the active LLM adapter. */
     get adapterName(): string;
@@ -325,6 +342,7 @@ declare class AIService implements IAIService {
      *    maximum number of iterations (`maxIterations`) is reached.
      */
     chatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): Promise<AIResult>;
+    private chatWithToolsImpl;
     /**
      * Stream chat with automatic tool call resolution.
      *
@@ -333,6 +351,29 @@ declare class AIService implements IAIService {
      * fed back until a final text stream is produced.
      */
     streamChatWithTools(messages: ModelMessage[], options?: ChatWithToolsOptions): AsyncIterable<TextStreamPart<ToolSet>>;
+    /**
+     * Register a dispatcher callback for a tool. Called by
+     * `registerActionsAsTools()` when action approval is enabled so the
+     * approval handler can re-run the exact same code path the LLM
+     * would have triggered.
+     */
+    registerPendingActionDispatcher(toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>): void;
+    proposePendingAction(input: ProposePendingActionInput): Promise<{
+        id: string;
+    }>;
+    approvePendingAction(id: string, actorId: string): Promise<{
+        status: 'executed' | 'failed';
+        result?: unknown;
+        error?: string;
+    }>;
+    rejectPendingAction(id: string, actorId: string, reason?: string): Promise<void>;
+    listPendingActions(filter?: {
+        status?: PendingActionStatus | PendingActionStatus[];
+        conversationId?: string;
+        objectName?: string;
+        limit?: number;
+    }): Promise<PendingActionRow[]>;
+    private loadPendingRow;
 }
 
 /**
@@ -354,6 +395,12 @@ interface AIServicePluginOptions {
     models?: AI.ModelConfig[];
     /** Default model id (must appear in `models`). */
     defaultModelId?: string;
+    /**
+     * Explicit trace recorder override. When set, auto-detection
+     * of {@link ObjectQLTraceRecorder} is skipped.
+     *
+     * Set to `null` to disable tracing entirely.
+     */
     /**
      * Explicit trace recorder override. When set, auto-detection
      * of {@link ObjectQLTraceRecorder} is skipped.
@@ -361,6 +408,31 @@ interface AIServicePluginOptions {
      * Set to `null` to disable tracing entirely.
      */
     traceRecorder?: TraceRecorder | null;
+    /**
+     * Base URL prepended to relative `target` paths for `type:'api'`
+     * actions invoked by the AI tool runtime. When unset, falls back to
+     * `process.env.OS_AI_ACTION_API_BASE_URL`. If neither is set, api
+     * actions are skipped at registration with a clear reason.
+     */
+    apiActionBaseUrl?: string;
+    /**
+     * Extra HTTP headers (e.g. `{ Authorization: 'Bearer ...' }`) applied
+     * to every `type:'api'` action dispatch. Useful for forwarding the
+     * caller's session token so server-side authorization still applies.
+     */
+    apiActionHeaders?: Record<string, string>;
+    /**
+     * Opt into Human-In-The-Loop approval for dangerous actions exposed
+     * as AI tools. When `true`, actions with `confirmText`, `mode:'delete'`,
+     * or `variant:'danger'` are still registered as tools — but invoking
+     * them enqueues an `ai_pending_actions` row and returns
+     * `{ status: 'pending_approval' }` instead of running. A human
+     * operator approves via Studio's pending-actions inbox to execute.
+     *
+     * Defaults to `false` (safer: dangerous actions stay invisible to LLM
+     * until an operator explicitly enables this routing).
+     */
+    enableActionApproval?: boolean;
 }
 /**
  * AIServicePlugin — Kernel plugin for the unified AI capability service.
@@ -937,6 +1009,163 @@ interface PackageToolContext {
  */
 declare function registerPackageTools(registry: ToolRegistry, context: PackageToolContext): void;
 
+/**
+ * Actions-as-Tools — turn declarative {@link Action} metadata into
+ * AI-callable tools so an agent can not only **read** the user's data
+ * (via `query_data` / `data_explorer`) but also **act** on it.
+ *
+ * Phase 1 scope (this module):
+ *   - Only `type: 'script'` actions are auto-exposed. Their handler is
+ *     resolved through {@link IDataEngine.executeAction} (the same
+ *     dispatcher used by Studio's "row toolbar" buttons), so the LLM
+ *     ends up calling exactly the same business logic the UI does.
+ *   - Skip any action that is dangerous (`confirmText`, `variant: 'danger'`,
+ *     `mode: 'delete'`) — these require Phase 2 HITL plumbing.
+ *   - Skip any action whose owner opted out via `aiExposed: false` (the
+ *     hint is read from the action record but not formalised in the Zod
+ *     schema yet; spec change is backwards-compatible additive).
+ *
+ * The tool's JSON Schema is materialised from `action.params[]`,
+ * resolving field-backed params (`{ field: 'priority' }`) against the
+ * owning object so the LLM sees the same type/options/required
+ * constraints the modal dialog would render.
+ */
+
+/** Minimal field shape we care about when resolving param types. */
+interface FieldDef {
+    type?: string;
+    label?: string;
+    required?: boolean;
+    options?: Array<{
+        value: string;
+        label?: unknown;
+    } | string>;
+    description?: string;
+}
+/** Minimal object shape — same as what {@link SchemaRetriever} consumes. */
+interface ObjectDef {
+    name: string;
+    label?: string;
+    pluralLabel?: string;
+    fields?: Record<string, FieldDef>;
+    actions?: Action[];
+}
+/**
+ * Dependencies needed to invoke an Action from the AI tool runtime.
+ *
+ * The `metadata` service is used at registration time to resolve param
+ * field types; the `dataEngine` is used at call time to (a) load the
+ * subject record when a `recordIdParam` is configured and (b) dispatch
+ * to the registered handler via `executeAction`.
+ *
+ * `automation` enables `type:'flow'` actions to dispatch into the
+ * automation service's flow runner. When omitted, flow actions are
+ * skipped at registration time with a clear reason.
+ *
+ * `apiClient` (or `apiBaseUrl`) enables `type:'api'` actions to perform
+ * an HTTP call to the action's `target` URL. The default client uses
+ * the global `fetch` and prepends `apiBaseUrl` to relative `target`s.
+ * Supply a custom client when you need bespoke auth, in-process
+ * routing, or stubbing in tests.
+ *
+ * `principal` lets callers attribute AI-initiated mutations to a known
+ * user id; it defaults to a synthetic `'ai_agent'` user so traces /
+ * audit always have *some* actor.
+ */
+interface ActionToolsContext {
+    metadata: IMetadataService;
+    dataEngine: IDataEngine;
+    /** Automation service for `type:'flow'` action dispatch. Optional. */
+    automation?: IAutomationService;
+    /** Custom API client for `type:'api'` actions. Defaults to a fetch-based client. */
+    apiClient?: ApiActionClient;
+    /** Base URL prepended to relative `target` paths for `type:'api'` actions. */
+    apiBaseUrl?: string;
+    /** Extra HTTP headers (e.g. auth bearer) applied to every `type:'api'` call. */
+    apiHeaders?: Record<string, string>;
+    /** Synthetic user attribution for AI-initiated calls. */
+    principal?: {
+        id: string;
+        name?: string;
+    };
+    /** Tool-name prefix (default: `action_`). Keeps namespace separate from data tools. */
+    toolPrefix?: string;
+    /**
+     * AI service used to enqueue HITL approvals for dangerous actions.
+     * When supplied together with `enableActionApproval: true`, actions
+     * that would otherwise be skipped on safety grounds (`confirmText`,
+     * `mode:'delete'`, `variant:'danger'`) are registered as tools whose
+     * handler proposes a pending action and returns
+     * `{ status: 'pending_approval' }` instead of executing.
+     */
+    aiService?: {
+        proposePendingAction?: (input: {
+            objectName: string;
+            actionName: string;
+            toolName: string;
+            toolInput: Record<string, unknown>;
+            conversationId?: string;
+            messageId?: string;
+            proposedBy?: string;
+        }) => Promise<{
+            id: string;
+        }>;
+        registerPendingActionDispatcher?: (toolName: string, dispatch: (input: Record<string, unknown>) => Promise<unknown>) => void;
+    };
+    /**
+     * Opt into the HITL approval queue for dangerous actions. Default
+     * is `false` (safer: dangerous actions stay invisible to the LLM
+     * until an operator explicitly enables approval routing).
+     */
+    enableActionApproval?: boolean;
+}
+/**
+ * Minimal HTTP client shape used by `type:'api'` action dispatch.
+ *
+ * Implementations are expected to return a JSON-deserialised body (or
+ * `null` for empty responses) on 2xx, and throw on non-2xx so the tool
+ * surfaces the failure to the LLM as a tool error.
+ */
+interface ApiActionClient {
+    request(input: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+}
+declare function actionSkipReason(action: Action, ctx?: {
+    automation?: IAutomationService;
+    apiClient?: ApiActionClient;
+    apiBaseUrl?: string;
+    enableActionApproval?: boolean;
+    aiService?: ActionToolsContext['aiService'];
+}): string | null;
+/** Compute the AI tool name for a given action (prefixed for namespacing). */
+declare function actionToolName(action: Action, prefix?: string): string;
+/**
+ * Convert a single {@link Action} into a complete {@link AIToolDefinition}.
+ *
+ * Returns `null` when the action is filtered out by {@link actionSkipReason}.
+ */
+declare function actionToToolDefinition(action: Action, ownerObject: ObjectDef | undefined, allObjects: Map<string, ObjectDef>, toolPrefix?: string): AIToolDefinition | null;
+/**
+ * Walk every registered object in the {@link IMetadataService}, pick out
+ * each object's actions, and register the ones that pass {@link actionSkipReason}
+ * as AI tools.
+ *
+ * Returns the list of registered tool names and a parallel list of
+ * `{ action, reason }` for actions that were intentionally skipped —
+ * useful for Studio's "AI exposure" diagnostics surface.
+ */
+declare function registerActionsAsTools(registry: ToolRegistry, context: ActionToolsContext): Promise<{
+    registered: string[];
+    skipped: Array<{
+        action: string;
+        reason: string;
+    }>;
+}>;
+
 /**
  * Runtime context passed when chatting with the ambient assistant.
  *
@@ -1229,6 +1458,58 @@ declare const DATA_CHAT_AGENT: Agent;
  */
 declare const METADATA_ASSISTANT_AGENT: Agent;
 
+/**
+ * Built-in `data_explorer` skill — the read-only data-Q&A capability
+ * bundle that the `data_chat` agent (and any other agent that wants
+ * data-exploration powers) attaches to its `skills[]`.
+ *
+ * Following the platform's metadata-driven philosophy, the agent
+ * itself no longer hardcodes which tools it can call; instead it
+ * names this skill and the SkillRegistry resolves the tool list at
+ * request time. Disabling this skill via the metadata service
+ * disables data exploration for every agent that references it,
+ * without code changes.
+ */
+declare const DATA_EXPLORER_SKILL: Skill;
+
+/**
+ * Built-in `metadata_authoring` skill — the write-side schema-design
+ * capability bundle attached to the `metadata_assistant` agent (and
+ * any other agent that should be allowed to mutate schema).
+ *
+ * Splitting this off from the agent record lets us:
+ * - Reuse the same authoring tools across multiple agent personas
+ *   (e.g. an "ops bot" that ALSO can author).
+ * - Disable authoring globally by setting `active: false` on the
+ *   skill metadata, without redeploying the agent.
+ * - Layer permissions via `Skill.permissions` independent of the
+ *   agent's permissions.
+ */
+declare const METADATA_AUTHORING_SKILL: Skill;
+
+/**
+ * Built-in `actions_executor` skill — the write-side counterpart to
+ * `data_explorer`.
+ *
+ * Where `data_explorer` lets an agent **answer** questions about the
+ * user's data, `actions_executor` lets the same agent **perform**
+ * business operations: complete tasks, start workflows, send invites,
+ * etc. The concrete tools are not enumerated here — they're materialised
+ * at runtime from every `Action` declared on every object the metadata
+ * service knows about (see `registerActionsAsTools` in
+ * `tools/action-tools.ts`). The skill records the *intent* ("agent may
+ * invoke business actions"); the registry expands it into actual tools
+ * after metadata is loaded.
+ *
+ * The `tools` array is intentionally empty — Phase 1 lets the
+ * skill-registry resolver fall through to the global tool list when an
+ * agent's skill bundle would otherwise filter out the dynamically
+ * registered `action_*` tools. Skills that want to restrict the set
+ * should be authored project-side with the specific `action_<name>`
+ * tools they want to expose.
+ */
+declare const ACTIONS_EXECUTOR_SKILL: Skill;
+
 declare const ActionRefSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     type: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -1283,7 +1564,7 @@ declare const AiConversationObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -1422,7 +1703,7 @@ declare const AiConversationObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -1855,7 +2136,7 @@ declare const AiConversationObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "upsert" | "create" | "import" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -1926,6 +2207,7 @@ declare const AiConversationObject: Omit<{
         } | undefined;
         shortcut?: string | undefined;
         bulkEnabled?: boolean | undefined;
+        aiExposed?: boolean | undefined;
         recordIdParam?: string | undefined;
         recordIdField?: string | undefined;
         bodyShape?: "flat" | {
@@ -3207,7 +3489,7 @@ declare const AiMessageObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -3346,7 +3628,7 @@ declare const AiMessageObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -3779,7 +4061,7 @@ declare const AiMessageObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "upsert" | "create" | "import" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -3850,6 +4132,7 @@ declare const AiMessageObject: Omit<{
         } | undefined;
         shortcut?: string | undefined;
         bulkEnabled?: boolean | undefined;
+        aiExposed?: boolean | undefined;
         recordIdParam?: string | undefined;
         recordIdField?: string | undefined;
         bodyShape?: "flat" | {
@@ -5133,7 +5416,7 @@ declare const AiTraceObject: Omit<{
     abstract: boolean;
     datasource: string;
     fields: Record<string, {
-        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "avatar" | "vector" | "date" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
+        type: "number" | "boolean" | "file" | "text" | "json" | "tags" | "currency" | "code" | "date" | "avatar" | "vector" | "datetime" | "signature" | "progress" | "url" | "textarea" | "email" | "phone" | "password" | "markdown" | "html" | "richtext" | "percent" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "color" | "rating" | "slider" | "qrcode";
         required: boolean;
         searchable: boolean;
         multiple: boolean;
@@ -5272,7 +5555,7 @@ declare const AiTraceObject: Omit<{
                     autoRotate: boolean;
                 } | undefined;
             };
-            scope: "field" | "database" | "record" | "table";
+            scope: "record" | "field" | "database" | "table";
             deterministicEncryption: boolean;
             searchableEncryption: boolean;
         } | undefined;
@@ -5705,7 +5988,7 @@ declare const AiTraceObject: Omit<{
         trash: boolean;
         mru: boolean;
         clone: boolean;
-        apiMethods?: ("search" | "upsert" | "create" | "import" | "delete" | "list" | "get" | "update" | "history" | "bulk" | "aggregate" | "restore" | "purge" | "export")[] | undefined;
+        apiMethods?: ("restore" | "export" | "import" | "delete" | "purge" | "upsert" | "search" | "create" | "list" | "get" | "update" | "history" | "bulk" | "aggregate")[] | undefined;
     } | undefined;
     recordTypes?: string[] | undefined;
     sharingModel?: "private" | "read" | "full" | "read_write" | undefined;
@@ -5776,6 +6059,7 @@ declare const AiTraceObject: Omit<{
         } | undefined;
         shortcut?: string | undefined;
         bulkEnabled?: boolean | undefined;
+        aiExposed?: boolean | undefined;
         recordIdParam?: string | undefined;
         recordIdField?: string | undefined;
         bodyShape?: "flat" | {
@@ -8972,125 +9256,871 @@ declare const AiTraceObject: Omit<{
 }, "fields">;
 
 /**
- * SchemaRetriever — Keyword-based metadata retrieval for AI prompts.
- *
- * Given a free-text query (typically the user's last message), surfaces the
- * most relevant `object` definitions and renders a compact schema snippet
- * suitable for injection into the system prompt.
- *
- * v1 strategy is intentionally simple:
- * - Tokenise the query into lower-case alphanumeric terms
- * - Score each registered object by counting term hits against its name,
- *   label, field names, and field labels
- * - Return the top `limit` matches above the score threshold
- *
- * This does *not* use embeddings — for v1 the user-defined object catalogue
- * is small enough (< 1000 objects in practice) that a single linear scan
- * over already-cached metadata is faster than a vector round-trip and
- * eliminates the need for a vector store.
+ * ai_traces — built-in Studio list view.
  *
- * Future versions can swap in {@link IAIService.embed} backed retrieval
- * behind the same `retrieve()` shape.
+ * Exposes per-call observability for every LLM invocation that flowed
+ * through the `AIService`. Ships with the platform so users don't have
+ * to author a view for an object they didn't create.
  *
- * @example
- * ```ts
- * const retriever = new SchemaRetriever(metadataService);
- * const hits = await retriever.retrieve('how many open tasks are due this week?');
- * const snippet = SchemaRetriever.renderSnippet(hits);
- * // snippet:
- * //   ## Schema context (auto-injected)
- * //   ### task — Project Task
- * //     - id: text
- * //     - title: text
- * //     - status: select(open|in_progress|done)
- * //     - due_date: date
- * ```
- */
-declare class SchemaRetriever {
-    private readonly metadata;
-    private readonly options;
-    constructor(metadata: IMetadataService, options?: SchemaRetrieverOptions);
-    /**
-     * 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.
-     */
-    retrieve(query: string): Promise<SchemaHit[]>;
-    /**
-     * 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: SchemaHit[], maxFieldsPerObject?: number): string;
-}
-/** A scored retrieval result. */
-interface SchemaHit {
-    object: ObjectShape;
-    score: number;
-}
-/** Options for {@link SchemaRetriever}. */
-interface SchemaRetrieverOptions {
-    /** Maximum number of objects to return (default: 3). */
-    limit?: number;
-    /** Minimum score required to include an object (default: 1). */
-    minScore?: number;
-    /** Maximum fields rendered per object in the snippet (default: 12). */
-    maxFieldsPerObject?: number;
-}
-/** Minimal shape of an object definition we care about. */
-interface ObjectShape {
-    name: string;
-    label?: string;
-    pluralLabel?: string;
-    description?: string;
-    fields?: Record<string, FieldShape>;
-}
-/** Minimal shape of a field definition. */
-interface FieldShape {
-    type?: string;
-    label?: string;
-    options?: unknown;
-    reference?: string;
-}
-
-/**
- * Context for the `query_data` tool.
+ * - Default list: grid sorted by `created_at` desc, showing the columns an
+ *   operator usually wants at a glance (operation, model, latency, tokens,
+ *   cost, status).
+ * - `errors` view: pre-filtered to status="error" for triage.
+ * - `by_model` view: grouped by model for cost / quality comparison.
  *
- * Wires together the three services it needs:
- * - {@link IAIService} for structured-output generation of the ObjectQL query
- * - {@link IMetadataService} for schema discovery
- * - {@link IDataEngine} for actually executing the resolved query
+ * Registered via the AIService plugin's manifest payload — appears
+ * automatically in Studio when AIService is loaded.
  */
-interface QueryDataToolContext {
-    ai: IAIService;
-    metadata: IMetadataService;
-    dataEngine: IDataEngine;
-    /** Maximum number of records returned per call (default: 100). */
-    maxLimit?: number;
-}
-/**
- * Zod schema used to constrain the LLM's structured output.
- *
- * Kept small and strict — every property is documented so providers like
- * OpenAI Structured Outputs and Anthropic Tool Use can render high-quality
- * prompts from the schema metadata.
+declare const AiTraceView: {
+    list?: {
+        type: "map" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "chart" | "grid";
+        columns: string[] | {
+            field: string;
+            label?: string | undefined;
+            width?: number | undefined;
+            align?: "left" | "center" | "right" | undefined;
+            hidden?: boolean | undefined;
+            sortable?: boolean | undefined;
+            resizable?: boolean | undefined;
+            wrap?: boolean | undefined;
+            type?: string | undefined;
+            pinned?: "left" | "right" | undefined;
+            summary?: "none" | "min" | "max" | "count" | "sum" | "avg" | "count_empty" | "count_filled" | "count_unique" | "percent_empty" | "percent_filled" | undefined;
+            link?: boolean | undefined;
+            action?: string | undefined;
+        }[];
+        name?: string | undefined;
+        label?: string | undefined;
+        data?: {
+            provider: "object";
+            object: string;
+        } | {
+            provider: "api";
+            read?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+            write?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+        } | {
+            provider: "value";
+            items: unknown[];
+        } | undefined;
+        filter?: {
+            field: string;
+            operator: string;
+            value?: string | number | boolean | (string | number)[] | null | undefined;
+        }[] | undefined;
+        sort?: string | {
+            field: string;
+            order: "asc" | "desc";
+        }[] | undefined;
+        searchableFields?: string[] | undefined;
+        filterableFields?: string[] | undefined;
+        resizable?: boolean | undefined;
+        striped?: boolean | undefined;
+        bordered?: boolean | undefined;
+        compactToolbar?: boolean | undefined;
+        selection?: {
+            type: "none" | "multiple" | "single";
+        } | undefined;
+        navigation?: {
+            mode: "none" | "split" | "page" | "modal" | "drawer" | "popover" | "new_window";
+            preventNavigation: boolean;
+            openNewTab: boolean;
+            view?: string | undefined;
+            width?: string | number | undefined;
+        } | undefined;
+        pagination?: {
+            pageSize: number;
+            pageSizeOptions?: number[] | undefined;
+        } | undefined;
+        kanban?: {
+            groupByField: string;
+            columns: string[];
+            summarizeField?: string | undefined;
+        } | undefined;
+        calendar?: {
+            startDateField: string;
+            titleField: string;
+            endDateField?: string | undefined;
+            colorField?: string | undefined;
+        } | undefined;
+        gantt?: {
+            startDateField: string;
+            endDateField: string;
+            titleField: string;
+            progressField?: string | undefined;
+            dependenciesField?: string | undefined;
+        } | undefined;
+        gallery?: {
+            coverFit: "cover" | "contain";
+            cardSize: "small" | "medium" | "large";
+            coverField?: string | undefined;
+            titleField?: string | undefined;
+            visibleFields?: string[] | undefined;
+        } | undefined;
+        timeline?: {
+            startDateField: string;
+            titleField: string;
+            scale: "day" | "week" | "month" | "quarter" | "year" | "hour";
+            endDateField?: string | undefined;
+            groupByField?: string | undefined;
+            colorField?: string | undefined;
+        } | undefined;
+        chart?: {
+            chartType: "bar" | "line" | "pie" | "area" | "scatter";
+            xAxisField: string;
+            yAxisFields: string[];
+            aggregation?: "min" | "max" | "count" | "sum" | "avg" | undefined;
+            groupByField?: string | undefined;
+        } | undefined;
+        description?: string | undefined;
+        sharing?: {
+            type: "personal" | "collaborative";
+            lockedBy?: string | undefined;
+        } | undefined;
+        rowHeight?: "medium" | "short" | "compact" | "tall" | "extra_tall" | undefined;
+        grouping?: {
+            fields: {
+                field: string;
+                order: "asc" | "desc";
+                collapsed: boolean;
+            }[];
+        } | undefined;
+        rowColor?: {
+            field: string;
+            colors?: Record<string, string> | undefined;
+        } | undefined;
+        hiddenFields?: string[] | undefined;
+        fieldOrder?: string[] | undefined;
+        rowActions?: string[] | undefined;
+        bulkActions?: string[] | undefined;
+        bulkActionDefs?: Record<string, any>[] | undefined;
+        virtualScroll?: boolean | undefined;
+        conditionalFormatting?: {
+            condition: {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            } | {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            };
+            style: Record<string, string>;
+        }[] | undefined;
+        inlineEdit?: boolean | undefined;
+        exportOptions?: ("json" | "csv" | "xlsx" | "pdf")[] | undefined;
+        userActions?: {
+            sort: boolean;
+            search: boolean;
+            filter: boolean;
+            rowHeight: boolean;
+            addRecordForm: boolean;
+            buttons?: string[] | undefined;
+        } | undefined;
+        appearance?: {
+            showDescription: boolean;
+            allowedVisualizations?: ("map" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "grid")[] | undefined;
+        } | undefined;
+        tabs?: {
+            name: string;
+            pinned: boolean;
+            isDefault: boolean;
+            visible: boolean;
+            label?: string | undefined;
+            icon?: string | undefined;
+            view?: string | undefined;
+            filter?: {
+                field: string;
+                operator: string;
+                value?: string | number | boolean | (string | number)[] | null | undefined;
+            }[] | undefined;
+            order?: number | undefined;
+        }[] | undefined;
+        addRecord?: {
+            enabled: boolean;
+            position: "top" | "bottom" | "both";
+            mode: "modal" | "form" | "inline";
+            formView?: string | undefined;
+        } | undefined;
+        showRecordCount?: boolean | undefined;
+        allowPrinting?: boolean | undefined;
+        emptyState?: {
+            title?: string | undefined;
+            message?: string | undefined;
+            icon?: string | undefined;
+        } | undefined;
+        aria?: {
+            ariaLabel?: string | undefined;
+            ariaDescribedBy?: string | undefined;
+            role?: string | undefined;
+        } | undefined;
+        responsive?: {
+            breakpoint?: "md" | "xs" | "sm" | "lg" | "xl" | "2xl" | undefined;
+            hiddenOn?: ("md" | "xs" | "sm" | "lg" | "xl" | "2xl")[] | undefined;
+            columns?: {
+                xs?: number | undefined;
+                sm?: number | undefined;
+                md?: number | undefined;
+                lg?: number | undefined;
+                xl?: number | undefined;
+                '2xl'?: number | undefined;
+            } | undefined;
+            order?: {
+                xs?: number | undefined;
+                sm?: number | undefined;
+                md?: number | undefined;
+                lg?: number | undefined;
+                xl?: number | undefined;
+                '2xl'?: number | undefined;
+            } | undefined;
+        } | undefined;
+        performance?: {
+            lazyLoad?: boolean | undefined;
+            virtualScroll?: {
+                enabled: boolean;
+                itemHeight?: number | undefined;
+                overscan?: number | undefined;
+            } | undefined;
+            cacheStrategy?: "none" | "cache-first" | "network-first" | "stale-while-revalidate" | undefined;
+            prefetch?: boolean | undefined;
+            pageSize?: number | undefined;
+            debounceMs?: number | undefined;
+        } | undefined;
+    } | undefined;
+    form?: {
+        type: "split" | "modal" | "drawer" | "simple" | "tabbed" | "wizard";
+        data?: {
+            provider: "object";
+            object: string;
+        } | {
+            provider: "api";
+            read?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+            write?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+        } | {
+            provider: "value";
+            items: unknown[];
+        } | undefined;
+        sections?: {
+            collapsible: boolean;
+            collapsed: boolean;
+            columns: 1 | 2 | 3 | 4;
+            fields: (string | {
+                field: string;
+                label?: string | undefined;
+                placeholder?: string | undefined;
+                helpText?: string | undefined;
+                readonly?: boolean | undefined;
+                required?: boolean | undefined;
+                hidden?: boolean | undefined;
+                colSpan?: number | undefined;
+                widget?: string | undefined;
+                dependsOn?: string | undefined;
+                visibleOn?: {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            })[];
+            label?: string | undefined;
+        }[] | undefined;
+        groups?: {
+            collapsible: boolean;
+            collapsed: boolean;
+            columns: 1 | 2 | 3 | 4;
+            fields: (string | {
+                field: string;
+                label?: string | undefined;
+                placeholder?: string | undefined;
+                helpText?: string | undefined;
+                readonly?: boolean | undefined;
+                required?: boolean | undefined;
+                hidden?: boolean | undefined;
+                colSpan?: number | undefined;
+                widget?: string | undefined;
+                dependsOn?: string | undefined;
+                visibleOn?: {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            })[];
+            label?: string | undefined;
+        }[] | undefined;
+        defaultSort?: {
+            field: string;
+            order: "asc" | "desc";
+        }[] | undefined;
+        sharing?: {
+            enabled: boolean;
+            allowAnonymous: boolean;
+            publicLink?: string | undefined;
+            password?: string | undefined;
+            allowedDomains?: string[] | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        submitBehavior?: {
+            kind: "thank-you";
+            title?: string | undefined;
+            message?: string | undefined;
+        } | {
+            kind: "redirect";
+            url: string;
+            delayMs?: number | undefined;
+        } | {
+            kind: "continue";
+        } | {
+            kind: "next-record";
+        } | undefined;
+        aria?: {
+            ariaLabel?: string | undefined;
+            ariaDescribedBy?: string | undefined;
+            role?: string | undefined;
+        } | undefined;
+    } | undefined;
+    listViews?: Record<string, {
+        type: "map" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "chart" | "grid";
+        columns: string[] | {
+            field: string;
+            label?: string | undefined;
+            width?: number | undefined;
+            align?: "left" | "center" | "right" | undefined;
+            hidden?: boolean | undefined;
+            sortable?: boolean | undefined;
+            resizable?: boolean | undefined;
+            wrap?: boolean | undefined;
+            type?: string | undefined;
+            pinned?: "left" | "right" | undefined;
+            summary?: "none" | "min" | "max" | "count" | "sum" | "avg" | "count_empty" | "count_filled" | "count_unique" | "percent_empty" | "percent_filled" | undefined;
+            link?: boolean | undefined;
+            action?: string | undefined;
+        }[];
+        name?: string | undefined;
+        label?: string | undefined;
+        data?: {
+            provider: "object";
+            object: string;
+        } | {
+            provider: "api";
+            read?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+            write?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+        } | {
+            provider: "value";
+            items: unknown[];
+        } | undefined;
+        filter?: {
+            field: string;
+            operator: string;
+            value?: string | number | boolean | (string | number)[] | null | undefined;
+        }[] | undefined;
+        sort?: string | {
+            field: string;
+            order: "asc" | "desc";
+        }[] | undefined;
+        searchableFields?: string[] | undefined;
+        filterableFields?: string[] | undefined;
+        resizable?: boolean | undefined;
+        striped?: boolean | undefined;
+        bordered?: boolean | undefined;
+        compactToolbar?: boolean | undefined;
+        selection?: {
+            type: "none" | "multiple" | "single";
+        } | undefined;
+        navigation?: {
+            mode: "none" | "split" | "page" | "modal" | "drawer" | "popover" | "new_window";
+            preventNavigation: boolean;
+            openNewTab: boolean;
+            view?: string | undefined;
+            width?: string | number | undefined;
+        } | undefined;
+        pagination?: {
+            pageSize: number;
+            pageSizeOptions?: number[] | undefined;
+        } | undefined;
+        kanban?: {
+            groupByField: string;
+            columns: string[];
+            summarizeField?: string | undefined;
+        } | undefined;
+        calendar?: {
+            startDateField: string;
+            titleField: string;
+            endDateField?: string | undefined;
+            colorField?: string | undefined;
+        } | undefined;
+        gantt?: {
+            startDateField: string;
+            endDateField: string;
+            titleField: string;
+            progressField?: string | undefined;
+            dependenciesField?: string | undefined;
+        } | undefined;
+        gallery?: {
+            coverFit: "cover" | "contain";
+            cardSize: "small" | "medium" | "large";
+            coverField?: string | undefined;
+            titleField?: string | undefined;
+            visibleFields?: string[] | undefined;
+        } | undefined;
+        timeline?: {
+            startDateField: string;
+            titleField: string;
+            scale: "day" | "week" | "month" | "quarter" | "year" | "hour";
+            endDateField?: string | undefined;
+            groupByField?: string | undefined;
+            colorField?: string | undefined;
+        } | undefined;
+        chart?: {
+            chartType: "bar" | "line" | "pie" | "area" | "scatter";
+            xAxisField: string;
+            yAxisFields: string[];
+            aggregation?: "min" | "max" | "count" | "sum" | "avg" | undefined;
+            groupByField?: string | undefined;
+        } | undefined;
+        description?: string | undefined;
+        sharing?: {
+            type: "personal" | "collaborative";
+            lockedBy?: string | undefined;
+        } | undefined;
+        rowHeight?: "medium" | "short" | "compact" | "tall" | "extra_tall" | undefined;
+        grouping?: {
+            fields: {
+                field: string;
+                order: "asc" | "desc";
+                collapsed: boolean;
+            }[];
+        } | undefined;
+        rowColor?: {
+            field: string;
+            colors?: Record<string, string> | undefined;
+        } | undefined;
+        hiddenFields?: string[] | undefined;
+        fieldOrder?: string[] | undefined;
+        rowActions?: string[] | undefined;
+        bulkActions?: string[] | undefined;
+        bulkActionDefs?: Record<string, any>[] | undefined;
+        virtualScroll?: boolean | undefined;
+        conditionalFormatting?: {
+            condition: {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            } | {
+                dialect: "cel" | "js" | "cron" | "template";
+                source?: string | undefined;
+                ast?: unknown;
+                meta?: {
+                    rationale?: string | undefined;
+                    generatedBy?: string | undefined;
+                } | undefined;
+            };
+            style: Record<string, string>;
+        }[] | undefined;
+        inlineEdit?: boolean | undefined;
+        exportOptions?: ("json" | "csv" | "xlsx" | "pdf")[] | undefined;
+        userActions?: {
+            sort: boolean;
+            search: boolean;
+            filter: boolean;
+            rowHeight: boolean;
+            addRecordForm: boolean;
+            buttons?: string[] | undefined;
+        } | undefined;
+        appearance?: {
+            showDescription: boolean;
+            allowedVisualizations?: ("map" | "kanban" | "calendar" | "gantt" | "gallery" | "timeline" | "grid")[] | undefined;
+        } | undefined;
+        tabs?: {
+            name: string;
+            pinned: boolean;
+            isDefault: boolean;
+            visible: boolean;
+            label?: string | undefined;
+            icon?: string | undefined;
+            view?: string | undefined;
+            filter?: {
+                field: string;
+                operator: string;
+                value?: string | number | boolean | (string | number)[] | null | undefined;
+            }[] | undefined;
+            order?: number | undefined;
+        }[] | undefined;
+        addRecord?: {
+            enabled: boolean;
+            position: "top" | "bottom" | "both";
+            mode: "modal" | "form" | "inline";
+            formView?: string | undefined;
+        } | undefined;
+        showRecordCount?: boolean | undefined;
+        allowPrinting?: boolean | undefined;
+        emptyState?: {
+            title?: string | undefined;
+            message?: string | undefined;
+            icon?: string | undefined;
+        } | undefined;
+        aria?: {
+            ariaLabel?: string | undefined;
+            ariaDescribedBy?: string | undefined;
+            role?: string | undefined;
+        } | undefined;
+        responsive?: {
+            breakpoint?: "md" | "xs" | "sm" | "lg" | "xl" | "2xl" | undefined;
+            hiddenOn?: ("md" | "xs" | "sm" | "lg" | "xl" | "2xl")[] | undefined;
+            columns?: {
+                xs?: number | undefined;
+                sm?: number | undefined;
+                md?: number | undefined;
+                lg?: number | undefined;
+                xl?: number | undefined;
+                '2xl'?: number | undefined;
+            } | undefined;
+            order?: {
+                xs?: number | undefined;
+                sm?: number | undefined;
+                md?: number | undefined;
+                lg?: number | undefined;
+                xl?: number | undefined;
+                '2xl'?: number | undefined;
+            } | undefined;
+        } | undefined;
+        performance?: {
+            lazyLoad?: boolean | undefined;
+            virtualScroll?: {
+                enabled: boolean;
+                itemHeight?: number | undefined;
+                overscan?: number | undefined;
+            } | undefined;
+            cacheStrategy?: "none" | "cache-first" | "network-first" | "stale-while-revalidate" | undefined;
+            prefetch?: boolean | undefined;
+            pageSize?: number | undefined;
+            debounceMs?: number | undefined;
+        } | undefined;
+    }> | undefined;
+    formViews?: Record<string, {
+        type: "split" | "modal" | "drawer" | "simple" | "tabbed" | "wizard";
+        data?: {
+            provider: "object";
+            object: string;
+        } | {
+            provider: "api";
+            read?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+            write?: {
+                url: string;
+                method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
+                headers?: Record<string, string> | undefined;
+                params?: Record<string, unknown> | undefined;
+                body?: unknown;
+            } | undefined;
+        } | {
+            provider: "value";
+            items: unknown[];
+        } | undefined;
+        sections?: {
+            collapsible: boolean;
+            collapsed: boolean;
+            columns: 1 | 2 | 3 | 4;
+            fields: (string | {
+                field: string;
+                label?: string | undefined;
+                placeholder?: string | undefined;
+                helpText?: string | undefined;
+                readonly?: boolean | undefined;
+                required?: boolean | undefined;
+                hidden?: boolean | undefined;
+                colSpan?: number | undefined;
+                widget?: string | undefined;
+                dependsOn?: string | undefined;
+                visibleOn?: {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            })[];
+            label?: string | undefined;
+        }[] | undefined;
+        groups?: {
+            collapsible: boolean;
+            collapsed: boolean;
+            columns: 1 | 2 | 3 | 4;
+            fields: (string | {
+                field: string;
+                label?: string | undefined;
+                placeholder?: string | undefined;
+                helpText?: string | undefined;
+                readonly?: boolean | undefined;
+                required?: boolean | undefined;
+                hidden?: boolean | undefined;
+                colSpan?: number | undefined;
+                widget?: string | undefined;
+                dependsOn?: string | undefined;
+                visibleOn?: {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | {
+                    dialect: "cel" | "js" | "cron" | "template";
+                    source?: string | undefined;
+                    ast?: unknown;
+                    meta?: {
+                        rationale?: string | undefined;
+                        generatedBy?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            })[];
+            label?: string | undefined;
+        }[] | undefined;
+        defaultSort?: {
+            field: string;
+            order: "asc" | "desc";
+        }[] | undefined;
+        sharing?: {
+            enabled: boolean;
+            allowAnonymous: boolean;
+            publicLink?: string | undefined;
+            password?: string | undefined;
+            allowedDomains?: string[] | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        submitBehavior?: {
+            kind: "thank-you";
+            title?: string | undefined;
+            message?: string | undefined;
+        } | {
+            kind: "redirect";
+            url: string;
+            delayMs?: number | undefined;
+        } | {
+            kind: "continue";
+        } | {
+            kind: "next-record";
+        } | undefined;
+        aria?: {
+            ariaLabel?: string | undefined;
+            ariaDescribedBy?: string | undefined;
+            role?: string | undefined;
+        } | undefined;
+    }> | undefined;
+};
+
+/**
+ * SchemaRetriever — Keyword-based metadata retrieval for AI prompts.
+ *
+ * Given a free-text query (typically the user's last message), surfaces the
+ * most relevant `object` definitions and renders a compact schema snippet
+ * suitable for injection into the system prompt.
+ *
+ * v1 strategy is intentionally simple:
+ * - Tokenise the query into lower-case alphanumeric terms
+ * - Score each registered object by counting term hits against its name,
+ *   label, field names, and field labels
+ * - Return the top `limit` matches above the score threshold
+ *
+ * This does *not* use embeddings — for v1 the user-defined object catalogue
+ * is small enough (< 1000 objects in practice) that a single linear scan
+ * over already-cached metadata is faster than a vector round-trip and
+ * eliminates the need for a vector store.
+ *
+ * Future versions can swap in {@link IAIService.embed} backed retrieval
+ * behind the same `retrieve()` shape.
+ *
+ * @example
+ * ```ts
+ * const retriever = new SchemaRetriever(metadataService);
+ * const hits = await retriever.retrieve('how many open tasks are due this week?');
+ * const snippet = SchemaRetriever.renderSnippet(hits);
+ * // snippet:
+ * //   ## Schema context (auto-injected)
+ * //   ### task — Project Task
+ * //     - id: text
+ * //     - title: text
+ * //     - status: select(open|in_progress|done)
+ * //     - due_date: date
+ * ```
+ */
+declare class SchemaRetriever {
+    private readonly metadata;
+    private readonly options;
+    constructor(metadata: IMetadataService, options?: SchemaRetrieverOptions);
+    /**
+     * 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.
+     */
+    retrieve(query: string): Promise<SchemaHit[]>;
+    /**
+     * 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: SchemaHit[], maxFieldsPerObject?: number): string;
+}
+/** A scored retrieval result. */
+interface SchemaHit {
+    object: ObjectShape;
+    score: number;
+}
+/** Options for {@link SchemaRetriever}. */
+interface SchemaRetrieverOptions {
+    /** Maximum number of objects to return (default: 3). */
+    limit?: number;
+    /** Minimum score required to include an object (default: 1). */
+    minScore?: number;
+    /** Maximum fields rendered per object in the snippet (default: 12). */
+    maxFieldsPerObject?: number;
+}
+/** Minimal shape of an object definition we care about. */
+interface ObjectShape {
+    name: string;
+    label?: string;
+    pluralLabel?: string;
+    description?: string;
+    fields?: Record<string, FieldShape>;
+}
+/** Minimal shape of a field definition. */
+interface FieldShape {
+    type?: string;
+    label?: string;
+    options?: unknown;
+    reference?: string;
+}
+
+/**
+ * Context for the `query_data` tool.
+ *
+ * Wires together the three services it needs:
+ * - {@link IAIService} for structured-output generation of the ObjectQL query
+ * - {@link IMetadataService} for schema discovery
+ * - {@link IDataEngine} for actually executing the resolved query
+ */
+interface QueryDataToolContext {
+    ai: IAIService;
+    metadata: IMetadataService;
+    dataEngine: IDataEngine;
+    /** Maximum number of records returned per call (default: 100). */
+    maxLimit?: number;
+}
+/**
+ * Zod schema used to constrain the LLM's structured output.
+ *
+ * Kept small and strict — every property is documented so providers like
+ * OpenAI Structured Outputs and Anthropic Tool Use can render high-quality
+ * prompts from the schema metadata.
+ *
+ * NOTE: `where` is intentionally typed as a JSON string rather than a free-form
+ * record. OpenAI's Structured Outputs surface rejects `propertyNames`
+ * (which Zod's `z.record(z.string(), ...)` emits), and Anthropic's tool-use
+ * surface dislikes open-ended object schemas without `additionalProperties`.
+ * Having the model emit a JSON-encoded filter sidesteps both restrictions and
+ * keeps the tool portable across providers.
  */
 declare const QueryPlanSchema: z.ZodObject<{
     objectName: z.ZodString;
-    where: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    whereJson: z.ZodNullable<z.ZodString>;
+    fields: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    orderBy: z.ZodNullable<z.ZodArray<z.ZodObject<{
         field: z.ZodString;
         order: z.ZodEnum<{
             asc: "asc";
             desc: "desc";
         }>;
     }, z.core.$strip>>>;
-    limit: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 /** Strongly-typed query plan inferred from the LLM. */
 type QueryPlan = z.infer<typeof QueryPlanSchema>;
@@ -9249,4 +10279,4 @@ declare function buildAssistantRoutes(aiService: AIService, agentRuntime: AgentR
  */
 declare function buildToolRoutes(aiService: AIService, logger: Logger): RouteDefinition[];
 
-export { AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, type CostEstimate, DATA_CHAT_AGENT, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, METADATA_ASSISTANT_AGENT, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerDataTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };
+export { ACTIONS_EXECUTOR_SKILL, AIService, type AIServiceConfig, AIServicePlugin, type AIServicePluginOptions, type ActionToolsContext, type AgentChatContext, AgentRuntime, AiConversationObject, AiMessageObject, AiTraceObject, AiTraceView, type CostEstimate, DATA_CHAT_AGENT, DATA_EXPLORER_SKILL, DATA_TOOL_DEFINITIONS, type DataToolContext, type FieldShape, type IConversationService, type IPackageRegistry, InMemoryConversationService, METADATA_ASSISTANT_AGENT, METADATA_AUTHORING_SKILL, METADATA_TOOL_DEFINITIONS, MemoryLLMAdapter, type MetadataToolContext, ModelRegistry, type ModelRegistryConfig, NullTraceRecorder, ObjectQLConversationService, ObjectQLTraceRecorder, type ObjectShape, PACKAGE_TOOL_DEFINITIONS, type PackageToolContext, QUERY_DATA_TOOL, type QueryDataToolContext, type QueryPlan, type RouteDefinition, type RouteRequest, type RouteResponse, type RouteUserContext, type SchemaHit, SchemaRetriever, type SchemaRetrieverOptions, type SkillContext, SkillRegistry, type SkillSummary, type TokenUsage, type ToolExecutionResult, type ToolHandler, ToolRegistry, type TraceEvent, type TraceOperation, type TraceRecorder, VercelLLMAdapter, type VercelLLMAdapterConfig, actionSkipReason, actionToToolDefinition, actionToolName, addFieldTool, buildAIRoutes, buildAgentRoutes, buildAssistantRoutes, buildToolRoutes, buildTraceEvent, computeCost, createObjectTool, createPackageTool, createQueryDataHandler, deleteFieldTool, describeObjectTool, encodeStreamPart, encodeVercelDataStream, getActivePackageTool, getPackageTool, listObjectsTool, listPackagesTool, modifyFieldTool, registerActionsAsTools, registerDataTools, registerMetadataTools, registerPackageTools, registerQueryDataTool, setActivePackageTool };