@dbx-tools/appkit-mastra 0.9.140 → 0.9.143

package/src/agents.ts

@@ -45,10 +45,18 @@ import { createCodeMode, createTool } from "@mastra/core/tools";
 import type { Workspace } from "@mastra/core/workspace";
 import { createSkillTools, createWorkspaceTools } from "@mastra/core/workspace";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
-import { QuickJsCodeModeTransport } from "@mastra/quickjs";
 
 import { buildRenderDataTool } from "./chart.ts";
-import type { MastraPluginConfig } from "./config.ts";
+import type {
+  MastraCodeModeConfig,
+  MastraCodeModeTransport,
+  MastraPluginConfig,
+} from "./config.ts";
+import {
+  buildFollowUpSuggestionsProcessor,
+  buildSuggestFollowUpsTool,
+  resolveFollowUpSuggestionsConfig,
+} from "./follow-up-suggestions.ts";
 import { buildGenieToolkitProvider, resolveGenieSpaces } from "./genie.ts";
 import { withRequestMemoryScope, type MemoryBuilder } from "./memory.ts";
 import { buildModel, RESPONSES_PROVIDER_OPTIONS } from "./model.ts";
@@ -64,7 +72,28 @@ import {
 } from "./workspaces.ts";
 
 const codeModeLogger = log.logger("mastra/code-mode");
