@dbx-tools/appkit-mastra 0.1.71 → 0.1.72

package/README.md

@@ -88,6 +88,94 @@ Override per plugin or per agent by passing `memory` / `storage` as
 index / schema). The fields are typed in [`config.ts`](src/config.ts);
 the wiring is in [`memory.ts`](src/memory.ts).
 
+### Conversations (threads)
+
+When storage is on, a user owns many conversation threads. The plugin
+resolves the thread a request targets from `RequestContext`, in order:
+
+1. A **client-selected thread id** - the thread-selection header
+   (`x-mastra-thread-id`) or `?threadId=` query. This is how the chat UI
+   references a specific conversation: it picks an id from the threads
+   listing (or mints one for a new chat) and stamps it on every call, so
+   streaming, history, and clear all target that thread.
+2. The **per-session cookie** (`appkit_<plugin-name>_session_id`), minted
+   on first contact, as the single-thread fallback for clients that
+   don't manage threads explicitly.
+
+The thread id pins both `agent.stream()` persistence and the history /
+threads routes, so client and server can never disagree on which
+conversation is active. Two custom routes back the UI's conversation
+management (registered alongside `/route/history`):
+
+- `GET /route/threads` (`/route/threads/:agentId`) - one page of the
+  caller's threads, newest first, **scoped to the caller's resource** so
+  a user only ever sees their own conversations.
+- `DELETE /route/threads` - delete the targeted thread (id from the
+  thread-selection header). Ownership is enforced server-side: a thread
+  is only removed when it belongs to the caller.
+
+Each thread is auto-titled from its opening turn (Mastra's
+`generateTitle`), but titling runs on the **small / fast chat tier**
+(`ModelClass.ChatFast`) via the dedicated summarizer in
+[`summarize.ts`](src/summarize.ts) - not the agent's primary model - so
+naming a conversation never spends the heavyweight model. The route
+handlers live in [`threads.ts`](src/threads.ts); the thread-id
+resolution is in [`server.ts`](src/server.ts). The drop-in `MastraChat`
+from `@dbx-tools/appkit-mastra-ui` renders the whole conversation sidebar
+over these routes with no extra wiring.
+
+### Summarization (`summarize` tool)
+
+Every agent gets a system-default ambient `summarize` tool that condenses
+arbitrary text (long content, notes, transcripts, bulky tool results) on
+the small / fast chat tier instead of the agent's primary model. It takes
+`text` plus optional `instructions` (e.g. "one sentence", "list the action
+items") and a `maxWords` soft cap, and returns `{ summary }`. The same
+small-tier summarizer backs conversation titling above. Shadow it by
+defining a same-named tool in `config.tools` (or a per-agent `tools`), and
+reuse it programmatically via the exported `summarizeText(config, text,
+opts)` / `buildSummarizeTool(config)`.
+
+### Managed Memory (Databricks Agent Memory, Beta)
+
+`managedMemory` swaps the Postgres `PgVector` semantic-recall layer for
+[Databricks Managed Agent Memory](https://docs.databricks.com/aws/en/generative-ai/agent-framework/managed-memory)
+- a Unity Catalog memory-store. When active, every agent gets two
+ambient tools (`save_memory`, `search_memory`) plus an auto-recall input
+processor that searches the user's entries with the latest message and
+injects the top matches before each turn. Entries are scoped per-user
+via OBO (the model never sets the scope). The thread / message
+transcript still uses `PostgresStore` only when `lakebase()` is
+registered - managed memory does not pull in Lakebase.
+
+```ts
+mastra({
+  // Prefer-if-available: enabled automatically when MEMORY_STORE is set
+  // and the workspace exposes the memory-stores API; otherwise PgVector.
+  managedMemory: true, // or { store, topK, autoCreate, recall, tools }
+});
+```
+
+The store is a three-level Unity Catalog name (`catalog.schema.name`),
+resolved from `managedMemory.store` or the `MEMORY_STORE` env var.
+Enable semantics:
+
+- **omitted** (default, prefer-if-available): on only when `MEMORY_STORE`
+  is set and the API is reachable; otherwise the `PgVector` path.
+- **`false`**: never use managed memory.
+- **`true`**: enable; store must come from `MEMORY_STORE`.
+- **object**: enable with explicit `store` (or `MEMORY_STORE`) plus
+  `topK`, `autoCreate`, `recall`, `tools`, `entryPath` overrides.
+
+Required Unity Catalog privileges for the app service principal:
+`CREATE MEMORY STORE` on the schema (only when `autoCreate` is on, the
+default), plus `READ MEMORY STORE` / `WRITE MEMORY STORE` on the store.
+The capability probe and optional store auto-create run once at setup as
+the service principal. Managed Memory is Beta and REST-only; on any
+probe, create, or search failure the plugin logs and falls back to the
+`PgVector` path so chat stays available. The connector lives in
+[`connectors/managed-memory/`](src/connectors/managed-memory).
+
 ## The `tools(plugins)` callback
 
 Each agent supplies either a static `tools: { ... }` record or a

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { appkitUtils, logUtils } from "@dbx-tools/shared";
 import * as _mastra_core_agent0 from "@mastra/core/agent";
 import { Agent, AgentConfig, ToolsInput } from "@mastra/core/agent";
 import * as _mastra_core_tools0 from "@mastra/core/tools";
-import { Tool, createTool } from "@mastra/core/tools";
+import { Tool, createTool, createTool as createTool$1 } from "@mastra/core/tools";
 import * as _databricks_appkit0 from "@databricks/appkit";
 import { BasePluginConfig, IAppRouter, Plugin, ResourceRequirement } from "@databricks/appkit";
 import { z } from "zod";
@@ -29,6 +29,99 @@ import * as _mastra_core_channels0 from "@mastra/core/channels";
 export * from "@dbx-tools/appkit-mastra-shared";
 export * from "@dbx-tools/model";
 
+//#region packages/appkit-mastra/src/connectors/managed-memory/types.d.ts
+/**
+ * Type contract for the Databricks Managed Agent Memory connector.
+ *
+ * Managed Memory is a Beta Unity Catalog feature (REST-only, no TS
+ * SDK yet) that stores long-term agent memories as scoped entries in a
+ * UC `memory-store`. In `@dbx-tools/appkit-mastra` it plays the role
+ * the Postgres `PgVector` semantic-recall layer otherwise fills: an
+ * auto-recall input processor reads the user's top entries before each
+ * turn, and `save_memory` / `search_memory` tools let the agent persist
+ * and look up durable facts. Every read / write is scoped to the OBO
+ * user id resolved in trusted server code - the model never sets scope.
+ */
+/**
+ * Caller-facing configuration for the managed-memory backend, set via
+ * {@link MastraPluginConfig.managedMemory}. Every field is optional;
+ * the object form only needs to override what differs from the
+ * connector defaults.
+ */
+interface ManagedMemoryConfig {
+  /**
+   * Three-level Unity Catalog name of the memory store
+   * (`catalog.schema.name`). Falls back to the `MEMORY_STORE` env var
+   * when omitted. Required (here or in env) whenever managed memory is
+   * explicitly enabled; in prefer-if-available mode its absence simply
+   * leaves managed memory off.
+   */
+  store?: string;
+  /** Description stamped on the store when {@link autoCreate} creates it. */
+  description?: string;
+  /**
+   * Number of entries the recall processor injects and `search_memory`
+   * returns by default. Defaults to {@link DEFAULT_TOPK}.
+   */
+  topK?: number;
+  /**
+   * Create the store at setup when it doesn't exist (requires
+   * `CREATE MEMORY STORE` on the schema). Defaults to `true`; set
+   * `false` to require the store be provisioned out of band.
+   */
+  autoCreate?: boolean;
+  /**
+   * Attach the auto-recall input processor that injects the user's
+   * top entries before each turn. Defaults to `true`.
+   */
+  recall?: boolean;
+  /**
+   * Expose the `save_memory` / `search_memory` ambient tools to every
+   * agent. Defaults to `true`.
+   */
+  tools?: boolean;
+  /**
+   * Entry path new `save_memory` writes land under. Defaults to
+   * {@link DEFAULT_ENTRY_PATH}. Managed Memory keys entries by path
+   * within a scope, so a stable path accumulates notes for a user.
+   */
+  entryPath?: string;
+}
+/**
+ * A single memory entry as returned by the search endpoint. Fields
+ * mirror the UC memory-store wire shape but are all optional except
+ * `contents` because the Beta API surface may still drift.
+ */
+interface MemoryEntry {
+  /** Entry path within the scope (e.g. `/memories/notes.md`). */
+  path?: string;
+  /** Entry body - the recalled text. */
+  contents: string;
+  /** Optional one-line summary of the entry. */
+  description?: string;
+  /** Relevance score from the search ranker, when present. */
+  score?: number;
+}
+/**
+ * Resolved managed-memory runtime handed to the tools and recall
+ * processor when managed memory is the active long-term backend.
+ * Built once at setup after the capability probe succeeds; carries the
+ * store target and recall sizing, not the workspace client (that is
+ * resolved per-request from the OBO execution context).
+ */
+interface ManagedMemoryRuntime {
+  /** Three-level UC name of the resolved store. */
+  storeName: string;
+  /** Entries to recall / return per call. */
+  topK: number;
+  /** Default path for `save_memory` writes. */
+  entryPath: string;
+  /** Whether to expose the `save_memory` / `search_memory` tools. */
+  tools: boolean;
+  /** Whether to attach the auto-recall input processor. */
+  recall: boolean;
+}
+//#endregion
 //#region packages/appkit-mastra/src/genie.d.ts
 /** Default alias used when a single unnamed Genie space is wired up. */
 declare const DEFAULT_GENIE_ALIAS = "default";
@@ -252,8 +345,40 @@ interface MastraPluginConfig extends BasePluginConfig {
   /**
    * PgVector store for Mastra memory recall. `true` reuses the
    * `lakebase` plugin's pool; an object opens a dedicated store.
+   *
+   * When {@link managedMemory} is active it takes over the long-term /
+   * semantic-recall role and `PgVector` is not built, regardless of
+   * this setting; thread / message transcript (`storage`) is
+   * unaffected.
    */
   memory?: boolean | MastraMemoryConfig;
+  /**
+   * Databricks Managed Agent Memory (Beta) as the long-term /
+   * semantic-recall backend, replacing the Postgres `PgVector` role.
+   * When active, every agent gets `save_memory` / `search_memory` tools
+   * and an auto-recall input processor that injects the user's top
+   * entries before each turn; entries are scoped per-user via OBO. The
+   * thread / message transcript still uses `PostgresStore` only when
+   * the `lakebase` plugin is registered - managed memory does not pull
+   * in Lakebase.
+   *
+   * - `undefined` (default, prefer-if-available): enabled only when the
+   *   `MEMORY_STORE` env var names a store and the workspace exposes the
+   *   memory-stores API; otherwise the `PgVector` path is used.
+   * - `false`: never use managed memory.
+   * - `true`: enable; the store must be named via the `MEMORY_STORE`
+   *   env var (a missing store is a setup error).
+   * - {@link ManagedMemoryConfig}: enable with explicit `store`
+   *   (or `MEMORY_STORE`), recall size, auto-create, and tool / recall
+   *   toggles.
+   *
+   * The store is a three-level Unity Catalog name (`catalog.schema.name`).
+   * The app service principal needs `CREATE MEMORY STORE` on the schema
+   * when auto-create is on, plus `READ/WRITE MEMORY STORE`. On any probe
+   * or create failure the plugin logs and falls back to the `PgVector`
+   * path so chat stays available.
+   */
+  managedMemory?: boolean | ManagedMemoryConfig;
   /**
    * Code-defined agents. Accepts three shapes for convenience:
    *
@@ -502,6 +627,17 @@ interface MastraPluginConfig extends BasePluginConfig {
 }
 //#endregion
 //#region packages/appkit-mastra/src/memory.d.ts
+/** Options controlling how {@link MemoryBuilder} resolves each agent's memory. */
+interface MemoryBuilderOptions {
+  /**
+   * Skip building / attaching `PgVector` (and its `semanticRecall`)
+   * for every agent. Set when Databricks Managed Memory is the active
+   * long-term backend - it fills the semantic-recall role instead, via
+   * the recall input processor and memory tools. Thread / message
+   * storage (`PostgresStore`) is unaffected.
+   */
+  suppressVector?: boolean;
+}
 /**
  * Builds one `Memory` per agent against a shared service-principal
  * Lakebase pool. Per-instance state keeps the shared `PgVector` alive
@@ -510,8 +646,9 @@ interface MastraPluginConfig extends BasePluginConfig {
 declare class MemoryBuilder {
   private readonly config;
   private readonly servicePrincipalPool;
+  private readonly options;
   private sharedVector;
-  constructor(config: MastraPluginConfig, servicePrincipalPool: Pool);
+  constructor(config: MastraPluginConfig, servicePrincipalPool: Pool, options?: MemoryBuilderOptions);
   /**
    * Build a `Memory` for `agentId` after the plugin/agent cascade.
    * Returns `undefined` when the agent has neither storage nor a
@@ -843,6 +980,14 @@ declare function buildAgents(opts: {
   config: MastraPluginConfig;
   context: appkitUtils.PluginContextLike | undefined;
   memoryBuilder?: MemoryBuilder;
+  /**
+   * Active Databricks Managed Memory runtime, present only when managed
+   * memory was resolved and probed successfully at setup. When set,
+   * every agent gets the `save_memory` / `search_memory` tools and the
+   * auto-recall input processor; the `PgVector` path is suppressed
+   * upstream in `memory.ts`.
+   */
+  managedMemory?: ManagedMemoryRuntime;
   log: logUtils.Logger;
 }): Promise<BuiltAgents>;
 //#endregion
@@ -971,6 +1116,144 @@ declare function buildRenderDataTool(config: MastraPluginConfig): _mastra_core_t
   chartId: string;
 }, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "render_data", unknown>;
 //#endregion
