@dbx-tools/appkit-mastra 0.1.33 → 0.1.35

package/package.json

@@ -9,13 +9,13 @@
     }
   },
   "name": "@dbx-tools/appkit-mastra",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17",
-    "@dbx-tools/appkit-mastra-shared": "0.1.33",
-    "@dbx-tools/genie": "0.1.33",
-    "@dbx-tools/genie-shared": "0.1.33",
-    "@dbx-tools/shared": "0.1.33",
+    "@dbx-tools/appkit-mastra-shared": "0.1.35",
+    "@dbx-tools/genie": "0.1.35",
+    "@dbx-tools/genie-shared": "0.1.35",
+    "@dbx-tools/shared": "0.1.35",
     "@mastra/ai-sdk": "^1",
     "@mastra/core": "^1",
     "@mastra/express": "^1",

package/src/genie.ts

@@ -41,15 +41,9 @@ import {
   type MinimalWriter,
   type StartedEvent,
 } from "@dbx-tools/appkit-mastra-shared";
-import { genieEventChat } from "@dbx-tools/genie";
+import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
 import { type GenieMessage } from "@dbx-tools/genie-shared";
-import {
-  apiUtils,
-  appkitUtils,
-  commonUtils,
-  logUtils,
-  stringUtils,
-} from "@dbx-tools/shared";
+import { appkitUtils, commonUtils, logUtils, stringUtils } from "@dbx-tools/shared";
 import type { RequestContext } from "@mastra/core/request-context";
 import { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import { createTool } from "@mastra/core/tools";
@@ -565,8 +559,15 @@ function buildSpaceDescriptionTool(opts: { spaceId: string; alias: string }) {
       const ctx = ctxRaw as ToolExecuteCtx;
       const { client } = requireClient(ctx, toolId);
       const signal = ctx?.abortSignal;
-      const apiCtx = signal ? apiUtils.toContext(signal) : undefined;
-      const space = await client.genie.getSpace({ space_id: spaceId }, apiCtx);
+      // Route through the package's central Genie space fetch. The
+      // description surface (title / description / warehouse id) lives
+      // on the directory-listing shape, so skip the larger
+      // `serialized_space` payload here.
+      const space = await getGenieSpace(spaceId, {
+        workspaceClient: client,
+        serialized: false,
+        ...(signal ? { context: signal } : {}),
+      });
       return {
         spaceId,
         ...(space.title ? { title: space.title } : {}),
@@ -594,8 +595,13 @@ function buildSpaceSerializedTool(opts: { spaceId: string; alias: string }) {
       const ctx = ctxRaw as ToolExecuteCtx;
       const { client } = requireClient(ctx, toolId);
       const signal = ctx?.abortSignal;
-      const apiCtx = signal ? apiUtils.toContext(signal) : undefined;
-      const space = await client.genie.getSpace({ space_id: spaceId }, apiCtx);
+      // Central Genie space fetch with the opt-in `serialized_space`
+      // blob (catalogs, tables, sample questions, prompts) that the
+      // typed SDK `getSpace` omits - the whole point of this tool.
+      const space = await getGenieSpace(spaceId, {
+        workspaceClient: client,
+        ...(signal ? { context: signal } : {}),
+      });
       return { space };
     },
   });
@@ -1044,3 +1050,92 @@ export function hasAnyGenieSpaces(
 ): boolean {
   return Object.keys(resolveGenieSpaces(config, context)).length > 0;
 }
+
+/* --------------------------- starter suggestions --------------------------- */
+
+/**
+ * Default cap on starter suggestions surfaced to the chat empty
+ * state. Sample-question lists can run long (10+ on a curated
+ * space); a handful of one-tap prompts reads better than a wall of
+ * buttons.
+ */
+const SUGGESTION_LIMIT = 6;
+
+/**
+ * How long a space's parsed sample questions stay cached. They're
+ * authored config that changes rarely, and the lookup is an extra
+ * REST round-trip per chat mount, so a few minutes of caching keeps
+ * the empty state instant on reload without going stale for long.
+ */
+const SUGGESTION_CACHE_TTL_MS = 10 * 60_000;
+
+/** Space-id -> cached sample questions with an absolute expiry. */
+const _suggestionCache = new Map<string, { questions: string[]; expires: number }>();
+
+/** Read a space's cached questions, or `undefined` on miss / expiry. */
+function readSuggestionCache(spaceId: string): string[] | undefined {
+  const entry = _suggestionCache.get(spaceId);
+  if (!entry) return undefined;
+  if (entry.expires <= Date.now()) {
+    _suggestionCache.delete(spaceId);
+    return undefined;
+  }
+  return entry.questions;
+}
+
+/** Cache a space's parsed questions for {@link SUGGESTION_CACHE_TTL_MS}. */
+function writeSuggestionCache(spaceId: string, questions: string[]): void {
+  _suggestionCache.set(spaceId, {
+    questions,
+    expires: Date.now() + SUGGESTION_CACHE_TTL_MS,
+  });
+}
+
+/**
+ * Collect the curated starter questions across every resolved Genie
+ * space, deduped and capped. Each space's `sample_questions` are
+ * fetched once (cached for {@link SUGGESTION_CACHE_TTL_MS}) via
+ * {@link getGenieSpace} + {@link genieSampleQuestions}, then merged in
+ * alias-iteration order so a single-space app surfaces that space's
+ * questions and a multi-space app round-trips breadth-first up to the
+ * cap. A per-space fetch failure degrades to "no questions for that
+ * space" (logged, not thrown) so one unreachable space never blanks
+ * the whole list. Returns `[]` when no spaces are configured.
+ */
+export async function collectSpaceSuggestions(opts: {
+  spaces: Record<string, GenieSpaceConfig>;
+  client: WorkspaceClient;
+  signal?: AbortSignal;
+  limit?: number;
+}): Promise<string[]> {
+  const limit = opts.limit ?? SUGGESTION_LIMIT;
+  const merged: string[] = [];
+  const seen = new Set<string>();
+
+  for (const { spaceId } of Object.values(opts.spaces)) {
+    let questions = readSuggestionCache(spaceId);
+    if (!questions) {
+      try {
+        const space = await getGenieSpace(spaceId, {
+          workspaceClient: opts.client,
+          ...(opts.signal ? { context: opts.signal } : {}),
+        });
+        questions = genieSampleQuestions(space);
+        writeSuggestionCache(spaceId, questions);
+      } catch (err) {
+        log.warn("suggestions:fetch-error", {
+          spaceId,
+          error: commonUtils.errorMessage(err),
+        });
+        questions = [];
+      }
+    }
+    for (const question of questions) {
+      if (seen.has(question)) continue;
+      seen.add(question);
+      merged.push(question);
+      if (merged.length >= limit) return merged;
+    }
+  }
+  return merged;
+}

package/src/plugin.ts

@@ -50,6 +50,7 @@ import type {
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.js";
 import { fetchChart } from "./chart.js";
 import type { MastraPluginConfig } from "./config.js";
+import { collectSpaceSuggestions, resolveGenieSpaces } from "./genie.js";
 import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { buildObservability } from "./observability.js";
@@ -209,6 +210,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       historyPath: `${basePath}/route/history`,
       historyPathTemplate: `${basePath}/route/history/:agentId`,
       embedPathTemplate: `${basePath}/embed/:type/:id`,
+      suggestionsPath: `${basePath}/suggestions`,
+      suggestionsPathTemplate: `${basePath}/suggestions/:agentId`,
       defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
       agents: Object.keys(this.built?.agents ?? {}),
     };
@@ -305,12 +308,60 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         .catch(next);
     });
 
