@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/package.json CHANGED
@@ -36,23 +36,23 @@
36
36
  },
37
37
  "dependencies": {
38
38
  "@databricks/appkit": "0.81.0",
39
- "@dbx-tools/appkit": "^0.9.176",
40
- "@dbx-tools/appkit-model-gateway": "^0.9.176",
41
- "@dbx-tools/cache": "^0.9.176",
42
- "@dbx-tools/core": "^0.9.176",
43
- "@dbx-tools/databricks": "^0.9.176",
44
- "@dbx-tools/fs": "^0.9.176",
45
- "@dbx-tools/genie": "^0.9.176",
46
- "@dbx-tools/model": "^0.9.176",
47
- "@dbx-tools/model-protocol": "^0.9.176",
48
- "@dbx-tools/path": "^0.9.176",
49
- "@dbx-tools/postgres": "^0.9.176",
50
- "@dbx-tools/shared-core": "^0.9.176",
51
- "@dbx-tools/shared-fs": "^0.9.176",
52
- "@dbx-tools/shared-genie": "^0.9.176",
53
- "@dbx-tools/shared-mastra": "^0.9.176",
54
- "@dbx-tools/shared-model": "^0.9.176",
55
- "@dbx-tools/shared-model-gateway": "^0.9.176",
39
+ "@dbx-tools/appkit": "^0.9.177",
40
+ "@dbx-tools/appkit-model-gateway": "^0.9.177",
41
+ "@dbx-tools/cache": "^0.9.177",
42
+ "@dbx-tools/core": "^0.9.177",
43
+ "@dbx-tools/databricks": "^0.9.177",
44
+ "@dbx-tools/fs": "^0.9.177",
45
+ "@dbx-tools/genie": "^0.9.177",
46
+ "@dbx-tools/model": "^0.9.177",
47
+ "@dbx-tools/model-protocol": "^0.9.177",
48
+ "@dbx-tools/path": "^0.9.177",
49
+ "@dbx-tools/postgres": "^0.9.177",
50
+ "@dbx-tools/shared-core": "^0.9.177",
51
+ "@dbx-tools/shared-fs": "^0.9.177",
52
+ "@dbx-tools/shared-genie": "^0.9.177",
53
+ "@dbx-tools/shared-mastra": "^0.9.177",
54
+ "@dbx-tools/shared-model": "^0.9.177",
55
+ "@dbx-tools/shared-model-gateway": "^0.9.177",
56
56
  "@mastra/ai-sdk": "1.10.5",
57
57
  "@mastra/core": "1.71.0",
58
58
  "@mastra/express": "1.5.15",
@@ -90,7 +90,7 @@
90
90
  "./package.json": "./package.json"
91
91
  }
92
92
  },
93
- "version": "0.9.176",
93
+ "version": "0.9.177",
94
94
  "types": "./lib/index.d.ts",
