@dbx-tools/appkit-mastra 0.1.58 → 0.1.68

package/dist/src/config.d.ts

@@ -1,295 +0,0 @@
-/**
- * Plugin configuration types and shared `RequestContext` keys.
- *
- * Kept in a leaf module so `plugin.ts`, `server.ts`, `model.ts`, and
- * `memory.ts` can import them without creating a cycle.
- */
-import type { BasePluginConfig } from "@databricks/appkit";
-import type { appkitUtils } from "@dbx-tools/shared";
-import type { AgentConfig } from "@mastra/core/agent";
-import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
-import type { MastraAgentDefinition, MastraTools } from "./agents.js";
-import type { GenieSpacesConfig } from "./genie.js";
-/**
- * `RequestContext` key under which {@link MastraServer} stores the
- * resolved AppKit user. `model.ts` reads it to mint user-scoped
- * Databricks tokens.
- */
-export declare const MASTRA_USER_KEY = "mastra__user";
-/**
- * `RequestContext` keys for AppKit user metadata stamped by
- * {@link MastraServer}. Surfaced as trace metadata via
- * {@link TRACE_REQUEST_CONTEXT_KEYS} so traces are filterable by who
- * issued the request without leaking the full user object.
- */
-export declare const MASTRA_USER_NAME_KEY = "mastra__userName";
-export declare const MASTRA_USER_EMAIL_KEY = "mastra__userEmail";
-/**
- * `RequestContext` key for the per-HTTP-request id stamped by
- * {@link MastraServer}. Reads `X-Request-Id` from the incoming
- * headers when present (so an upstream load balancer / API gateway
- * can keep its trace correlation), falls back to a freshly minted
- * UUID. Echoed back on the response and surfaced on every span via
- * {@link TRACE_REQUEST_CONTEXT_KEYS} so logs and traces share a
- * join key.
- */
-export declare const MASTRA_REQUEST_ID_KEY = "mastra__requestId";
-/**
- * Canonical list of `RequestContext` keys we want Mastra to extract
- * as metadata on every observability span (agent runs, model calls,
- * tool invocations, workflow steps).
- *
- * Mirrors {@link https://mastra.ai/docs/observability/tracing/overview#automatic-metadata-from-requestcontext}:
- * passed verbatim into `Observability.configs[*].requestContextKeys`,
- * so any key listed here is read from `RequestContext` at trace
- * start and attached as scalar span metadata. Keep the set to plain
- * scalars - never include {@link MASTRA_USER_KEY} (it carries the
- * full AppKit execution context with a `WorkspaceClient` reference).
- *
- * Order is purely cosmetic; Mastra de-dupes internally.
- */
-export declare const TRACE_REQUEST_CONTEXT_KEYS: readonly string[];
-/** AppKit execution context plus the canonical user id. */
-export interface User {
-    id: string;
-    executionContext: appkitUtils.ExecutionContextLike;
-}
-/** PgVector config with an optional Mastra store id. */
-export type MastraMemoryConfig = PgVectorConfig & {
-    id?: string;
-};
-/** Configuration accepted by the Mastra AppKit plugin. */
-export interface MastraPluginConfig extends BasePluginConfig {
-    /** Mastra OpenAI-compatible provider id. Defaults to `"databricks"`. */
-    providerId?: string;
-    /**
-     * PostgresStore for Mastra threads/messages. `true` reuses the
-     * `lakebase` plugin's pool; an object opens a dedicated store.
-     */
-    storage?: boolean | PostgresStoreConfig;
-    /**
-     * PgVector store for Mastra memory recall. `true` reuses the
-     * `lakebase` plugin's pool; an object opens a dedicated store.
-     */
-    memory?: boolean | MastraMemoryConfig;
-    /**
-     * Code-defined agents. Accepts three shapes for convenience:
-     *
-     * - **Record**: `{ analyst: def, helper: def }` - keys become the
-     *   registered ids and the first key is the default.
-     * - **Single definition**: `def` - registered under
-     *   `slugify(def.name)` (or `"default"` when `name` is omitted) and
-     *   automatically marked as the default agent.
-     * - **Array**: `[def1, def2]` - each registered under
-     *   `slugify(def.name)` (or `agent_${i}` when `name` is omitted);
-     *   the first entry is the default.
-     *
-     * Each entry becomes a Mastra `Agent` reachable at
-     * `/api/<plugin>/route/chat/<id>` (the chat route also matches
-     * `:agentId`). When `agents` is omitted entirely, the plugin
-     * registers a single built-in `default` analyst so the bare
-     * `mastra()` call still mounts a working chat endpoint.
-     *
-     * @example Single-agent shorthand
-     * ```ts
-     * mastra({
-     *   agents: createAgent({ instructions: "..." }),
-     * });
-     * ```
-     *
-     * @example Array
-     * ```ts
-     * mastra({
-     *   agents: [
-     *     createAgent({ name: "analyst", instructions: "..." }),
-     *     createAgent({ name: "helper", instructions: "..." }),
-     *   ],
-     * });
-     * ```
-     *
-     * @example Record (explicit ids)
-     * ```ts
-     * mastra({
-     *   agents: {
-     *     analyst: createAgent({ instructions: "..." }),
-     *     helper: createAgent({ instructions: "..." }),
-     *   },
-     *   defaultAgent: "analyst",
-     * });
-     * ```
-     */
-    agents?: Record<string, MastraAgentDefinition> | MastraAgentDefinition | MastraAgentDefinition[];
-    /**
-     * Ambient tools spread into every registered agent's tools record;
-     * per-agent tools win on key collision. Use for a small shared
-     * library; for per-agent tools set `agents[id].tools` instead.
-     */
-    tools?: MastraTools;
-    /**
-     * Agent id used when the client doesn't specify one (the bare,
-     * un-suffixed history / suggestions routes resolve to it).
-     * Defaults to the first key in `agents` (or `"default"` when
-     * `agents` is omitted). Must match an id in `agents` when both are
-     * set; a mismatch throws at setup with the available candidates.
-     */
-    defaultAgent?: string;
-    /**
-     * Plugin-level default model applied to every agent that omits its
-     * own `model`. Mirrors AppKit's `agents({ defaultModel })`.
-     *
-     * - `string`: shorthand for "use the OBO auto-resolver but swap the
-     *   `modelId`" (e.g. `"databricks-claude-sonnet-4-6"`).
-     * - Any other Mastra `DynamicArgument<MastraModelConfig>`: passed
-     *   through verbatim. Use this when you need full control over auth
-     *   or `providerId`.
-     *
-     * Resolution order per agent: `def.model` → `defaultModel` →
-     * built-in `/serving-endpoints` resolver.
-     */
-    defaultModel?: AgentConfig["model"] | string;
-    /**
-     * Allow loose model names (`"claude sonnet"`) to be fuzzy-matched
-     * against the workspace's Model Serving endpoints. Defaults to
-     * `true`; set `false` to require exact endpoint names everywhere.
-     */
-    modelFuzzyMatch?: boolean;
-    /**
-     * Fuse.js score threshold for the fuzzy matcher (0 = exact match,
-     * 1 = anything matches). Defaults to `0.4`. Lower values reject
-     * loose matches; raise it if you have a sprawling endpoint
-     * catalogue with similar-looking names.
-     */
-    modelFuzzyThreshold?: number;
-    /**
-     * TTL for the in-memory serving-endpoints list cache, in
-     * milliseconds. Defaults to 5 minutes. The cache is per workspace
-     * host and shared across users; concurrent callers coalesce on a
-     * single in-flight fetch.
-     */
-    modelCacheTtlMs?: number;
-    /**
-     * Allow clients to override the active model per request via the
-     * `X-Mastra-Model` header, `?model=` query string, or `model` body
-     * field. Defaults to `true`. Disable when running multi-tenant
-     * where untrusted clients shouldn't pick the backing endpoint.
-     */
-    modelOverride?: boolean;
-    /**
-     * Priority-ordered list of endpoint names tried *first* when no
-     * agent / plugin / env / request-override model id is set, ahead of
-     * the dynamic score-classified catalogue. The resolver picks the
-     * first id that is actually present in the workspace's
-     * `/serving-endpoints` listing.
-     *
-     * When unset, resolution is driven by the live Foundation Model API
-     * `quality` / `speed` / `cost` scores: endpoints are classified into
-     * chat classes (`classifyEndpoints`) and walked best-first
-     * (ChatThinking -> ChatBalanced -> ChatFast), with the small built-in
-     * `FALLBACK_MODEL_IDS` list as the floor when the catalogue can't be
-     * read. Set this to
-     * pin a regulated workspace to an approved subset, or to put custom
-     * endpoints in front of the auto-classified catalogue.
-     */
-    defaultModelFallbacks?: readonly string[];
-    /**
-     * When `true` (default), every agent gets a built-in input
-     * processor that strips `chartId` fields from prior assistant
-     * tool-invocation results before they reach the model. This
-     * prevents the model from reusing turn-scoped chartIds it sees
-     * in memory recall (which would leave `[chart:<id>]` markers
-     * pointing at writer events that no longer exist).
-     *
-     * Set to `false` to opt out - useful if a non-default agent
-     * needs full visibility into prior chartIds (e.g. an audit
-     * agent reasoning about chart lineage).
-     */
-    stripStaleCharts?: boolean;
-    /**
-     * Style guardrails appended to every agent's `instructions` to curb
-     * common LLM-isms (em dashes, emojis, sycophantic openers, throwaway
-     * closers, excessive hedging).
-     *
-     * - `undefined` (default): use the built-in
-     *   `DEFAULT_STYLE_INSTRUCTIONS` from `agents.ts`.
-     * - `string`: replace the default with the supplied block.
-     * - `false`: disable entirely (agents see only their bespoke
-     *   `instructions`).
-     *
-     * Appended (not prepended) so the agent's role and rules come first
-     * and the style block leans on the model's recency bias.
-     */
-    styleInstructions?: string | false;
-    /**
-     * Genie spaces this plugin's agents can delegate to. One Mastra
-     * tool is registered per alias (`genie` for the well-known
-     * `default` alias, `genie_<alias>` otherwise). Each tool spins
-     * up a per-question Genie sub-agent that runs Databricks
-     * "agent mode" against the space, broadcasts wire events to the
-     * UI, fetches statement rows for non-empty results, and returns
-     * a `(string | data | chart)[]` summary the host UI renders
-     * inline.
-     *
-     * Entries accept either a full {@link GenieSpaceConfig} object
-     * or a bare `space_id` string when no extras are needed:
-     *
-     * ```ts
-     * mastra({
-     *   genieSpaces: {
-     *     default: "01ef0d3c0e1b1f4a8d2c3e4f5a6b7c8d",
-     *     forecasts: { spaceId: "01ef...", hint: "weekly demand forecasts" },
-     *   },
-     * });
-     * ```
-     *
-     * Reach the spaces from an agent's `tools(plugins)` callback via
-     * `plugins.genie?.toolkit()`; the resulting tools accept
-     * `{ content, conversationId? }` and return a hydrated summary.
-     *
-     * **Fallback discovery** (highest precedence first): if this
-     * field is omitted, the Genie agent also picks up spaces from
-     * (1) the AppKit `genie({ spaces: { ... } })` plugin instance
-     * when registered, and (2) the `DATABRICKS_GENIE_SPACE_ID`
-     * env var (registered under the `default` alias). This keeps
-     * existing AppKit deployments working without restating the
-     * spaces config in two places.
-     */
-    genieSpaces?: GenieSpacesConfig;
-    /**
-     * TTL for the in-memory Genie space metadata cache, in
-     * milliseconds. Defaults to 5 minutes. The Genie agent calls
-     * `client.genie.getSpace(...)` on every cold-start to get the
-     * title / description / warehouse id; cached responses skip the
-     * round-trip and concurrent callers coalesce on a single
-     * in-flight fetch. Drop to a smaller value when analysts are
-     * actively editing space metadata and you want changes visible
-     * within seconds; raise it to amortise the round-trip when
-     * space metadata is effectively frozen.
-     *
-     * Backed by AppKit's `CacheManager`, so the cache participates
-     * in telemetry spans (`cache.getOrExecute`) and benefits from
-     * Lakebase persistence when the `lakebase` plugin is wired up.
-     */
-    genieSpaceCacheTtlMs?: number;
-    /**
-     * Maximum LLM steps each agent gets per turn. One step = one
-     * round-trip to the underlying model (a tool call consumes a
-     * step, the final-text reply consumes one too). Applies to
-     * every agent registered through {@link MastraPluginConfig.agents}
-     * - per-agent overrides aren't surfaced yet because the same
-     * ceiling has been sufficient across every workload we've run.
-     *
-     * Defaults to {@link DEFAULT_AGENT_MAX_STEPS} (25), sized to fit
-     * a decomposed Genie turn (grounding + several `ask_genie` calls
-     * + `prepare_chart` per dataset + the final-text reply) with
-     * headroom for the model to chain a couple of follow-ups before
-     * answering. Mastra's own `agent.generate` default of 5 would
-     * cut multi-step orchestration off after 2-3 tool calls, so
-     * explicitly raising the ceiling here is what lets the
-     * agent-mode loop play out.
-     *
-     * Lower when an unusually slow or expensive model makes long
-     * turns unaffordable; raise for exploratory workloads that need
-     * to drill deep into a dataset within a single turn.
-     */
-    agentMaxSteps?: number;
-}

