@dbx-tools/appkit-mastra 0.1.5 → 0.1.13

package/dist/src/genie.d.ts

@@ -21,6 +21,7 @@
  */
 import { genie } from "@databricks/appkit";
 import { createTool } from "@mastra/core/tools";
+import type { MastraPluginConfig } from "./config.js";
 /** Live AppKit `GeniePlugin` instance. */
 export type GeniePluginInstance = InstanceType<ReturnType<typeof genie>["plugin"]>;
 /** Full `exports()` shape of the AppKit `genie` plugin. */
@@ -37,11 +38,16 @@ export type GenieConversation = Awaited<ReturnType<GenieExports["getConversation
  * Normalised progress event surfaced to the UI as a Mastra
  * `tool-output` chunk. Loading pill events (`started`, `status`,
  * `sql`, `suggested`, `error`) are pure UI metadata and never reach
- * the LLM. The `chart` variant carries the rows from a Genie SQL
- * statement so the host UI's `<ChartSlot>` can render them inline
- * via the same path as the `render_data` tool; the LLM still only
- * sees the matching {@link datasetSchema} metadata in
- * `genieAnswer`'s sibling `datasets[]` field.
+ * the LLM.
+ *
+ * The `chart` variant is the wire shape emitted by
+ * {@link emitChartWithPlanning} (used by both this Genie
+ * draining loop and the system-level `render_data` tool). All
+ * fields except `chartId` are optional because two events per
+ * chartId arrive on the wire: the first carries the rows
+ * (`title` + `description?` + `data`); the second, on planner
+ * success, carries just the resolved Echarts spec (`option`).
+ * The host UI's `<ChartSlot>` merges them by `chartId`.
  */
 export type GenieProgress = {
     kind: "started";
@@ -61,9 +67,10 @@ export type GenieProgress = {
 } | {
     kind: "chart";
     chartId: string;
-    title: string;
+    title?: string;
     description?: string;
-    data: Array<Record<string, unknown>>;
+    data?: Array<Record<string, unknown>>;
+    option?: Record<string, unknown>;
 } | {
     kind: "text";
     content: string;
@@ -86,10 +93,16 @@ export declare function defaultGenieToolName(alias: string): string;
  * Build one `sendMessage` tool per configured Genie alias plus a single
  * `getConversation` tool. Returns a record keyed by tool id, ready to
  * spread into an `Agent`'s `tools` map.
+ *
+ * `config` must be the active plugin config; Genie's
+ * `query_result` events are routed through
+ * {@link emitChartWithPlanning} which uses it to resolve the
+ * chart-planner's model.
  */
 export declare function buildGenieTools(opts: {
     aliases: string[];
     exports: GenieExports;
+    config: MastraPluginConfig;
     signal?: AbortSignal;
 }): Record<string, ReturnType<typeof createTool>>;
 /**
@@ -111,6 +124,8 @@ export declare function buildGenieTools(opts: {
  * all-or-nothing bundle. Wire `only` / `except` / `prefix` / `rename`
  * later if a caller needs them.
  */
-export declare function buildGenieProvider(plugin: GeniePluginInstance): {
+export declare function buildGenieProvider(plugin: GeniePluginInstance, opts: {
+    config: MastraPluginConfig;
+}): {
     toolkit(opts?: unknown): Record<string, ReturnType<typeof createTool>>;
 };

package/dist/src/genie.js

@@ -19,11 +19,19 @@
  * LLM never sees rows, and charts come from the separate
  * `render_data` tool when the model decides one is useful.
  */
-import { randomUUID } from "node:crypto";
 import { genie } from "@databricks/appkit";
-import { stringUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, stringUtils } from "@dbx-tools/appkit-shared";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
+import { emitChartWithPlanning } from "./chart.js";
+/**
+ * Module-level logger tagged `[mastra/genie]`. Uses the shared
+ * {@link logUtils.logger} so calls below `LOG_LEVEL` are
+ * discarded for free. Default `LOG_LEVEL` is `info`; flip to
+ * `debug` to see per-turn timing (`query_result` → planner
+ * waits → `drain:return`).
+ */
+const log = logUtils.logger("mastra/genie");
 /**
  * Per-dataset metadata surfaced to the LLM. The actual rows are
  * dispatched separately as a `kind: "chart"` writer event so the
@@ -240,6 +248,11 @@ export function defaultGenieToolName(alias) {
  * Build one `sendMessage` tool per configured Genie alias plus a single
  * `getConversation` tool. Returns a record keyed by tool id, ready to
  * spread into an `Agent`'s `tools` map.
+ *
+ * `config` must be the active plugin config; Genie's
+ * `query_result` events are routed through
+ * {@link emitChartWithPlanning} which uses it to resolve the
+ * chart-planner's model.
  */
 export function buildGenieTools(opts) {
     const tools = {};
@@ -250,23 +263,17 @@ export function buildGenieTools(opts) {
             description: stringUtils.toDescription `
         Ask the Databricks Genie space "${alias}" a single
         natural-language question. Genie translates it to SQL,
-        runs the SQL against the configured datasets, and returns
-        \`genieAnswer\` (its prose answer) plus \`datasets[]\`
-        (one metadata entry per executed query). Each dataset
-        carries a short \`chartId\`; embed
-        \`[[chart:<chartId>]]\` on its own line in your reply at
-        the position where you want that data rendered as an
-        inline chart. Do not paraphrase row values - the chart is
-        the rendering. Add interpretation around the chart
-        (highlights, deltas, anomalies, takeaways) instead of
-        repeating numbers.
+        runs it, and returns \`genieAnswer\` (prose) plus
+        \`datasets[]\` (one entry per executed query, each with
+        a short \`chartId\`). Embed \`[[chart:<chartId>]]\` on
+        its own line at the position you want that data rendered
+        as an inline chart. Add interpretation around the chart
+        (deltas, anomalies, takeaways); do not paraphrase row
+        values.
 
-        Calling this tool is expensive; issue **one** focused
-        question per user turn. If the first answer doesn't fit,
-        ask the user a clarifying question rather than
-        re-querying with rephrased intent. Prefer aggregated
-        questions over raw-row queries (e.g. ask for "monthly
-        averages" instead of "all rows" for time-series).
+        Issue ONE focused question per user turn. Prefer
+        aggregated queries over raw-row queries for time-series
+        and distributions.
       `,
             inputSchema: sendMessageSchema,
             outputSchema: genieToolOutputSchema,
@@ -274,7 +281,12 @@ export function buildGenieTools(opts) {
                 const stream = opts.exports.sendMessage(alias, content, conversationId, {
                     signal: opts.signal,
                 });
-                return drainGenieStream(stream, ctx.writer);
+                const requestContext = ctx
+                    ?.requestContext;
+                return drainGenieStream(stream, ctx.writer, {
+                    config: opts.config,
+                    ...(requestContext ? { requestContext } : {}),
+                });
             },
         });
     }
@@ -303,23 +315,29 @@ export function buildGenieTools(opts) {
  * 1. {@link GenieProgress} pill events on the writer (`started`,
  *    `status`, `sql`, `suggested`, `error`) drive the loading
  *    pill in the chat bubble.
- * 2. `kind: "chart"` events on the writer carry the row payload
- *    from each Genie SQL statement so the host UI's
- *    `<ChartSlot>` can render the chart inline at the marker
- *    position the model picked. The data never reaches the LLM.
- * 3. The `DrainResult` returned to the LLM contains
- *    Genie's prose answer plus a `datasets[]` array of metadata
- *    (chartId, title, columns, rowCount, sql) the model uses to
- *    cite charts via `[[chart:<chartId>]]` markers.
+ * 2. `kind: "chart"` events on the writer (emitted via
+ *    {@link emitChartWithPlanning}) carry the row payload from
+ *    each Genie SQL statement and, on planner success, a
+ *    follow-up event with the rendered Echarts spec. The host
+ *    UI's `<ChartSlot>` merges the two by `chartId` and
+ *    renders inline at the marker position the model picked.
+ *    The data never reaches the LLM.
+ * 3. The `DrainResult` returned to the LLM contains Genie's
+ *    prose answer plus a `datasets[]` array of metadata
+ *    (chartId, title, columns, rowCount, sql) the model uses
+ *    to cite charts via `[[chart:<chartId>]]` markers.
  *
  * `query_result` and `message_result` events arrive in either
- * order; we buffer per-statement metadata in
- * {@link DatasetMeta} so each half can fill in the bits it knows
- * about and we emit the chart event once `query_result` lands
- * (with whatever title was already set, falling back to a
- * generic label otherwise).
+ * order; we buffer per-statement scratch keyed by `statementId`
+ * so each half can fill in what it knows. The chart event
+ * fires the moment `query_result` lands; the planner runs in
+ * the background. We `Promise.allSettled` every planner promise
+ * before returning so all chart work is attributed to the tool's
+ * trace span and so the LLM's `datasets[]` includes every
+ * chartId that has actually been queued.
  */
-async function drainGenieStream(stream, writer) {
+async function drainGenieStream(stream, writer, opts) {
+    const { config, requestContext } = opts;
     let conversationId;
     let genieAnswer;
     let suggestedFollowUps;
@@ -331,15 +349,23 @@ async function drainGenieStream(stream, writer) {
     // behaviour here so the UI status pill doesn't flicker and we don't
     // burn writer bytes on no-op events.
     let lastStatus;
-    // Per-statement scratch keyed by Genie's `statementId`. Filled in
-    // by both `query_result` (rows + columns) and `message_result`
-    // (sql + title + description); the LLM-bound `datasets[]` is
-    // built from this at end-of-stream, and chart writer events fire
-    // when `query_result` lands.
-    const datasetsByStatementId = new Map();
-    // Best-effort progress emission. Awaited so the underlying agent
-    // stream sees events in order; write failures are swallowed so a
-    // dead writer (e.g. closed downstream) can't take the tool down.
+    const scratchByStatementId = new Map();
+    const getScratch = (statementId) => {
+        let s = scratchByStatementId.get(statementId);
+        if (!s) {
+            s = { statementId, columns: [], rowCount: 0 };
+            scratchByStatementId.set(statementId, s);
+        }
+        return s;
+    };
+    /**
+     * Planner promises kicked off per `query_result`. Awaited
+     * (Promise.allSettled) before drainGenieStream returns so the
+     * Genie tool's trace span covers the chart work and the LLM's
+     * `datasets[]` accurately reflects every chartId that's been
+     * queued for rendering.
+     */
+    const plannerPromises = [];
     const emit = async (event) => {
         if (!writer)
             return;
@@ -351,13 +377,12 @@ async function drainGenieStream(stream, writer) {
         }
     };
     for await (const event of stream) {
-        // Uncomment to log every raw Genie wire event before the switch
-        // routes it through the writer / DrainResult. Useful when tuning
-        // the pill / answer pipeline against real Genie payloads (status
-        // codes, attachment shapes, query_result manifests Genie surfaces
-        // only on certain question types, etc.).
-        // eslint-disable-next-line no-console
-        // console.log("[mastra/genie] event", event);
+        // Per-event raw payload for tuning the pill / answer pipeline
+        // against real Genie traffic. At `info` (the default) this is
+        // discarded for free; flip `LOG_LEVEL=debug` to see every
+        // raw wire event before the switch routes it through writer
+        // and DrainResult.
+        log.debug("event", { type: event.type, payload: event });
         switch (event.type) {
             case "message_start":
                 conversationId = event.conversationId;
@@ -382,17 +407,30 @@ async function drainGenieStream(stream, writer) {
                 const columns = (event.data?.manifest?.schema?.columns ?? []).map((c) => c.name);
                 const dataArray = (event.data?.result?.data_array ?? []);
                 const rows = genieRowsToObjects(columns, dataArray);
-                const meta = upsertDatasetMeta(datasetsByStatementId, event.statementId, {
-                    columns,
-                    rowCount: rows.length,
-                });
-                await emit({
-                    kind: "chart",
-                    chartId: meta.chartId,
-                    title: meta.title ?? `Genie query`,
-                    ...(meta.description ? { description: meta.description } : {}),
+                const scratch = getScratch(event.statementId);
+                // emitChartWithPlanning emits the dataset event immediately
+                // and kicks off the chart-planner agent in the background.
+                // It returns the chartId synchronously; the plannerPromise
+                // is awaited at end-of-stream so chart work shows up under
+                // this tool's trace span.
+                const { chartId, plannerPromise } = await emitChartWithPlanning({
+                    ...(writer ? { writer } : {}),
+                    config,
+                    ...(requestContext ? { requestContext } : {}),
+                    title: scratch.title ?? `Genie query`,
+                    ...(scratch.description ? { description: scratch.description } : {}),
                     data: rows,
                 });
+                scratch.chartId = chartId;
+                scratch.columns = columns;
+                scratch.rowCount = rows.length;
+                plannerPromises.push(plannerPromise);
+                log.debug("query_result", {
+                    statementId: event.statementId,
+                    chartId,
+                    rows: rows.length,
+                    columns,
+                });
                 break;
             }
             case "message_result":
@@ -400,14 +438,15 @@ async function drainGenieStream(stream, writer) {
                 for (const attachment of event.message.attachments ?? []) {
                     const sqlText = attachment.query?.query;
                     const stmtId = attachment.query?.statementId;
-                    if (sqlText && stmtId) {
-                        upsertDatasetMeta(datasetsByStatementId, stmtId, {
-                            sql: sqlText,
-                            ...(attachment.query?.title ? { title: attachment.query.title } : {}),
-                            ...(attachment.query?.description
-                                ? { description: attachment.query.description }
-                                : {}),
-                        });
+                    if (stmtId) {
+                        const scratch = getScratch(stmtId);
+                        if (sqlText)
+                            scratch.sql = sqlText;
+                        if (attachment.query?.title)
+                            scratch.title = attachment.query.title;
+                        if (attachment.query?.description) {
+                            scratch.description = attachment.query.description;
+                        }
                     }
                     if (sqlText) {
                         await emit({
@@ -441,20 +480,40 @@ async function drainGenieStream(stream, writer) {
                 break;
         }
     }
-    // Strip statementId / row-only fields when handing the LLM the
-    // datasets - the model never references statementId, and the
-    // chartId is what the marker uses.
+    // Wait for all chart planners to settle before returning so the
+    // tool's trace span covers chart work and the LLM's
+    // `datasets[]` reflects only chartIds the client has actually
+    // received writer events for. Failures in `emitChartWithPlanning`
+    // are already swallowed inside the helper, so this never
+    // throws.
+    log.debug("planners:awaiting", { count: plannerPromises.length });
+    await Promise.allSettled(plannerPromises);
+    log.debug("planners:settled", { count: plannerPromises.length });
+    // Build the LLM-bound `datasets[]` from scratch entries that
+    // actually ran a query (chartId is assigned at `query_result`
+    // time). Entries that only saw `message_result` metadata
+    // without a row payload are skipped.
     const datasets = [];
-    for (const meta of datasetsByStatementId.values()) {
+    for (const scratch of scratchByStatementId.values()) {
+        if (!scratch.chartId)
+            continue;
         datasets.push({
-            chartId: meta.chartId,
-            ...(meta.title ? { title: meta.title } : {}),
-            ...(meta.description ? { description: meta.description } : {}),
-            columns: meta.columns,
-            rowCount: meta.rowCount,
-            ...(meta.sql ? { sql: meta.sql } : {}),
+            chartId: scratch.chartId,
+            ...(scratch.title ? { title: scratch.title } : {}),
+            ...(scratch.description ? { description: scratch.description } : {}),
+            columns: scratch.columns,
+            rowCount: scratch.rowCount,
+            ...(scratch.sql ? { sql: scratch.sql } : {}),
         });
     }
+    log.debug("drain:return", {
+        conversationId,
+        hasAnswer: typeof genieAnswer === "string",
+        answerLength: genieAnswer?.length ?? 0,
+        chartIds: datasets.map((d) => d.chartId),
+        suggestedCount: suggestedFollowUps?.length ?? 0,
+        error,
+    });
     return {
         ...(conversationId ? { conversationId } : {}),
         ...(genieAnswer ? { genieAnswer } : {}),
@@ -463,30 +522,6 @@ async function drainGenieStream(stream, writer) {
         ...(error ? { error } : {}),
     };
 }
-/**
- * Get-or-create-and-merge the per-statement scratch entry. Both
- * `query_result` and `message_result` paths call this with their
- * partial bag of fields; the resulting record is the union of
- * everything we know about that statement so far.
- */
-function upsertDatasetMeta(store, statementId, patch) {
-    const existing = store.get(statementId);
-    const merged = {
-        chartId: existing?.chartId ?? randomUUID().replace(/-/g, "").slice(0, 8),
-        statementId,
-        columns: patch.columns ?? existing?.columns ?? [],
-        rowCount: patch.rowCount ?? existing?.rowCount ?? 0,
-        ...(patch.title ?? existing?.title
-            ? { title: patch.title ?? existing?.title }
-            : {}),
-        ...(patch.description ?? existing?.description
-            ? { description: patch.description ?? existing?.description }
-            : {}),
-        ...(patch.sql ?? existing?.sql ? { sql: patch.sql ?? existing?.sql } : {}),
-    };
-    store.set(statementId, merged);
-    return merged;
-}
 /**
  * Convert Genie's `data_array` (column-positional `string | null`
  * tuples) into plain JS row objects keyed by column name. Numeric
@@ -538,7 +573,7 @@ function coerceCell(cell) {
  * all-or-nothing bundle. Wire `only` / `except` / `prefix` / `rename`
  * later if a caller needs them.
  */
-export function buildGenieProvider(plugin) {
+export function buildGenieProvider(plugin, opts) {
     return {
         toolkit(_opts) {
             const aliases = extractGenieAliases(plugin);
@@ -548,6 +583,7 @@ export function buildGenieProvider(plugin) {
                     sendMessage: plugin.sendMessage.bind(plugin),
                     getConversation: plugin.getConversation.bind(plugin),
                 },
+                config: opts.config,
             });
         },
     };

package/dist/src/history.js

@@ -15,9 +15,11 @@
  * the handler runs - no cookie or user lookups happen here, and the
  * session-cookie logic stays the single source of truth in `server.ts`.
  */
+import { logUtils } from "@dbx-tools/appkit-shared";
 import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
 import { registerApiRoute } from "@mastra/core/server";
+const log = logUtils.logger("mastra/history");
 /** Default history page size; matches the Mastra storage default. */
 const DEFAULT_PER_PAGE = 20;
 /** Hard cap so a misbehaving client can't fetch the whole thread at once. */
@@ -42,8 +44,10 @@ export async function loadHistory(opts) {
     const page = Math.max(0, Math.trunc(opts.page ?? 0));
     const memory = await opts.agent.getMemory();
     if (!memory) {
+        log.debug("recall:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
         return { uiMessages: [], page, perPage, total: 0, hasMore: false };
     }
+    const startedAt = Date.now();
     const result = await memory.recall({
         threadId: opts.threadId,
         ...(opts.resourceId ? { resourceId: opts.resourceId } : {}),
@@ -56,6 +60,16 @@ export async function loadHistory(opts) {
     });
     const chronological = sortChronological(result.messages);
     const uiMessages = toAISdkV5Messages(chronological);
+    log.debug("recall:done", {
+        agentId: opts.agent.id,
+        threadId: opts.threadId,
+        page,
+        perPage,
+        returned: uiMessages.length,
+        total: result.total,
+        hasMore: result.hasMore,
+        elapsedMs: Date.now() - startedAt,
+    });
     return {
         uiMessages,
         page,

package/dist/src/memory.d.ts

@@ -14,6 +14,14 @@
  *   index is almost always what users want; opt into per-agent recall
  *   by passing a {@link MastraMemoryConfigOverride} on the agent.
  *
+ * Additionally, {@link MemoryBuilder.instanceStorage} returns a
+ * **Mastra-instance-level** `PostgresStore` (schema `mastra_instance`)
+ * used for workflow snapshots - the persistence layer
+ * `agent.resumeStream()` reads from when waking a suspended
+ * `requireApproval` tool call. Per-agent stores are not enough for
+ * this: workflow runs are scoped to the Mastra instance, not an
+ * individual agent's `Memory`.
+ *
  * Plugin-level `config.storage` / `config.memory` act as the baseline
  * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
  * is registered); per-agent settings cascade on top of that.
@@ -21,6 +29,7 @@
 import { lakebase } from "@databricks/appkit";
 import { pluginUtils } from "@dbx-tools/appkit-shared";
 import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
 import type { MastraAgentDefinition } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
 /** Pool handle returned by the AppKit `lakebase` plugin `exports().pool`. */
@@ -62,6 +71,18 @@ export declare class MemoryBuilder {
      * vector store enabled - Mastra accepts a missing `memory` field
      * and treats the agent as stateless.
      */
+    /**
+     * Build the Mastra-instance-level storage used for workflow
+     * snapshots. Returns `undefined` when plugin-level `storage` is
+     * disabled, in which case `agent.resumeStream()` (and therefore
+     * the `requireApproval` flow) will not be available.
+     *
+     * The store lives in a dedicated `mastra_instance` schema so it
+     * never collides with per-agent `mastra_<agentId>` namespaces.
+     * Workflow snapshots are not per-agent state; they belong to the
+     * `Mastra` instance that owns the workflow execution.
+     */
+    instanceStorage(): PostgresStore | undefined;
     forAgent(agentId: string, def: MastraAgentDefinition): Memory | undefined;
     private buildStorage;
     /**

package/dist/src/memory.js

@@ -14,16 +14,25 @@
  *   index is almost always what users want; opt into per-agent recall
  *   by passing a {@link MastraMemoryConfigOverride} on the agent.
  *
+ * Additionally, {@link MemoryBuilder.instanceStorage} returns a
+ * **Mastra-instance-level** `PostgresStore` (schema `mastra_instance`)
+ * used for workflow snapshots - the persistence layer
+ * `agent.resumeStream()` reads from when waking a suspended
+ * `requireApproval` tool call. Per-agent stores are not enough for
+ * this: workflow runs are scoped to the Mastra instance, not an
+ * individual agent's `Memory`.
+ *
  * Plugin-level `config.storage` / `config.memory` act as the baseline
  * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
  * is registered); per-agent settings cascade on top of that.
  */
 import { lakebase } from "@databricks/appkit";
-import { pluginUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
 import { randomUUID } from "node:crypto";
+const log = logUtils.logger("mastra/memory");
 /**
  * True when any plugin-level or per-agent setting could need the
  * Lakebase pool. Used by `plugin.ts` to gate pool acquisition; the
@@ -75,13 +84,49 @@ export class MemoryBuilder {
      * vector store enabled - Mastra accepts a missing `memory` field
      * and treats the agent as stateless.
      */
+    /**
+     * Build the Mastra-instance-level storage used for workflow
+     * snapshots. Returns `undefined` when plugin-level `storage` is
+     * disabled, in which case `agent.resumeStream()` (and therefore
+     * the `requireApproval` flow) will not be available.
+     *
+     * The store lives in a dedicated `mastra_instance` schema so it
+     * never collides with per-agent `mastra_<agentId>` namespaces.
+     * Workflow snapshots are not per-agent state; they belong to the
+     * `Mastra` instance that owns the workflow execution.
+     */
+    instanceStorage() {
+        const setting = this.config.storage;
+        if (!setting)
+            return undefined;
+        if (typeof setting === "object") {
+            return new PostgresStore(withId(setting, "mastra-store__instance"));
+        }
+        return new PostgresStore({
+            id: "mastra-store__instance",
+            schemaName: "mastra_instance",
+            pool: this.requirePool(),
+        });
+    }
     forAgent(agentId, def) {
         const storageSetting = def.storage ?? this.config.storage;
         const memorySetting = def.memory ?? this.config.memory;
         const storage = this.buildStorage(agentId, storageSetting);
         const vector = this.buildVector(memorySetting);
-        if (!storage && !vector)
+        if (!storage && !vector) {
+            log.debug("agent:stateless", { agentId });
             return undefined;
+        }
+        log.debug("agent:configured", {
+            agentId,
+            storage: storage !== undefined,
+            vector: vector !== undefined,
+            vectorMode: vector === undefined
+                ? "off"
+                : typeof memorySetting === "object"
+                    ? "dedicated"
+                    : "shared",
+        });
         return new Memory({
             ...(storage ? { storage } : {}),
             ...(vector ? { vector, embedder: fastembed } : {}),

package/dist/src/model.js

@@ -263,6 +263,7 @@ export async function buildModel(config, requestContext, overrides = {}) {
  * to the top of the priority list.
  */
 async function pickModelId(config, requestContext, overrides, user, host) {
+    const log = logUtils.logger(config);
     const serving = resolveServingConfig(config, FALLBACK_MODEL_IDS);
     const override = serving.allowOverride
         ? requestContext.get(MASTRA_MODEL_OVERRIDE_KEY)
@@ -270,15 +271,21 @@ async function pickModelId(config, requestContext, overrides, user, host) {
     const explicit = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
     // Cheap exit: when the caller named a specific model and fuzzy
     // matching is off, there's no reason to touch the catalogue at all.
-    if (explicit !== undefined && !serving.fuzzy)
+    if (explicit !== undefined && !serving.fuzzy) {
+        log.debug("model selected", { modelId: explicit, source: "explicit" });
         return explicit;
+    }
     const endpoints = await listServingEndpoints(user.executionContext.client, host, {
         ttlMs: serving.ttlMs,
     });
     const modelId = explicit !== undefined
         ? resolveModelId(explicit, endpoints, { threshold: serving.threshold }).modelId
         : pickFirstAvailable(serving.fallbacks, endpoints);
-    //logUtils.logger(config).debug(`model selected: ${modelId}`);
+    log.debug("model selected", {
+        modelId,
+        source: explicit !== undefined ? "fuzzy-match" : "fallback",
+        requestedExplicit: explicit,
+    });
     return modelId;
 }
 /**
@@ -305,9 +312,9 @@ const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
  *   1. Rewrites the outgoing `messages` array to repair Mastra/AI SDK
  *      stream-replay quirks that Databricks-hosted Claude rejects (see
  *      {@link sanitizeServingMessages}).
- *   2. When `MASTRA_DEBUG_LLM=1`, dumps the (post-sanitize) JSON body
- *      to stderr so 4xx debugging doesn't have to fight AI SDK's
- *      `[Array]` formatter.
+ *   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
+ *      4xx debugging doesn't have to fight AI SDK's `[Array]`
+ *      formatter.
  *
  * Safe to call from any hot path: {@link commonUtils.memoize} ensures
  * the wrapper is installed at most once per process, so subsequent
@@ -315,7 +322,7 @@ const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
  * {@link buildModel} fires on every agent step.
  */
 const setupFetchInterceptor = commonUtils.memoize(() => {
-    const debug = Boolean(process.env.MASTRA_DEBUG_LLM);
+    const log = logUtils.logger("mastra/llm");
     const original = globalThis.fetch.bind(globalThis);
     globalThis.fetch = (async (input, init) => {
         const url = httpUtils.toURL(input);
@@ -328,14 +335,11 @@ const setupFetchInterceptor = commonUtils.memoize(() => {
         if (rewritten !== init.body) {
             init = { ...init, body: rewritten };
         }
-        if (debug) {
-            try {
-                console.error("[mastra:llm-debug] -> POST", url.toString());
-                console.error(JSON.stringify(JSON.parse(rewritten), null, 2));
-            }
-            catch {
-                console.error("[mastra:llm-debug] -> POST", url.toString(), "(non-JSON body)");
-            }
+        try {
+            log.debug("POST", { url: url.toString(), body: JSON.parse(rewritten) });
+        }
+        catch {
+            log.debug("POST", { url: url.toString(), bodyType: "non-JSON" });
         }
         return original(input, init);
     });