@dbx-tools/appkit-mastra 0.3.44 → 0.4.0

package/lib/src/summarize.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Small-tier summarization for the Mastra plugin.
+ *
+ * Two surfaces, both backed by the fast / small chat tier
+ * ({@link model.ModelClass.ChatFast}) resolved through the same
+ * `/serving-endpoints` pipeline as the main agents:
+ *
+ *   - A dedicated `summarize` tool (see {@link buildSummarizeTool})
+ *     agents can call to condense arbitrary text without burning the
+ *     heavyweight chat model.
+ *   - The model + instructions Mastra's memory uses to auto-name
+ *     conversation threads (`generateTitle`), so titling reuses the
+ *     same small tier rather than the agent's primary model.
+ *
+ * Mirrors the chart-planner wiring in `chart.ts`: a per-config cached
+ * `Agent` on the fast tier, invoked via `agent.generate(...)` inside
+ * the active `asUser` scope so tokens stay user-scoped.
+ *
+ * @module
+ */
+import type { MastraModelConfig } from "@mastra/core/llm";
+import type { RequestContext } from "@mastra/core/request-context";
+import type { MastraPluginConfig } from "./config.js";
+/**
+ * Instructions Mastra's `generateTitle` hands the small-tier model to
+ * name a conversation thread from its opening turn. Kept terse so the
+ * model returns a bare title with no decoration.
+ */
+export declare const TITLE_INSTRUCTIONS: string;
+/**
+ * Resolve the small-tier model for summarization / titling. Reused by
+ * both the summarizer agent and Mastra memory's `generateTitle`.
+ *
+ * Returned as a `requestContext`-taking function (a Mastra
+ * `DynamicArgument<MastraModelConfig>`) so each call mints user-scoped
+ * tokens via {@link buildModel}, exactly like the primary agents.
+ */
+export declare function summaryModel(config: MastraPluginConfig): (args: {
+    requestContext: RequestContext;
+}) => Promise<MastraModelConfig>;
+/** Options accepted by {@link summarizeText}. */
+export 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).
+ */
+export 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.
+ */
+export declare function buildSummarizeTool(config: MastraPluginConfig): import("@mastra/core/tools").Tool<{
+    text: string;
+    instructions?: string | undefined;
+    maxWords?: number | undefined;
+}, unknown, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "summarize", unknown>;

package/lib/src/summarize.js

