@dbx-tools/appkit-mastra 0.1.4 → 0.1.12

package/src/history.ts

@@ -0,0 +1,210 @@
+/**
+ * Thread history loader exposed as a Mastra custom API route.
+ *
+ * Backed entirely by native Mastra: looks up the active agent by id,
+ * asks its `Memory` instance to `recall` a page of `MastraDBMessage`s,
+ * and converts the result to AI SDK V5 `UIMessage`s with the official
+ * {@link toAISdkV5Messages} helper from `@mastra/ai-sdk/ui`. No direct
+ * database reads.
+ *
+ * The route is registered through {@link historyRoute} as a Mastra
+ * `registerApiRoute` so it sits in the same dispatcher pipeline as
+ * `chatRoute`. That means the `MastraServer` auth middleware (in
+ * `./server.ts`) has already populated `RequestContext` with
+ * `MASTRA_THREAD_ID_KEY` and `MASTRA_RESOURCE_ID_KEY` by the time
+ * the handler runs - no cookie or user lookups happen here, and the
+ * session-cookie logic stays the single source of truth in `server.ts`.
+ */
+
+import { logUtils } from "@dbx-tools/appkit-shared";
+import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
+import type { Agent } from "@mastra/core/agent";
+import type { MastraDBMessage } from "@mastra/core/agent/message-list";
+import {
+  MASTRA_RESOURCE_ID_KEY,
+  MASTRA_THREAD_ID_KEY,
+} from "@mastra/core/request-context";
+import { registerApiRoute } from "@mastra/core/server";
+import type { ContextWithMastra } from "@mastra/core/server";
+import type {
+  MastraHistoryResponse,
+  MastraHistoryUIMessage,
+} from "@dbx-tools/appkit-mastra-shared";
+
+const log = logUtils.logger("mastra/history");
+
+/** Default history page size; matches the Mastra storage default. */
+const DEFAULT_PER_PAGE = 20;
+/** Hard cap so a misbehaving client can't fetch the whole thread at once. */
+const MAX_PER_PAGE = 200;
+
+/** Inputs accepted by {@link loadHistory}. */
+export interface LoadHistoryOptions {
+  agent: Agent;
+  threadId: string;
+  resourceId?: string;
+  page?: number;
+  perPage?: number;
+  /** When true, returns the *oldest* page first (chronological). */
+  ascending?: boolean;
+}
+
+/**
+ * Fetch a page of UI-formatted messages for a thread.
+ *
+ * Uses the agent's resolved `Memory` (`getMemory()`) so per-agent
+ * storage namespaces (`mastra_<agentId>` schemas) and any future
+ * memory-side filters apply 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.
+ *
+ * Pagination is descending-by-default: page 0 is the most recent
+ * page, page 1 the page before that, etc. The returned `uiMessages`
+ * are always re-sorted into chronological order (oldest -> newest)
+ * so the client can prepend them above the existing transcript
+ * without sorting locally.
+ */
+export async function loadHistory(
+  opts: LoadHistoryOptions,
+): Promise<MastraHistoryResponse> {
+  const perPage = clampPerPage(opts.perPage);
+  const page = Math.max(0, Math.trunc(opts.page ?? 0));
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    log.debug("recall:no-memory", { agentId: opts.agent.id, threadId: opts.threadId });
+    return { uiMessages: [], page, perPage, total: 0, hasMore: false };
+  }
+  const startedAt = Date.now();
+  const result = await memory.recall({
+    threadId: opts.threadId,
+    ...(opts.resourceId ? { resourceId: opts.resourceId } : {}),
+    page,
+    perPage,
+    orderBy: {
+      field: "createdAt",
+      direction: opts.ascending ? "ASC" : "DESC",
+    },
+  });
+  const chronological = sortChronological(result.messages);
+  const uiMessages = toAISdkV5Messages(
+    chronological,
+  ) as unknown as MastraHistoryUIMessage[];
+  log.debug("recall:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    page,
+    perPage,
+    returned: uiMessages.length,
+    total: result.total,
+    hasMore: result.hasMore,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return {
+    uiMessages,
+    page,
+    perPage,
+    total: result.total,
+    hasMore: result.hasMore,
+  };
+}
+
+/** Options accepted by {@link historyRoute}. */
+export type HistoryRouteOptions =
+  | { path: `${string}:agentId${string}`; agent?: never }
+  | { path: string; agent: string };
+
+/**
+ * Register a `GET <path>` Mastra custom API route that returns a page
+ * of AI SDK V5 `UIMessage`s for the caller's current thread.
+ *
+ * Modeled after `chatRoute` from `@mastra/ai-sdk`: pass `agent` for a
+ * fixed-agent mount, or include `:agentId` in the path for dynamic
+ * routing. Pairs cleanly with the AppKit Mastra plugin's chat route
+ * layout (`/route/chat` + `/route/chat/:agentId`).
+ *
+ * The handler reads `threadId` and `resourceId` from `RequestContext`
+ * (populated upstream by `MastraServer.registerAuthMiddleware`), so
+ * no cookie or user lookups happen here.
+ */
+export function historyRoute(options: HistoryRouteOptions) {
+  const { path } = options;
+  const fixedAgent = "agent" in options ? options.agent : undefined;
+  if (!fixedAgent && !path.includes(":agentId")) {
+    throw new Error(
+      "historyRoute path must include `:agentId` or `agent` must be passed explicitly",
+    );
+  }
+  return registerApiRoute(path, {
+    method: "GET",
+    handler: async (c: ContextWithMastra) => {
+      const mastra = c.get("mastra");
+      const requestContext = c.get("requestContext");
+      const agentId = fixedAgent ?? c.req.param("agentId");
+      if (!agentId) {
+        return c.json({ error: "agentId is required" }, 400);
+      }
+      const agent = mastra.getAgentById(agentId);
+      if (!agent) {
+        return c.json({ error: `Unknown agent "${agentId}"` }, 404);
+      }
+      const threadId = requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
+      if (!threadId) {
+        return c.json({ error: "thread id missing from request context" }, 400);
+      }
+      const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as
+        | string
+        | undefined;
+      const payload = await loadHistory({
+        agent,
+        threadId,
+        ...(resourceId ? { resourceId } : {}),
+        page: parseIntParam(c.req.query("page")),
+        perPage: parseIntParam(c.req.query("perPage")),
+      });
+      return c.json(payload);
+    },
+  });
+}
+
+/** Coerce / clamp `perPage`; falls back to the page-size default. */
+function clampPerPage(value: number | undefined): number {
+  if (value === undefined || Number.isNaN(value)) return DEFAULT_PER_PAGE;
+  const n = Math.trunc(value);
+  if (n <= 0) return DEFAULT_PER_PAGE;
+  return Math.min(n, MAX_PER_PAGE);
+}
+
+/**
+ * Sort messages oldest-first by `createdAt`, falling back to whatever
+ * order the storage returned them in. The native `recall` call honors
+ * `orderBy` but doesn't guarantee a stable secondary sort, so we
+ * normalize here before handing the page to the AI SDK converter.
+ */
+function sortChronological(messages: MastraDBMessage[]): MastraDBMessage[] {
+  return [...messages].sort((a, b) => {
+    const ta = toEpoch(a.createdAt);
+    const tb = toEpoch(b.createdAt);
+    return ta - tb;
+  });
+}
+
+function toEpoch(value: unknown): number {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "string" || typeof value === "number") {
+    const parsed = new Date(value).getTime();
+    return Number.isNaN(parsed) ? 0 : parsed;
+  }
+  return 0;
+}
+
+/**
+ * Coerce a Hono query value into a non-negative integer. Returns
+ * `undefined` for empty / non-numeric / negative inputs so
+ * {@link loadHistory} can apply its built-in defaults.
+ */
+function parseIntParam(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  return Math.trunc(n);
+}

