@dbx-tools/appkit-mastra 0.1.58 → 0.1.67

package/dist/src/agents.d.ts

@@ -1,316 +0,0 @@
-/**
- * Agent registration for the Mastra AppKit plugin.
- *
- * Mirrors the shape of the AppKit `agents` plugin (`config.agents` map
- * of {@link MastraAgentDefinition}, dual-form `tools` accepting a plain
- * record or a `(plugins) => tools` callback). Resolves each definition
- * into a Mastra `Agent` instance during plugin setup; user-supplied
- * tool callbacks are invoked exactly once with a typed
- * {@link MastraPlugins} map built from registered sibling plugins.
- *
- * When no agents are registered the plugin falls back to a single
- * built-in analyst so the bare `mastra()` call still mounts a working
- * streamable agent for demos.
- */
-import { appkitUtils, logUtils } from "@dbx-tools/shared";
-import type { AgentConfig, ToolsInput } from "@mastra/core/agent";
-import { Agent } from "@mastra/core/agent";
-import type { Tool } from "@mastra/core/tools";
-import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
-import type { MastraPluginConfig } from "./config.js";
-import type { MemoryBuilder } from "./memory.js";
-/**
- * Tool record accepted by every Mastra `Agent.tools` field and by the
- * `tools(plugins)` callback on {@link MastraAgentDefinition}.
- *
- * Alias of Mastra's `ToolsInput`, so it already accepts:
- *
- * - Mastra tools built with {@link createTool} (or `new Tool(...)`)
- * - Mastra tools built with the AppKit-shaped {@link tool} wrapper
- *   below
- * - Vercel AI SDK tools (`tool({ ... })` from `ai`)
- * - Provider-defined tools (e.g. `openai.tools.webSearch(...)`)
- *
- * Existing tool libraries drop in as-is - nothing in this package
- * forces a rebuild.
- */
-export type MastraTools = ToolsInput;
-/** Re-export of Mastra's native `createTool` for full-feature access. */
-export { createTool } from "@mastra/core/tools";
-/**
- * AppKit-shaped tool factory. Lets users mix-and-match tools across
- * AppKit's `agents` plugin and `mastra` with a single import:
- *
- * ```ts
- * import { tool } from "@dbx-tools/appkit-mastra";
- * import { z } from "zod";
- *
- * get_weather: tool({
- *   description: "Weather",
- *   schema: z.object({ city: z.string() }),
- *   execute: async ({ city }) => `Sunny in ${city}`,
- * }),
- * ```
- *
- * Maps onto Mastra's `createTool`:
- *
- * - `description` -> `description` (required)
- * - `schema` -> `inputSchema` (optional)
- * - `execute(input)` -> `execute(input, ctx)` - Mastra already calls
- *   the first arg with the parsed inputs, so the body shape is
- *   identical. The Mastra `context` arg is forwarded as the second
- *   parameter when the caller declares it.
- * - `id`: optional. Defaults to a stable identifier derived from
- *   `description` (slugified, with a short hash suffix for
- *   uniqueness). Pass an explicit `id` when you need a stable string
- *   for tracing or MCP exposure.
- *
- * Reach for {@link createTool} when you need Mastra-only fields
- * (`outputSchema`, `suspendSchema`, `requireApproval`, `mcp`, etc.).
- */
-export declare function tool(opts: AppKitToolOptions): Tool;
-/**
- * Input shape for the AppKit-style {@link tool} factory. A trimmed
- * subset of Mastra's `createTool` options that mirrors the
- * `@databricks/appkit/beta` `tool({ description, schema, execute })`
- * signature.
- *
- * Generics are intentionally absent - inference flows through the
- * caller's `schema` (typically a Zod object), and the `execute` body
- * destructures naturally from that. Reach for {@link createTool} when
- * you need the fully-typed input/output schemas wired explicitly.
- */
-export interface AppKitToolOptions {
-    /** Optional stable identifier; auto-derived from `description` when omitted. */
-    id?: string;
-    /** Human-readable description shown to the model. Required. */
-    description: string;
-    /**
-     * Optional input schema (any Standard Schema instance, e.g. Zod).
-     * Maps to Mastra's `inputSchema`; passed through to the model
-     * verbatim.
-     */
-    schema?: unknown;
-    /**
-     * Execute body. First arg is the parsed input (typed off `schema`
-     * when supplied), second arg is the full Mastra execution context
-     * (request context, abort signal, mastra instance) if you need it.
-     */
-    execute: (input: any, context?: unknown) => unknown;
-}
-/**
- * Identity helper that brands a definition as a Mastra agent. Mirrors
- * AppKit's `createAgent(def)` so the registration shape matches:
- *
- * ```ts
- * const support = createAgent({
- *   instructions: "...",
- *   model: "databricks-claude-sonnet-4-6",
- *   tools(plugins) { return { ... }; },
- * });
- * ```
- *
- * Returns the definition unchanged - the wrapper exists only to anchor
- * type inference and to match the AppKit API surface.
- */
-export declare function createAgent<T extends MastraAgentDefinition>(def: T): T;
-/**
- * Filter / rename options accepted by every plugin's `.toolkit()`
- * method. Mirrors AppKit's `ToolkitOptions` verbatim so options pass
- * through unchanged - the underlying AppKit plugin does the filtering
- * and we just adapt the resulting entries into Mastra tools.
- */
-export interface ToolkitOptions {
-    /**
-     * Key prefix prepended to every tool name. AppKit's default is
-     * `${pluginName}.` when omitted; pass an explicit `""` to drop it.
-     */
-    prefix?: string;
-    /** Allowlist of local tool names. */
-    only?: string[];
-    /** Denylist of local tool names. */
-    except?: string[];
-    /** Remap specific local names to different keys. */
-    rename?: Record<string, string>;
-}
-/**
- * Toolkit provider shape every entry in the {@link MastraPlugins} map
- * exposes. Identical to AppKit's `PluginToolkitProvider` - any AppKit
- * plugin that implements the standard `ToolProvider` interface
- * (`getAgentTools` + `executeAgentTool` + `toolkit`) is reachable
- * through this surface automatically.
- */
-export interface MastraPluginToolkitProvider {
-    /**
-     * Returns a Mastra-shaped tools record adapted from the plugin's
-     * agent tools. Each tool dispatches back through the plugin's
-     * `executeAgentTool` so OBO auth and telemetry spans stay intact.
-     */
-    toolkit(opts?: ToolkitOptions): MastraTools;
-}
-/**
- * Plugin map handed to the function form of
- * {@link MastraAgentDefinition.tools}. Mirrors AppKit's `Plugins`
- * type exactly: a string-keyed record where every value exposes
- * `.toolkit(opts)`.
- *
- * Implemented as a runtime Proxy that auto-discovers any registered
- * AppKit plugin implementing the standard `ToolProvider` interface
- * (`analytics`, `files`, `lakebase`, `genie`, plus any third-party
- * plugin that does the same). Unknown names resolve to `undefined`
- * at runtime, so guard with `?.` and `?? {}` when spreading from a
- * plugin that may not be registered in every environment.
- *
- * @example
- * ```ts
- * createAgent({
- *   instructions: "...",
- *   tools(plugins) {
- *     return {
- *       ...plugins.analytics.toolkit(),
- *       ...plugins.files.toolkit({ only: ["uploads.read"] }),
- *       get_weather: tool({
- *         description: "Weather",
- *         schema: z.object({ city: z.string() }),
- *         execute: async ({ city }) => `Sunny in ${city}`,
- *       }),
- *     };
- *   },
- * });
- * ```
- */
-export type MastraPlugins = Record<string, MastraPluginToolkitProvider>;
-/** Function form of {@link MastraAgentDefinition.tools}. */
-export type MastraToolsFn = (plugins: MastraPlugins) => MastraTools | Promise<MastraTools>;
-/**
- * A code-defined Mastra agent. Mirrors the shape AppKit's `agents`
- * plugin uses for `AgentDefinition`. The registry key under
- * `config.agents` is the `agentId` the client streams against; `name`
- * is purely informational (defaults to the key).
- */
-export interface MastraAgentDefinition {
-    /** Display name used as `Agent.name`. Defaults to the registry key. */
-    name?: string;
-    /** Optional long-form description; surfaced as `Agent.description`. */
-    description?: string;
-    /** System prompt body. */
-    instructions: string;
-    /**
-     * Per-agent model override.
-     *
-     * - `undefined` (default): falls back to the workspace
-     *   `/serving-endpoints` resolver that {@link buildModel} configures
-     *   from the per-request `WorkspaceClient`.
-     * - `string`: shorthand for "use the default resolver but swap the
-     *   `modelId`" (e.g. `"databricks-meta-llama-3-3-70b-instruct"`).
-     * - Any other Mastra `DynamicArgument<MastraModelConfig>`: passed
-     *   straight through to `Agent.model`. Use this when you need full
-     *   control over auth or providerId.
-     */
-    model?: AgentConfig["model"] | string;
-    /**
-     * Per-agent tool record. Either a plain map or a callback that
-     * receives the typed {@link MastraPlugins} sibling-plugin index and
-     * returns a map. The callback runs exactly once at agent setup; the
-     * result is cached for the agent's lifetime.
-     */
-    tools?: MastraTools | MastraToolsFn;
-    /**
-     * Per-agent semantic recall (PgVector) override. Cascades from
-     * `config.memory`; the agent value wins when set.
-     *
-     * - `undefined` (default): inherit `config.memory`. When that's
-     *   enabled, the agent **shares the plugin-level singleton `PgVector`
-     *   instance** (cross-agent semantic recall across the same index).
-     * - `false`: disable semantic recall for this agent only.
-     * - `true`: enable using the shared singleton (same as default when
-     *   plugin memory is enabled; useful to opt in when plugin disabled).
-     * - {@link MastraMemoryConfig} object: dedicated `PgVector` for this
-     *   agent (private recall index). Bypasses the shared singleton.
-     */
-    memory?: boolean | MastraMemoryConfigOverride;
-    /**
-     * Per-agent thread/message storage (`PostgresStore`) override.
-     * Cascades from `config.storage`; the agent value wins when set.
-     *
-     * - `undefined` (default): inherit `config.storage`. When that's
-     *   enabled, the agent gets its **own per-agent `PostgresStore`**
-     *   keyed by `schemaName: "mastra_<agentId>"` so threads and
-     *   messages stay isolated between agents in the same database.
-     * - `false`: disable storage for this agent only (purely in-memory).
-     * - `true`: enable with the per-agent default schema.
-     * - {@link MastraStorageConfigOverride} object: dedicated
-     *   `PostgresStore` config (custom schema, connection, etc.).
-     */
-    storage?: boolean | MastraStorageConfigOverride;
-}
-/**
- * Distributive `Omit` so unions in `PostgresStoreConfig` /
- * `PgVectorConfig` keep their discriminants after the override types
- * strip `id`. The built-in `Omit` collapses unions to one shape with
- * common fields only, which loses the connection-style discriminants.
- */
-type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
-/**
- * `PostgresStoreConfig` minus `id` - per-agent overrides accept any
- * Mastra-supported storage shape. `id` is filled in automatically
- * from the agent registry key so traces stay stable.
- */
-export type MastraStorageConfigOverride = DistributiveOmit<PostgresStoreConfig, "id"> & {
-    id?: string;
-};
-/**
- * `PgVectorConfig` minus `id` - per-agent overrides accept any
- * Mastra-supported vector shape. `id` is filled in automatically
- * from the agent registry key.
- */
-export type MastraMemoryConfigOverride = DistributiveOmit<PgVectorConfig, "id"> & {
-    id?: string;
-};
-/** Output of {@link buildAgents}: resolved agents plus the default id. */
-export interface BuiltAgents {
-    agents: Record<string, Agent>;
-    defaultAgentId: string;
-}
-/** Fallback agent id used when `config.agents` is omitted entirely. */
-export declare const FALLBACK_AGENT_ID = "default";
-/**
- * Default per-turn step ceiling applied to every registered agent
- * when {@link MastraPluginConfig.agentMaxSteps} is unset. 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 - well above Mastra's own `agent.generate` default of
- * 5, which would cut multi-step orchestration off mid-loop.
- */
-export declare const DEFAULT_AGENT_MAX_STEPS = 25;
-/**
- * Style guardrails appended to every agent's `instructions` to curb
- * common LLM-isms (em dashes, emojis, sycophantic openers, excessive
- * hedging, throwaway closers). Appended rather than prepended so the
- * agent's role/context comes first; the model's recency bias then
- * helps the style rules dominate the response surface.
- *
- * Override globally via {@link MastraPluginConfig.styleInstructions}
- * (pass `false` to disable entirely, or a string to replace).
- */
-export declare const DEFAULT_STYLE_INSTRUCTIONS: string;
-/**
- * Resolve every entry in `config.agents` into a Mastra `Agent`
- * instance. When `config.agents` is omitted the plugin registers a
- * single built-in `default` analyst so the bare `mastra()` call still
- * yields a working agent.
- *
- * Per-agent tool callbacks are invoked once with a typed
- * {@link MastraPlugins} index built from registered sibling plugins
- * (currently `genie`; extend `MastraPlugins` to surface more).
- *
- * @throws when `config.defaultAgent` is set to an id that isn't in the
- *   resolved registry; this is a wiring bug, not a runtime condition.
- */
-export declare function buildAgents(opts: {
-    config: MastraPluginConfig;
-    context: appkitUtils.PluginContextLike | undefined;
-    memoryBuilder?: MemoryBuilder;
-    log: logUtils.Logger;
-}): Promise<BuiltAgents>;