@dbx-tools/appkit-mastra 0.1.33 → 0.1.35

package/dist/src/genie.d.ts

@@ -33,6 +33,7 @@
  * `instructions` when you want the canonical "how to drive the
  * Genie tools" guidance.
  */
+import { WorkspaceClient } from "@databricks/sdk-experimental";
 import { appkitUtils } from "@dbx-tools/shared";
 import type { MastraTools } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
@@ -153,3 +154,20 @@ export declare function buildGenieToolkitProvider(opts: {
  * absent-plugin semantics) when neither source is configured.
  */
 export declare function hasAnyGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): boolean;
+/**
+ * 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 declare function collectSpaceSuggestions(opts: {
+    spaces: Record<string, GenieSpaceConfig>;
+    client: WorkspaceClient;
+    signal?: AbortSignal;
+    limit?: number;
+}): Promise<string[]>;

package/dist/src/genie.js

@@ -36,9 +36,9 @@
 import { CacheManager, genie } from "@databricks/appkit";
 import { ApiError, HttpError, WorkspaceClient } from "@databricks/sdk-experimental";
 import { ChartSchema, } from "@dbx-tools/appkit-mastra-shared";
-import { genieEventChat } from "@dbx-tools/genie";
+import { genieEventChat, genieSampleQuestions, getGenieSpace } from "@dbx-tools/genie";
 import {} 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 { MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
@@ -461,8 +461,15 @@ function buildSpaceDescriptionTool(opts) {
             const ctx = ctxRaw;
             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 } : {}),
@@ -489,8 +496,13 @@ function buildSpaceSerializedTool(opts) {
             const ctx = ctxRaw;
             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 };
         },
     });
@@ -893,3 +905,83 @@ export function buildGenieToolkitProvider(opts) {
 export function hasAnyGenieSpaces(config, context) {
     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();
+/** Read a space's cached questions, or `undefined` on miss / expiry. */
+function readSuggestionCache(spaceId) {
+    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, questions) {
+    _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) {
+    const limit = opts.limit ?? SUGGESTION_LIMIT;
+    const merged = [];
+    const seen = new Set();
+    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/dist/src/plugin.d.ts

@@ -109,6 +109,15 @@ export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
     };
     clientConfig(): Record<string, unknown>;
     injectRoutes(router: IAppRouter): void;
+    /**
+     * 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 fetchSuggestions;
     /**
      * Implementation backing the `data` embed resolver
      * (`GET /embed/data/:id`). Runs inside the AppKit user-context proxy so

package/dist/src/plugin.js

@@ -33,6 +33,7 @@ import { Mastra } from "@mastra/core/mastra";
 import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID } from "./agents.js";
 import { fetchChart } from "./chart.js";
+import { collectSpaceSuggestions, resolveGenieSpaces } from "./genie.js";
 import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { buildObservability } from "./observability.js";
@@ -174,6 +175,8 @@ export class MastraPlugin extends Plugin {
             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 ?? {}),
         };
@@ -266,12 +269,59 @@ export class MastraPlugin extends Plugin {
             })
                 .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, res) => {
+            const controller = new AbortController();
+            req.on("close", () => controller.abort());
+            this.userScopedSelf(req)
+                .fetchSuggestions(controller.signal)
+                .then((questions) => res.json({ questions }))
+                .catch((err) => {
+                // 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.
+     */
+    async fetchSuggestions(signal) {
+        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