+//#region packages/appkit-mastra/src/connectors/managed-memory/client.d.ts
+/** Workspace client carried on an AppKit execution context. */
+type WorkspaceClient$1 = appkitUtils.WorkspaceClientLike;
+/** Parsed three-level Unity Catalog name. */
+interface StoreName {
+  catalog: string;
+  schema: string;
+  name: string;
+}
+/**
+ * Error thrown for a non-2xx memory-store response. Carries the HTTP
+ * status so callers can distinguish "feature unavailable / store
+ * missing" (probe falls back) from genuine failures.
+ */
+declare class ManagedMemoryError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  constructor(status: number, statusText: string, body: string);
+}
+/**
+ * Split a three-level `catalog.schema.name` into its parts. Throws when
+ * the input isn't exactly three dot-separated, non-empty segments so a
+ * misconfigured `MEMORY_STORE` fails loudly at setup rather than
+ * silently hitting a malformed URL.
+ */
+declare function parseStoreName(fullName: string): StoreName;
+/**
+ * Fetch a store by full name. Returns the raw store payload when it
+ * exists, or `null` on 404 so callers can treat "missing" as a normal
+ * condition (the capability probe and `ensureStore` both rely on this).
+ * Any other non-2xx status throws.
+ */
+declare function getStore(client: WorkspaceClient$1, fullName: string, signal?: AbortSignal): Promise<unknown | null>;
+/**
+ * Probe for the store and create it when missing. Returns `true` when
+ * the store exists (found or created). The create body splits the
+ * three-level name into the catalog / schema / name fields the API
+ * expects. A `getStore` 404 followed by a successful create is the
+ * common first-run path.
+ */
+declare function ensureStore(client: WorkspaceClient$1, fullName: string, description: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Write (upsert) an entry into the store under `scope`. Scope is the
+ * OBO user id resolved in trusted code; it travels as a query parameter
+ * so the API isolates one user's memories from another's.
+ */
+declare function writeEntry(client: WorkspaceClient$1, fullName: string, scope: string, entry: {
+  path: string;
+  contents: string;
+  description?: string;
+}, signal?: AbortSignal): Promise<void>;
+/**
+ * Semantic search over a user's entries within `scope`. Returns up to
+ * `topK` entries, parsed defensively so a renamed / missing Beta field
+ * degrades to an empty list rather than crashing the turn.
+ */
+declare function search(client: WorkspaceClient$1, fullName: string, scope: string, query: string, topK: number, signal?: AbortSignal): Promise<MemoryEntry[]>;
+//#endregion
+//#region packages/appkit-mastra/src/connectors/managed-memory/context.d.ts
+/** Resolved per-request memory context: the client to call and the scope. */
+interface MemoryRequestContext {
+  client: appkitUtils.WorkspaceClientLike;
+  scope: string;
+}
+/**
+ * Resolve the OBO-scoped workspace client and the memory scope for the
+ * current turn. Mirrors `model.ts`: prefer the AppKit user stamped on
+ * the request context, fall back to the ambient execution context (the
+ * active OBO scope or the service principal). Scope is the Mastra
+ * resource id (the per-user thread owner) when present, else the user
+ * id. Returns `null` when neither yields a usable scope.
+ */
+declare function resolveMemoryContext(requestContext: RequestContext | undefined): MemoryRequestContext | null;
+//#endregion
+//#region packages/appkit-mastra/src/connectors/managed-memory/defaults.d.ts
+/**
+ * Default values and environment variable names for the managed-memory
+ * connector. Kept in a leaf module so the client, tools, recall
+ * processor, and plugin setup can share them without a cycle.
+ */
+/**
+ * Environment variable holding the three-level Unity Catalog store name
+ * (`catalog.schema.name`). Read when {@link ManagedMemoryConfig.store}
+ * is omitted; also the sole enable signal in prefer-if-available mode
+ * (managed memory stays off when it is unset).
+ */
+declare const MEMORY_STORE_ENV = "MEMORY_STORE";
+/**
+ * Default number of entries the recall processor injects and
+ * `search_memory` returns. Matches the prior `PgVector`
+ * `semanticRecall.topK` so behavior is unchanged after the swap.
+ */
+declare const DEFAULT_TOPK = 3;
+/**
+ * Default path `save_memory` writes land under. Managed Memory keys
+ * entries by path within a scope, so a single stable path accumulates a
+ * user's notes rather than scattering them.
+ */
+declare const DEFAULT_ENTRY_PATH = "/memories/notes.md";
+/** Description stamped on the store when the connector auto-creates it. */
+declare const DEFAULT_STORE_DESCRIPTION = "Long-term agent memory managed by @dbx-tools/appkit-mastra.";
+//#endregion
+//#region packages/appkit-mastra/src/connectors/managed-memory/resolve.d.ts
+/**
+ * Fully-resolved managed-memory target: everything `plugin.ts` needs to
+ * probe the API, optionally create the store, and (on success) build
+ * the runtime / tools / recall processor.
+ */
+interface ManagedMemoryTarget {
+  storeName: string;
+  description: string;
+  topK: number;
+  entryPath: string;
+  autoCreate: boolean;
+  recall: boolean;
+  tools: boolean;
+}
+/**
+ * Resolve the managed-memory target from config + env, or `null` when
+ * managed memory is disabled. Throws when explicitly enabled but no
+ * store name can be resolved (config or `MEMORY_STORE`), so a
+ * misconfiguration surfaces at setup rather than silently falling back.
+ */
+declare function resolveManagedMemoryTarget(config: MastraPluginConfig): ManagedMemoryTarget | null;
+//#endregion
+//#region packages/appkit-mastra/src/connectors/managed-memory/tools.d.ts
+/** Mastra tool record shape (kept local to avoid an `agents.ts` cycle). */
+type MastraTools$1 = Record<string, ReturnType<typeof createTool$1>>;
+/**
+ * Build the `save_memory` / `search_memory` tool pair bound to a
+ * resolved managed-memory runtime. The runtime supplies the store name,
+ * recall size, and default entry path; the per-request client and scope
+ * are resolved inside each `execute`.
+ */
+declare function buildManagedMemoryTools(runtime: ManagedMemoryRuntime): MastraTools$1;
+/** Render an entry to a single recall line (summary prefix when present). */
+declare function renderEntry(entry: MemoryEntry): string;
+//#endregion
 //#region packages/appkit-mastra/src/mcp.d.ts
 /**
  * A built MCP server plus the request paths it answers on, relative to
@@ -1032,7 +1315,32 @@ declare class MastraServer$1 extends MastraServer {
    * response header so dev tools can copy it from either side.
    */
   configureRequestContextRequestId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  /**
+   * Resolve the thread id this request targets and pin it on
+   * `RequestContext` (consumed by the agent stream for persistence and
+   * by the history / threads routes). Resolution order:
+   *
+   *   1. A client-supplied thread id (the thread-selection header /
+   *      `?threadId=` query). This is how the chat UI references a
+   *      specific conversation among the many a user owns - it picks a
+   *      thread id from the `/threads` listing (or mints one for a new
+   *      conversation) and stamps it here. The id is scoped to the
+   *      caller's resource by the recall / list routes, so a client
+   *      can only ever read or write its own threads.
+   *   2. The per-session cookie (`appkit_<plugin-name>_session_id`),
+   *      minted on first contact. This is the default single-thread
+   *      fallback for clients that don't manage threads explicitly, so
+   *      existing embeds keep one stable conversation per session with
+   *      no client changes.
+   */
   configureRequestContextThreadId(req: express.Request, res: express.Response, requestContext: RequestContext): void;
+  /**
+   * Read the client-selected thread id from the request, preferring
+   * the thread-selection header over the `?threadId=` query. Returns
+   * `null` when neither carries a non-empty value so the caller falls
+   * back to the session cookie.
+   */
+  private readRequestedThreadId;
   configureRequestContextModelOverride(req: express.Request, requestContext: RequestContext): void;
 }
 //#endregion
