@dbx-tools/appkit-mastra 0.3.28 → 0.3.30

package/src/rest.ts

@@ -1,4 +1,3 @@
-import { appkit } from "@dbx-tools/appkit";
 /**
  * Minimal authenticated Databricks REST helper. Pulls the workspace
  * host and a fresh bearer header off an OBO-scoped `WorkspaceClient`
@@ -7,8 +6,13 @@ import { appkit } from "@dbx-tools/appkit";
  * 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;
 
@@ -58,10 +62,5 @@ export async function readResponseText(res: Response): Promise<string> {
 /** Parse a response body as JSON, returning `{}` on empty / invalid bodies. */
 export async function readResponseJson(res: Response): Promise<unknown> {
   const text = await readResponseText(res);
-  if (!text) return {};
-  try {
-    return JSON.parse(text);
-  } catch {
-    return {};
-  }
+  return json.parse<unknown>(text, {});
 }

package/src/server.ts

@@ -7,9 +7,8 @@
  * @module
  */
 
-import { randomUUID } from "node:crypto";
 import { getExecutionContext } from "@databricks/appkit";
-import { http, log, object, string, token } from "@dbx-tools/shared-core";
+import { hash, http, log, object, string, token } from "@dbx-tools/shared-core";
 import { feedback, thread } from "@dbx-tools/shared-mastra";
 import {
   MASTRA_RESOURCE_ID_KEY,
@@ -21,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,
@@ -95,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);
@@ -142,7 +142,7 @@ export class MastraServer extends MastraServerExpress {
     if (requestContext.get(MASTRA_REQUEST_ID_KEY)) return;
     const headerValue = req.headers["x-request-id"];
     const upstream = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-    const requestId = upstream?.trim() || randomUUID();
+    const requestId = upstream?.trim() || hash.id();
     requestContext.set(MASTRA_REQUEST_ID_KEY, requestId);
     res.setHeader("X-Request-Id", requestId);
   }
@@ -218,7 +218,7 @@ export class MastraServer extends MastraServerExpress {
     );
     let sessionId = cookies[cookieName];
     if (!sessionId) {
-      sessionId = randomUUID();
+      sessionId = hash.id();
       res.cookie(cookieName, sessionId, {
         httpOnly: true,
         sameSite: "lax",

package/src/serving-sanitize.ts

@@ -1,11 +1,26 @@
-import { string } from "@dbx-tools/shared-core";
-import { type ChatMessage, type ChatRole, openaiChat } 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.
+ *
+ * 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,
+  type ChatRole,
+  openaiChat,
+  openaiResponses,
+} from "@dbx-tools/shared-model";
+
 /**
  * A chat message as it arrives on the serving wire, plus the extended-thinking
  * fields Databricks-hosted Claude adds. The OpenAI-standard part of the shape
@@ -19,7 +34,9 @@ export interface ServingChatMessage extends ChatMessage {
   reasoning_content?: unknown;
 }
 
-const REASONING_PART_TYPES = new Set(["reasoning", "thinking", "redacted_thinking"]);
+// Shared with the Responses sanitize path so both wire surfaces agree on what
+// counts as a signed reasoning block.
+const REASONING_PART_TYPES = openaiResponses.REASONING_TYPES;
 
 /**
  * Parse, sanitize, and re-serialize a `/serving-endpoints/...` POST
@@ -27,12 +44,8 @@ const REASONING_PART_TYPES = new Set(["reasoning", "thinking", "redacted_thinkin
  * JSON or no rewrite was needed.
  */
 export function rewriteServingBody(body: string): string {
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(body) as Record<string, unknown>;
-  } catch {
-    return body;
-  }
+  const parsed = json.parseRecord(body);
+  if (!parsed) return body;
 
   // Runs regardless of `messages`: Databricks refuses to parse a body carrying
   // an unknown top-level field, so this failure is not specific to a transcript.

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