@dbx-tools/appkit-mastra 0.9.176 → 0.9.177

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/model.ts CHANGED
@@ -24,11 +24,7 @@
24
24
 
25
25
  import { createWorkspaceClient, type WorkspaceClient } from "@databricks/appkit";
26
26
  import { tryGetExecutionContext } from "@dbx-tools/appkit";
27
- import {
28
- SmartRouterService,
29
- SMART_ROUTER_DEFAULT_SETTINGS,
30
- smartRouterCandidates,
31
- } from "@dbx-tools/appkit-model-gateway";
27
+ import { SmartRouterService, smartRouterCandidates } from "@dbx-tools/appkit-model-gateway";
32
28
  import {
33
29
  classes,
34
30
  endpointCapabilities,
@@ -46,7 +42,12 @@ import { contracts, type ServingEndpointSummary } from "@dbx-tools/shared-model"
46
42
  import { SMART_ROUTER_MODEL_ID, isSmartRouterModelId } from "@dbx-tools/shared-model-gateway";
47
43
  import { RequestContext } from "@mastra/core/request-context";
48
44
 
49
- import { MASTRA_USER_KEY, type MastraPluginConfig, type User } from "./config.ts";
45
+ import {
46
+ executionContextUserId,
47
+ MASTRA_USER_KEY,
48
+ type MastraPluginConfig,
49
+ type User,
50
+ } from "./config.ts";
50
51
  import {
51
52
  MASTRA_MODEL_OVERRIDE_KEY,
52
53
  MASTRA_RESOLVED_MODEL_KEY,
@@ -58,7 +59,13 @@ import { recordActiveTraceAuth, recordActiveTraceModel } from "./telemetry.ts";
58
59
  type ModelClass = contracts.ModelClass;
59
60
  const { parseModelClass } = classes;
60
61
  const { selectModel } = resolve;
61
- const smartRouter = new SmartRouterService(SMART_ROUTER_DEFAULT_SETTINGS);
62
+ const smartRouter = new SmartRouterService();
63
+ const MASTRA_SMART_ROUTER_RESOLUTION_KEY = "mastra__smart_router_resolution";
64
+
65
+ interface SmartRouterModelResolution {
66
+ readonly modelId: string;
67
+ readonly source: string;
68
+ }
62
69
 
63
70
  /** Virtual endpoint shown when Smart Router is enabled for the active identity. */
64
71
  export const SMART_ROUTER_ENDPOINT: ServingEndpointSummary = {
@@ -90,12 +97,12 @@ export interface BuildModelOverrides {
90
97
  */
91
98
  modelId?: string;
92
99
  /**
93
- * Chat capability class to resolve when no explicit model id is
94
- * supplied. Used by internal agents (e.g. the chart planner asks for
95
- * {@link model.ModelClass.ChatFast}) to express intent without pinning an
96
- * endpoint name; the live catalogue is classified and the top
97
- * available model in the class is chosen, falling back to the
98
- * class's static list when the workspace has none.
100
+ * Chat capability class for internal model work. When no model id is
101
+ * supplied, this bypasses request and environment model overrides so
102
+ * background tasks such as titles and follow-ups cannot inherit the
103
+ * primary agent's Smart Router selection. The live catalogue chooses
104
+ * the top available model in the class, falling back to the class's
105
+ * static list when the workspace has none.
99
106
  */
100
107
  modelClass?: ModelClass;
101
108
  /** Arbitrary request, messages, JSON, or text used to build Smart Router task context. */
@@ -108,6 +115,7 @@ export interface BuildModelOverrides {
108
115
  interface ResolvedModelWorkspaceClient {
109
116
  client: WorkspaceClient;
110
117
  auth: "obo" | "service-principal";
118
+ cacheIdentity?: string;
111
119
  }
112
120
 
113
121
  /** Resolve an OBO workspace client when present, else a service-principal client. */
@@ -120,6 +128,7 @@ function resolveModelWorkspaceContext(
120
128
  return {
121
129
  client: executionContext.client,
122
130
  auth: "isUserContext" in executionContext ? "obo" : "service-principal",
131
+ cacheIdentity: executionContextUserId(executionContext),
123
132
  };
124
133
  }
125
134
  return { client: createWorkspaceClient(), auth: "service-principal" };
@@ -134,6 +143,7 @@ function selectionInput(
134
143
  config: MastraPluginConfig,
135
144
  requested: string | undefined,
136
145
  defaultClass: ModelClass | undefined,
146
+ cacheIdentity: string | undefined,
137
147
  serving = resolveServingConfig(config),
138
148
  ) {
139
149
  const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
@@ -147,6 +157,7 @@ function selectionInput(
147
157
  fallbacks: serving.fallbacks.slice(),
148
158
  liveOnly: requested === undefined,
149
159
  ttlMs: serving.ttlMs,
160
+ ...(cacheIdentity !== undefined ? { cacheIdentity } : {}),
150
161
  };
151
162
  }
152
163
 
@@ -166,8 +177,10 @@ export function resolveDefaultModelId(
166
177
  return SMART_ROUTER_MODEL_ID;
167
178
  }
168
179
  const requested = overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
169
- return selection.resolveModel(endpoints, selectionInput(config, requested, overrides.modelClass))
170
- .modelId;
180
+ return selection.resolveModel(
181
+ endpoints,
182
+ selectionInput(config, requested, overrides.modelClass, undefined),
183
+ ).modelId;
171
184
  }
172
185
 
173
186
  /**
@@ -196,7 +209,7 @@ export async function buildModel(
196
209
  const resolved = overrides.workspaceClient
197
210
  ? { client: overrides.workspaceClient, auth: "service-principal" as const }
198
211
  : resolveModelWorkspaceContext(context);
199
- const { client, auth } = resolved;
212
+ const { client, auth, cacheIdentity } = resolved;
200
213
  recordActiveTraceAuth(auth);
201
214
  const clientConfig = client.config;
202
215
  const host = (await clientConfig.getHost()).toString();
@@ -204,20 +217,29 @@ export async function buildModel(
204
217
  await clientConfig.authenticate(headers);
205
218
  const logger = log.logger(config);
206
219
  const serving = resolveServingConfig(config);
207
- const override = serving.allowOverride
208
- ? (context.get(MASTRA_MODEL_OVERRIDE_KEY) as string | undefined)
209
- : undefined;
220
+ const internalClassOnly = overrides.modelClass !== undefined && overrides.modelId === undefined;
221
+ const override =
222
+ serving.allowOverride && !internalClassOnly
223
+ ? (context.get(MASTRA_MODEL_OVERRIDE_KEY) as string | undefined)
224
+ : undefined;
210
225
 
211
226
  // The override / agent default / env value can be either a concrete
212
227
  // endpoint name or a model class slug ("chat-thinking" /
213
228
  // "chat-balanced" / "chat-fast"). A class slug becomes a class intent
214
229
  // (let the live catalogue pick the best model in that band); anything
215
230
  // else is an explicit name fuzzy-matched against the catalogue. An
216
- // internal `overrides.modelClass` (e.g. the chart planner) is the
217
- // floor when nothing was requested.
218
- const requested = override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
231
+ // internal `overrides.modelClass` (e.g. titles, follow-ups, or the chart
232
+ // planner) is authoritative unless that caller also pins `modelId`. It must
233
+ // not inherit the primary agent's request or environment selection.
234
+ const requested =
235
+ override ??
236
+ overrides.modelId ??
237
+ (!internalClassOnly ? process.env.DATABRICKS_SERVING_ENDPOINT_NAME : undefined);
219
238
  const smartRouterInput = overrides.smartRouterInput ?? context.get(MASTRA_SMART_ROUTER_INPUT_KEY);
220
239
  const smartRouterRequested = isSmartRouterModelId(requested);
240
+ if (smartRouterRequested && smartRouterInput === undefined) {
241
+ throw new Error("Smart Router requires task input before it can resolve a concrete model");
242
+ }
221
243
  let modelId: string;
222
244
  let source: string;
223
245
  if (
@@ -225,36 +247,55 @@ export async function buildModel(
225
247
  overrides.modelClass === undefined &&
226
248
  smartRouterInput !== undefined
227
249
  ) {
228
- const endpoints = await listServingEndpoints(client, host, { ttlMs: serving.ttlMs });
229
- const candidates = smartRouterCandidates(
230
- endpoints.filter((endpoint) => endpointCapabilities(endpoint).tools),
231
- "codex",
232
- );
233
- const enabled = await smartRouter.isEnabled(candidates, client);
234
- if (enabled) {
235
- const selected = await smartRouter.select(smartRouterInput, candidates, { client });
236
- modelId = selected.value.name;
237
- source = SMART_ROUTER_MODEL_ID;
238
- } else if (smartRouterRequested) {
239
- throw new Error("Databricks Smart Router is not enabled for the active workspace identity");
240
- } else {
241
- const resolved = await selectModel(
242
- client,
243
- host,
244
- selectionInput(config, requested, overrides.modelClass, serving),
245
- );
246
- modelId = resolved.modelId;
247
- source = resolved.source;
250
+ let pending = context.get(MASTRA_SMART_ROUTER_RESOLUTION_KEY) as
251
+ Promise<SmartRouterModelResolution> | undefined;
252
+ if (!pending) {
253
+ pending = (async () => {
254
+ const endpoints = await listServingEndpoints(client, host, {
255
+ ttlMs: serving.ttlMs,
256
+ ...(cacheIdentity !== undefined ? { cacheIdentity } : {}),
257
+ });
258
+ const candidates = smartRouterCandidates(
259
+ endpoints.filter((endpoint) => endpointCapabilities(endpoint).tools),
260
+ "codex",
261
+ );
262
+ // An explicit Smart Router request does not need a synthetic preflight:
263
+ // the real selection is the availability check. Auto mode still probes
264
+ // so it can fall back to the configured model policy when unavailable.
265
+ const enabled = smartRouterRequested || (await smartRouter.isEnabled(candidates, client));
266
+ if (enabled) {
267
+ const selected = await smartRouter.select(smartRouterInput, candidates, { client });
268
+ return { modelId: selected.value.name, source: SMART_ROUTER_MODEL_ID };
269
+ }
270
+ const fallback = await selectModel(
271
+ client,
272
+ host,
273
+ selectionInput(config, requested, overrides.modelClass, cacheIdentity, serving),
274
+ );
275
+ return { modelId: fallback.modelId, source: fallback.source };
276
+ })();
277
+ context.set(MASTRA_SMART_ROUTER_RESOLUTION_KEY, pending);
278
+ }
279
+ try {
280
+ ({ modelId, source } = await pending);
281
+ } catch (error) {
282
+ if (context.get(MASTRA_SMART_ROUTER_RESOLUTION_KEY) === pending) {
283
+ context.set(MASTRA_SMART_ROUTER_RESOLUTION_KEY, undefined);
284
+ }
285
+ throw error;
248
286
  }
249
287
  } else {
250
288
  const resolved = await selectModel(
251
289
  client,
252
290
  host,
253
- selectionInput(config, requested, overrides.modelClass, serving),
291
+ selectionInput(config, requested, overrides.modelClass, cacheIdentity, serving),
254
292
  );
255
293
  modelId = resolved.modelId;
256
294
  source = resolved.source;
257
295
  }
296
+ if (isSmartRouterModelId(modelId)) {
297
+ throw new Error("Smart Router did not resolve to a concrete serving endpoint");
298
+ }
258
299
  logger.debug("model selected", { modelId, source, requested });
259
300
  context.set(MASTRA_RESOLVED_MODEL_KEY, modelId);
260
301
  recordActiveTraceModel(modelId);
package/src/summarize.ts CHANGED
@@ -1,16 +1,9 @@
1
1
  /**
2
2
  * Small-tier summarization for the Mastra plugin.
3
3
  *
4
- * Two surfaces, both backed by the fast / small chat tier
4
+ * A dedicated `summarize` tool backed by the fast / small chat tier
5
5
  * ({@link model.ModelClass.ChatFast}) resolved through the same
6
- * `/serving-endpoints` pipeline as the main agents:
7
- *
8
- * - A dedicated `summarize` tool (see {@link buildSummarizeTool})
9
- * agents can call to condense arbitrary text without burning the
10
- * heavyweight chat model.
11
- * - The model + instructions Mastra's memory uses to auto-name
12
- * conversation threads (`generateTitle`), so titling reuses the
13
- * same small tier rather than the agent's primary model.
6
+ * `/serving-endpoints` pipeline as the main agents.
14
7
  *
15
8
  * Mirrors the chart-planner wiring in `chart.ts`: a per-config cached
16
9
  * `Agent` on the fast tier, invoked via `agent.generate(...)` inside
@@ -46,9 +39,9 @@ const SUMMARIZER_INSTRUCTIONS = [
46
39
  ].join("\n");
47
40
 
48
41
  /**
49
- * Instructions Mastra's `generateTitle` hands the small-tier model to
50
- * name a conversation thread from its opening turn. Kept terse so the
51
- * model returns a bare title with no decoration.
42
+ * Instructions Mastra's `generateTitle` hands the agent model to name a
43
+ * conversation thread from its opening turn. Kept terse so the model returns
44
+ * a bare title with no decoration.
52
45
  */
53
46
  export const TITLE_INSTRUCTIONS = [
54
47
  "Generate a short, specific title for this conversation, 3 to 6 words.",
@@ -59,8 +52,7 @@ export const TITLE_INSTRUCTIONS = [
59
52
  ].join(" ");
60
53
 
61
54
  /**
62
- * Resolve the small-tier model for summarization / titling. Reused by
63
- * both the summarizer agent and Mastra memory's `generateTitle`.
55
+ * Resolve the small-tier model for summarization.
64
56
  *
65
57
  * Returned as a `requestContext`-taking function (a Mastra
66
58
  * `DynamicArgument<MastraModelConfig>`) so each call mints user-scoped