@@ -1192,6 +1500,25 @@ declare class MastraPlugin extends Plugin<MastraPluginConfig> {
    * `getExecutionContext()` returns the OBO-scoped client.
    */
   private listModels;
+  /**
+   * Resolve and probe the Databricks Managed Memory backend at setup.
+   *
+   * Returns the runtime (store + recall sizing + tool / recall toggles)
+   * when managed memory is enabled and the workspace memory-stores API
+   * is reachable, else `undefined` so the caller uses the PgVector path.
+   *
+   * The probe runs as the service principal (setup is outside any
+   * `asUser` scope, so `getExecutionContext()` yields the SP client):
+   * the SP owns the store and is the identity that can `CREATE MEMORY
+   * STORE`. When `autoCreate` is on the store is created if missing.
+   *
+   * A misconfiguration where managed memory is explicitly enabled but no
+   * store name is resolvable throws ({@link resolveManagedMemoryTarget})
+   * - that is a wiring bug, not a runtime condition. Every other failure
+   * (feature unavailable, permission denied, network) is caught, logged,
+   * and degraded to a PgVector fallback so chat stays available.
+   */
+  private resolveManagedMemory;
   private buildAgentAndServer;
 }
 declare const mastra: _databricks_appkit0.ToPlugin<typeof MastraPlugin, MastraPluginConfig, "mastra">;
