@dbx-tools/appkit-mastra 0.3.37 → 0.3.40

package/README.md

@@ -388,6 +388,33 @@ plugin.mastra({
 Use `mcp: false` to disable MCP. Turn on `tools: true` only for ambient tools
 that are safe outside an in-process chat turn.
 
+## Driving A Turn From Outside The Routes
+
+Another plugin (or a scheduled job) can run an agent turn directly, but a raw
+`agent.generate(prompt)` loses everything the HTTP middleware stamps - most
+visibly the AppKit user, which every user-scoped tool reads. `ask_genie` then
+fails with "invoke the tool from an agent turn served by the mastra plugin", so
+the turn answers "the data source is unreachable" where the chat routes answer
+with real data.
+
+`exports().createRequestContext()` builds the missing context:
+
+```ts
+const mastra = context.getPlugins()?.get("mastra")?.exports();
+const requestContext = await mastra.createRequestContext({
+  threadId: conversationId,
+  resourceId: userId,
+});
+const result = await mastra.getDefault().generate(prompt, { requestContext });
+```
+
+The AppKit user, the memory thread / resource pair, and a request id (so the
+turn's spans join up in traces) are stamped exactly as the request middleware
+stamps them. Call it inside an `asUser(req)` scope to inherit the caller's OBO
+identity; outside one it resolves to the service principal.
+[`@dbx-tools/teams`](../teams) uses this so a Teams card turn has the same tool
+reach - and therefore the same answer - as a chat turn.
+
 ## API Gate
 
 The stock `@mastra/express` app has broad management routes. The plugin's

package/package.json

@@ -3,7 +3,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reggie-db/dbx-tools.git",
-    "directory": "workspaces/node/appkit-mastra"
+    "directory": "packages/node/appkit-mastra"
   },
   "devDependencies": {
     "@types/express": "^5.0.5",
@@ -28,27 +28,31 @@
     "express": "^5.1.0",
     "pg": "^8.22.0",
     "zod": "4.3.6",
-    "@dbx-tools/appkit": "0.3.37",
-    "@dbx-tools/genie": "0.3.37",
-    "@dbx-tools/model": "0.3.37",
-    "@dbx-tools/shared-core": "0.3.37",
-    "@dbx-tools/core": "0.3.37",
-    "@dbx-tools/shared-genie": "0.3.37",
-    "@dbx-tools/shared-model": "0.3.37",
-    "@dbx-tools/shared-mastra": "0.3.37"
+    "@dbx-tools/appkit": "0.3.40",
+    "@dbx-tools/model": "0.3.40",
+    "@dbx-tools/genie": "0.3.40",
+    "@dbx-tools/core": "0.3.40",
+    "@dbx-tools/shared-mastra": "0.3.40",
+    "@dbx-tools/shared-genie": "0.3.40",
+    "@dbx-tools/shared-model": "0.3.40",
+    "@dbx-tools/shared-core": "0.3.40"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.37",
+  "version": "0.3.40",
   "types": "index.ts",
   "type": "module",
   "exports": {
     ".": "./index.ts",
     "./package.json": "./package.json"
   },
+  "files": [
+    "index.ts",
+    "src"
+  ],
   "dbxToolsConfig": {
     "tags": [
       "node"

package/src/plugin.ts

@@ -70,6 +70,7 @@ import {
 import { display, type ServingEndpointSummary } from "@dbx-tools/shared-model";
 import type { Agent } from "@mastra/core/agent";
 import { Mastra } from "@mastra/core/mastra";
+import type { RequestContext } from "@mastra/core/request-context";
 import express from "express";
 import type { Pool } from "pg";
 
@@ -89,7 +90,12 @@ import { buildMcpServer, type ResolvedMcp } from "./mcp";
 import { createMemoryBuilder, createServicePrincipalPool, needsLakebase } from "./memory";
 import { logFeedback, resolveFeedbackEnabled } from "./mlflow";
 import { buildObservability } from "./observability";
-import { attachRoutePatchMiddleware, isMastraRequestAllowed, MastraServer } from "./server";
+import {
+  attachRoutePatchMiddleware,
+  createRequestContext,
+  isMastraRequestAllowed,
+  MastraServer,
+} from "./server";
 import { resolveServingConfig } from "./serving";
 import { fetchStatementData, STATEMENT_ROW_CAP } from "./statement";
 import { threadsRoute } from "./threads";
@@ -303,6 +309,24 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         (this.built && this.built.agents[this.built.defaultAgentId]) ?? null,
       /** Underlying Mastra instance for advanced use (custom routes etc.). */
       getMastra: () => this.mastra,
+      /**
+       * Build the `RequestContext` an agent turn driven from OUTSIDE this
+       * plugin's routes needs (a Teams activity on another plugin's endpoint, a
+       * scheduled job).
+       *
+       * Mastra's user-scoped tools - `ask_genie` most visibly - read the AppKit
+       * user off the request context, which only the HTTP middleware stamps.
+       * Calling `agent.generate` with a raw prompt therefore answers "the data
+       * source is unreachable" where the chat routes answer with real data.
+       * Passing this as `requestContext` closes that gap, so an out-of-band turn
+       * has exactly the capabilities a chat turn has.
+       *
+       * Must be called INSIDE an `asUser(req)` scope to inherit the caller's
+       * OBO identity; outside one it resolves to the service principal.
+       */
+      createRequestContext: (
+        options: { threadId?: string; resourceId?: string; requestId?: string } = {},
+      ): Promise<RequestContext> => createRequestContext(options),
       /**
        * MCP endpoint info when `config.mcp` is enabled, else `null`.
        * Streamable HTTP is `http`; the SSE pair is the legacy transport.

package/src/server.ts

@@ -13,7 +13,7 @@ import { feedback, thread } from "@dbx-tools/shared-mastra";
 import {
   MASTRA_RESOURCE_ID_KEY,
   MASTRA_THREAD_ID_KEY,
-  type RequestContext,
+  RequestContext,
 } from "@mastra/core/request-context";
 import { MastraServer as MastraServerExpress } from "@mastra/express";
 import { trace } from "@opentelemetry/api";
@@ -40,6 +40,78 @@ import { extractModelOverride, MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig }
  */
 const INVALID_TRACE_ID = "0".repeat(32);
 
+/**
+ * Stamp the AppKit user (plus the resource id and trace metadata) onto
+ * `requestContext`.
+ *
+ * Split out of {@link MastraServer} because the HTTP middleware is not the only
+ * caller that needs it: an out-of-band turn (a Teams activity arriving on
+ * another plugin's route, a scheduled job) drives `agent.generate` directly, and
+ * without this stamp every user-scoped tool - `ask_genie` above all - fails with
+ * "invoke the tool from an agent turn served by the mastra plugin". Those
+ * callers build a context with {@link createRequestContext} instead of a
+ * request.
+ *
+ * Idempotent: returns immediately when the user and resource id are already
+ * present, so the middleware can call it over a context another layer stamped.
+ */
+export async function stampRequestContextUser(requestContext: RequestContext): Promise<void> {
+  if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))) return;
+  const executionContext = getExecutionContext();
+  const user: User = {
+    id: executionContextUserId(executionContext),
+    executionContext,
+  };
+  requestContext.set(MASTRA_USER_KEY, user);
+  requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
+  // AppKit's `UserContext` surfaces display name / email only on
+  // OBO requests. Service-context calls (background tasks, server
+  // start-up) leave these undefined and we skip the stamp so
+  // downstream trace metadata stays absent rather than empty.
+  let userName: string | undefined;
+  let email: string | undefined;
+  if ("isUserContext" in executionContext) {
+    userName = executionContext.userName;
+    email = executionContext.userEmail;
+  } else if (process.env.NODE_ENV === "development") {
+    const currentUser = await executionContext.client.currentUser.me();
+    userName = currentUser?.userName;
+    email = currentUser?.emails?.filter((email) => email.primary).find((email) => email.value)
+      ?.value as string;
+  }
+  if (userName) {
+    requestContext.set(MASTRA_USER_NAME_KEY, userName);
+  }
+  if (email) {
+    requestContext.set(MASTRA_USER_EMAIL_KEY, email);
+  }
+}
+
+/**
+ * Build the `RequestContext` a NON-HTTP agent turn needs.
+ *
+ * Everything Mastra's tools read off the context is stamped the same way the
+ * request middleware stamps it - the AppKit user (so `ask_genie` and the model
+ * resolver can mint user-scoped tokens), the memory thread / resource pair, and
+ * a request id so the turn's spans join up in traces. The result is passed as
+ * `requestContext` to `agent.generate` / `agent.stream`.
+ *
+ * This is what makes a card turn answer with the SAME data a chat turn does: the
+ * difference between the two endpoints is presentation, not capability.
+ */
+export async function createRequestContext(
+  options: { threadId?: string; resourceId?: string; requestId?: string } = {},
+): Promise<RequestContext> {
+  const requestContext = new RequestContext();
+  await stampRequestContextUser(requestContext);
+  if (options.threadId) requestContext.set(MASTRA_THREAD_ID_KEY, options.threadId);
+  // Stamped AFTER the user so an explicit resource id (a channel member, say)
+  // wins over the ambient identity `stampRequestContextUser` defaulted to.
+  if (options.resourceId) requestContext.set(MASTRA_RESOURCE_ID_KEY, options.resourceId);
+  requestContext.set(MASTRA_REQUEST_ID_KEY, options.requestId ?? hash.id());
+  return requestContext;
+}
+
 /**
  * `@mastra/express` subclass that stamps `RequestContext` with the
  * AppKit user, resource id, and a thread id backed by an HTTP-only
@@ -92,35 +164,7 @@ export class MastraServer extends MastraServerExpress {
   }
 
   async configureRequestContextUser(requestContext: RequestContext) {
-    if ([MASTRA_USER_KEY, MASTRA_RESOURCE_ID_KEY].every((key) => requestContext.get(key))) return;
-    const executionContext = getExecutionContext();
-    const user: User = {
-      id: executionContextUserId(executionContext),
-      executionContext,
-    };
-    requestContext.set(MASTRA_USER_KEY, user);
-    requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id);
-    // AppKit's `UserContext` surfaces display name / email only on
-    // OBO requests. Service-context calls (background tasks, server
-    // start-up) leave these undefined and we skip the stamp so
-    // downstream trace metadata stays absent rather than empty.
-    let userName: string | undefined;
-    let email: string | undefined;
-    if ("isUserContext" in executionContext) {
-      userName = executionContext.userName;
-      email = executionContext.userEmail;
-    } else if (process.env.NODE_ENV === "development") {
-      const currentUser = await executionContext.client.currentUser.me();
-      userName = currentUser?.userName;
-      email = currentUser?.emails?.filter((email) => email.primary).find((email) => email.value)
-        ?.value as string;
-    }
-    if (userName) {
-      requestContext.set(MASTRA_USER_NAME_KEY, userName);
-    }
-    if (email) {
-      requestContext.set(MASTRA_USER_EMAIL_KEY, email);
-    }
+    await stampRequestContextUser(requestContext);
   }
 
   /**

package/test/chart.test.ts

@@ -1,63 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { z } from "zod";
-
-import { chartPlanSchema } from "../src/chart";
-
-/**
- * Walk every nested schema node, yielding each object so a test can
- * assert on keywords wherever they appear in the tree.
- */
-function* nodes(schema: unknown): Generator<Record<string, unknown>> {
-  if (Array.isArray(schema)) {
-    for (const item of schema) yield* nodes(item);
-    return;
-  }
-  if (typeof schema !== "object" || schema === null) return;
-  const record = schema as Record<string, unknown>;
-  yield record;
-  for (const value of Object.values(record)) yield* nodes(value);
-}
-
-describe("chart plan JSON schema", () => {
-  // Databricks' Gemini serving endpoints validate `response_json_schema`
-  // and reject JSON Schema 2020-12 `prefixItems` with "schema at
-  // properties.series.items.properties.data.items.anyOf.2.items must be a
-  // boolean or an object". Zod emits `prefixItems` for `z.tuple`, so the
-  // scatter `[x, y]` point must stay a length-constrained number array.
-  it("emits no prefixItems, so Gemini accepts it as a response schema", () => {
-    const jsonSchema = z.toJSONSchema(chartPlanSchema);
-    const offenders = [...nodes(jsonSchema)].filter((node) => "prefixItems" in node);
-    assert.deepEqual(offenders, []);
-  });
-
-  it("types the scatter point as a two-number array", () => {
-    const jsonSchema = z.toJSONSchema(chartPlanSchema) as Record<string, any>;
-    const variants = jsonSchema.properties.series.items.properties.data.items.anyOf;
-    const arrayVariant = variants.find((v: Record<string, unknown>) => v.type === "array");
-    assert.deepEqual(arrayVariant, {
-      type: "array",
-      items: { type: "number" },
-      minItems: 2,
-      maxItems: 2,
-    });
-  });
-});
-
-describe("chart data point coercion", () => {
-  const dataPoint = chartPlanSchema.shape.series.element.shape.data.element;
-
-  it("keeps the shapes a SQL row set produces", () => {
-    assert.equal(dataPoint.parse(12.5), 12.5);
-    assert.equal(dataPoint.parse("12.5"), 12.5);
-    assert.equal(dataPoint.parse(null), null);
-    assert.deepEqual(dataPoint.parse([1, 2]), [1, 2]);
-    assert.deepEqual(dataPoint.parse({ name: "ATL", value: 3 }), { name: "ATL", value: 3 });
-  });
-
-  it("degrades unusable values to null instead of failing the plan", () => {
-    assert.equal(dataPoint.parse("not a number"), null);
-    assert.equal(dataPoint.parse(Number.POSITIVE_INFINITY), null);
-    assert.equal(dataPoint.parse({ nope: true }), null);
-  });
-});

package/test/config.test.ts

@@ -1,64 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { ConfigurationError } from "@databricks/appkit";
-
-import { MASTRA_CONFIG_SCHEMA } from "../src/config";
-import { normalizeGenieSpaces } from "../src/genie";
-import { invalidFields } from "../src/validation";
-
-describe("mastra config schema", () => {
-  it("describes every published property", () => {
-    const properties = Object.entries(MASTRA_CONFIG_SCHEMA.properties ?? {});
-    assert.ok(properties.length > 0);
-    for (const [name, schema] of properties) {
-      assert.equal(typeof schema, "object", `${name} must be a schema object`);
-      const description = (schema as { description?: unknown }).description;
-      assert.equal(typeof description, "string", `${name} must carry a description`);
-      assert.ok((description as string).length > 0, `${name} description must be non-empty`);
-    }
-  });
-});
-
-describe("genie space normalization", () => {
-  it("wraps bare space ids and passes objects through", () => {
-    assert.deepEqual(normalizeGenieSpaces({ default: "01ef", sales: { spaceId: "02ef" } }), {
-      default: { spaceId: "01ef" },
-      sales: { spaceId: "02ef" },
-    });
-  });
-
-  it("treats no config as no spaces", () => {
-    assert.deepEqual(normalizeGenieSpaces(undefined), {});
-    assert.deepEqual(normalizeGenieSpaces({}), {});
-  });
-
-  it("fails loudly on an alias with no space id", () => {
-    for (const spaces of [
-      { default: undefined },
-      { default: "" },
-      { sales: { spaceId: "" } },
-    ] as Parameters<typeof normalizeGenieSpaces>[0][]) {
-      assert.throws(() => normalizeGenieSpaces(spaces), ConfigurationError);
-    }
-  });
-
-  it("names the env var only for the default alias", () => {
-    assert.throws(() => normalizeGenieSpaces({ default: undefined }), /DATABRICKS_GENIE_SPACE_ID/);
-    assert.throws(() => normalizeGenieSpaces({ sales: undefined }), /genieSpaces\.sales/);
-  });
-});
-
-describe("request body validation", () => {
-  it("reports distinct dot-joined field paths", () => {
-    assert.deepEqual(
-      invalidFields({
-        issues: [{ path: ["traceId"] }, { path: ["value", 0] }, { path: ["traceId"] }],
-      }),
-      ["traceId", "value.0"],
-    );
-  });
-
-  it("drops the root path, which names no field", () => {
-    assert.deepEqual(invalidFields({ issues: [{ path: [] }] }), []);
-  });
-});

package/test/serving-sanitize.test.ts

@@ -1,98 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-
-import { rewriteServingResponseBody } from "../src/serving-sanitize";
-
-/**
- * Trimmed copy of a real Databricks-hosted Gemini reply: `content` is the
- * Gemini-native parts array, and the text part also carries the signed
- * `thoughtSignature` the model returns alongside it.
- */
-const geminiPartsResponse = {
-  model: "gemini-3.1-flash-lite",
-  choices: [
-    {
-      message: {
-        role: "assistant",
-        content: [
-          { type: "text", text: "Fuel Mart Weekly Sales Summary", thoughtSignature: "AY89a18" },
-        ],
-      },
-      index: 0,
-      finish_reason: "stop",
-    },
-  ],
-  usage: { prompt_tokens: 2098, completion_tokens: 5, total_tokens: 2201 },
-  object: "chat.completion",
-};
-
-describe("serving response sanitize", () => {
-  it("flattens Gemini's content parts to the string the AI SDK expects", () => {
-    const result = JSON.parse(rewriteServingResponseBody(JSON.stringify(geminiPartsResponse)));
-    assert.equal(result.choices[0].message.content, "Fuel Mart Weekly Sales Summary");
-  });
-
-  it("preserves every sibling field while rewriting content", () => {
-    const result = JSON.parse(rewriteServingResponseBody(JSON.stringify(geminiPartsResponse)));
-    assert.equal(result.choices[0].finish_reason, "stop");
-    assert.equal(result.choices[0].message.role, "assistant");
-    assert.deepEqual(result.usage, geminiPartsResponse.usage);
-    assert.equal(result.model, "gemini-3.1-flash-lite");
-  });
-
-  it("joins multiple text parts and ignores non-text ones", () => {
-    const body = JSON.stringify({
-      choices: [
-        {
-          message: {
-            content: [
-              { type: "text", text: "Fuel Mart " },
-              { type: "image", image_url: "https://example.invalid/x.png" },
-              { type: "text", text: "Sales" },
-            ],
-          },
-        },
-      ],
-    });
-    const result = JSON.parse(rewriteServingResponseBody(body));
-    assert.equal(result.choices[0].message.content, "Fuel Mart Sales");
-  });
-
-  it("flattens a parts array holding no text to an empty string", () => {
-    const body = JSON.stringify({
-      choices: [{ message: { content: [{ thoughtSignature: "AY89" }] }, finish_reason: "stop" }],
-    });
-    const result = JSON.parse(rewriteServingResponseBody(body));
-    assert.equal(result.choices[0].message.content, "");
-    assert.equal(result.choices[0].finish_reason, "stop");
-  });
-
-  it("returns a compliant OpenAI response byte-identical", () => {
-    const body = JSON.stringify({
-      choices: [{ message: { role: "assistant", content: "already a string" } }],
-    });
-    assert.equal(rewriteServingResponseBody(body), body);
-  });
-
-  it("leaves a non-JSON or choice-less body untouched", () => {
-    assert.equal(rewriteServingResponseBody("not json"), "not json");
-    assert.equal(
-      rewriteServingResponseBody('{"error_code":"BAD_REQUEST"}'),
-      '{"error_code":"BAD_REQUEST"}',
-    );
-  });
-
-  it("repairs every choice when the provider returns more than one", () => {
-    const body = JSON.stringify({
-      choices: [
-        { message: { content: [{ type: "text", text: "first" }] } },
-        { message: { content: [{ type: "text", text: "second" }] } },
-      ],
-    });
-    const result = JSON.parse(rewriteServingResponseBody(body));
-    assert.deepEqual(
-      result.choices.map((c: { message: { content: string } }) => c.message.content),
-      ["first", "second"],
-    );
-  });
-});

package/test/tsconfig.json

@@ -1,14 +0,0 @@
-// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
-{
-  "extends": "../tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "rootDir": ".."
-  },
-  "include": [
-    "**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}

package/tsconfig.json

@@ -1,41 +0,0 @@
-// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
-{
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib",
-    "alwaysStrict": true,
-    "declaration": true,
-    "esModuleInterop": true,
-    "experimentalDecorators": true,
-    "inlineSourceMap": true,
-    "inlineSources": true,
-    "lib": [
-      "ES2022"
-    ],
-    "module": "ESNext",
-    "noEmitOnError": false,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitAny": true,
-    "noImplicitReturns": true,
-    "noImplicitThis": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "resolveJsonModule": true,
-    "strict": true,
-    "strictNullChecks": true,
-    "strictPropertyInitialization": true,
-    "stripInternal": true,
-    "target": "ES2022",
-    "types": [
-      "node"
-    ],
-    "moduleResolution": "bundler",
-    "skipLibCheck": true
-  },
-  "include": [
-    "src/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}