@dbx-tools/appkit-mastra 0.1.58 → 0.1.68

package/dist/src/plugin.d.ts

@@ -1,177 +0,0 @@
-/**
- * AppKit plugin that builds one or more Mastra `Agent` instances and
- * mounts the `@mastra/express` server. Clients drive the conversation
- * over the standard Mastra agent stream (`@mastra/client-js`'s
- * `getAgent(id).stream()`), so there's no bespoke chat transport to
- * keep in sync.
- *
- * - Agents: registered through `config.agents` at plugin creation
- *   ({@link MastraAgentDefinition}). Each entry's `tools` field accepts
- *   either a plain record or a `(plugins) => tools` callback that gets
- *   a typed sibling-plugin index ({@link MastraPlugins}). Omit
- *   `config.agents` to get a single built-in `default` analyst.
- * - Model: each agent call resolves a `MastraModelConfig` via
- *   {@link buildModel} from `./model.js`. Per-agent `model` overrides
- *   (`AgentConfig["model"]` or a `modelId` string) flow through
- *   {@link buildAgents}.
- * - Memory / storage: per-agent, built by {@link createMemoryBuilder}
- *   from `./memory.js`. Both auto-default to `true` when the
- *   `lakebase` plugin is registered (unless the caller passed
- *   `false` or a custom config). Storage namespaces per agent via
- *   `schemaName: "mastra_<agentId>"`; the vector store is a single
- *   shared singleton across every agent.
- * - Server: the Express subapp wiring lives in `./server.js`.
- * - HTTP: AppKit mounts this plugin under `/api/mastra`. Alongside the
- *   Mastra agent routes, the plugin registers `/route/history`
- *   (load + clear thread history), `/models`, `/suggestions`, and the
- *   generic `/embed/:type/:id` resolver for inline chart / data
- *   markers.
- */
-import { Plugin, type IAppRouter, type ResourceRequirement } from "@databricks/appkit";
-import type { Agent } from "@mastra/core/agent";
-import { Mastra } from "@mastra/core/mastra";
-import { type ServingEndpointSummary } from "@dbx-tools/model";
-import type { MastraPluginConfig } from "./config.js";
-import { MastraServer } from "./server.js";
-/**
- * AppKit plugin (registered name: `mastra`) that hosts Mastra agents
- * with optional Lakebase-backed memory and AI SDK chat routes under
- * the plugin mount (typically `/api/mastra`).
- */
-export declare class MastraPlugin extends Plugin<MastraPluginConfig> {
-    static manifest: {
-        name: "mastra";
-        displayName: string;
-        description: string;
-        stability: "beta";
-        resources: {
-            required: never[];
-            optional: Omit<ResourceRequirement, "required">[];
-        };
-    };
-    /**
-     * Tighten resource requirements based on which features are enabled.
-     * AppKit calls this at registration time (config-aware) so disabled
-     * features don't surface their resource asks to the host app.
-     */
-    static getResourceRequirements(config: MastraPluginConfig): ResourceRequirement[];
-    private log;
-    private built;
-    private mastra;
-    private mastraApp;
-    private mastraServer;
-    /**
-     * Dedicated service-principal Lakebase pool backing Mastra memory /
-     * storage. Built once in {@link buildAgentAndServer} (outside any
-     * `asUser` scope, so it never inherits a request's OBO identity) and
-     * drained in {@link abortActiveOperations}. `null` until setup runs
-     * or when Lakebase isn't needed.
-     */
-    private servicePrincipalPool;
-    setup(): Promise<void>;
-    /**
-     * When the `lakebase` plugin is registered, auto-enable `storage`
-     * and `memory` unless the caller opted out explicitly (`false` or a
-     * custom config object). Run after `setup:complete` so the lookup
-     * is reliable: any plugin that registers itself synchronously is
-     * already in the registry by the time this fires.
-     */
-    private applyLakebaseAutoDefaults;
-    /**
-     * Drain the memory service-principal pool on shutdown. AppKit calls
-     * this during teardown; the lakebase plugin closes its own SP / OBO
-     * pools the same way. Fire-and-forget so shutdown isn't blocked on a
-     * slow drain, and clear the handle so a re-`setup()` rebuilds it.
-     */
-    abortActiveOperations(): void;
-    exports(): {
-        /**
-         * Ids of every registered agent in registration order. Matches
-         * AppKit `agents.list()` so callers can iterate the registry the
-         * same way under both plugins.
-         */
-        list: () => string[];
-        /**
-         * Look up a registered agent by id. Returns `null` (not
-         * undefined) when unknown so call sites can early-return without
-         * a separate `in` check.
-         */
-        get: (id: string) => Agent | null;
-        /**
-         * The agent the client converses with when it doesn't name one.
-         * Resolves to `config.defaultAgent`, the first registered id, or
-         * the built-in `default` fallback.
-         */
-        getDefault: () => Agent | null;
-        /** Underlying Mastra instance for advanced use (custom routes etc.). */
-        getMastra: () => Mastra<Record<string, Agent<any, import("@mastra/core/agent").ToolsInput, undefined, unknown, import("@mastra/core/agent").AgentEditorConfig | undefined>>, Record<string, import("@mastra/core/workflows").AnyWorkflow>, Record<string, import("@mastra/core/vector").MastraVector<any>>, Record<string, import("@mastra/core/tts").MastraTTS>, import("@mastra/core/logger").IMastraLogger, Record<string, import("@mastra/core/mcp").MCPServerBase<any>>, Record<string, import("@mastra/core/evals").MastraScorer<any, any, any, any>>, Record<string, import("@mastra/core/tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, import("@mastra/core/processors").Processor<any, unknown>>, Record<string, import("@mastra/core/memory").MastraMemory>, Record<string, import("@mastra/core/channels").ChannelProvider>> | null;
-        /** Express subapp Mastra is mounted on; mostly for tests. */
-        getMastraServer: () => MastraServer | null;
-        /**
-         * Fetch the workspace's Model Serving endpoints (cached). Same
-         * payload the `GET /models` route returns; surfaced here so
-         * other plugins / scripts can introspect the catalogue without
-         * an HTTP round-trip. AppKit wraps this with `asUser(req)` for
-         * OBO scoping automatically.
-         */
-        listModels: () => Promise<ServingEndpointSummary[]>;
-        /**
-         * Force-evict cached endpoint listings via AppKit's
-         * `CacheManager`. Useful in tests or right after an admin
-         * deploys a new endpoint and doesn't want to wait for the TTL.
-         * Returns the underlying `CacheManager.delete`/`clear` promise.
-         */
-        clearModelsCache: (host?: string) => Promise<void>;
-    };
-    clientConfig(): Record<string, unknown>;
-    injectRoutes(router: IAppRouter): void;
-    /**
-     * Invoke the Mastra express sub-app. Exists as a method (instead of reading
-     * `this.mastraApp` through the `asUser(req)` proxy at the call site) so the
-     * proxy binds this plain method - whose `.bind` is `Function.prototype.bind`
-     * - rather than the express app, whose `.bind` is the HTTP BIND route
-     * registrar (see the note in `injectRoutes`). Runs inside the user scope so
-     * `getExecutionContext()` returns the OBO client for the agent/model
-     * resolvers.
-     */
-    private dispatchMastra;
-    /**
-     * 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
-     * `getExecutionContext()` returns the OBO-scoped workspace
-     * client, then reuses the same `fetchStatementData` pipeline
-     * the `get_statement` tool runs so the LLM and the UI see the
-     * exact same shape for the same statement.
-     *
-     * Returns `undefined` for upstream 404s so the route can map
-     * them to a clean HTTP 404; any other failure bubbles up.
-     */
-    private fetchStatement;
-    /**
-     * Return `this.asUser(req)` when the request carries an OBO token,
-     * otherwise return `this` directly. Prevents the noisy AppKit warn
-     * (`asUser() called without user token in development mode. Skipping
-     * user impersonation.`) on every request in local dev where the
-     * browser never sends `x-forwarded-access-token`. Behavior is
-     * unchanged in production: a missing token always means a real OBO
-     * proxy call (and AppKit will throw upstream if that's wrong).
-     */
-    private userScopedSelf;
-    /**
-     * Implementation backing both the `/models` route and the
-     * `listModels` export. Runs inside the AppKit user-context proxy so
-     * `getExecutionContext()` returns the OBO-scoped client.
-     */
-    private listModels;
-    private buildAgentAndServer;
-}
-export declare const mastra: import("@databricks/appkit").ToPlugin<typeof MastraPlugin, MastraPluginConfig, "mastra">;