package/dist/src/config.js

@@ -1,55 +0,0 @@
-/**
- * Plugin configuration types and shared `RequestContext` keys.
- *
- * Kept in a leaf module so `plugin.ts`, `server.ts`, `model.ts`, and
- * `memory.ts` can import them without creating a cycle.
- */
-import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, } from "@mastra/core/request-context";
-/**
- * `RequestContext` key under which {@link MastraServer} stores the
- * resolved AppKit user. `model.ts` reads it to mint user-scoped
- * Databricks tokens.
- */
-export const MASTRA_USER_KEY = "mastra__user";
-/**
- * `RequestContext` keys for AppKit user metadata stamped by
- * {@link MastraServer}. Surfaced as trace metadata via
- * {@link TRACE_REQUEST_CONTEXT_KEYS} so traces are filterable by who
- * issued the request without leaking the full user object.
- */
-export const MASTRA_USER_NAME_KEY = "mastra__userName";
-export const MASTRA_USER_EMAIL_KEY = "mastra__userEmail";
-/**
- * `RequestContext` key for the per-HTTP-request id stamped by
- * {@link MastraServer}. Reads `X-Request-Id` from the incoming
- * headers when present (so an upstream load balancer / API gateway
- * can keep its trace correlation), falls back to a freshly minted
- * UUID. Echoed back on the response and surfaced on every span via
- * {@link TRACE_REQUEST_CONTEXT_KEYS} so logs and traces share a
- * join key.
- */
-export const MASTRA_REQUEST_ID_KEY = "mastra__requestId";
-/**
- * Canonical list of `RequestContext` keys we want Mastra to extract
- * as metadata on every observability span (agent runs, model calls,
- * tool invocations, workflow steps).
- *
- * Mirrors {@link https://mastra.ai/docs/observability/tracing/overview#automatic-metadata-from-requestcontext}:
- * passed verbatim into `Observability.configs[*].requestContextKeys`,
- * so any key listed here is read from `RequestContext` at trace
- * start and attached as scalar span metadata. Keep the set to plain
- * scalars - never include {@link MASTRA_USER_KEY} (it carries the
- * full AppKit execution context with a `WorkspaceClient` reference).
- *
- * Order is purely cosmetic; Mastra de-dupes internally.
- */
-export const TRACE_REQUEST_CONTEXT_KEYS = [
-    MASTRA_RESOURCE_ID_KEY,
-    MASTRA_THREAD_ID_KEY,
-    MASTRA_REQUEST_ID_KEY,
-    MASTRA_USER_NAME_KEY,
-    MASTRA_USER_EMAIL_KEY,
-    // Model override key is owned by `serving.ts`; spelled inline here
-    // so this module stays leaf-level (no cycles with `serving.ts`).
-    "mastra__model_override",
-];

