@dbx-tools/appkit-mastra 0.9.99 → 0.9.105

package/src/agents.ts

@@ -34,6 +34,7 @@ import type {
   ToolsInput,
 } from "@mastra/core/agent";
 import { Agent } from "@mastra/core/agent";
+import { createEventedAgent } from "@mastra/core/agent/durable";
 import { SkillSearchProcessor } from "@mastra/core/processors";
 import type { OutputProcessor } from "@mastra/core/processors";
 import { MASTRA_RESOURCE_ID_KEY } from "@mastra/core/request-context";
@@ -409,6 +410,41 @@ export const FALLBACK_AGENT_ID = "default";
  */
 export const DEFAULT_AGENT_MAX_STEPS = 25;
 
+const EVENTED_CONSTRUCTOR_MODEL = {
+  specificationVersion: "v3",
+  provider: "dbx-tools",
+  modelId: "deferred",
+  supportedUrls: {},
+  async doGenerate() {
+    throw new Error("Deferred evented constructor model must not execute");
+  },
+  async doStream() {
+    throw new Error("Deferred evented constructor model must not execute");
+  },
+} as never;
+
+/**
+ * `EventedAgent` delegates model resolution to the wrapped agent at execution
+ * time, but its constructor also probes an untyped `__model` slot and otherwise
+ * calls `getModel()` with an empty request context. Temporarily filling that
+ * probe avoids an eager service-principal lookup while preserving the wrapped
+ * agent's request-scoped model resolver for real turns.
+ */
+function createBackgroundAgent(agent: Agent, maxSteps: number): Agent {
+  const modelSlot = "__model";
+  const descriptor = Object.getOwnPropertyDescriptor(agent, modelSlot);
+  Object.defineProperty(agent, modelSlot, {
+    configurable: true,
+    value: EVENTED_CONSTRUCTOR_MODEL,
+  });
+  try {
+    return createEventedAgent({ agent, maxSteps }) as unknown as Agent;
+  } finally {
+    if (descriptor) Object.defineProperty(agent, modelSlot, descriptor);
+    else delete (agent as Agent & { __model?: unknown }).__model;
+  }
+}
+
 const FALLBACK_AGENT_INSTRUCTIONS = `You are a data analyst. The user will ask questions about
 business metrics and may share personal preferences you should remember across turns.
 
@@ -421,6 +457,13 @@ Rules:
 3. If you don't have enough information to answer, ask a clarifying
    question instead of guessing.`;
 
