@dbx-tools/appkit-mastra 0.9.70 → 0.9.72

package/src/openapi-tool.ts

@@ -0,0 +1,252 @@
+/**
+ * OpenAPI operation loading and JSON Schema extraction.
+ *
+ * @module
+ */
+import { readFile } from "node:fs/promises";
+import { object } from "@dbx-tools/shared-core";
+import { urlBuilder, type UrlBuilder } from "@dbx-tools/shared-core/net";
+import type { JSONSchema7 } from "json-schema";
+import { z } from "zod";
+
+const HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "HEAD",
+  "TRACE",
+] as const;
+
+const JsonObjectSchema = z
+  .record(z.string(), z.unknown())
+  .describe("A JSON object embedded in an OpenAPI document.");
+
+const OpenApiMediaTypeSchema = z
+  .object({
+    schema: JsonObjectSchema.describe("The JSON Schema for this media type."),
+  })
+  .describe("One OpenAPI media type.");
+
+const OpenApiRequestBodySchema = z
+  .object({
+    content: z
+      .record(z.string(), OpenApiMediaTypeSchema)
+      .describe("Request media types keyed by content type."),
+  })
+  .describe("An OpenAPI request body.");
+
+const OpenApiResponseSchema = z
+  .object({
+    content: z
+      .record(z.string(), OpenApiMediaTypeSchema)
+      .optional()
+      .describe("Response media types keyed by content type."),
+  })
+  .describe("One OpenAPI response.");
+
+const OpenApiOperationSchema = z
+  .object({
+    operationId: z.string().describe("The stable operation identifier."),
+    summary: z.string().optional().describe("The short operation summary."),
+    description: z.string().optional().describe("The full operation description."),
+    requestBody: OpenApiRequestBodySchema.optional().describe(
+      "The optional operation request body.",
+    ),
+    responses: z
+      .record(z.string(), OpenApiResponseSchema)
+      .describe("Operation responses keyed by HTTP status."),
+  })
+  .describe("The OpenAPI fields required to define a tool.");
+
+const OpenApiPathSchema = z
+  .object({
+    get: OpenApiOperationSchema.optional(),
+    post: OpenApiOperationSchema.optional(),
+    put: OpenApiOperationSchema.optional(),
+    patch: OpenApiOperationSchema.optional(),
+    delete: OpenApiOperationSchema.optional(),
+    options: OpenApiOperationSchema.optional(),
+    head: OpenApiOperationSchema.optional(),
+    trace: OpenApiOperationSchema.optional(),
+  })
+  .describe("Operations available at one OpenAPI path.");
+
+const OpenApiDocumentSchema = z
+  .object({
+    paths: z
+      .record(z.string(), OpenApiPathSchema)
+      .refine((paths) => Object.keys(paths).length > 0, "OpenAPI paths must not be empty")
+      .describe("OpenAPI path items keyed by URL path."),
+    components: JsonObjectSchema.optional().describe("Reusable OpenAPI components."),
+    servers: z
+      .array(
+        z.object({
+          url: z.string().describe("Server base URL."),
+        }),
+      )
+      .optional()
+      .describe("OpenAPI server definitions."),
+  })
+  .describe("An OpenAPI document used to define HTTP tools.");
+
+type OpenApiDocument = z.infer<typeof OpenApiDocumentSchema>;
+type OpenApiOperation = z.infer<typeof OpenApiOperationSchema>;
+
+/** HTTP method supported by an {@link OpenApiTool}. */
+export type OpenApiHttpMethod = (typeof HTTP_METHODS)[number];
+
+/** One executable HTTP operation derived from an OpenAPI document. */
+export interface OpenApiTool {
+  /** Stable operation identifier. */
+  id: string;
+  /** Model-facing operation description. */
+  description: string;
+  /** Resolved operation URL, or the OpenAPI path for a local document without a server URL. */
+  url: string;
+  /** HTTP method used by the operation. */
+  method: OpenApiHttpMethod;
+  /** JSON Schema describing operation input. */
+  inputSchema: JSONSchema7;
+  /** JSON Schema describing a successful operation result. */
+  outputSchema: JSONSchema7;
+}
+
+/** Request options used while loading an OpenAPI document. */
+export interface OpenApiToolsOptions {
+  /** Cancels an HTTP request or file read. */
+  signal?: AbortSignal;
+  /** Headers sent when `source` is an HTTP(S) URL. */
+  headers?: RequestInit["headers"];
+}
+
+/** Load an HTTP(S) URL or local file and return its OpenAPI operations as tool schemas. */
+export async function openApiTools(
+  source: string,
+  options: OpenApiToolsOptions = {},
+): Promise<OpenApiTool[]> {
+  const sourceUrl = httpUrl(source);
+  const document = OpenApiDocumentSchema.parse(
+    sourceUrl
+      ? await fetchDocument(sourceUrl, options)
+      : await readDocument(source, options.signal),
+  );
+  return Object.entries(document.paths).flatMap(([path, item]) =>
+    HTTP_METHODS.flatMap((method) => {
+      const operation = item[method.toLowerCase() as Lowercase<OpenApiHttpMethod>];
+      return operation ? [operationTool(document, sourceUrl, path, method, operation)] : [];
+    }),
+  );
+}
+
+function httpUrl(source: string): UrlBuilder | undefined {
+  const url = urlBuilder(source);
+  return url?.scheme === "http" || url?.scheme === "https" ? url : undefined;
+}
+
+async function fetchDocument(url: URL, options: OpenApiToolsOptions): Promise<unknown> {
+  const response = await fetch(url, {
+    signal: options.signal,
+    headers: options.headers,
+  });
+  if (!response.ok) {
+    throw new Error(`OpenAPI request failed with HTTP ${response.status}: ${url}`);
+  }
+  return response.json();
+}
+
+async function readDocument(path: string, signal?: AbortSignal): Promise<unknown> {
+  return JSON.parse(await readFile(path, { encoding: "utf8", signal }));
+}
+
+function operationTool(
+  document: OpenApiDocument,
+  sourceUrl: URL | undefined,
+  path: string,
+  method: OpenApiHttpMethod,
+  operation: OpenApiOperation,
+): OpenApiTool {
+  const requestSchema = jsonSchema(operation.requestBody?.content) ?? { type: "object" };
+  const responseSchema = successfulResponseSchema(operation);
+  return {
+    id: operation.operationId,
+    description:
+      operation.description?.trim() || operation.summary?.trim() || operation.operationId,
+    url: operationUrl(document, sourceUrl, path),
+    method,
+    inputSchema: resolveReferences(document, requestSchema) as JSONSchema7,
+    outputSchema: resolveReferences(document, responseSchema) as JSONSchema7,
+  };
+}
+
+function successfulResponseSchema(operation: OpenApiOperation): Record<string, unknown> {
+  for (const [status, response] of Object.entries(operation.responses)) {
+    const schema = jsonSchema(response.content);
+    if (/^2(?:\d{2}|XX)$/i.test(status) && schema) return schema;
+  }
+  return {};
+}
+
+function jsonSchema(
+  content: Record<string, z.infer<typeof OpenApiMediaTypeSchema>> | undefined,
+): Record<string, unknown> | undefined {
+  const mediaType = Object.entries(content ?? {}).find(([type]) =>
+    /^application\/(?:[^+;]+\+)?json(?:;|$)/i.test(type),
+  );
+  return mediaType?.[1].schema;
+}
+
+function operationUrl(document: OpenApiDocument, sourceUrl: URL | undefined, path: string): string {
+  const server = document.servers?.[0]?.url;
+  if (server) {
+    const base = sourceUrl ? urlBuilder(new URL(server, sourceUrl)) : httpUrl(server);
+    return base
+      ? base.withPathAppend(path).toString()
+      : `${server.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+  }
+  return sourceUrl ? urlBuilder(sourceUrl)?.withPathReplace(path).toString() ?? path : path;
+}
+
+function resolveReferences(
+  document: OpenApiDocument,
+  value: unknown,
+  active: ReadonlySet<string> = new Set(),
+): unknown {
+  if (Array.isArray(value)) return value.map((item) => resolveReferences(document, item, active));
+  if (!object.isRecord(value)) return value;
+  const reference = typeof value.$ref === "string" ? value.$ref : undefined;
+  if (reference) {
+    if (active.has(reference)) throw new Error(`Cyclic OpenAPI reference: ${reference}`);
+    const target = referenceTarget(document, reference);
+    const next = new Set(active).add(reference);
+    const { $ref: _ignored, ...siblings } = value;
+    return {
+      ...(resolveReferences(document, target, next) as Record<string, unknown>),
+      ...(resolveReferences(document, siblings, next) as Record<string, unknown>),
+    };
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, resolveReferences(document, child, active)]),
+  );
+}
+
+function referenceTarget(document: OpenApiDocument, reference: string): unknown {
+  if (!reference.startsWith("#/")) throw new Error(`Unsupported OpenAPI reference: ${reference}`);
+  let current: unknown = document;
+  for (const rawSegment of reference.slice(2).split("/")) {
+    const segment = rawSegment.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (!object.isRecord(current) || !(segment in current)) {
+      throw new Error(`Unresolved OpenAPI reference: ${reference}`);
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+if (import.meta.main) {
+  const source = process.argv[2];
+  if (!source) throw new Error("Usage: bun openapi-tool.ts <openapi-url-or-file>");
+  console.log(JSON.stringify(await openApiTools(source), null, 2));
+}

package/src/server.ts

@@ -29,13 +29,13 @@ import {
 } from "./config.ts";
 import { requestUserEmail, requestUserId } from "./identity.ts";
 import { resolveFeedbackEnabled } from "./mlflow.ts";
-import { recordActiveTraceAuth, recordActiveTraceUser } from "./telemetry.ts";
-
 import {
   extractModelOverride,
   MASTRA_MODEL_OVERRIDE_KEY,
+  MASTRA_RESOLVED_MODEL_KEY,
   resolveServingConfig,
 } from "./serving.ts";
+import { recordActiveTraceAuth, recordActiveTraceUser } from "./telemetry.ts";
 /**
  * OpenTelemetry's sentinel for "no valid trace" - 32 zero hex chars.
  * `trace.getActiveSpan()` returns a non-recording span with this id
@@ -52,6 +52,7 @@ const TRUSTED_REQUEST_CONTEXT_KEYS = [
   MASTRA_REQUEST_ID_KEY,
   MASTRA_SCOPES_KEY,
   MASTRA_MODEL_OVERRIDE_KEY,
+  MASTRA_RESOLVED_MODEL_KEY,
 ] as const;
 
 /** Remove browser-supplied values for fields owned by trusted server middleware. */
@@ -225,9 +226,7 @@ export class MastraServer extends ExpressMastraServer {
     });
     const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
     if (user) {
-      recordActiveTraceAuth(
-        "isUserContext" in user.executionContext ? "obo" : "service-principal",
-      );
+      recordActiveTraceAuth("isUserContext" in user.executionContext ? "obo" : "service-principal");
     }
     const traceUser = [
       requestContext.get(MASTRA_USER_EMAIL_KEY),

package/src/serving.ts

@@ -24,6 +24,9 @@ import type { MastraPluginConfig } from "./config.ts";
  */
 export const MASTRA_MODEL_OVERRIDE_KEY = "mastra__model_override";
 
+/** RequestContext key carrying the endpoint selected for the active agent step. */
+export const MASTRA_RESOLVED_MODEL_KEY = "mastra__resolved_model";
+
 /**
  * Minimal Express-ish request shape used by {@link extractModelOverride}.
  * Keeps this module independent of `express` so the helper can be

package/src/workspaces.ts

@@ -23,6 +23,7 @@ import { ConfigurationError, createWorkspaceClient } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
 import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { errorUtils, log, object, stringUtils, token } from "@dbx-tools/shared-core";
+import { posixPath } from "@dbx-tools/shared-fs";
 import type { RequestContext } from "@mastra/core/request-context";
 import {
   CompositeFilesystem,
@@ -676,9 +677,83 @@ function buildWorkspaceSkillsResolver(
   extraSkillPaths: string[] = [],
 ): SkillsResolver {
   return async (context: SkillsContext) => {
-    const { skillPaths } = await resolveWorkspaceContribution(resolvers, context);
-    const merged = [...(skillPaths ?? []), ...extraSkillPaths];
-    logger.debug("skills:resolved", { skillPaths, extraSkillPaths });
+    const contribution = await resolveWorkspaceContribution(resolvers, context);
+    const skillPaths = await uniqueSkillPaths(contribution);
+    const merged = [...skillPaths, ...extraSkillPaths];
+    logger.debug("skills:resolved", {
+      configuredSkillPaths: contribution.skillPaths,
+      skillPaths,
+      extraSkillPaths,
+    });
     return merged;
   };
 }
+
+/** Expand mounted roots and keep the first concrete skill for each directory name. */
+async function uniqueSkillPaths(contribution: WorkspaceMountContribution): Promise<string[]> {
+  const selected = new Map<string, string>();
+  const unresolved: string[] = [];
+  for (const root of contribution.skillPaths ?? []) {
+    const mount = mountedFilesystem(root, contribution.mounts);
+    if (!mount) {
+      unresolved.push(root);
+      continue;
+    }
+    let candidates: string[];
+    try {
+      candidates = await concreteSkillPaths(root, mount.path, mount.filesystem);
+    } catch (error) {
+      logger.debug("skills:root-expansion-failed", {
+        root,
+        error: errorUtils.errorMessage(error),
+      });
+      unresolved.push(root);
+      continue;
+    }
+    if (candidates.length === 0) {
+      unresolved.push(root);
+      continue;
+    }
+    for (const candidate of candidates) {
+      const name = posixPath.basename(candidate);
+      const existing = selected.get(name);
+      if (existing) {
+        logger.debug("skills:duplicate-skipped", { name, path: candidate, selected: existing });
+      } else {
+        selected.set(name, candidate);
+      }
+    }
+  }
+  return [...selected.values(), ...unresolved];
+}
+
+/** Find the most-specific mounted filesystem containing one skill path. */
+function mountedFilesystem(
+  skillPath: string,
+  mounts: Readonly<Record<string, WorkspaceFilesystem>>,
+): { filesystem: WorkspaceFilesystem; path: string } | undefined {
+  return Object.entries(mounts)
+    .filter(([mount]) => skillPath === mount || skillPath.startsWith(`${mount}/`))
+    .sort(([left], [right]) => right.length - left.length)
+    .map(([path, filesystem]) => ({ filesystem, path }))[0];
+}
+
+/** Return concrete child skill directories from one mounted skill root. */
+async function concreteSkillPaths(
+  root: string,
+  mount: string,
+  filesystem: WorkspaceFilesystem,
+): Promise<string[]> {
+  const relativeRoot = root === mount ? "." : root.slice(mount.length + 1);
+  if (await filesystem.exists(posixPath.join(relativeRoot, "SKILL.md"))) return [root];
+  const entries = await filesystem.readdir(relativeRoot);
+  const candidates: string[] = [];
+  for (const entry of entries) {
+    if (entry.type !== "directory") continue;
+    const relative = posixPath.join(relativeRoot, entry.name);
+    if (await filesystem.exists(posixPath.join(relative, "SKILL.md"))) {
+      candidates.push(posixPath.join(root, entry.name));
+    }
+  }
+  return candidates;
+}