-let resolvedCodeModeTransport: Promise<CodeModeTransport> | undefined;
+const ISOLATED_VM_PACKAGE = "@mastra/isolated-vm";
+const QUICKJS_PACKAGE = "@mastra/quickjs";
+let isolatedVmDependency: Promise<typeof import("@mastra/isolated-vm")> | undefined;
+let quickJsDependency: Promise<typeof import("@mastra/quickjs")> | undefined;
+
+type NormalizedCodeModeConfig = MastraCodeModeConfig;
+
+interface ResolvedCodeModeConfig {
+  readonly id?: string;
+  readonly timeout?: number;
+  readonly provider: Exclude<MastraCodeModeTransport, "auto">;
+  readonly transport: CodeModeTransport;
+}
+
+type CodeModeFailureCategory =
+  "unsupported-runtime" | "dependency-unavailable" | "construction-failed";
+
+interface CodeModeFailure {
+  readonly category: CodeModeFailureCategory;
+  readonly error?: Error;
+  readonly provider: Exclude<MastraCodeModeTransport, "auto">;
+}
 
 /** Return whether this boot environment matches isolated-vm's supported app shape. */
 function supportsIsolatedVmTransport(): boolean {
@@ -77,6 +106,36 @@ function supportsIsolatedVmTransport(): boolean {
   return [...process.execArgv, ...nodeOptions].includes("--no-node-snapshot");
 }
 
+/** Return whether the current runtime satisfies QuickJS' published engine floor. */
+function supportsQuickJsTransport(): boolean {
+  if (process.versions.bun) return true;
+  if (process.release.name !== "node") return false;
+  const [majorText, minorText] = process.versions.node.split(".");
+  const major = Number.parseInt(majorText ?? "", 10);
+  const minor = Number.parseInt(minorText ?? "", 10);
+  return (
+    Number.isFinite(major) &&
+    Number.isFinite(minor) &&
+    (major > 20 || (major === 20 && minor >= 19))
+  );
+}
+
+/** Import the optional native transport at most once for this process. */
+function loadIsolatedVmDependency(): Promise<typeof import("@mastra/isolated-vm")> {
+  isolatedVmDependency ??= import(/* @vite-ignore */ ISOLATED_VM_PACKAGE) as Promise<
+    typeof import("@mastra/isolated-vm")
+  >;
+  return isolatedVmDependency;
+}
+
+/** Import the optional portable transport at most once for this process. */
+function loadQuickJsDependency(): Promise<typeof import("@mastra/quickjs")> {
+  quickJsDependency ??= import(/* @vite-ignore */ QUICKJS_PACKAGE) as Promise<
+    typeof import("@mastra/quickjs")
+  >;
+  return quickJsDependency;
+}
+
 /**
  * Tool record accepted by every Mastra `Agent.tools` field and by the
  * `tools(plugins)` callback on {@link MastraAgentDefinition}.
@@ -607,26 +666,125 @@ function appendInstructionBlock(instructions: AgentInstructions, block: string):
   return [instructions, { role: "system", content: block }] as AgentInstructions;
 }
 
-/** Resolve one native Code Mode transport during plugin startup. */
-function codeModeTransport(): Promise<CodeModeTransport> {
-  resolvedCodeModeTransport ??= (async () => {
+/** Normalize the public Code Mode shorthand into one startup configuration. */
+function normalizeCodeModeConfig(
+  codeMode: MastraPluginConfig["codeMode"],
+): NormalizedCodeModeConfig | undefined {
+  if (codeMode === undefined || codeMode === false) return undefined;
+  return typeof codeMode === "string" ? { transport: codeMode } : codeMode;
+}
+
+/** Try one optional Code Mode transport without applying fallback policy. */
+async function tryCodeModeTransport(
+  provider: Exclude<MastraCodeModeTransport, "auto">,
+): Promise<ResolvedCodeModeConfig | CodeModeFailure> {
+  if (provider === "isolated-vm") {
     if (!supportsIsolatedVmTransport()) {
-      codeModeLogger.info("transport selected", { provider: "quickjs" });
-      return new QuickJsCodeModeTransport();
+      return { category: "unsupported-runtime", provider };
     }
+    let module: typeof import("@mastra/isolated-vm");
     try {
-      const { IsolatedVmCodeModeTransport } = await import("@mastra/isolated-vm");
-      const transport = new IsolatedVmCodeModeTransport();
-      codeModeLogger.info("transport selected", { provider: "isolated-vm" });
-      return transport;
+      module = await loadIsolatedVmDependency();
     } catch (caught) {
-      codeModeLogger.warn("isolated-vm unavailable; using QuickJS", {
+      return {
+        category: "dependency-unavailable",
         error: errorUtils.toError(caught),
-      });
-      return new QuickJsCodeModeTransport();
+        provider,
+      };
     }
-  })();
-  return resolvedCodeModeTransport;
+    try {
+      return { provider, transport: new module.IsolatedVmCodeModeTransport() };
+    } catch (caught) {
+      return {
+        category: "construction-failed",
+        error: errorUtils.toError(caught),
+        provider,
+      };
+    }
+  }
+
+  if (!supportsQuickJsTransport()) {
+    return { category: "unsupported-runtime", provider };
+  }
+  let module: typeof import("@mastra/quickjs");
+  try {
+    module = await loadQuickJsDependency();
+  } catch (caught) {
+    return {
+      category: "dependency-unavailable",
+      error: errorUtils.toError(caught),
+      provider,
+    };
+  }
+  try {
+    return { provider, transport: new module.QuickJsCodeModeTransport() };
+  } catch (caught) {
+    return {
+      category: "construction-failed",
+      error: errorUtils.toError(caught),
+      provider,
+    };
+  }
+}
+
+function isCodeModeFailure(
+  result: ResolvedCodeModeConfig | CodeModeFailure,
+): result is CodeModeFailure {
+  return "category" in result;
+}
+
+/** Produce the actionable startup error for an explicitly required transport. */
+function requiredCodeModeError(failure: CodeModeFailure): ConfigurationError {
+  const runtime = process.versions.bun
+    ? `Bun ${process.versions.bun}`
+    : `${process.release.name} ${process.versions.node}`;
+  const install = `bun add ${failure.provider === "isolated-vm" ? ISOLATED_VM_PACKAGE : QUICKJS_PACKAGE}`;
+  const reason =
+    failure.category === "unsupported-runtime"
+      ? `is not supported by ${runtime}`
+      : failure.category === "dependency-unavailable"
+        ? "could not be loaded"
+        : "could not be initialized";
+  return new ConfigurationError(
+    `mastra: codeMode transport "${failure.provider}" ${reason}. Install the optional transport with \`${install}\` and use a supported runtime.`,
+    failure.error ? { cause: failure.error } : undefined,
+  );
+}
+
+/** Resolve the configured optional transport once during plugin startup. */
+async function resolveCodeModeConfig(
+  codeMode: MastraPluginConfig["codeMode"],
+): Promise<ResolvedCodeModeConfig | undefined> {
+  const config = normalizeCodeModeConfig(codeMode);
+  if (!config) return undefined;
+
+  const providers: readonly Exclude<MastraCodeModeTransport, "auto">[] =
+    config.transport === "auto" ? ["isolated-vm", "quickjs"] : [config.transport];
+  const failures: CodeModeFailure[] = [];
+  for (const provider of providers) {
+    const result = await tryCodeModeTransport(provider);
+    if (!isCodeModeFailure(result)) {
+      codeModeLogger.info("transport selected", { provider });
+      return { ...result, id: config.id, timeout: config.timeout };
+    }
+    failures.push(result);
+    if (config.transport !== "auto") throw requiredCodeModeError(result);
+    const fields = {
+      category: result.category,
+      provider,
+      ...(result.error ? { error: result.error } : {}),
+    };
+    if (result.category === "unsupported-runtime") {
+      codeModeLogger.info("automatic transport unsupported", fields);
+    } else {
+      codeModeLogger.warn("automatic transport unavailable", fields);
+    }
+  }
+
+  codeModeLogger.info("automatic Code Mode disabled", {
+    reasons: failures.map(({ category, provider }) => ({ category, provider })),
+  });
+  return undefined;
 }
 
 type CodeModeResolver<TRequestContext extends Record<string, unknown> | unknown = unknown> = (
@@ -640,12 +798,11 @@ type CodeModeResolver<TRequestContext extends Record<string, unknown> | unknown
 
 /** Build request-scoped native Code Mode over all executable context tools. */
 async function buildCodeMode<TRequestContext extends Record<string, unknown> | unknown>(
-  config: MastraPluginConfig,
+  config: ResolvedCodeModeConfig,
   tools: MastraTools,
   workspace: Workspace | undefined,
   requestContext: RequestContext<TRequestContext>,
 ): Promise<ReturnType<typeof createCodeMode> | undefined> {
-  if (config.codeMode === false) return undefined;
   const workspaceTools = workspace
     ? await createWorkspaceTools(workspace, { requestContext, workspace })
     : {};
@@ -660,10 +817,13 @@ async function buildCodeMode<TRequestContext extends Record<string, unknown> | u
     ),
   ) as ToolsInput;
   if (Object.keys(executableTools).length === 0) return undefined;
-  const options = typeof config.codeMode === "object" ? config.codeMode : {};
   const codeMode = createCodeMode(
-    { tools: executableTools, ...options },
-    await codeModeTransport(),
+    {
+      tools: executableTools,
+      ...(config.id !== undefined ? { id: config.id } : {}),
+      ...(config.timeout !== undefined ? { timeout: config.timeout } : {}),
+    },
+    config.transport,
   );
   if (!("mastra_workspace_read_file" in workspaceTools)) return codeMode;
   return {
@@ -674,11 +834,11 @@ async function buildCodeMode<TRequestContext extends Record<string, unknown> | u
 
 /** Resolve Code Mode lazily so workspace and dynamic tool policy follow each request. */
 function codeModeResolver<TRequestContext extends Record<string, unknown> | unknown>(
-  config: MastraPluginConfig,
+  config: ResolvedCodeModeConfig | undefined,
   tools: MastraTools,
   workspace: Workspace | undefined,
 ): CodeModeResolver<TRequestContext> | undefined {
-  if (config.codeMode === false) return undefined;
+  if (!config) return undefined;
   return ({ requestContext }) => buildCodeMode(config, tools, workspace, requestContext);
 }
 
@@ -731,6 +891,7 @@ export async function buildAgents(opts: {
     standardSkills = [],
     excludedWorkspaceSkillNames = [],
   } = opts;
+  const codeModeConfig = await resolveCodeModeConfig(config.codeMode);
   const definitions = resolveDefinitions(config);
   const ids = Object.keys(definitions);
   const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
@@ -742,9 +903,14 @@ export async function buildAgents(opts: {
   // user can shadow either by including a same-named tool in their own
   // `config.tools` or per-agent `tools`. Merge order is
   // `system -> standard skills -> user-ambient -> per-agent`, last write wins.
+  const followUps = resolveFollowUpSuggestionsConfig(config.followUpSuggestions);
+  const followUpProcessor = buildFollowUpSuggestionsProcessor(config);
   const systemTools: MastraTools = {
     render_data: buildRenderDataTool(config),
     summarize: buildSummarizeTool(config),
+    ...(followUps?.exposeTool && followUps.mode !== "genie"
+      ? { suggest_follow_ups: buildSuggestFollowUpsTool(config) }
+      : {}),
   };
   const standardSkillTools =
     standardSkills.length > 0 ? createSkillTools(resolveAgentSkills([...standardSkills])) : {};
@@ -798,7 +964,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);
-    const resolveCodeMode = codeModeResolver(config, tools, workspace);
+    const resolveCodeMode = codeModeResolver(codeModeConfig, tools, workspace);
     const agent = new Agent({
       id,
       name: def.name ?? id,
@@ -832,6 +998,7 @@ export async function buildAgents(opts: {
       inputProcessors: [...inputProcessors, ...workspaceSkillInputProcessors(workspace, config)],
       outputProcessors: [
         toolErrorLoggingProcessor(log),
+        ...(followUpProcessor ? [followUpProcessor] : []),
         ...outputProcessorFactories.flatMap((factory) => {
           const processor = factory(id);
           return processor ? [processor] : [];

package/src/chat.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import { errorUtils, log } from "@dbx-tools/shared-core";
+import { errorUtils, log, object } from "@dbx-tools/shared-core";
 import { routes } from "@dbx-tools/shared-mastra";
 import {
   isStaleMastraResumeError,
@@ -15,6 +15,14 @@ import { isEventedAgent } from "@mastra/core/agent/durable";
 import { registerApiRoute } from "@mastra/core/server";
 import { createUIMessageStreamResponse } from "ai";
 
+import type { MastraPluginConfig } from "./config.ts";
+import {
+  buildFollowUpSuggestionsTransform,
+  FOLLOW_UP_NATIVE_QUESTIONS_KEY,
+  FOLLOW_UP_RUN_ID_KEY,
+  FOLLOW_UP_USER_TEXT_KEY,
+  resolveFollowUpSuggestionsConfig,
+} from "./follow-up-suggestions.ts";
 import { withRequestMemoryScope } from "./memory.ts";
 
 const logger = log.logger("mastra/chat");
@@ -24,8 +32,31 @@ export function agentAbortSignal(agent: unknown, signal: AbortSignal): AbortSign
   return isEventedAgent(agent) ? undefined : signal;
 }
 
+function latestUserText(value: unknown): string | undefined {
+  if (!Array.isArray(value)) return undefined;
+  for (let index = value.length - 1; index >= 0; index -= 1) {
+    const message = value[index];
+    if (!object.isRecord(message) || message.role !== "user") continue;
+    if (typeof message.content === "string" && message.content.trim()) {
+      return message.content.trim();
+    }
+    if (!Array.isArray(message.parts)) continue;
+    const text = message.parts
+      .flatMap((part) =>
+        object.isRecord(part) && part.type === "text" && typeof part.text === "string"
+          ? [part.text]
+          : [],
+      )
+      .join("\n")
+      .trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
 /** Register detached chat, durable observation, and explicit abort routes. */
-export function agentChatRoutes() {
+export function agentChatRoutes(config: MastraPluginConfig = {}) {
+  const followUps = resolveFollowUpSuggestionsConfig(config.followUpSuggestions);
   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`;
@@ -56,6 +87,12 @@ export function agentChatRoutes() {
         }
         const status = rawStatus as "draft" | "published" | undefined;
         const abortSignal = agentAbortSignal(mastra.getAgentById(agentId), context.req.raw.signal);
+        const runId =
+          typeof params.runId === "string" && params.runId ? params.runId : crypto.randomUUID();
+        const userText = latestUserText(params.messages);
+        if (userText) requestContext.setRaw(FOLLOW_UP_USER_TEXT_KEY, userText);
+        requestContext.setRaw(FOLLOW_UP_NATIVE_QUESTIONS_KEY, []);
+        requestContext.setRaw(FOLLOW_UP_RUN_ID_KEY, runId);
         const stream = await handleChatStream({
           mastra,
           agentId,
@@ -67,11 +104,15 @@ export function agentChatRoutes() {
           params: withRequestMemoryScope(
             {
               ...params,
+              runId,
               requestContext,
               ...(abortSignal ? { abortSignal } : {}),
             },
             requestContext,
           ),
+          ...(followUps && followUps.mode !== "genie"
+            ? { experimentalTransform: buildFollowUpSuggestionsTransform(runId) }
+            : {}),
           version: "v7",
           sendReasoning: true,
           sendSources: true,
@@ -97,6 +138,9 @@ export function agentChatRoutes() {
         const observed = await agent.observe(runId);
         const stream = toAISdkStream(observed.output, {
           from: "agent",
+          ...(followUps && followUps.mode !== "genie"
+            ? { experimentalTransform: buildFollowUpSuggestionsTransform(runId) }
+            : {}),
           version: "v7",
           sendReasoning: true,
           sendSources: true,

package/src/config.ts

@@ -166,8 +166,13 @@ export interface MastraWorkspaceSkillsConfig {
   ttlMs?: number;
 }
 
+/** Native Mastra Code Mode execution transport. */
+export type MastraCodeModeTransport = "auto" | "isolated-vm" | "quickjs";
+
 /** Native Mastra Code Mode settings for sandboxed multi-tool orchestration. */
 export interface MastraCodeModeConfig {
+  /** Code Mode execution transport. */
+  transport: MastraCodeModeTransport;
   /** Generated orchestration tool id. Defaults to `execute_typescript`. */
   id?: string;
   /** Maximum orchestration program runtime in milliseconds. Defaults to 30 seconds. */
@@ -213,6 +218,18 @@ export interface MastraMcpConfig {
   extraTools?: MastraTools;
 }
 
+/** Optional post-turn follow-up suggestion policy. */
+export interface FollowUpSuggestionsConfig {
+  /** Native Genie only, ChatFast generated only, or automatic selection when true. */
+  mode: true | "generated" | "genie";
+  /** Maximum questions emitted for one turn. Defaults to 3, maximum 10. */
+  limit?: number;
+  /** Tail-generation timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Also expose the generator as an explicitly callable agent tool. */
+  exposeTool?: boolean;
+}
+
 /** Configuration accepted by the Mastra AppKit plugin. */
 export interface MastraPluginConfig extends BasePluginConfig {
   /**
@@ -237,14 +254,14 @@ export interface MastraPluginConfig extends BasePluginConfig {
   memory?: boolean | MastraMemoryConfig;
   /**
    * Expose executable tools available to the current request through native
-   * Mastra Code Mode. Defaults on whenever the request has executable tools.
-   * The plugin selects Mastra's isolated-vm transport once during startup and
-   * falls back to Mastra QuickJS when the native transport is unavailable.
-   * These transports do not execute through the workspace command sandbox;
-   * SSH is used only when an exposed SSH-backed tool is called. Set `false` to
-   * opt out.
+   * Mastra Code Mode. Defaults to `false`. `auto` selects an installed,
+   * runtime-supported optional transport during startup and leaves Code Mode
+   * disabled when none is available. Explicit transport values fail startup
+   * when their optional dependency or runtime support is unavailable. These
+   * transports do not execute through the workspace command sandbox; SSH is
+   * used only when an exposed SSH-backed tool is called.
    */
-  codeMode?: boolean | MastraCodeModeConfig;
+  codeMode?: false | MastraCodeModeTransport | MastraCodeModeConfig;
   /**
    * Sandbox for auto-created agent workspaces. Defaults to Monty. `false`
    * disables command execution; `true` or `"monty"` selects Monty; an explicit
@@ -503,6 +520,12 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * to drill deep into a dataset within a single turn.
    */
   agentMaxSteps?: number;
+  /**
+   * Optional post-turn follow-up questions. `true` selects sources
+   * automatically; `"generated"` or `"genie"` pins one source; `false` or
+   * omission disables follow-ups.
+   */
+  followUpSuggestions?: false | true | "generated" | "genie" | FollowUpSuggestionsConfig;
   /**
    * Wire Mastra spans into AppKit's global OTel pipeline via
    * `@mastra/otel-bridge`.
@@ -700,9 +723,10 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
         "PgVector store for Mastra semantic recall. `true` captures the `lakebase` plugin's existing service-principal pool; an object opens a separately configured store. Auto-enabled when the `lakebase` plugin is registered.",
     },
     codeMode: {
-      type: ["boolean", "object"],
+      type: ["boolean", "string", "object"],
+      default: false,
       description:
-        "Expose all executable tools available to the current request through native Mastra Code Mode for TypeScript batching, aggregation, and arithmetic. The plugin uses Mastra isolated-vm with the existing QuickJS fallback; neither transport runs through the workspace command sandbox, so SSH is used only when an SSH-backed tool is called. False disables it.",
+        'Expose executable request tools through native Mastra Code Mode for TypeScript batching, aggregation, and arithmetic. Defaults to false. Use "auto" to select an installed supported optional transport or stay disabled, "isolated-vm" to require the native transport, "quickjs" to require the portable transport, or an object with transport plus id and timeout. Neither transport runs through the workspace command sandbox.',
     },
     sandbox: {
       type: ["boolean", "string", "object"],
@@ -780,6 +804,11 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
       description:
         "Maximum LLM steps each agent gets per turn (a tool call and the final reply each consume one). Defaults to 25.",
     },
+    followUpSuggestions: {
+      type: ["boolean", "string", "object"],
+      description:
+        'Optional post-turn follow-ups. True selects sources automatically; "generated" or "genie" pins one source; an object adds a limit, timeout, and optional tool exposure. Defaults off.',
+    },
     stripStaleCharts: {
       type: "boolean",
       description: