@dbx-tools/appkit-mastra 0.9.69 → 0.9.71

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/telemetry.ts

@@ -36,11 +36,11 @@ import {
   updateActiveMlflowTraceTags,
 } from "./mlflow.ts";
 import {
+  APPKIT_AGENT_TRACE_ROOT_ATTR,
   MLFLOW_AGENT_TAG,
   MLFLOW_AGENT_TAG_ATTR,
   MLFLOW_GENIE_TAG,
   MLFLOW_GENIE_TAG_ATTR,
-  MLFLOW_MODEL_TAG,
   MLFLOW_LOCAL_TAG,
   MLFLOW_OBO_AUTH_TAG,
   MLFLOW_SP_AUTH_TAG,
@@ -50,10 +50,9 @@ import {
 export {
   MLFLOW_AGENT_TAG,
   MLFLOW_AGENT_TAG_ATTR,
+  APPKIT_AGENT_TRACE_ROOT_ATTR,
   MLFLOW_GENIE_TAG,
   MLFLOW_GENIE_TAG_ATTR,
-  MLFLOW_MODEL_TAG,
-  MLFLOW_MODEL_TAG_ATTR,
   MLFLOW_LOCAL_TAG,
   MLFLOW_LOCAL_TAG_ATTR,
   MLFLOW_OBO_AUTH_TAG,
@@ -130,8 +129,8 @@ interface TraceTarget {
 }
 
 interface ChatTraceState {
-  readonly models: Set<string>;
   readonly tags: Map<string, string>;
+  firstModel?: string;
   user?: string;
 }
 
@@ -187,21 +186,14 @@ function activeChatTraceState(): ChatTraceState | undefined {
   return context.active().getValue(CHAT_TRACE_STATE_KEY) as ChatTraceState | undefined;
 }
 
-function setChatTraceTag(
-  state: ChatTraceState,
-  name: string,
-  value: ChatTraceTagValue,
-): void {
+function setChatTraceTag(state: ChatTraceState, name: string, value: ChatTraceTagValue): void {
   const tag = stringUtils.trimToNull(name);
   if (!tag) return;
   state.tags.set(tag, String(value));
 }
 
 /** Inject one MLflow trace tag into the active chat request. */
-export function recordActiveTraceTag(
-  name: string,
-  value: ChatTraceTagValue = true,
-): void {
+export function recordActiveTraceTag(name: string, value: ChatTraceTagValue = true): void {
   const state = activeChatTraceState();
   if (state) setChatTraceTag(state, name, value);
 }
@@ -217,11 +209,17 @@ export function recordActiveTraceTags(
   }
 }
 
-/** Record a selected model on the active chat trace, preserving first-use order. */
+/** Record the first selected model as the active chat trace's `agent` tag. */
 export function recordActiveTraceModel(modelId: string): void {
   const value = stringUtils.trimToNull(modelId);
   if (!value) return;
-  activeChatTraceState()?.models.add(value);
+  const state = activeChatTraceState();
+  if (!state || state.firstModel) return;
+  state.firstModel = value;
+  setChatTraceTag(state, MLFLOW_AGENT_TAG, value);
+  const span = trace.getActiveSpan();
+  if (span?.isRecording()) span.setAttribute(MLFLOW_AGENT_TAG_ATTR, value);
+  updateActiveMlflowTraceTags({ [MLFLOW_AGENT_TAG]: value });
 }
 
 /** Record the best resolved user identifier on the active chat trace. */
@@ -237,20 +235,6 @@ export function recordActiveTraceAuth(auth: "obo" | "service-principal"): void {
   recordActiveTraceTag(auth === "obo" ? MLFLOW_OBO_AUTH_TAG : MLFLOW_SP_AUTH_TAG);
 }
 
-/** Serialize model tags as a scalar or an ordered JSON array for multiple values. */
-export function modelTraceTag(models: Iterable<string>): string | undefined {
-  const values: string[] = [];
-  const seen = new Set<string>();
-  for (const model of models) {
-    const value = stringUtils.trimToNull(model);
-    if (!value || seen.has(value)) continue;
-    seen.add(value);
-    values.push(value);
-  }
-  if (values.length === 0) return undefined;
-  return values.length === 1 ? values[0] : JSON.stringify(values);
-}
-
 /** Publish the turn's MLflow trace id before the handler writes the body. */
 function stampMlflowTraceId(res: express.Response, span: Span): void {
   if (res.headersSent) return;
@@ -425,20 +409,18 @@ class AssistantResponseCollector {
 function resolveTraceTarget(): TraceTarget | undefined {
   const activeContext = context.active();
   if (directMlflowTracingActive()) {
-    const span = trace
-      .getTracer(CHAT_TURN_TRACER)
-      .startSpan(
-        "mastra.chat_turn",
-        {
-          kind: SpanKind.SERVER,
-          attributes: {
-            [MLFLOW_AGENT_TAG_ATTR]: "true",
-            [MLFLOW_SPAN_TYPE_ATTR]: MLFLOW_SPAN_TYPE_AGENT,
-            [GEN_AI_OPERATION_NAME_ATTR]: "invoke_agent",
-          },
+    const span = trace.getTracer(CHAT_TURN_TRACER).startSpan(
+      "mastra.chat_turn",
+      {
+        kind: SpanKind.SERVER,
+        attributes: {
+          [APPKIT_AGENT_TRACE_ROOT_ATTR]: true,
+          [MLFLOW_SPAN_TYPE_ATTR]: MLFLOW_SPAN_TYPE_AGENT,
+          [GEN_AI_OPERATION_NAME_ATTR]: "invoke_agent",
         },
-        trace.deleteSpan(activeContext),
-      );
+      },
+      trace.deleteSpan(activeContext),
+    );
     if (!span.isRecording()) {
       span.end();
       return undefined;
@@ -454,20 +436,18 @@ function resolveTraceTarget(): TraceTarget | undefined {
   const active = trace.getActiveSpan();
   if (active?.isRecording()) return { span: active, owned: false };
 
-  const span = trace
-    .getTracer(CHAT_TURN_TRACER)
-    .startSpan(
-      "mastra.chat_turn",
-      {
-        kind: SpanKind.SERVER,
-        attributes: {
-          [MLFLOW_AGENT_TAG_ATTR]: "true",
-          [MLFLOW_SPAN_TYPE_ATTR]: MLFLOW_SPAN_TYPE_AGENT,
-          [GEN_AI_OPERATION_NAME_ATTR]: "invoke_agent",
-        },
+  const span = trace.getTracer(CHAT_TURN_TRACER).startSpan(
+    "mastra.chat_turn",
+    {
+      kind: SpanKind.SERVER,
+      attributes: {
+        [APPKIT_AGENT_TRACE_ROOT_ATTR]: true,
+        [MLFLOW_SPAN_TYPE_ATTR]: MLFLOW_SPAN_TYPE_AGENT,
+        [GEN_AI_OPERATION_NAME_ATTR]: "invoke_agent",
       },
-      activeContext,
-    );
+    },
+    activeContext,
+  );
   if (!span.isRecording()) {
     span.end();
     return undefined;
@@ -506,9 +486,8 @@ export function chatTurnTelemetryMiddleware(
     next();
     return;
   }
-  const traceState: ChatTraceState = { models: new Set(), tags: new Map() };
+  const traceState: ChatTraceState = { tags: new Map() };
   const traceRequestTime = Date.now();
-  setChatTraceTag(traceState, MLFLOW_AGENT_TAG, true);
   if (!appkit.isDatabricksAppEnv()) {
     setChatTraceTag(traceState, MLFLOW_LOCAL_TAG, true);
   }
@@ -525,7 +504,6 @@ export function chatTurnTelemetryMiddleware(
   traceState.user = stampMlflowActor(target.span, req);
   target.span.setAttribute(MLFLOW_SPAN_TYPE_ATTR, MLFLOW_SPAN_TYPE_AGENT);
   target.span.setAttribute(GEN_AI_OPERATION_NAME_ATTR, "invoke_agent");
-  target.span.setAttribute(MLFLOW_AGENT_TAG_ATTR, "true");
   const identity =
     typeof options.identity === "function" ? options.identity(req) : options.identity;
   if (identity) {
@@ -544,10 +522,7 @@ export function chatTurnTelemetryMiddleware(
     const fullInput = serialized(messages);
     requestPreview = textOnlyChatInput(messages) ?? fullInput;
     target.span.setAttribute(CHAT_MESSAGES_ATTR, fullInput);
-    target.span.setAttribute(
-      MLFLOW_SPAN_INPUTS_ATTR,
-      requestPreview.slice(0, TRACE_IO_LIMIT),
-    );
+    target.span.setAttribute(MLFLOW_SPAN_INPUTS_ATTR, requestPreview.slice(0, TRACE_IO_LIMIT));
   }
 
   const collector = new AssistantResponseCollector();
@@ -584,8 +559,6 @@ export function chatTurnTelemetryMiddleware(
   const finalizeTrace = (): void => {
     if (traceFinalized) return;
     traceFinalized = true;
-    const model = modelTraceTag(traceState.models);
-    if (model) setChatTraceTag(traceState, MLFLOW_MODEL_TAG, model);
     const tags = Object.fromEntries(traceState.tags);
     for (const [name, value] of traceState.tags) {
       target.span.setAttribute(`${MLFLOW_TRACE_TAG_PREFIX}${name}`, value);
@@ -651,7 +624,6 @@ export function chatTurnTelemetryMiddleware(
     .setSpan(context.active(), target.span)
     .setValue(CHAT_TRACE_STATE_KEY, traceState);
   context.with(chatContext, () => {
-    updateActiveMlflowTraceTags({ [MLFLOW_AGENT_TAG]: "true" });
     next();
   });
 }

package/src/trace-attributes.ts

@@ -7,9 +7,6 @@ export const MLFLOW_AGENT_TAG = "agent";
 /** Experiment-UI tag marking a turn that called Genie. */
 export const MLFLOW_GENIE_TAG = "genie";
 
-/** Experiment-UI tag recording the model or ordered models used by a turn. */
-export const MLFLOW_MODEL_TAG = "model";
-
 /** Experiment-UI tag marking a turn that invoked OBO authentication. */
 export const MLFLOW_OBO_AUTH_TAG = "obo_auth";
 
@@ -25,8 +22,8 @@ export const MLFLOW_AGENT_TAG_ATTR = `${MLFLOW_TRACE_TAG_PREFIX}${MLFLOW_AGENT_T
 /** Attribute key for the `genie` trace tag. */
 export const MLFLOW_GENIE_TAG_ATTR = `${MLFLOW_TRACE_TAG_PREFIX}${MLFLOW_GENIE_TAG}`;
 
-/** Attribute key for the `model` trace tag. */
-export const MLFLOW_MODEL_TAG_ATTR = `${MLFLOW_TRACE_TAG_PREFIX}${MLFLOW_MODEL_TAG}`;
+/** Internal root marker used by direct MLflow span filtering. */
+export const APPKIT_AGENT_TRACE_ROOT_ATTR = "appkit.mastra.trace.agent";
 
 /** Attribute key for the `obo_auth` trace tag. */
 export const MLFLOW_OBO_AUTH_TAG_ATTR = `${MLFLOW_TRACE_TAG_PREFIX}${MLFLOW_OBO_AUTH_TAG}`;

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;
+}