95
95
  "dbxToolsConfig": {
96
96
  "tags": [
package/src/agents.ts CHANGED
@@ -919,8 +919,16 @@ export async function buildAgents(opts: {
919
919
  ? { suggest_follow_ups: buildSuggestFollowUpsTool(config) }
920
920
  : {}),
921
921
  };
922
- const standardSkillTools =
923
- standardSkills.length > 0 ? createSkillTools(resolveAgentSkills([...standardSkills])) : {};
922
+ let standardSkillTools: MastraTools = {};
923
+ if (standardSkills.length > 0) {
924
+ const processSkills = resolveAgentSkills([...standardSkills]);
925
+ // These skills are immutable startup snapshots. Build their shared BM25
926
+ // catalogue while the app initializes so no chat session pays the first
927
+ // parse/index cost. Workspace-file skills retain their separate dynamic,
928
+ // non-blocking refresh path below.
929
+ await processSkills.list();
930
+ standardSkillTools = createSkillTools(processSkills);
931
+ }
924
932
  const ambientTools = {
925
933
  ...systemTools,
926
934
  ...standardSkillTools,
@@ -960,6 +968,7 @@ export async function buildAgents(opts: {
960
968
  extraSkillMounts,
961
969
  excludeSkillNames: excludedWorkspaceSkillNames,
962
970
  fallbackToTmp: config.workspaceFallbackToTmp,
971
+ ...(config.workspaceSkills === false ? { skills: [] } : {}),
963
972
  ...(config.workspaceTools !== undefined ? { tools: config.workspaceTools } : {}),
964
973
  pluginContext: context,
965
974
  sandbox: config.sandbox,
package/src/chat.ts CHANGED
@@ -4,16 +4,20 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { log, toError, errorMessage, isRecord } from "@dbx-tools/shared-core";
7
+ import { log, toError, errorMessage, isRecord, sleep } from "@dbx-tools/shared-core";
8
8
  import {
9
9
  MASTRA_ROUTES,
10
+ RESPONSE_COMPLETE_PART_TYPE,
10
11
  isStaleMastraResumeError,
11
12
  STALE_MASTRA_RESUME_STREAM_TEXT,
12
13
  } from "@dbx-tools/shared-mastra";
13
14
  import { handleChatStream, toAISdkStream } from "@mastra/ai-sdk";
14
15
  import { isEventedAgent } from "@mastra/core/agent/durable";
16
+ import type { EventedAgent } from "@mastra/core/agent/durable";
15
17
  import { registerApiRoute } from "@mastra/core/server";
18
+ import type { DataChunkType, MastraStreamTransform } from "@mastra/core/stream";
16
19
  import { createUIMessageStreamResponse } from "ai";
20
+ import type { UIMessageChunk } from "ai";
17
21
 
18
22
  import type { MastraPluginConfig } from "./config.ts";
19
23
  import {
@@ -28,6 +32,142 @@ import { activeChatTracingOptions } from "./telemetry.ts";
28
32
 
29
33
  const logger = log.logger("mastra/chat");
30
34
 
35
+ /** Keep a quiet chat stream below the Databricks Apps ingress idle window. */
36
+ export const CHAT_STREAM_KEEPALIVE_MS = 10_000;
37
+
38
+ /** Bound reconnects to producerless durable-run topics before ingress times out. */
39
+ export const CHAT_RUN_OBSERVE_IDLE_TIMEOUT_MS = 15_000;
40
+
41
+ /** Maximum age for a persisted `running` snapshot without a local producer. */
42
+ const CHAT_REMOTE_RUN_FRESHNESS_MS = 60_000;
43
+
44
+ const chatStreamHeartbeat = (): UIMessageChunk => ({
45
+ type: "data-stream-heartbeat",
46
+ data: null,
47
+ transient: true,
48
+ });
49
+
50
+ /** Mark the answer complete while post-turn processors continue before finish. */
51
+ export function buildResponseCompleteTransform(): MastraStreamTransform {
52
+ return () => {
53
+ let emitted = false;
54
+ return new TransformStream({
55
+ transform(chunk, controller) {
56
+ controller.enqueue(chunk);
57
+ if (
58
+ !emitted &&
59
+ chunk.type === "step-finish" &&
60
+ chunk.payload.stepResult.isContinued !== true &&
61
+ (chunk.payload.output.toolCalls?.length ?? 0) === 0
62
+ ) {
63
+ emitted = true;
64
+ const part: DataChunkType = {
65
+ type: RESPONSE_COMPLETE_PART_TYPE,
66
+ data: null,
67
+ transient: true,
68
+ };
69
+ controller.enqueue(part as never);
70
+ }
71
+ },
72
+ });
73
+ };
74
+ }
75
+
76
+ function chatStreamTransforms(
77
+ runId: string,
78
+ generatedFollowUps: boolean,
79
+ ): readonly MastraStreamTransform[] {
80
+ return [
81
+ buildResponseCompleteTransform(),
82
+ ...(generatedFollowUps ? [buildFollowUpSuggestionsTransform(runId)] : []),
83
+ ];
84
+ }
85
+
86
+ function deferredChatStream(open: () => Promise<ReadableStream<UIMessageChunk>>): Response {
87
+ let reader: ReadableStreamDefaultReader<UIMessageChunk> | undefined;
88
+ let timer: ReturnType<typeof setInterval> | undefined;
89
+ let settled = false;
90
+
91
+ const stream = new ReadableStream<UIMessageChunk>({
92
+ start(controller) {
93
+ const writeHeartbeat = () => {
94
+ if (!settled) controller.enqueue(chatStreamHeartbeat());
95
+ };
96
+ writeHeartbeat();
97
+ timer = setInterval(writeHeartbeat, CHAT_STREAM_KEEPALIVE_MS);
98
+ timer.unref?.();
99
+
100
+ void (async () => {
101
+ try {
102
+ const opened = await open();
103
+ if (settled) {
104
+ await opened.cancel();
105
+ return;
106
+ }
107
+ reader = opened.getReader();
108
+ while (true) {
109
+ const { done, value } = await reader.read();
110
+ if (done) break;
111
+ controller.enqueue(value);
112
+ }
113
+ } catch (error) {
114
+ if (!settled) {
115
+ controller.enqueue({ type: "error", errorText: errorMessage(error) });
116
+ }
117
+ } finally {
118
+ const shouldClose = !settled;
119
+ settled = true;
120
+ if (timer) clearInterval(timer);
121
+ reader?.releaseLock();
122
+ if (shouldClose) controller.close();
123
+ }
124
+ })();
125
+ },
126
+ async cancel(reason) {
127
+ settled = true;
128
+ if (timer) clearInterval(timer);
129
+ await reader?.cancel(reason);
130
+ },
131
+ });
132
+ return createUIMessageStreamResponse({
133
+ stream,
134
+ keepAliveMs: CHAT_STREAM_KEEPALIVE_MS,
135
+ });
136
+ }
137
+
138
+ async function backgroundRunAvailable(agent: EventedAgent, runId: string): Promise<boolean> {
139
+ if (agent.runRegistry.has(runId)) return true;
140
+ const active = await agent.listActiveRuns();
141
+ const run = active.runs.find((candidate) => candidate.runId === runId);
142
+ if (!run) return false;
143
+ const updatedAt =
144
+ run.updatedAt instanceof Date ? run.updatedAt.getTime() : Date.parse(String(run.updatedAt));
145
+ return Number.isFinite(updatedAt) && Date.now() - updatedAt <= CHAT_REMOTE_RUN_FRESHNESS_MS;
146
+ }
147
+
148
+ async function observeBackgroundRun(agent: EventedAgent, runId: string) {
149
+ const available = await Promise.race([
150
+ backgroundRunAvailable(agent, runId),
151
+ sleep(CHAT_RUN_OBSERVE_IDLE_TIMEOUT_MS).then(() => false),
152
+ ]);
153
+ if (!available) throw new Error(`Run ${runId} is no longer available`);
154
+
155
+ const pending = agent.observe(runId, {
156
+ idleTimeoutMs: CHAT_RUN_OBSERVE_IDLE_TIMEOUT_MS,
157
+ isAlive: () =>
158
+ Promise.race([
159
+ backgroundRunAvailable(agent, runId),
160
+ sleep(CHAT_RUN_OBSERVE_IDLE_TIMEOUT_MS).then(() => false),
161
+ ]),
162
+ });
163
+ return Promise.race([
164
+ pending,
165
+ sleep(CHAT_RUN_OBSERVE_IDLE_TIMEOUT_MS).then(() => {
166
+ throw new Error(`Run ${runId} is no longer available`);
167
+ }),
168
+ ]);
169
+ }
170
+
31
171
  /** Client request cancellation is detached only for evented background agents. */
32
172
  export function agentAbortSignal(agent: unknown, signal: AbortSignal): AbortSignal | undefined {
33
173
  return isEventedAgent(agent) ? undefined : signal;
@@ -94,33 +234,35 @@ export function agentChatRoutes(config: MastraPluginConfig = {}) {
94
234
  requestContext.setRaw(FOLLOW_UP_NATIVE_QUESTIONS_KEY, []);
95
235
  requestContext.setRaw(FOLLOW_UP_RUN_ID_KEY, runId);
96
236
  const tracingOptions = activeChatTracingOptions(undefined);
97
- const stream = await handleChatStream({
98
- mastra,
99
- agentId,
100
- ...(versionId
101
- ? { agentVersion: { versionId } }
102
- : status
103
- ? { agentVersion: { status } }
104
- : {}),
105
- params: withRequestMemoryScope(
106
- {
107
- ...params,
108
- runId,
237
+ return deferredChatStream(async () => {
238
+ return handleChatStream({
239
+ mastra,
240
+ agentId,
241
+ ...(versionId
242
+ ? { agentVersion: { versionId } }
243
+ : status
244
+ ? { agentVersion: { status } }
245
+ : {}),
246
+ params: withRequestMemoryScope(
247
+ {
248
+ ...params,
249
+ runId,
250
+ requestContext,
251
+ ...(tracingOptions ? { tracingOptions } : {}),
252
+ ...(abortSignal ? { abortSignal } : {}),
253
+ },
109
254
  requestContext,
110
- ...(tracingOptions ? { tracingOptions } : {}),
111
- ...(abortSignal ? { abortSignal } : {}),
112
- },
113
- requestContext,
114
- ),
115
- ...(followUps && followUps.mode !== "genie"
116
- ? { experimentalTransform: buildFollowUpSuggestionsTransform(runId) }
117
- : {}),
118
- version: "v7",
119
- sendReasoning,
120
- sendSources: true,
121
- onError: serializeChatStreamError,
255
+ ),
256
+ experimentalTransform: chatStreamTransforms(
257
+ runId,
258
+ Boolean(followUps && followUps.mode !== "genie"),
259
+ ),
260
+ version: "v7",
261
+ sendReasoning,
262
+ sendSources: true,
263
+ onError: serializeChatStreamError,
264
+ });
122
265
  });
123
- return createUIMessageStreamResponse({ stream });
124
266
  },
125
267
  }),
126
268
  registerApiRoute(runPath, {
@@ -137,18 +279,20 @@ export function agentChatRoutes(config: MastraPluginConfig = {}) {
137
279
  { status: 409 },
138
280
  );
139
281
  }
140
- const observed = await agent.observe(runId);
141
- const stream = toAISdkStream(observed.output, {
142
- from: "agent",
143
- ...(followUps && followUps.mode !== "genie"
144
- ? { experimentalTransform: buildFollowUpSuggestionsTransform(runId) }
145
- : {}),
146
- version: "v7",
147
- sendReasoning,
148
- sendSources: true,
149
- onError: serializeChatStreamError,
282
+ return deferredChatStream(async () => {
283
+ const observed = await observeBackgroundRun(agent, runId);
284
+ return toAISdkStream(observed.output, {
285
+ from: "agent",
286
+ experimentalTransform: chatStreamTransforms(
287
+ runId,
288
+ Boolean(followUps && followUps.mode !== "genie"),
289
+ ),
290
+ version: "v7",
291
+ sendReasoning,
292
+ sendSources: true,
293
+ onError: serializeChatStreamError,
294
+ });
150
295
  });
151
- return createUIMessageStreamResponse({ stream });
152
296
  },
153
297
  }),
154
298
  registerApiRoute(abortPath, {
package/src/config.ts CHANGED
@@ -275,8 +275,9 @@ export interface MastraPluginConfig extends BasePluginConfig {
275
275
  /** Native Mastra workspace tool availability, approval, and hook configuration. */
276
276
  workspaceTools?: WorkspaceToolsConfig;
277
277
  /**
278
- * Use Mastra's native workspace skill manager. Defaults to true. Pass an
279
- * object to tune on-demand discovery and loaded-skill state.
278
+ * Use Mastra's native workspace-file skill manager. Defaults to true. Pass
279
+ * false to disable workspace-file discovery on auto-created workspaces, or
280
+ * an object to tune its process-cached, asynchronously refreshed index.
280
281
  */
281
282
  workspaceSkills?: boolean | MastraWorkspaceSkillsConfig;
282
283
  /**
@@ -748,7 +749,7 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
748
749
  workspaceSkills: {
749
750
  type: ["boolean", "object"],
750
751
  description:
751
- "Use Mastra's native on-demand workspace skill search and writable skill saves. Defaults to true.",
752
+ "Use Mastra's native process-cached workspace-file skill search with asynchronous refresh. Defaults to true; false disables workspace-file discovery on auto-created workspaces.",
752
753
  },
753
754
  workspaceTools: {
754
755
  type: "object",
@@ -11,13 +11,12 @@ import {
11
11
  FollowUpSuggestionsPartDataSchema,
12
12
  } from "@dbx-tools/shared-mastra";
13
13
  import { ModelClass } from "@dbx-tools/shared-model";
14
- import { Agent } from "@mastra/core/agent";
15
14
  import type { MessageList } from "@mastra/core/agent/message-list";
16
- import type { MastraModelConfig } from "@mastra/core/llm";
17
15
  import type { OutputProcessor } from "@mastra/core/processors";
18
16
  import type { RequestContext } from "@mastra/core/request-context";
19
17
  import type { DataChunkType, LLMStepResult, MastraStreamTransform } from "@mastra/core/stream";
20
18
  import { createTool } from "@mastra/core/tools";
19
+ import { generateText, Output } from "ai";
21
20
  import { z } from "zod";
22
21
 
23
22
  import type { FollowUpSuggestionsConfig, MastraPluginConfig } from "./config.ts";
@@ -117,7 +116,6 @@ const FOLLOW_UP_INSTRUCTIONS = [
117
116
  TYPOGRAPHY_RULE,
118
117
  ].join(" ");
119
118
 
120
- const suggestionAgents = new WeakMap<MastraPluginConfig, Agent>();
121
119
  const generatedRunParts = new Map<string, FollowUpSuggestionsPartData>();
122
120
  const GENERATED_RUN_PART_TTL_MS = 5 * 60_000;
123
121
 
@@ -135,28 +133,6 @@ export function resolveFollowUpSuggestionsConfig(
135
133
  };
136
134
  }
137
135
 
138
- function followUpModel(
139
- config: MastraPluginConfig,
140
- ): (args: { requestContext: RequestContext }) => Promise<MastraModelConfig> {
141
- return ({ requestContext }) =>
142
- buildModel(config, requestContext, { modelClass: FOLLOW_UP_MODEL_CLASS });
143
- }
144
-
145
- function suggestionAgent(config: MastraPluginConfig): Agent {
146
- let agent = suggestionAgents.get(config);
147
- if (!agent) {
148
- agent = new Agent({
149
- id: "follow-up-suggestions",
150
- name: "Follow-up suggestions",
151
- description: "Generates grounded next questions using the fast chat model.",
152
- instructions: FOLLOW_UP_INSTRUCTIONS,
153
- model: followUpModel(config),
154
- });
155
- suggestionAgents.set(config, agent);
156
- }
157
- return agent;
158
- }
159
-
160
136
  function normalizedQuestion(value: string): string {
161
137
  return value
162
138
  .trim()
@@ -255,12 +231,17 @@ export async function suggestFollowUps(
255
231
  "Maximum questions": String(settings.limit),
256
232
  });
257
233
  try {
258
- const result = await suggestionAgent(config).generate(prompt, {
259
- structuredOutput: { schema: FollowUpOutputSchema },
260
- ...(options.requestContext ? { requestContext: options.requestContext } : {}),
234
+ const model = await buildModel(config, options.requestContext, {
235
+ modelClass: FOLLOW_UP_MODEL_CLASS,
236
+ });
237
+ const result = await generateText({
238
+ model,
239
+ instructions: FOLLOW_UP_INSTRUCTIONS,
240
+ prompt,
241
+ output: Output.object({ schema: FollowUpOutputSchema }),
261
242
  abortSignal,
262
243
  });
263
- const parsed = FollowUpOutputSchema.parse(result.object);
244
+ const parsed = FollowUpOutputSchema.parse(result.output);
264
245
  return acceptedQuestions(parsed.questions, options, settings.limit);
265
246
  } catch (error) {
266
247
  if (!options.abortSignal?.aborted) {
package/src/memory.ts CHANGED
@@ -257,12 +257,10 @@ export class MemoryBuilder {
257
257
  ...(vector
258
258
  ? { semanticRecall: { topK: 3, messageRange: 2, scope: "resource" as const } }
259
259
  : {}),
260
- // Auto-name each thread from its opening turn so the
261
- // conversation list the UI renders shows meaningful titles
262
- // instead of raw ids. Titling runs on the small / fast chat
263
- // tier (see `summarize.ts`) rather than the agent's primary
264
- // model, so naming a thread never spends the heavyweight model.
265
- // Only meaningful when storage is on; harmless otherwise.
260
+ // Auto-name each thread from its opening turn using the fast chat tier.
261
+ // Title generation is awaited before Mastra settles the response stream,
262
+ // so reusing the primary agent model can keep the UI busy long after the
263
+ // answer text has finished streaming.
266
264
  ...(storage
267
265
  ? {
268
266
  generateTitle: {