+    // `GET /suggestions` (and `/suggestions/:agentId`) returns the
+    // curated starter questions for the agent's Genie space(s) - the
+    // author-configured `sample_questions`, surfaced as one-tap
+    // prompts on the chat empty state. Returns `{ questions: [] }`
+    // when no Genie space is wired so the client renders a bare
+    // empty state (no built-in example prompts). The `:agentId`
+    // segment is accepted for URL symmetry with the chat / history
+    // routes; Genie spaces are resolved per-plugin, not per-agent,
+    // so it doesn't change the result. OBO-scoped like the other
+    // data routes so the space lookup runs as the calling user.
+    const handleSuggestions = (req: express.Request, res: express.Response): void => {
+      const controller = new AbortController();
+      req.on("close", () => controller.abort());
+      this.userScopedSelf(req)
+        .fetchSuggestions(controller.signal)
+        .then((questions) => res.json({ questions }))
+        .catch((err: unknown) => {
+          // Suggestions are a non-critical enhancement; a lookup
+          // failure should leave the chat usable with a bare empty
+          // state rather than surfacing a 500. Log and degrade.
+          this.log.warn("suggestions:error", {
+            error: err instanceof Error ? err.message : String(err),
+          });
+          res.json({ questions: [] });
+        });
+    };
+    router.get("/suggestions", handleSuggestions);
+    router.get("/suggestions/:agentId", handleSuggestions);
+
     router.use("", (req, res, next) => {
       if (!this.mastraApp) return res.status(503).end();
       return this.userScopedSelf(req).mastraApp!(req, res, next);
     });
   }
 
+  /**
+   * Implementation backing the `/suggestions` route. Runs inside the
+   * AppKit user-context proxy so `getExecutionContext()` returns the
+   * OBO-scoped client. Resolves the plugin's Genie spaces and merges
+   * their curated `sample_questions` (see {@link collectSpaceSuggestions}).
+   * Returns `[]` when no Genie space is configured so the client
+   * shows a bare empty state instead of built-in example prompts.
+   */
+  private async fetchSuggestions(signal?: AbortSignal): Promise<string[]> {
+    const spaces = resolveGenieSpaces(this.config, this.context);
+    if (Object.keys(spaces).length === 0) return [];
+    const client = getExecutionContext().client;
+    return collectSpaceSuggestions({
+      spaces,
+      client,
+      ...(signal ? { signal } : {}),
+    });
+  }
+
   /**
    * Implementation backing the `data` embed resolver
    * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so