package/dist/src/genie.d.ts

@@ -1,161 +0,0 @@
-/**
- * Genie tools for Mastra.
- *
- * Surfaces each configured Genie space as a small set of flat Mastra
- * tools the calling agent drives directly - no inner orchestrator
- * agent. The central agent decomposes user questions, picks which
- * space to ask, streams the per-turn wire events (status, thinking,
- * sql, rows) through `ctx.writer`, and composes the final reply.
- * Rows are never fetched eagerly: the agent reads a statement's
- * values only when it needs to reason about them, otherwise it embeds
- * a `[data:<statement_id>]` marker in prose and lets the host UI
- * resolve the data. Charts are minted asynchronously and referenced
- * by `[chart:<chartId>]` markers so prose isn't blocked on chart
- * generation; the host UI fetches the cached spec by id once ready.
- * Space description and serialized-space lookups are available for
- * grounding when the agent needs schema context.
- *
- * Each tool's `execute` pulls the per-request
- * {@link WorkspaceClient} off `ctx.requestContext` (stamped by
- * `MastraServer` under {@link MASTRA_USER_KEY}) and the per-call
- * `writer` / `abortSignal` off `ctx`, so the tools are stateless
- * across requests and the central agent owns the loop.
- *
- * The tools talk to Genie directly via `@dbx-tools/genie`
- * (`genieEventChat`); statement-row fetching is delegated to
- * {@link fetchStatementData} from `./statement.js`, which wraps
- * the workspace `statementExecution.getStatement` API. AppKit's
- * stock `genie` plugin is honored only for its `spaces` config
- * so existing AppKit-style wiring keeps working without change.
- *
- * Suggested orchestration prompt for the central agent lives in
- * {@link GENIE_INSTRUCTIONS}; compose it into the agent's own
- * `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";
-/** Default alias used when a single unnamed Genie space is wired up. */
-export declare const DEFAULT_GENIE_ALIAS = "default";
-/** Per-space Genie agent configuration. */
-export interface GenieSpaceConfig {
-    /** Genie `space_id`. Required; resolves via `client.genie.getSpace`. */
-    spaceId: string;
-    /**
-     * Optional human-readable description appended to the per-space
-     * tool descriptions so the calling LLM has hints about *what
-     * data* this space covers (e.g. "orders, returns,
-     * fulfillment"). When omitted, only the space's own
-     * `description` (fetched on first use of `get_space_description`)
-     * is shown.
-     */
-    hint?: string;
-}
-/** Map of alias -> space config. Accepts either explicit objects or bare space ids. */
-export type GenieSpacesConfig = Record<string, GenieSpaceConfig | string>;
-/**
- * Suggested orchestration prompt for the central agent that owns
- * the Genie tools. Compose into your agent's `instructions` to
- * get the canonical "decompose questions, ask Genie focused
- * sub-questions, place data / chart markers in prose" behavior:
- *
- * ```ts
- * createAgent({
- *   instructions: `${myAgentInstructions}\n\n${GENIE_INSTRUCTIONS}`,
- *   tools(plugins) {
- *     return { ...plugins.genie?.toolkit() };
- *   },
- * });
- * ```
- *
- * The prompt references the bare tool names (`ask_genie`,
- * `get_space_description`, `get_space_serialized`,
- * `get_statement`, `prepare_chart`) used for the single-space
- * default alias. Multi-space deployments should write their own
- * variant that names the suffixed per-space tools
- * (e.g. `ask_genie_sales`).
- */
-export declare const GENIE_INSTRUCTIONS: string;
-/**
- * Normalize the {@link GenieSpacesConfig} record. Bare-string
- * entries (`{ default: "01ef..." }`) get wrapped as
- * `{ spaceId: "01ef..." }`; object entries pass through unchanged.
- * `undefined` and empty-string values are dropped so callers can
- * pass `process.env.X` directly (matches AppKit `genie()`'s
- * defensive treatment of unset env vars).
- */
-export declare function normalizeGenieSpaces(spaces: GenieSpacesConfig | Record<string, string | GenieSpaceConfig | undefined> | undefined): Record<string, GenieSpaceConfig>;
-/**
- * Discover Genie space aliases from every supported source and
- * merge them into a single record. Precedence (highest first):
- *
- *   1. {@link MastraPluginConfig.genieSpaces} on the `mastra(...)`
- *      call. Explicit Mastra wiring always wins so users can
- *      override AppKit's defaults per-agent.
- *   2. AppKit `genie({ spaces: { ... } })` plugin instance. Lets
- *      users keep using the existing AppKit config format
- *      (`genie({ spaces: { sales: "...", ops: "..." } })`)
- *      without restating the same record on the Mastra plugin.
- *      Read off the live plugin instance via a structural cast
- *      since `Plugin.config` is TS-protected (not runtime-private).
- *   3. `DATABRICKS_GENIE_SPACE_ID` env var (registered under the
- *      well-known `default` alias). Matches the AppKit `genie()`
- *      plugin's fallback behavior so a bare `mastra()` + `genie()`
- *      pair just works.
- *
- * Aliases collide cleanly: a higher-precedence source's value
- * replaces a lower one's wholesale. Sources that contribute zero
- * aliases (or contribute only `undefined` / empty entries) are
- * silently ignored.
- */
-export declare function resolveGenieSpaces(config: MastraPluginConfig, context: appkitUtils.PluginContextLike | undefined): Record<string, GenieSpaceConfig>;
-/**
- * Build the flat Mastra tools record for every configured Genie
- * space. Two shared, space-agnostic tools (`get_statement`,
- * `prepare_chart`) are registered once regardless of how many
- * spaces are wired; the per-space tools (`ask_genie`,
- * `get_space_description`, `get_space_serialized`) are suffixed
- * with `_<alias>` for non-default aliases so multi-space
- * deployments stay disambiguated.
- *
- * Returns a record keyed by tool id, ready to spread into the
- * central `Agent`'s `tools` map (or surfaced via the
- * `plugins.genie?.toolkit()` callback). Returns an empty record
- * when `spaces` resolves to zero entries so the caller can spread
- * safely.
- */
-export declare function buildGenieTools(opts: {
-    spaces: GenieSpacesConfig | Record<string, GenieSpaceConfig>;
-    config: MastraPluginConfig;
-}): MastraTools;
-/**
- * Plugin-toolkit adapter so the `plugins.genie?.toolkit()` lookup
- * inside an agent's `tools(plugins)` callback returns the
- * flat Genie tools record instead of throwing on missing plugin.
- * Mirrors AppKit's `PluginToolkitProvider` shape.
- */
-export declare function buildGenieToolkitProvider(opts: {
-    spaces: GenieSpacesConfig | Record<string, GenieSpaceConfig>;
-    config: MastraPluginConfig;
-}): {
-    toolkit(opts?: unknown): MastraTools;
-};
-/**
- * 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[]>;