@@ -0,0 +1,142 @@
+/**
+ * Small-tier summarization for the Mastra plugin.
+ *
+ * Two surfaces, both backed by the fast / small chat tier
+ * ({@link model.ModelClass.ChatFast}) resolved through the same
+ * `/serving-endpoints` pipeline as the main agents:
+ *
+ *   - A dedicated `summarize` tool (see {@link buildSummarizeTool})
+ *     agents can call to condense arbitrary text without burning the
+ *     heavyweight chat model.
+ *   - The model + instructions Mastra's memory uses to auto-name
+ *     conversation threads (`generateTitle`), so titling reuses the
+ *     same small tier rather than the agent's primary model.
+ *
+ * Mirrors the chart-planner wiring in `chart.ts`: a per-config cached
+ * `Agent` on the fast tier, invoked via `agent.generate(...)` inside
+ * the active `asUser` scope so tokens stay user-scoped.
+ *
+ * @module
+ */
+import { string } from "@dbx-tools/shared-core";
+import { model } from "@dbx-tools/shared-model";
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { buildModel } from "./model.js";
+/** Fast / small chat tier used for both titling and summaries. */
+const SUMMARY_MODEL_CLASS = model.ModelClass.ChatFast;
+/** System prompt for the summarizer agent (and the `summarize` tool). */
+const SUMMARIZER_INSTRUCTIONS = [
+    "You are a summarization engine.",
+    "Given a block of text, produce a faithful, concise summary of it.",
+    "Default to a few sentences; follow any length guidance the caller gives.",
+    "Plain prose. No preamble, no headers, no bullet points unless asked.",
+    "Never use emojis. Use hyphens (-) only, never em dashes or en dashes.",
+    "Never add information, opinions, or details not present in the input.",
+    "Output only the summary.",
+].join("\n");
+/**
+ * Instructions Mastra's `generateTitle` hands the small-tier model to
+ * name a conversation thread from its opening turn. Kept terse so the
+ * model returns a bare title with no decoration.
+ */
+export const TITLE_INSTRUCTIONS = [
+    "Generate a short, specific title for this conversation, 3 to 6 words.",
+    "Capture the user's topic, not the assistant's response.",
+    "Plain text only: no surrounding quotes, no trailing punctuation,",
+    "no emojis, and no em dashes. Output only the title.",
+].join(" ");
+/**
+ * Resolve the small-tier model for summarization / titling. Reused by
+ * both the summarizer agent and Mastra memory's `generateTitle`.
+ *
+ * Returned as a `requestContext`-taking function (a Mastra
+ * `DynamicArgument<MastraModelConfig>`) so each call mints user-scoped
+ * tokens via {@link buildModel}, exactly like the primary agents.
+ */
+export function summaryModel(config) {
+    return ({ requestContext }) => buildModel(config, requestContext, { modelClass: SUMMARY_MODEL_CLASS });
+}
+/**
+ * One summarizer `Agent` per plugin config, cached on config-object
+ * identity so a hot tool path doesn't pay the constructor cost each
+ * call. `WeakMap` lets retired configs (e.g. test reconfigurations)
+ * release their agent without manual eviction.
+ */
+const summarizerAgents = new WeakMap();
+function getSummarizerAgent(config) {
+    let agent = summarizerAgents.get(config);
+    if (!agent) {
+        agent = new Agent({
+            id: "summarizer",
+            name: "Summarizer",
+            description: "Condenses text into a short summary using a fast, small model.",
+            instructions: SUMMARIZER_INSTRUCTIONS,
+            model: summaryModel(config),
+        });
+        summarizerAgents.set(config, agent);
+    }
+    return agent;
+}
+/** Inputs accepted by the `summarize` tool. */
+const summarizeInput = z.object({
+    text: z.string().min(1).describe("The text to summarize."),
+    instructions: z
+        .string()
+        .optional()
+        .describe("Optional extra guidance for the summary, e.g. 'one sentence' or 'list the action items'."),
+    maxWords: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional soft cap on the summary length, in words."),
+});
+/**
+ * Summarize `text` with the small-tier summarizer agent, returning the
+ * trimmed summary string. Throws on model failure (the caller decides
+ * how to degrade).
+ */
+export async function summarizeText(config, text, options = {}) {
+    const { instructions, maxWords, requestContext, abortSignal } = options;
+    const prompt = string.toDescription({
+        ...(instructions ? { Guidance: instructions } : {}),
+        ...(maxWords !== undefined ? { "Max length (words)": String(maxWords) } : {}),
+        Text: text,
+    });
+    const result = await getSummarizerAgent(config).generate(prompt, {
+        ...(requestContext ? { requestContext } : {}),
+        ...(abortSignal ? { abortSignal } : {}),
+    });
+    return result.text.trim();
+}
+/**
+ * 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.
+ */
+export function buildSummarizeTool(config) {
+    return createTool({
+        id: "summarize",
+        description: "Summarize a block of text using a fast, small model. Use it to condense long " +
+            "content, notes, transcripts, or tool results into a short summary without " +
+            "spending the main chat model.",
+        inputSchema: summarizeInput,
+        execute: async (input, context) => {
+            const { text, instructions, maxWords } = input;
+            const ctx = context;
+            const summary = await summarizeText(config, text, {
+                ...(instructions ? { instructions } : {}),
+                ...(maxWords !== undefined ? { maxWords } : {}),
+                ...(ctx?.requestContext ? { requestContext: ctx.requestContext } : {}),
+                ...(ctx?.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
+            });
+            return { summary };
+        },
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3VtbWFyaXplLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3N1bW1hcml6ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW1CRztBQUVILE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUNoRCxPQUFPLEVBQUUsS0FBSyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDaEQsT0FBTyxFQUFFLEtBQUssRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBRzNDLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUNoRCxPQUFPLEVBQUUsQ0FBQyxFQUFFLE1BQU0sS0FBSyxDQUFDO0FBR3hCLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFFckMsa0VBQWtFO0FBQ2xFLE1BQU0sbUJBQW1CLEdBQUcsS0FBSyxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUM7QUFFdEQseUVBQXlFO0FBQ3pFLE1BQU0sdUJBQXVCLEdBQUc7SUFDOUIsaUNBQWlDO0lBQ2pDLG1FQUFtRTtJQUNuRSwwRUFBMEU7SUFDMUUsc0VBQXNFO0lBQ3RFLHVFQUF1RTtJQUN2RSx1RUFBdUU7SUFDdkUsMEJBQTBCO0NBQzNCLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0FBRWI7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLGtCQUFrQixHQUFHO0lBQ2hDLHVFQUF1RTtJQUN2RSx5REFBeUQ7SUFDekQsa0VBQWtFO0lBQ2xFLHFEQUFxRDtDQUN0RCxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztBQUVaOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLFVBQVUsWUFBWSxDQUMxQixNQUEwQjtJQUUxQixPQUFPLENBQUMsRUFBRSxjQUFjLEVBQUUsRUFBRSxFQUFFLENBQzVCLFVBQVUsQ0FBQyxNQUFNLEVBQUUsY0FBYyxFQUFFLEVBQUUsVUFBVSxFQUFFLG1CQUFt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QyxDQUFDO1lBQ2pGLE1BQU0sR0FBRyxHQUFHLE9BQ2dFLENBQUM7WUFDN0UsTUFBTSxPQUFPLEdBQUcsTUFBTSxhQUFhLENBQUMsTUFBTSxFQUFFLElBQUksRUFBRTtnQkFDaEQsR0FBRyxDQUFDLFlBQVksQ0FBQyxDQUFDLENBQUMsRUFBRSxZQUFZLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUN6QyxHQUFHLENBQUMsUUFBUSxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUMvQyxHQUFHLENBQUMsR0FBRyxFQUFFLGNBQWMsQ0FBQyxDQUFDLENBQUMsRUFBRSxjQUFjLEVBQUUsR0FBRyxDQUFDLGNBQWMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7Z0JBQ3RFLEdBQUcsQ0FBQyxHQUFHLEVBQUUsV0FBVyxDQUFDLENBQUMsQ0FBQyxFQUFFLFdBQVcsRUFBRSxHQUFHLENBQUMsV0FBVyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQzthQUM5RCxDQUFDLENBQUM7WUFDSCxPQUFPLEVBQUUsT0FBTyxFQUFFLENBQUM7UUFDckIsQ0FBQztLQUNGLENBQUMsQ0FBQztBQUNMLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFNtYWxsLXRpZXIgc3VtbWFyaXphdGlvbiBmb3IgdGhlIE1hc3RyYSBwbHVnaW4uXG4gKlxuICogVHdvIHN1cmZhY2VzLCBib3RoIGJhY2tlZCBieSB0aGUgZmFzdCAvIHNtYWxsIGNoYXQgdGllclxuICogKHtAbGluayBtb2RlbC5Nb2RlbENsYXNzLkNoYXRGYXN0fSkgcmVzb2x2ZWQgdGhyb3VnaCB0aGUgc2FtZVxuICogYC9zZXJ2aW5nLWVuZHBvaW50c2AgcGlwZWxpbmUgYXMgdGhlIG1haW4gYWdlbnRzOlxuICpcbiAqICAgLSBBIGRlZGljYXRlZCBgc3VtbWFyaXplYCB0b29sIChzZWUge0BsaW5rIGJ1aWxkU3VtbWFyaXplVG9vbH0pXG4gKiAgICAgYWdlbnRzIGNhbiBjYWxsIHRvIGNvbmRlbnNlIGFyYml0cmFyeSB0ZXh0IHdpdGhvdXQgYnVybmluZyB0aGVcbiAqICAgICBoZWF2eXdlaWdodCBjaGF0IG1vZGVsLlxuICogICAtIFRoZSBtb2RlbCArIGluc3RydWN0aW9ucyBNYXN0cmEncyBtZW1vcnkgdXNlcyB0byBhdXRvLW5hbWVcbiAqICAgICBjb252ZXJzYXRpb24gdGhyZWFkcyAoYGdlbmVyYXRlVGl0bGVgKSwgc28gdGl0bGluZyByZXVzZXMgdGhlXG4gKiAgICAgc2FtZSBzbWFsbCB0aWVyIHJhdGhlciB0aGFuIHRoZSBhZ2VudCdzIHByaW1hcnkgbW9kZWwuXG4gKlxuICogTWlycm9ycyB0aGUgY2hhcnQtcGxhbm5lciB3aXJpbmcgaW4gYGNoYXJ0LnRzYDogYSBwZXItY29uZmlnIGNhY2hlZFxuICogYEFnZW50YCBvbiB0aGUgZmFzdCB0aWVyLCBpbnZva2VkIHZpYSBgYWdlbnQuZ2VuZXJhdGUoLi4uKWAgaW5zaWRlXG4gKiB0aGUgYWN0aXZlIGBhc1VzZXJgIHNjb3BlIHNvIHRva2VucyBzdGF5IHVzZXItc2NvcGVkLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBzdHJpbmcgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuaW1wb3J0IHsgbW9kZWwgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtbW9kZWxcIjtcbmltcG9ydCB7IEFnZW50IH0gZnJvbSBcIkBtYXN0cmEvY29yZS9hZ2VudFwiO1xuaW1wb3J0IHR5cGUgeyBNYXN0cmFNb2RlbENvbmZpZyB9IGZyb20gXCJAbWFzdHJhL2NvcmUvbGxtXCI7XG5pbXBvcnQgdHlwZSB7IFJlcXVlc3RDb250ZXh0IH0gZnJvbSBcIkBtYXN0cmEvY29yZS9yZXF1ZXN0LWNvbnRleHRcIjtcbmltcG9ydCB7IGNyZWF0ZVRvb2wgfSBmcm9tIFwiQG1hc3RyYS9jb3JlL3Rvb2xzXCI7XG5pbXBvcnQgeyB6IH0gZnJvbSBcInpvZFwiO1xuXG5pbXBvcnQgdHlwZSB7IE1hc3RyYVBsdWdpbkNvbmZpZyB9IGZyb20gXCIuL2NvbmZpZ1wiO1xuaW1wb3J0IHsgYnVpbGRNb2RlbCB9IGZyb20gXCIuL21vZGVsXCI7XG5cbi8qKiBGYXN0IC8gc21hbGwgY2hhdCB0aWVyIHVzZWQgZm9yIGJvdGggdGl0bGluZyBhbmQgc3VtbWFyaWVzLiAqL1xuY29uc3QgU1VNTUFSWV9NT0RFTF9DTEFTUyA9IG1vZGVsLk1vZGVsQ2xhc3MuQ2hhdEZhc3Q7XG5cbi8qKiBTeXN0ZW0gcHJvbXB0IGZvciB0aGUgc3VtbWFyaXplciBhZ2VudCAoYW5kIHRoZSBgc3VtbWFyaXplYCB0b29sKS4gKi9cbmNvbnN0IFNVTU1BUklaRVJfSU5TVFJVQ1RJT05TID0gW1xuICBcIllvdSBhcmUgYSBzdW1tYXJpemF0aW9uIGVuZ2luZS5cIixcbiAgXCJHaXZlbiBhIGJsb2NrIG9mIHRleHQsIHByb2R1Y2UgYSBmYWl0aGZ1bCwgY29uY2lzZSBzdW1tYXJ5IG9mIGl0LlwiLFxuICBcIkRlZmF1bHQgdG8gYSBmZXcgc2VudGVuY2VzOyBmb2xsb3cgYW55IGxlbmd0aCBndWlkYW5jZSB0aGUgY2FsbGVyIGdpdmVzLlwiLFxuICBcIlBsYWluIHByb3NlLiBObyBwcmVhbWJsZSwgbm8gaGVhZGVycywgbm8gYnVsbGV0IHBvaW50cyB1bmxlc3MgYXNrZWQuXCIsXG4gIFwiTmV2ZXIgdXNlIGVtb2ppcy4gVXNlIGh5cGhlbnMgKC0pIG9ubHksIG5ldmVyIGVtIGRhc2hlcyBvciBlbiBkYXNoZXMuXCIsXG4gIFwiTmV2ZXIgYWRkIGluZm9ybWF0aW9uLCBvcGluaW9ucywgb3IgZGV0YWlscyBub3QgcHJlc2VudCBpbiB0aGUgaW5wdXQuXCIsXG4gIFwiT3V0cHV0IG9ubHkgdGhlIHN1bW1hcnkuXCIsXG5dLmpvaW4oXCJcXG5cIik7XG5cbi8qKlxuICogSW5zdHJ1Y3Rpb25zIE1hc3RyYSdzIGBnZW5lcmF0ZVRpdGxlYCBoYW5kcyB0aGUgc21hbGwtdGllciBtb2RlbCB0b1xuICogbmFtZSBhIGNvbnZlcnNhdGlvbiB0aHJlYWQgZnJvbSBpdHMgb3BlbmluZyB0dXJuLiBLZXB0IHRlcnNlIHNvIHRoZVxuICogbW9kZWwgcmV0dXJucyBhIGJhcmUgdGl0bGUgd2l0aCBubyBkZWNvcmF0aW9uLlxuICovXG5leHBvcnQgY29uc3QgVElUTEVfSU5TVFJVQ1RJT05TID0gW1xuICBcIkdlbmVyYXRlIGEgc2hvcnQsIHNwZWNpZmljIHRpdGxlIGZvciB0aGlzIGNvbnZlcnNhdGlvbiwgMyB0byA2IHdvcmRzLlwiLFxuICBcIkNhcHR1cmUgdGhlIHVzZXIncyB0b3BpYywgbm90IHRoZSBhc3Npc3RhbnQncyByZXNwb25zZS5cIixcbiAgXCJQbGFpbiB0ZXh0IG9ubHk6IG5vIHN1cnJvdW5kaW5nIHF1b3Rlcywgbm8gdHJhaWxpbmcgcHVuY3R1YXRpb24sXCIsXG4gIFwibm8gZW1vamlzLCBhbmQgbm8gZW0gZGFzaGVzLiBPdXRwdXQgb25seSB0aGUgdGl0bGUuXCIsXG5dLmpvaW4oXCIgXCIpO1xuXG4vKipcbiAqIFJlc29sdmUgdGhlIHNtYWxsLXRpZXIgbW9kZWwgZm9yIHN1bW1hcml6YXRpb24gLyB0aXRsaW5nLiBSZXVzZWQgYnlcbiAqIGJvdGggdGhlIHN1bW1hcml6ZXIgYWdlbnQgYW5kIE1hc3RyYSBtZW1vcnkncyBgZ2VuZXJhdGVUaXRsZWAuXG4gKlxuICogUmV0dXJuZWQgYXMgYSBgcmVxdWVzdENvbnRleHRgLXRha2luZyBmdW5jdGlvbiAoYSBNYXN0cmFcbiAqIGBEeW5hbWljQXJndW1lbnQ8TWFzdHJhTW9kZWxDb25maWc+YCkgc28gZWFjaCBjYWxsIG1pbnRzIHVzZXItc2NvcGVkXG4gKiB0b2tlbnMgdmlhIHtAbGluayBidWlsZE1vZGVsfSwgZXhhY3RseSBsaWtlIHRoZSBwcmltYXJ5IGFnZW50cy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHN1bW1hcnlNb2RlbChcbiAgY29uZmlnOiBNYXN0cmFQbHVnaW5Db25maWcsXG4pOiAoYXJnczogeyByZXF1ZXN0Q29udGV4dDogUmVxdWVzdENvbnRleHQgfSkgPT4gUHJvbWlzZTxNYXN0cmFNb2RlbENvbmZpZz4ge1xuICByZXR1cm4gKHsgcmVxdWVzdENvbnRleHQgfSkgPT5cbiAgICBidWlsZE1vZGVsKGNvbmZpZywgcmVxdWVzdENvbnRleHQsIHsgbW9kZWxDbGFzczogU1VNTUFSWV9NT0RFTF9DTEFTUyB9KTtcbn1cblxuLyoqXG4gKiBPbmUgc3VtbWFyaXplciBgQWdlbnRgIHBlciBwbHVnaW4gY29uZmlnLCBjYWNoZWQgb24gY29uZmlnLW9iamVjdFxuICogaWRlbnRpdHkgc28gYSBob3QgdG9vbCBwYXRoIGRvZXNuJ3QgcGF5IHRoZSBjb25zdHJ1Y3RvciBjb3N0IGVhY2hcbiAqIGNhbGwuIGBXZWFrTWFwYCBsZXRzIHJldGlyZWQgY29uZmlncyAoZS5nLiB0ZXN0IHJlY29uZmlndXJhdGlvbnMpXG4gKiByZWxlYXNlIHRoZWlyIGFnZW50IHdpdGhvdXQgbWFudWFsIGV2aWN0aW9uLlxuICovXG5jb25zdCBzdW1tYXJpemVyQWdlbnRzID0gbmV3IFdlYWtNYXA8TWFzdHJhUGx1Z2luQ29uZmlnLCBBZ2VudD4oKTtcblxuZnVuY3Rpb24gZ2V0U3VtbWFyaXplckFnZW50KGNvbmZpZzogTWFzdHJhUGx1Z2luQ29uZmlnKTogQWdlbnQge1xuICBsZXQgYWdlbnQgPSBzdW1tYXJpemVyQWdlbnRzLmdldChjb25maWcpO1xuICBpZiAoIWFnZW50KSB7XG4gICAgYWdlbnQgPSBuZXcgQWdlbnQoe1xuICAgICAgaWQ6IFwic3VtbWFyaXplclwiLFxuICAgICAgbmFtZTogXCJTdW1tYXJpemVyXCIsXG4gICAgICBkZXNjcmlwdGlvbjogXCJDb25kZW5zZXMgdGV4dCBpbnRvIGEgc2hvcnQgc3VtbWFyeSB1c2luZyBhIGZhc3QsIHNtYWxsIG1vZGVsLlwiLFxuICAgICAgaW5zdHJ1Y3Rpb25zOiBTVU1NQVJJWkVSX0lOU1RSVUNUSU9OUyxcbiAgICAgIG1vZGVsOiBzdW1tYXJ5TW9kZWwoY29uZmlnKSxcbiAgICB9KTtcbiAgICBzdW1tYXJpemVyQWdlbnRzLnNldChjb25maWcsIGFnZW50KTtcbiAgfVxuICByZXR1cm4gYWdlbnQ7XG59XG5cbi8qKiBJbnB1dHMgYWNjZXB0ZWQgYnkgdGhlIGBzdW1tYXJpemVgIHRvb2wuICovXG5jb25zdCBzdW1tYXJpemVJbnB1dCA9IHoub2JqZWN0KHtcbiAgdGV4dDogei5zdHJpbmcoKS5taW4oMSkuZGVzY3JpYmUoXCJUaGUgdGV4dCB0byBzdW1tYXJpemUuXCIpLFxuICBpbnN0cnVjdGlvbnM6IHpcbiAgICAuc3RyaW5nKClcbiAgICAub3B0aW9uYWwoKVxuICAgIC5kZXNjcmliZShcbiAgICAgIFwiT3B0aW9uYWwgZXh0cmEgZ3VpZGFuY2UgZm9yIHRoZSBzdW1tYXJ5LCBlLmcuICdvbmUgc2VudGVuY2UnIG9yICdsaXN0IHRoZSBhY3Rpb24gaXRlbXMnLlwiLFxuICAgICksXG4gIG1heFdvcmRzOiB6XG4gICAgLm51bWJlcigpXG4gICAgLmludCgpXG4gICAgLnBvc2l0aXZlKClcbiAgICAub3B0aW9uYWwoKVxuICAgIC5kZXNjcmliZShcIk9wdGlvbmFsIHNvZnQgY2FwIG9uIHRoZSBzdW1tYXJ5IGxlbmd0aCwgaW4gd29yZHMuXCIpLFxufSk7XG5cbi8qKiBPcHRpb25zIGFjY2VwdGVkIGJ5IHtAbGluayBzdW1tYXJpemVUZXh0fS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU3VtbWFyaXplT3B0aW9ucyB7XG4gIC8qKiBFeHRyYSBndWlkYW5jZSBmb3IgdGhlIHN1bW1hcnkgKGxlbmd0aCwgZm9jdXMsIGZvcm1hdCkuICovXG4gIGluc3RydWN0aW9ucz86IHN0cmluZztcbiAgLyoqIFNvZnQgY2FwIG9uIHN1bW1hcnkgbGVuZ3RoLCBpbiB3b3Jkcy4gKi9cbiAgbWF4V29yZHM/OiBudW1iZXI7XG4gIC8qKiBBY3RpdmUgcmVxdWVzdCBjb250ZXh0LCBzbyB0aGUgbW9kZWwgcmVzb2x2ZXIgbWludHMgdXNlci1zY29wZWQgdG9rZW5zLiAqL1xuICByZXF1ZXN0Q29udGV4dD86IFJlcXVlc3RDb250ZXh0O1xuICAvKiogQWJvcnQgc2lnbmFsIGJyaWRnZWQgZnJvbSB0aGUgY2FsbGluZyB0b29sIC8gcmVxdWVzdC4gKi9cbiAgYWJvcnRTaWduYWw/OiBBYm9ydFNpZ25hbDtcbn1cblxuLyoqXG4gKiBTdW1tYXJpemUgYHRleHRgIHdpdGggdGhlIHNtYWxsLXRpZXIgc3VtbWFyaXplciBhZ2VudCwgcmV0dXJuaW5nIHRoZVxuICogdHJpbW1lZCBzdW1tYXJ5IHN0cmluZy4gVGhyb3dzIG9uIG1vZGVsIGZhaWx1cmUgKHRoZSBjYWxsZXIgZGVjaWRlc1xuICogaG93IHRvIGRlZ3JhZGUpLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gc3VtbWFyaXplVGV4dChcbiAgY29uZmlnOiBNYXN0cmFQbHVnaW5Db25maWcsXG4gIHRleHQ6IHN0cmluZyxcbiAgb3B0aW9uczogU3VtbWFyaXplT3B0aW9ucyA9IHt9LFxuKTogUHJvbWlzZTxzdHJpbmc+IHtcbiAgY29uc3QgeyBpbnN0cnVjdGlvbnMsIG1heFdvcmRzLCByZXF1ZXN0Q29udGV4dCwgYWJvcnRTaWduYWwgfSA9IG9wdGlvbnM7XG4gIGNvbnN0IHByb21wdCA9IHN0cmluZy50b0Rlc2NyaXB0aW9uKHtcbiAgICAuLi4oaW5zdHJ1Y3Rpb25zID8geyBHdWlkYW5jZTogaW5zdHJ1Y3Rpb25zIH0gOiB7fSksXG4gICAgLi4uKG1heFdvcmRzICE9PSB1bmRlZmluZWQgPyB7IFwiTWF4IGxlbmd0aCAod29yZHMpXCI6IFN0cmluZyhtYXhXb3JkcykgfSA6IHt9KSxcbiAgICBUZXh0OiB0ZXh0LFxuICB9KTtcbiAgY29uc3QgcmVzdWx0ID0gYXdhaXQgZ2V0U3VtbWFyaXplckFnZW50KGNvbmZpZykuZ2VuZXJhdGUocHJvbXB0LCB7XG4gICAgLi4uKHJlcXVlc3RDb250ZXh0ID8geyByZXF1ZXN0Q29udGV4dCB9IDoge30pLFxuICAgIC4uLihhYm9ydFNpZ25hbCA/IHsgYWJvcnRTaWduYWwgfSA6IHt9KSxcbiAgfSk7XG4gIHJldHVybiByZXN1bHQudGV4dC50cmltKCk7XG59XG5cbi8qKlxuICogQnVpbGQgdGhlIGBzdW1tYXJpemVgIHRvb2wuIEV4cG9zZWQgYXMgYW4gYW1iaWVudCBzeXN0ZW0gdG9vbCAobGlrZVxuICogYHJlbmRlcl9kYXRhYCkgc28gZXZlcnkgYWdlbnQgY2FuIG9mZmxvYWQgY29uZGVuc2luZyBsb25nIGNvbnRlbnQsXG4gKiBub3RlcywgdHJhbnNjcmlwdHMsIG9yIGJ1bGt5IHRvb2wgcmVzdWx0cyB0byB0aGUgZmFzdCB0aWVyIGluc3RlYWQgb2ZcbiAqIHNwZW5kaW5nIGl0cyBwcmltYXJ5IGNoYXQgbW9kZWwuIFRoZSB0b29sIHJlYWRzIHRoZSBsaXZlXG4gKiBgcmVxdWVzdENvbnRleHRgIC8gYGFib3J0U2lnbmFsYCBvZmYgdGhlIE1hc3RyYSBleGVjdXRpb24gY29udGV4dCBzb1xuICogaXRzIG1vZGVsIGNhbGwgc3RheXMgdXNlci1zY29wZWQgYW5kIGNhbmNlbHMgd2l0aCB0aGUgdHVybi5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGJ1aWxkU3VtbWFyaXplVG9vbChjb25maWc6IE1hc3RyYVBsdWdpbkNvbmZpZykge1xuICByZXR1cm4gY3JlYXRlVG9vbCh7XG4gICAgaWQ6IFwic3VtbWFyaXplXCIsXG4gICAgZGVzY3JpcHRpb246XG4gICAgICBcIlN1bW1hcml6ZSBhIGJsb2NrIG9mIHRleHQgdXNpbmcgYSBmYXN0LCBzbWFsbCBtb2RlbC4gVXNlIGl0IHRvIGNvbmRlbnNlIGxvbmcgXCIgK1xuICAgICAgXCJjb250ZW50LCBub3RlcywgdHJhbnNjcmlwdHMsIG9yIHRvb2wgcmVzdWx0cyBpbnRvIGEgc2hvcnQgc3VtbWFyeSB3aXRob3V0IFwiICtcbiAgICAgIFwic3BlbmRpbmcgdGhlIG1haW4gY2hhdCBtb2RlbC5cIixcbiAgICBpbnB1dFNjaGVtYTogc3VtbWFyaXplSW5wdXQsXG4gICAgZXhlY3V0ZTogYXN5bmMgKGlucHV0LCBjb250ZXh0KSA9PiB7XG4gICAgICBjb25zdCB7IHRleHQsIGluc3RydWN0aW9ucywgbWF4V29yZHMgfSA9IGlucHV0IGFzIHouaW5mZXI8dHlwZW9mIHN1bW1hcml6ZUlucHV0PjtcbiAgICAgIGNvbnN0IGN0eCA9IGNvbnRleHQgYXNcbiAgICAgICAgeyByZXF1ZXN0Q29udGV4dD86IFJlcXVlc3RDb250ZXh0OyBhYm9ydFNpZ25hbD86IEFib3J0U2lnbmFsIH0gfCB1bmRlZmluZWQ7XG4gICAgICBjb25zdCBzdW1tYXJ5ID0gYXdhaXQgc3VtbWFyaXplVGV4dChjb25maWcsIHRleHQsIHtcbiAgICAgICAgLi4uKGluc3RydWN0aW9ucyA/IHsgaW5zdHJ1Y3Rpb25zIH0gOiB7fSksXG4gICAgICAgIC4uLihtYXhXb3JkcyAhPT0gdW5kZWZpbmVkID8geyBtYXhXb3JkcyB9IDoge30pLFxuICAgICAgICAuLi4oY3R4Py5yZXF1ZXN0Q29udGV4dCA/IHsgcmVxdWVzdENvbnRleHQ6IGN0eC5yZXF1ZXN0Q29udGV4dCB9IDoge30pLFxuICAgICAgICAuLi4oY3R4Py5hYm9ydFNpZ25hbCA/IHsgYWJvcnRTaWduYWw6IGN0eC5hYm9ydFNpZ25hbCB9IDoge30pLFxuICAgICAgfSk7XG4gICAgICByZXR1cm4geyBzdW1tYXJ5IH07XG4gICAgfSxcbiAgfSk7XG59XG4iXX0=

package/lib/src/threads.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Conversation-thread listing exposed as a Mastra custom API route.
+ *
+ * Backed entirely by native Mastra: looks up the active agent by id,
+ * asks its `Memory` instance to `listThreads` filtered to the caller's
+ * resource, and shapes each into the JSON-safe {@link MastraThread}
+ * wire type. A sibling `DELETE` removes a single named thread.
+ *
+ * A sibling `DELETE` removes a single named thread; a `PATCH` renames
+ * one ({@link renameThread}).
+ *
+ * Like {@link historyRoute} this registers through Mastra's
+ * `registerApiRoute` so it shares the `MastraServer` auth-middleware
+ * pipeline (in `./server.ts`), which has already stamped the resource
+ * id (`MASTRA_RESOURCE_ID_KEY`) and the targeted thread id
+ * (`MASTRA_THREAD_ID_KEY`, resolved from the thread-selection header /
+ * cookie) on `RequestContext` by the time a handler runs. Resource
+ * scoping lives here so a caller can only ever see, rename, or delete
+ * its own threads; no cookie or user lookups happen in this module.
+ *
+ * @module
+ */
+import { type MastraThread, type MastraThreadsResponse } from "@dbx-tools/shared-mastra";
+import type { Agent } from "@mastra/core/agent";
+/** Inputs accepted by {@link listThreads}. */
+export interface ListThreadsOptions {
+    agent: Agent;
+    resourceId: string;
+    page?: number;
+    perPage?: number;
+}
+/**
+ * Fetch a page of the resource's conversation threads, newest
+ * (`updatedAt` DESC) first.
+ *
+ * Uses the agent's resolved `Memory` (`getMemory()`) so the per-agent
+ * storage namespace (`mastra_<agentId>` schema) applies automatically.
+ * When the agent has no memory configured the response is a successful
+ * empty page so callers don't have to special-case stateless agents.
+ */
+export declare function listThreads(opts: ListThreadsOptions): Promise<MastraThreadsResponse>;
+/** Inputs accepted by {@link deleteThread}. */
+export interface DeleteThreadOptions {
+    agent: Agent;
+    threadId: string;
+    resourceId: string;
+}
+/**
+ * Delete a single named thread (and every message on it).
+ *
+ * Ownership is enforced: the thread is only removed when it belongs to
+ * the calling resource, so a client can't delete another user's
+ * conversation by guessing its id. A thread that doesn't exist (or
+ * isn't owned by the caller) is a successful no-op (`deleted: false`)
+ * so the UI can fire-and-forget.
+ */
+export declare function deleteThread(opts: DeleteThreadOptions): Promise<{
+    deleted: boolean;
+}>;
+/** Inputs accepted by {@link renameThread}. */
+export interface RenameThreadOptions {
+    agent: Agent;
+    threadId: string;
+    resourceId: string;
+    title: string;
+}
+/**
+ * Rename a single thread, returning the updated wire thread.
+ *
+ * Ownership is enforced the same way {@link deleteThread} enforces it:
+ * the title is only changed when the thread belongs to the calling
+ * resource, so a client can't rename another user's conversation by
+ * guessing its id. Existing thread `metadata` is preserved untouched
+ * (Mastra's `updateThread` replaces the row, so it must be passed back
+ * in). Returns `null` when the thread doesn't exist, isn't owned by the
+ * caller, or the agent has no memory configured, letting the route map
+ * that to a 404.
+ */
+export declare function renameThread(opts: RenameThreadOptions): Promise<MastraThread | null>;
+/** Options accepted by {@link threadsRoute}. */
+export type ThreadsRouteOptions = {
+    path: `${string}:agentId${string}`;
+    agent?: never;
+} | {
+    path: string;
+    agent: string;
+};
+/**
+ * Register the `<path>` Mastra custom API route. Handles three methods
+ * on the same mount:
+ *
+ *   - `GET`: a page of the resource's conversation threads
+ *     ({@link listThreads}).
+ *   - `DELETE`: remove the thread named by the thread-selection header
+ *     / `?threadId=` query ({@link deleteThread}). The id is read from
+ *     `RequestContext` (the auth middleware resolves it the same way it
+ *     does for streaming and history), so the client deletes any of its
+ *     threads by stamping the target id - no separate path param.
+ *   - `PATCH`: rename the thread named by the thread-selection header /
+ *     `?threadId=` query to the `{ title }` in the JSON body
+ *     ({@link renameThread}). Targets a thread the same way `DELETE`
+ *     does; 404s when the thread isn't owned by the caller.
+ *
+ * Follows the `@mastra/ai-sdk` agent-binding convention: pass `agent`
+ * for a fixed-agent mount, or include `:agentId` in the path for
+ * dynamic routing. The plugin registers both `/route/threads` (default
+ * agent) and `/route/threads/:agentId`.
+ */
+export declare function threadsRoute(options: ThreadsRouteOptions): import("@mastra/core/server").ApiRoute[];