+/** Tool-call guidance appended to every registered agent. */
+export const DEFAULT_TOOL_WORKFLOW_INSTRUCTIONS = [
+  "Tool workflow:",
+  "When the active model supports it, call multiple tools in the same turn when their inputs are independent, including multiple calls to the same tool.",
+  "Keep calls sequential when a later input depends on an earlier result or when calls mutate the same resource.",
+].join("\n");
+
 /**
  * Style guardrails appended to every agent's `instructions` to curb
  * common LLM-isms (em dashes, emojis, sycophantic openers, excessive
@@ -459,34 +502,36 @@ function resolveStyleInstructions(config: MastraPluginConfig): string | null {
   return DEFAULT_STYLE_INSTRUCTIONS;
 }
 
-/** Append the style block without narrowing Mastra's native instruction shapes. */
-function appendStyleInstructions(
+/** Append shared workflow and style blocks without narrowing Mastra's instruction shapes. */
+function appendDefaultInstructions(
   instructions: AgentInstructions,
   style: string | null,
 ): AgentInstructions {
-  if (!style) return instructions;
+  const suffix = style
+    ? `${DEFAULT_TOOL_WORKFLOW_INSTRUCTIONS}\n\n${style}`
+    : DEFAULT_TOOL_WORKFLOW_INSTRUCTIONS;
   if (typeof instructions === "string") {
-    return `${instructions.trimEnd()}\n\n${style}`;
+    return `${instructions.trimEnd()}\n\n${suffix}`;
   }
   if (Array.isArray(instructions)) {
     if (instructions.every((instruction) => typeof instruction === "string")) {
-      return [...instructions, style] as AgentInstructions;
+      return [...instructions, suffix] as AgentInstructions;
     }
-    return [...instructions, { role: "system", content: style }] as AgentInstructions;
+    return [...instructions, { role: "system", content: suffix }] as AgentInstructions;
   }
-  return [instructions, { role: "system", content: style }] as AgentInstructions;
+  return [instructions, { role: "system", content: suffix }] as AgentInstructions;
 }
 
 /**
- * Compose static or request-context-aware instructions with the shared style
- * policy while preserving Mastra's native generic inference.
+ * Compose static or request-context-aware instructions with shared workflow
+ * and style guidance while preserving Mastra's native generic inference.
  */
 function composeInstructions<TRequestContext extends Record<string, unknown> | unknown>(
   agentInstructions: AgentConfig<string, ToolsInput, undefined, TRequestContext>["instructions"],
   style: string | null,
 ): AgentConfig<string, ToolsInput, undefined, TRequestContext>["instructions"] {
   if (typeof agentInstructions !== "function") {
-    return appendStyleInstructions(agentInstructions, style) as AgentConfig<
+    return appendDefaultInstructions(agentInstructions, style) as AgentConfig<
       string,
       ToolsInput,
       undefined,
@@ -494,7 +539,7 @@ function composeInstructions<TRequestContext extends Record<string, unknown> | u
     >["instructions"];
   }
   return (async (args) =>
-    appendStyleInstructions(await agentInstructions(args), style)) as AgentConfig<
+    appendDefaultInstructions(await agentInstructions(args), style)) as AgentConfig<
     string,
     ToolsInput,
     undefined,
@@ -593,7 +638,7 @@ export async function buildAgents(opts: {
     const gated = approvalGatedToolIds(tools);
     if (gated.length > 0) approvalGatedByAgent.push({ agentId: id, toolIds: gated });
     const memory = memoryBuilder?.forAgent(id, def);
-    agents[id] = new Agent({
+    const agent = new Agent({
       id,
       name: def.name ?? id,
       // Always carry a non-empty description: it's surfaced to MCP
@@ -617,6 +662,10 @@ export async function buildAgents(opts: {
       inputProcessors: [...inputProcessors, ...workspaceSkillInputProcessors(workspace, config)],
       outputProcessors: [toolErrorLoggingProcessor(log)],
     });
+    agents[id] =
+      config.backgroundTurns === false
+        ? agent
+        : createBackgroundAgent(agent, config.agentMaxSteps ?? DEFAULT_AGENT_MAX_STEPS);
     // Surface the effective default model per agent so operators can
     // see at a glance which endpoint each agent points at without
     // having to fire a request and inspect a trace. The value is the

package/src/chat.ts

@@ -10,28 +10,120 @@ import {
   isStaleMastraResumeError,
   STALE_MASTRA_RESUME_STREAM_TEXT,
 } from "@dbx-tools/shared-mastra/resume";
-import { chatRoute } from "@mastra/ai-sdk";
+import { handleChatStream, toAISdkStream } from "@mastra/ai-sdk";
+import { isEventedAgent } from "@mastra/core/agent/durable";
+import { registerApiRoute } from "@mastra/core/server";
+import { createUIMessageStreamResponse } from "ai";
 
 const logger = log.logger("mastra/chat");
 
-/** Register the official AI SDK chat stream plus its approval continuation. */
+/** Client request cancellation is detached only for evented background agents. */
+export function agentAbortSignal(agent: unknown, signal: AbortSignal): AbortSignal | undefined {
+  return isEventedAgent(agent) ? undefined : signal;
+}
+
+/** Register detached chat, durable observation, and explicit abort routes. */
 export function agentChatRoutes() {
-  const path = `${routes.MASTRA_ROUTES.chat}/:agentId` as `${string}:agentId`;
+  const chatPath = `${routes.MASTRA_ROUTES.chat}/:agentId` as `${string}:agentId`;
+  const runPath =
+    `${routes.MASTRA_ROUTES.chat}/:agentId${routes.MASTRA_ROUTES.runs}/:runId` as `${string}:agentId${string}:runId`;
+  const abortPath =
+    `${runPath}${routes.MASTRA_ROUTES.abort}` as `${string}:agentId${string}:runId${string}`;
   return [
-    chatRoute({
-      path,
-      sendReasoning: true,
-      sendSources: true,
-      onError: serializeChatStreamError,
+    registerApiRoute(chatPath, {
+      method: "POST",
+      handler: async (context) => {
+        const params = await context.req.json();
+        const mastra = context.get("mastra");
+        const agentId = context.req.param("agentId");
+        if (!agentId) throw new Error("Agent ID is required");
+        const middlewareRequestContext = context.get("requestContext");
+        const requestContext = middlewareRequestContext || params.requestContext;
+        if (middlewareRequestContext && params.requestContext) {
+          mastra
+            .getLogger()
+            ?.warn('Multiple "requestContext" sources provided. Using middleware context.');
+        }
+        const versionId = context.req.query("versionId");
+        const rawStatus = context.req.query("status");
+        if (versionId && rawStatus) {
+          throw new Error('Query parameters "versionId" and "status" are mutually exclusive');
+        }
+        if (rawStatus && rawStatus !== "draft" && rawStatus !== "published") {
+          throw new Error('Query parameter "status" must be "draft" or "published"');
+        }
+        const status = rawStatus as "draft" | "published" | undefined;
+        const abortSignal = agentAbortSignal(mastra.getAgentById(agentId), context.req.raw.signal);
+        const stream = await handleChatStream({
+          mastra,
+          agentId,
+          ...(versionId
+            ? { agentVersion: { versionId } }
+            : status
+              ? { agentVersion: { status } }
+              : {}),
+          params: {
+            ...params,
+            requestContext,
+            ...(abortSignal ? { abortSignal } : {}),
+          },
+          version: "v7",
+          sendReasoning: true,
+          sendSources: true,
+          onError: serializeChatStreamError,
+        });
+        return createUIMessageStreamResponse({ stream });
+      },
+    }),
+    registerApiRoute(runPath, {
+      method: "GET",
+      handler: async (context) => {
+        const mastra = context.get("mastra");
+        const agentId = context.req.param("agentId");
+        const runId = context.req.param("runId");
+        if (!agentId || !runId) throw new Error("Agent ID and run ID are required");
+        const agent = mastra.getAgentById(agentId);
+        if (!isEventedAgent(agent)) {
+          return Response.json(
+            { error: `Agent ${agentId} does not support background turns` },
+            { status: 409 },
+          );
+        }
+        const observed = await agent.observe(runId);
+        const stream = toAISdkStream(observed.output, {
+          from: "agent",
+          version: "v7",
+          sendReasoning: true,
+          sendSources: true,
+          onError: serializeChatStreamError,
+        });
+        return createUIMessageStreamResponse({ stream });
+      },
+    }),
+    registerApiRoute(abortPath, {
+      method: "POST",
+      handler: async (context) => {
+        const mastra = context.get("mastra");
+        const agentId = context.req.param("agentId");
+        const runId = context.req.param("runId");
+        if (!agentId || !runId) throw new Error("Agent ID and run ID are required");
+        const agent = mastra.getAgentById(agentId);
+        if (!isEventedAgent(agent)) {
+          return Response.json(
+            { error: `Agent ${agentId} does not support background turns` },
+            { status: 409 },
+          );
+        }
+        return Response.json({ aborted: agent.abortRunStream(runId) });
+      },
     }),
   ];
 }
 
 /**
  * Keep a late or duplicate resume from failing the UI stream. Mastra's
- * `chatRoute` already swallows a couple of resume ids on the v6 approval
- * path; this covers the generic workflow errors `consumeStream` still
- * surfaces on v5.
+ * resume path can surface a workflow error after another client already
+ * resolved the same approval.
  */
 function serializeChatStreamError(error: unknown): string {
   if (isStaleMastraResumeError(error)) {

package/src/config.ts

@@ -199,7 +199,13 @@ export interface MastraMcpConfig {
 
 /** Configuration accepted by the Mastra AppKit plugin. */
 export interface MastraPluginConfig extends BasePluginConfig {
-  /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`; no env fallback. */
+  /**
+   * Run turns through Mastra's evented durable agent so execution continues
+   * after a browser disconnect and can be observed again by run id. Defaults
+   * to `true`.
+   */
+  backgroundTurns?: boolean;
+  /** AI SDK provider-options namespace. Defaults to `"openai"`; no env fallback. */
   providerId?: string;
   /**
    * PostgresStore for Mastra threads/messages. `true` reuses the
@@ -641,9 +647,14 @@ export interface MastraPluginConfig extends BasePluginConfig {
 export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
   type: "object",
   properties: {
+    backgroundTurns: {
+      type: "boolean",
+      description:
+        "Run turns through Mastra evented durable execution so they continue after browser disconnects and remain reconnectable by run id. Defaults to true.",
+    },
     providerId: {
       type: "string",
-      description: 'Mastra OpenAI-compatible provider id. Defaults to "databricks".',
+      description: 'AI SDK provider-options namespace. Defaults to "openai".',
     },
     remoteSkills: {
       type: ["string", "array", "object"],

package/src/model.ts

@@ -4,8 +4,8 @@
  * Each agent step calls {@link buildModel} with the active
  * `RequestContext`. The user stamped by `MastraServer` carries an
  * AppKit `WorkspaceClient`; we ask it for the workspace host and a
- * fresh bearer header, then point Mastra's OpenAI-compatible provider
- * at `/serving-endpoints` on that host.
+ * fresh bearer header, then construct a request-scoped Vercel AI SDK provider
+ * for the endpoint's native Databricks serving protocol.
  *
  * This module only adds the Mastra-specific glue. The actual model
  * selection - listing the workspace catalogue and resolving an
@@ -16,26 +16,21 @@
  * per-request override under {@link MASTRA_MODEL_OVERRIDE_KEY}, the
  * agent / plugin `modelId`, or `DATABRICKS_SERVING_ENDPOINT_NAME`),
  * pass the plugin's fuzzy / class / fallback knobs through, and wrap
- * the resolved id in the OpenAI-compatible provider config Mastra
- * expects. Catalogue fetches fail loud: network / auth errors
+ * the resolved id in the ProviderV4 model Mastra accepts. Catalogue fetches fail loud: network / auth errors
  * propagate so callers see the real SDK message.
  *
  * @module
  */
 
 import { getExecutionContext } from "@databricks/appkit";
-import { classes, invoke, policy, resolve } from "@dbx-tools/model";
-import { functionUtils, json, log, net } from "@dbx-tools/shared-core";
+import { classes, policy, resolve } from "@dbx-tools/model";
+import { createDatabricksLanguageModel } from "@dbx-tools/model-protocol/provider";
+import { log } from "@dbx-tools/shared-core";
 import { model, type ServingEndpointSummary } from "@dbx-tools/shared-model";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
 
 import { MASTRA_USER_KEY, type MastraPluginConfig, type User } from "./config.ts";
-import {
-  rewriteServingRequest,
-  rewriteServingResponseBody,
-  rewriteServingResponseStream,
-} from "./serving-sanitize.ts";
 import {
   MASTRA_MODEL_OVERRIDE_KEY,
   MASTRA_RESOLVED_MODEL_KEY,
@@ -133,7 +128,6 @@ export async function buildModel(
   requestContext: RequestContext,
   overrides: BuildModelOverrides = {},
 ): Promise<MastraModelConfig> {
-  void setupFetchInterceptor();
   // The chat path stamps the AppKit user on the request context via
   // `MastraServer`. The MCP transport routes don't thread that context
   // into tool execution, so fall back to the ambient execution context
@@ -145,11 +139,6 @@ export async function buildModel(
   const host = (await clientConfig.getHost()).toString();
   const headers = new Headers();
   await clientConfig.authenticate(headers);
-  // The OpenAI Node SDK appends paths like `/chat/completions` to whatever
-  // URL we hand it. Drop the trailing slash so the resulting URL stays
-  // well-formed (`/serving-endpoints/chat/completions`).
-  const url = new URL("/serving-endpoints", host).toString().replace(/\/$/, "");
-
   const logger = log.logger(config);
   const serving = resolveServingConfig(config);
   const override = serving.allowOverride
@@ -174,98 +163,11 @@ export async function buildModel(
   requestContext.set(MASTRA_RESOLVED_MODEL_KEY, modelId);
   recordActiveTraceModel(modelId);
 
-  return {
-    providerId: config.providerId ?? "databricks",
+  return createDatabricksLanguageModel({
     modelId,
-    url,
+    protocol: servingApi(modelId),
+    host,
     headers: Object.fromEntries(headers.entries()),
-    api: servingApi(modelId),
-  };
-}
-
-/** Chat Completions route whose provider-specific wire shapes are normalized here. */
-const CHAT_COMPLETIONS_PATH = `/${invoke.CHAT_COMPLETIONS_PATH}`;
-
-/**
- * Install a single shared `globalThis.fetch` wrapper for Chat Completions
- * requests. The wrapper does three things:
- *
- *   1. Rewrites outgoing JSON from either `init.body` or a `Request` to repair
- *      provider-specific request constraints (see {@link rewriteServingRequest}
- *      in `./serving-sanitize.js`).
- *   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
- *      4xx debugging doesn't have to fight AI SDK's `[Array]`
- *      formatter.
- *   3. Repairs buffered and streaming responses where a provider returns
- *      `choices[].message.content` or `choices[].delta.content` as a parts
- *      array that the AI SDK's OpenAI schema rejects.
- *
- * Safe to call from any hot path: {@link functionUtils.memoize} ensures
- * the wrapper is installed at most once per process, so subsequent
- * calls are a no-op even when {@link buildModel} fires on every agent
- * step.
- */
-const setupFetchInterceptor = functionUtils.memoize((): void => {
-  globalThis.fetch = createServingFetchInterceptor(globalThis.fetch.bind(globalThis));
-});
-
-/** Build the serving fetch wrapper; exported for transport-level regression tests. */
-export function createServingFetchInterceptor(original: typeof fetch): typeof fetch {
-  const logger = log.logger("mastra/llm");
-  return (async (input, init) => {
-    const url = net.urlBuilder(input);
-    const method = init?.method ?? (input instanceof Request ? input.method : "GET");
-    if (!url || url.pathname !== CHAT_COMPLETIONS_PATH || method.toUpperCase() !== "POST") {
-      return original(input, init);
-    }
-    const rewritten = await rewriteServingRequest(input, init);
-    const parsed = json.parse<unknown>(rewritten.body);
-    logger.debug(
-      "POST",
-      parsed === undefined
-        ? { url: url.toString(), bodyType: "non-JSON" }
-        : { url: url.toString(), body: parsed },
-    );
-    const response = await original(rewritten.input, rewritten.init);
-    return repairServingResponse(response);
-  }) as typeof globalThis.fetch;
-}
-
-/**
- * Rewrite a serving response whose body needs repair, leaving unsupported
- * content types byte-identical.
- *
- * SSE remains a live stream: a TransformStream repairs complete `data:` lines
- * as bytes arrive and preserves partial lines across network chunks. JSON is
- * buffered through the existing response-body repair. A non-JSON/non-SSE body
- * is returned untouched so the caller still sees the original response.
- */
-async function repairServingResponse(response: Response): Promise<Response> {
-  const contentType = response.headers.get("content-type") ?? "";
-  if (contentType.includes("text/event-stream") && response.body) {
-    return rebuildServingResponse(response, rewriteServingResponseStream(response.body));
-  }
-  if (!contentType.includes("application/json")) return response;
-
-  const body = await response.clone().text();
-  const rewritten = rewriteServingResponseBody(body);
-  if (rewritten === body) return response;
-  return rebuildServingResponse(response, rewritten);
-}
-
-/** Rebuild a transformed response without stale byte-length/encoding headers. */
-function rebuildServingResponse(
-  response: Response,
-  body: string | ReadableStream<Uint8Array>,
-): Response {
-  // `content-length` / `content-encoding` describe the ORIGINAL bytes, so they
-  // are dropped: the rewritten body is a different length and already decoded.
-  const headers = new Headers(response.headers);
-  headers.delete("content-length");
-  headers.delete("content-encoding");
-  return new Response(body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
+    providerName: config.providerId ?? "openai",
   });
 }

package/src/monty-sandbox.ts

@@ -9,15 +9,16 @@
  * @module
  */
 
+import { availableParallelism } from "node:os";
 import { configUtils } from "@dbx-tools/core";
 import { errorUtils, functionUtils, log } from "@dbx-tools/shared-core";
-import { availableParallelism } from "node:os";
-import type {
-  CommandResult,
-  ExecuteCommandOptions,
-  SandboxInfo,
+import {
+  MastraSandbox,
+  type CommandResult,
+  type ExecuteCommandOptions,
+  type ProviderStatus,
+  type SandboxInfo,
 } from "@mastra/core/workspace";
-import { MastraSandbox, type ProviderStatus } from "@mastra/core/workspace";
 import type { CheckoutOptions, Monty, MontyCrashedError, MontySession } from "@pydantic/monty";
 
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;

package/src/plugin.ts

@@ -458,6 +458,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
       agents: Object.keys(this.built?.agents ?? {}),
       feedbackEnabled: this.feedbackEnabled(),
+      backgroundTurns: this.config.backgroundTurns !== false,
       // In `service-principal` mode the chat works for any caller who can open
       // the app, so a UI that hides chat behind an OBO-token probe should show
       // it regardless. `"user"` mode keeps the OBO-gated behavior.
@@ -1190,6 +1191,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     this.logger.info("ready", {
       agents: Object.keys(this.built.agents),
       defaultAgent: this.built.defaultAgentId,
+      backgroundTurns: this.config.backgroundTurns !== false,
       apiAccess: this.config.apiAccess ?? "scoped",
       mcp: this.mcp ? `${this.basePath}${this.mcp.httpPath}` : "off",
       lakebase: memoryBuilder !== undefined,