package/src/memory.ts

@@ -20,7 +20,7 @@
  */
 
 import { lakebase } from "@databricks/appkit";
-import { pluginUtils } from "@dbx-tools/appkit-shared";
+import { logUtils, pluginUtils } from "@dbx-tools/appkit-shared";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
@@ -33,6 +33,8 @@ import type {
 } from "./agents.js";
 import type { MastraPluginConfig } from "./config.js";
 
+const log = logUtils.logger("mastra/memory");
+
 /** Pool handle returned by the AppKit `lakebase` plugin `exports().pool`. */
 export type LakebasePool = ReturnType<
   InstanceType<ReturnType<typeof lakebase>["plugin"]>["exports"]
@@ -109,7 +111,22 @@ export class MemoryBuilder {
 
     const storage = this.buildStorage(agentId, storageSetting);
     const vector = this.buildVector(memorySetting);
-    if (!storage && !vector) return undefined;
+    if (!storage && !vector) {
+      log.debug("agent:stateless", { agentId });
+      return undefined;
+    }
+
+    log.debug("agent:configured", {
+      agentId,
+      storage: storage !== undefined,
+      vector: vector !== undefined,
+      vectorMode:
+        vector === undefined
+          ? "off"
+          : typeof memorySetting === "object"
+            ? "dedicated"
+            : "shared",
+    });
 
     return new Memory({
       ...(storage ? { storage } : {}),

package/src/model.ts

@@ -306,6 +306,7 @@ async function pickModelId(
   user: User,
   host: string,
 ): Promise<string> {
+  const log = logUtils.logger(config);
   const serving = resolveServingConfig(config, FALLBACK_MODEL_IDS);
   const override = serving.allowOverride
     ? (requestContext.get(MASTRA_MODEL_OVERRIDE_KEY) as string | undefined)
@@ -315,7 +316,10 @@ async function pickModelId(
 
   // Cheap exit: when the caller named a specific model and fuzzy
   // matching is off, there's no reason to touch the catalogue at all.
-  if (explicit !== undefined && !serving.fuzzy) return explicit;
+  if (explicit !== undefined && !serving.fuzzy) {
+    log.debug("model selected", { modelId: explicit, source: "explicit" });
+    return explicit;
+  }
 
   const endpoints = await listServingEndpoints(user.executionContext.client, host, {
     ttlMs: serving.ttlMs,
@@ -324,7 +328,11 @@ async function pickModelId(
     explicit !== undefined
       ? resolveModelId(explicit, endpoints, { threshold: serving.threshold }).modelId
       : pickFirstAvailable(serving.fallbacks, endpoints);
-  //logUtils.logger(config).debug(`model selected: ${modelId}`);
+  log.debug("model selected", {
+    modelId,
+    source: explicit !== undefined ? "fuzzy-match" : "fallback",
+    requestedExplicit: explicit,
+  });
   return modelId;
 }
 
@@ -369,9 +377,9 @@ interface ChatMessage {
  *   1. Rewrites the outgoing `messages` array to repair Mastra/AI SDK
  *      stream-replay quirks that Databricks-hosted Claude rejects (see
  *      {@link sanitizeServingMessages}).
- *   2. When `MASTRA_DEBUG_LLM=1`, dumps the (post-sanitize) JSON body
- *      to stderr so 4xx debugging doesn't have to fight AI SDK's
- *      `[Array]` formatter.
+ *   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
+ *      4xx debugging doesn't have to fight AI SDK's `[Array]`
+ *      formatter.
  *
  * Safe to call from any hot path: {@link commonUtils.memoize} ensures
  * the wrapper is installed at most once per process, so subsequent
@@ -379,7 +387,7 @@ interface ChatMessage {
  * {@link buildModel} fires on every agent step.
  */
 const setupFetchInterceptor = commonUtils.memoize((): void => {
-  const debug = Boolean(process.env.MASTRA_DEBUG_LLM);
+  const log = logUtils.logger("mastra/llm");
   const original = globalThis.fetch.bind(globalThis);
   globalThis.fetch = (async (input, init) => {
     const url = httpUtils.toURL(input);
@@ -394,13 +402,10 @@ const setupFetchInterceptor = commonUtils.memoize((): void => {
     if (rewritten !== init.body) {
       init = { ...init, body: rewritten };
     }
-    if (debug) {
-      try {
-        console.error("[mastra:llm-debug] -> POST", url.toString());
-        console.error(JSON.stringify(JSON.parse(rewritten), null, 2));
-      } catch {
-        console.error("[mastra:llm-debug] -> POST", url.toString(), "(non-JSON body)");
-      }
+    try {
+      log.debug("POST", { url: url.toString(), body: JSON.parse(rewritten) });
+    } catch {
+      log.debug("POST", { url: url.toString(), bodyType: "non-JSON" });
     }
     return original(input, init);
   }) as typeof globalThis.fetch;

package/src/plugin.ts

@@ -46,6 +46,7 @@ import express from "express";
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.js";
 import type { MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
 import type { MastraPluginConfig } from "./config.js";
+import { historyRoute } from "./history.js";
 import { createMemoryBuilder, needsLakebase } from "./memory.js";
 import { attachRoutePatchMiddleware, MastraServer } from "./server.js";
 import {
@@ -187,6 +188,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       chatPath: `${basePath}/route/chat`,
       chatPathTemplate: `${basePath}/route/chat/:agentId`,
       modelsPath: `${basePath}/models`,
+      historyPath: `${basePath}/route/history`,
+      historyPathTemplate: `${basePath}/route/history/:agentId`,
       defaultAgent: this.built?.defaultAgentId ?? FALLBACK_AGENT_ID,
       agents: Object.keys(this.built?.agents ?? {}),
     };
@@ -200,7 +203,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // the Mastra subapp. Errors propagate to Express's default error
     // handler via `next(err)` so callers see the real SDK message.
     router.get("/models", (req, res, next) => {
-      this.asUser(req)
+      this.userScopedSelf(req)
         .listModels()
         .then((endpoints) => res.json({ endpoints }))
         .catch(next);
@@ -208,10 +211,23 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
 
     router.use("", (req, res, next) => {
       if (!this.mastraApp) return res.status(503).end();
-      return this.asUser(req).mastraApp!(req, res, next);
+      return this.userScopedSelf(req).mastraApp!(req, res, next);
     });
   }
 
+  /**
+   * 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(req: express.Request): this {
+    return req.header("x-forwarded-access-token") ? (this.asUser(req) as this) : this;
+  }
+
   /**
    * Implementation backing both the `/models` route and the
    * `listModels` export. Runs inside the AppKit user-context proxy so
@@ -233,6 +249,11 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       ? createMemoryBuilder(this.config, this.context)
       : undefined;
 
+    this.log.debug("build:start", {
+      lakebase: memoryBuilder !== undefined,
+      stripStaleCharts: this.config.stripStaleCharts !== false,
+    });
+
     // Build every agent declared in `config.agents` (or the built-in
     // fallback when none are declared). Each agent's `model` resolves
     // workspace URL + bearer at call time so concurrent requests get
@@ -260,9 +281,16 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       customApiRoutes: [
         chatRoute({ path: "/route/chat", agent: this.built.defaultAgentId }),
         chatRoute({ path: "/route/chat/:agentId" }),
+        historyRoute({ path: "/route/history", agent: this.built.defaultAgentId }),
+        historyRoute({ path: "/route/history/:agentId" }),
       ],
     });
     await this.mastraServer.init();
+    this.log.debug("build:done", {
+      agents: Object.keys(this.built.agents),
+      defaultAgent: this.built.defaultAgentId,
+      routes: ["/route/chat", "/route/history", "/models"],
+    });
   }
 }
 

package/src/processors/strip-stale-charts.ts

@@ -0,0 +1,105 @@
+/**
+ * Mastra input processor that strips `chartId` fields from every
+ * tool-invocation result in prior assistant messages before they
+ * reach the model.
+ *
+ * Why: chartIds are only meaningful within the assistant turn that
+ * minted them - the writer events backing them are gone after the
+ * stream closes. When the model sees old chartIds in memory recall
+ * (Mastra Memory persists tool results), it's tempted to type
+ * those ids into the new turn's `[[chart:<id>]]` markers, leaving
+ * the chat client's chart slots stuck with no matching event. This
+ * processor removes the temptation by deleting `chartId` keys from
+ * every assistant message's tool results before the prompt is
+ * built. The current turn's tool results don't exist yet at
+ * `processInput` time, so they pass through unmodified.
+ *
+ * The strip is recursive - any nested `chartId` field is removed,
+ * regardless of which tool produced the result. This covers Genie's
+ * `datasets[].chartId` and `render_data`'s top-level `chartId`
+ * uniformly without coupling to specific tool ids.
+ */
+
+import { logUtils } from "@dbx-tools/appkit-shared";
+import type {
+  InputProcessor,
+  ProcessInputArgs,
+} from "@mastra/core/processors";
+
+const log = logUtils.logger("mastra/processor/strip-stale-charts");
+
+/**
+ * Recursively clone `value`, omitting any property whose key is
+ * `chartId`. Arrays are mapped element-wise; primitives are
+ * returned as-is. The result is structurally identical to the
+ * input minus chartIds, so downstream message-shape consumers
+ * keep working.
+ */
+function stripChartIds(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stripChartIds);
+  }
+  if (value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      if (key === "chartId") continue;
+      out[key] = stripChartIds(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Input processor that scrubs `chartId` from every tool-invocation
+ * result in the message list. Wired onto every agent by default
+ * via {@link buildAgents}; opt out with
+ * `MastraPluginConfig.stripStaleCharts: false`.
+ */
+export const stripStaleChartsProcessor: InputProcessor = {
+  id: "strip-stale-charts",
+  description:
+    "Removes chartId fields from prior tool-invocation results so the model can't reuse turn-scoped ids from memory.",
+  processInput(args: ProcessInputArgs) {
+    let stripped = 0;
+    for (const message of args.messages) {
+      if (message.role !== "assistant") continue;
+      const parts = message.content?.parts;
+      if (!Array.isArray(parts)) continue;
+      for (const part of parts) {
+        // Tool-invocation parts hold the persisted tool result.
+        // We don't scrub the input args (`rawInput` / `args`) because
+        // the chartId there is the model's outgoing claim, not
+        // anything it could re-reference; only `result` carries
+        // ids that subsequent turns might copy.
+        if (
+          (part as { type?: unknown }).type !== "tool-invocation"
+        ) {
+          continue;
+        }
+        const inv = (part as { toolInvocation?: { result?: unknown } })
+          .toolInvocation;
+        if (!inv || inv.result === undefined) continue;
+        const before = inv.result;
+        const after = stripChartIds(before);
+        // Cheap structural check via JSON length - the actual
+        // strip writes a fresh object only when chartId keys
+        // existed, so different stringification length is a
+        // reliable signal that something was removed.
+        if (
+          typeof before === "object" &&
+          before !== null &&
+          JSON.stringify(before).length !== JSON.stringify(after).length
+        ) {
+          inv.result = after;
+          stripped += 1;
+        }
+      }
+    }
+    if (stripped > 0) {
+      log.debug("stripped", { results: stripped });
+    }
+    return args.messages;
+  },
+};

package/src/server.ts

@@ -42,61 +42,86 @@ export class MastraServer extends MastraServerExpress {
   override registerAuthMiddleware(): void {
     super.registerAuthMiddleware();
     this.app.use((req, res, next) => {
-      const executionContext = getExecutionContext();
-      const user: User = {
-        id:
-          "userId" in executionContext
-            ? executionContext.userId
-            : executionContext.serviceUserId,
-        executionContext,
-      };
       const requestContext = res.locals.requestContext! as RequestContext;
-      requestContext.set(MASTRA_USER_KEY, user);
-      if (!requestContext.get(MASTRA_RESOURCE_ID_KEY)) {
-        this.log.debug(`Setting resource id: ${user.id}`);
-        requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
-      }
-      const cookies = httpUtils.parseCookies(req.headers.cookie);
-      const cookieName = stringUtils.toIdentifierWithOptions(
-        { delimiter: "_", distinct: true },
-        "appkit",
-        this.config.name!,
-        "sessionId",
-      );
-      let sessionId = cookies[cookieName];
-      if (!sessionId) {
-        sessionId = randomUUID();
-        res.cookie(cookieName, sessionId, {
-          httpOnly: true,
-          sameSite: "lax",
-          secure: req.secure,
-          path: "/",
-        });
-      }
-      res.locals.sessionId = sessionId;
-      if (!requestContext.get(MASTRA_THREAD_ID_KEY)) {
-        this.log.debug(`Setting thread id: ${sessionId}`);
-        requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
-      }
-      // Per-request model override: only honored when the plugin
-      // opts in (default). Sources, in priority order, are
-      // `X-Mastra-Model` header, `?model=` query, and `model` /
-      // `modelId` body field; see `serving.ts`.
-      const serving = resolveServingConfig(this.config);
-      if (serving.allowOverride) {
-        const override = extractModelOverride({
-          headers: req.headers as Record<string, string | string[] | undefined>,
-          query: req.query as Record<string, unknown>,
-          body: req.body,
-        });
-        if (override) {
-          this.log.debug(`Model override: ${override}`);
-          requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
-        }
-      }
+      this.configureRequestContextUser(requestContext);
+      this.configureRequestContextThreadId(req, res, requestContext);
+      this.configureRequestContextModelOverride(req, requestContext);
+      this.log.debug("auth:middleware", {
+        method: req.method,
+        path: req.path,
+        threadId: requestContext.get(MASTRA_THREAD_ID_KEY),
+        resourceId: requestContext.get(MASTRA_RESOURCE_ID_KEY),
+        modelOverride: requestContext.get(
+          // imported below; logged so a misrouted request shows
+          // up alongside its model selection in `LOG_LEVEL=debug`.
+          "mastra__model_override",
+        ),
+      });
       next();
     });
   }
+
+  configureRequestContextUser(requestContext: RequestContext) {
+    if (
+      [MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))
+    )
+      return;
+    const executionContext = getExecutionContext();
+    const user: User = {
+      id:
+        "userId" in executionContext
+          ? executionContext.userId
+          : executionContext.serviceUserId,
+      executionContext,
+    };
+    requestContext.set(MASTRA_USER_KEY, user);
+    requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+  }
+
+  configureRequestContextThreadId(
+    req: express.Request,
+    res: express.Response,
+    requestContext: RequestContext,
+  ) {
+    if (requestContext.get(MASTRA_THREAD_ID_KEY)) return;
+    const cookies = httpUtils.parseCookies(req.headers.cookie);
+    const cookieName = stringUtils.toIdentifierWithOptions(
+      { delimiter: "_", distinct: true },
+      "appkit",
+      this.config.name!,
+      "sessionId",
+    );
+    let sessionId = cookies[cookieName];
+    if (!sessionId) {
+      sessionId = randomUUID();
+      res.cookie(cookieName, sessionId, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: req.secure,
+        path: "/",
+      });
+    }
+    requestContext.set(MASTRA_THREAD_ID_KEY, sessionId);
+  }
+
+  configureRequestContextModelOverride(
+    req: express.Request,
+    requestContext: RequestContext,
+  ) {
+    // Per-request model override: only honored when the plugin
+    // opts in (default). Sources, in priority order, are
+    // `X-Mastra-Model` header, `?model=` query, and `model` /
+    // `modelId` body field; see `serving.ts`.
+    const serving = resolveServingConfig(this.config);
+    if (serving.allowOverride) {
+      const override = extractModelOverride({
+        headers: req.headers as Record<string, string | string[] | undefined>,
+        query: req.query as Record<string, unknown>,
+        body: req.body,
+      });
+      if (override) requestContext.set(MASTRA_MODEL_OVERRIDE_KEY, override);
+    }
+  }
 }
 
 /**