@dbx-tools/appkit-mastra 0.3.29 → 0.3.31

package/src/rest.ts

@@ -1,5 +1,3 @@
-import { appkit } from "@dbx-tools/appkit";
-import { json } from "@dbx-tools/shared-core";
 /**
  * Minimal authenticated Databricks REST helper. Pulls the workspace
  * host and a fresh bearer header off an OBO-scoped `WorkspaceClient`
@@ -8,8 +6,13 @@ import { json } from "@dbx-tools/shared-core";
  * method (e.g. the MLflow assessments API); returns the raw `Response`
  * so callers decide how to treat status codes. Also carries the
  * defensive `Response` body readers those callers share.
+ *
+ * @module
  */
 
+import { appkit } from "@dbx-tools/appkit";
+import { json } from "@dbx-tools/shared-core";
+
 /** Workspace client carried on an AppKit execution context. */
 type WorkspaceClient = appkit.WorkspaceClientLike;
 

package/src/server.ts

@@ -20,6 +20,7 @@ import { trace } from "@opentelemetry/api";
 import type express from "express";
 
 import {
+  executionContextUserId,
   MASTRA_REQUEST_ID_KEY,
   MASTRA_SCOPES_KEY,
   MASTRA_USER_EMAIL_KEY,
@@ -94,7 +95,7 @@ export class MastraServer extends MastraServerExpress {
     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,
+      id: executionContextUserId(executionContext),
       executionContext,
     };
     requestContext.set(MASTRA_USER_KEY, user);

package/src/serving-sanitize.ts

@@ -1,3 +1,18 @@
+/**
+ * Repairs Mastra / AI SDK message replays sent to Databricks Model
+ * Serving before they hit the OpenAI-compatible `/chat/completions`
+ * route.
+ *
+ * Exists because the transcript Mastra persists is not always a transcript the
+ * provider will accept back: Databricks-hosted Claude rejects replayed
+ * extended-thinking blocks and reads a trailing assistant message as a prefill
+ * request. Both repairs are provider quirks, not schema violations, so they are
+ * applied on the wire (see the `globalThis.fetch` wrapper in `model.ts`) rather
+ * than by changing what the agent stores or what the UI shows.
+ *
+ * @module
+ */
+
 import { json, string } from "@dbx-tools/shared-core";
 import {
   type ChatMessage,
@@ -5,11 +20,6 @@ import {
   openaiChat,
   openaiResponses,
 } from "@dbx-tools/shared-model";
-/**
- * Repairs Mastra / AI SDK message replays sent to Databricks Model
- * Serving before they hit the OpenAI-compatible `/chat/completions`
- * route.
- */
 
 /**
  * A chat message as it arrives on the serving wire, plus the extended-thinking

package/src/storage-schema.ts

@@ -1,12 +1,15 @@
-import { string } from "@dbx-tools/shared-core";
 /**
  * Derive a Postgres-safe schema name for per-agent Mastra storage.
  *
  * Agent ids are often kebab-case route segments (`data-mesh-book-assistant`)
  * but {@link PostgresStore} validates `schemaName` with Mastra's
  * `parseSqlIdentifier` (letter/underscore start, `[A-Za-z0-9_]` only, max 63).
+ *
+ * @module
  */
 
+import { string } from "@dbx-tools/shared-core";
+
 const SCHEMA_PREFIX = "mastra_";
 const MAX_PG_IDENTIFIER_LEN = 63;
 

package/src/threads.ts

@@ -21,6 +21,7 @@
  * @module
  */
 
+import { ValidationError } from "@databricks/appkit";
 import { log } from "@dbx-tools/shared-core";
 import {
   wire,
@@ -36,6 +37,7 @@ import type { ContextWithMastra } from "@mastra/core/server";
 import { registerApiRoute } from "@mastra/core/server";
 
 import { clampPerPage, parseIntParam } from "./pagination";
+import { invalidFields } from "./validation";
 
 const logger = log.logger("mastra/threads");
 
@@ -43,6 +45,8 @@ const logger = log.logger("mastra/threads");
 const DEFAULT_PER_PAGE = 30;
 /** Hard cap so a misbehaving client can't fetch every thread at once. */
 const MAX_PER_PAGE = 200;
+/** Stable client message for a rename body that fails schema validation. */
+const INVALID_RENAME_MESSAGE = "Invalid thread rename request";
 
 /** Inputs accepted by {@link listThreads}. */
 export interface ListThreadsOptions {
@@ -220,8 +224,10 @@ export function threadsRoute(options: ThreadsRouteOptions) {
   const { path } = options;
   const fixedAgent = "agent" in options ? options.agent : undefined;
   if (!fixedAgent && !path.includes(":agentId")) {
-    throw new Error(
-      "threadsRoute path must include `:agentId` or `agent` must be passed explicitly",
+    throw ValidationError.invalidValue(
+      "threadsRoute.path",
+      path,
+      "a path containing `:agentId`, or an explicit `agent`",
     );
   }
   // Shared by GET / DELETE: resolve the active agent and the caller's
@@ -298,7 +304,8 @@ export function threadsRoute(options: ThreadsRouteOptions) {
         }
         const body = wire.MastraUpdateThreadRequestSchema.safeParse(await c.req.json());
         if (!body.success) {
-          return c.json({ error: body.error.message }, 400);
+          logger.warn("rename:invalid", { error: body.error.message });
+          return c.json({ error: INVALID_RENAME_MESSAGE, fields: invalidFields(body.error) }, 400);
         }
         const thread = await renameThread({
           agent: ctx.agent,

package/src/validation.ts

@@ -0,0 +1,22 @@
+/**
+ * Request-body validation helpers shared by every route that parses a JSON
+ * body with a schema from `@dbx-tools/shared-mastra`.
+ *
+ * A schema library's own issue text quotes the received body back, so it is
+ * logged rather than returned. What a client gets instead is a stable message
+ * plus the field paths that failed, which is enough to highlight the offending
+ * inputs.
+ *
+ * @module
+ */
+
+/** The subset of a failed parse result these helpers read. */
+export interface SchemaIssues {
+  issues: ReadonlyArray<{ path: PropertyKey[] }>;
+}
+
+/** Distinct dot-joined field paths a failed parse flagged. */
+export function invalidFields(error: SchemaIssues): string[] {
+  const fields = error.issues.map((issue) => issue.path.map(String).join(".")).filter(Boolean);
+  return [...new Set(fields)];
+}

package/test/config.test.ts

@@ -0,0 +1,64 @@
+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: [] }] }), []);
+  });
+});