@@ -1229,4 +1556,36 @@ interface ModelOverrideRequest {
  */
 declare function extractModelOverride(req: ModelOverrideRequest): string | null;
 //#endregion
-export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_GENIE_ALIAS, DEFAULT_STYLE_INSTRUCTIONS, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MastraAgentDefinition, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildMcpServer, buildRenderDataTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, extractModelOverride, fetchChart, mastra, normalizeGenieSpaces, prepareChart, resolveGenieSpaces, tool };
+//#region packages/appkit-mastra/src/summarize.d.ts
+/** Options accepted by {@link summarizeText}. */
+interface SummarizeOptions {
+  /** Extra guidance for the summary (length, focus, format). */
+  instructions?: string;
+  /** Soft cap on summary length, in words. */
+  maxWords?: number;
+  /** Active request context, so the model resolver mints user-scoped tokens. */
+  requestContext?: RequestContext;
+  /** Abort signal bridged from the calling tool / request. */
+  abortSignal?: AbortSignal;
+}
+/**
+ * Summarize `text` with the small-tier summarizer agent, returning the
+ * trimmed summary string. Throws on model failure (the caller decides
+ * how to degrade).
+ */
+declare function summarizeText(config: MastraPluginConfig, text: string, options?: SummarizeOptions): Promise<string>;
+/**
+ * Build the `summarize` tool. Exposed as an ambient system tool (like
+ * `render_data`) so every agent can offload condensing long content,
+ * notes, transcripts, or bulky tool results to the fast tier instead of
+ * spending its primary chat model. The tool reads the live
+ * `requestContext` / `abortSignal` off the Mastra execution context so
+ * its model call stays user-scoped and cancels with the turn.
+ */
+declare function buildSummarizeTool(config: MastraPluginConfig): _mastra_core_tools0.Tool<{
+  text: string;
+  instructions?: string | undefined;
+  maxWords?: number | undefined;
+}, unknown, unknown, unknown, _mastra_core_tools0.ToolExecutionContext<unknown, unknown, unknown>, "summarize", unknown>;
+//#endregion
+export { AppKitToolOptions, BuiltAgents, ChartPlannerRequest, DEFAULT_AGENT_MAX_STEPS, DEFAULT_ENTRY_PATH, DEFAULT_GENIE_ALIAS, DEFAULT_STORE_DESCRIPTION, DEFAULT_STYLE_INSTRUCTIONS, DEFAULT_TOPK, FALLBACK_AGENT_ID, FetchChartOptions, GENIE_INSTRUCTIONS, GenieSpaceConfig, GenieSpacesConfig, MASTRA_MODEL_OVERRIDE_KEY, MASTRA_REQUEST_ID_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, MASTRA_USER_NAME_KEY, MEMORY_STORE_ENV, ManagedMemoryConfig, ManagedMemoryError, ManagedMemoryRuntime, ManagedMemoryTarget, MastraAgentDefinition, MastraMcpConfig, MastraMemoryConfig, MastraMemoryConfigOverride, MastraPlugin, MastraPluginConfig, MastraPluginToolkitProvider, MastraPlugins, MastraStorageConfigOverride, MastraTools, MastraToolsFn, MemoryEntry, MemoryRequestContext, type ModelOverrideRequest, PrepareChartOptions, ResolvedMcp, type SummarizeOptions, TRACE_REQUEST_CONTEXT_KEYS, ToolkitOptions, User, buildAgents, buildGenieToolkitProvider, buildGenieTools, buildManagedMemoryTools, buildMcpServer, buildRenderDataTool, buildSummarizeTool, chartPlannerRequestSchema, collectSpaceSuggestions, createAgent, createTool, ensureStore, extractModelOverride, fetchChart, getStore, mastra, normalizeGenieSpaces, parseStoreName, prepareChart, renderEntry, resolveGenieSpaces, resolveManagedMemoryTarget, resolveMemoryContext, search, summarizeText, tool, writeEntry };