@dbx-tools/appkit-mastra 0.1.111 → 0.3.1

package/src/threads.ts

@@ -0,0 +1,338 @@
+/**
+ * Conversation-thread listing exposed as a Mastra custom API route.
+ *
+ * Backed entirely by native Mastra: looks up the active agent by id,
+ * asks its `Memory` instance to `listThreads` filtered to the caller's
+ * resource, and shapes each into the JSON-safe {@link MastraThread}
+ * wire type. A sibling `DELETE` removes a single named thread.
+ *
+ * A sibling `DELETE` removes a single named thread; a `PATCH` renames
+ * one ({@link renameThread}).
+ *
+ * Like {@link historyRoute} this registers through Mastra's
+ * `registerApiRoute` so it shares the `MastraServer` auth-middleware
+ * pipeline (in `./server.ts`), which has already stamped the resource
+ * id (`MASTRA_RESOURCE_ID_KEY`) and the targeted thread id
+ * (`MASTRA_THREAD_ID_KEY`, resolved from the thread-selection header /
+ * cookie) on `RequestContext` by the time a handler runs. Resource
+ * scoping lives here so a caller can only ever see, rename, or delete
+ * its own threads; no cookie or user lookups happen in this module.
+ */
+
+import {
+  wire,
+  type MastraDeleteThreadResponse,
+  type MastraThread,
+  type MastraThreadsResponse,
+  type MastraUpdateThreadResponse,
+} from "@dbx-tools/shared-mastra";
+import type { Agent } from "@mastra/core/agent";
+import type { StorageThreadType } from "@mastra/core/memory";
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from "@mastra/core/request-context";
+import type { ContextWithMastra } from "@mastra/core/server";
+import { registerApiRoute } from "@mastra/core/server";
+
+import { clampPerPage, parseIntParam } from "./pagination";
+import { log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("mastra/threads");
+
+/** Default threads page size. */
+const DEFAULT_PER_PAGE = 30;
+/** Hard cap so a misbehaving client can't fetch every thread at once. */
+const MAX_PER_PAGE = 200;
+
+/** Inputs accepted by {@link listThreads}. */
+export interface ListThreadsOptions {
+  agent: Agent;
+  resourceId: string;
+  page?: number;
+  perPage?: number;
+}
+
+/**
+ * Fetch a page of the resource's conversation threads, newest
+ * (`updatedAt` DESC) first.
+ *
+ * Uses the agent's resolved `Memory` (`getMemory()`) so the per-agent
+ * storage namespace (`mastra_<agentId>` schema) applies automatically.
+ * When the agent has no memory configured the response is a successful
+ * empty page so callers don't have to special-case stateless agents.
+ */
+export async function listThreads(opts: ListThreadsOptions): Promise<MastraThreadsResponse> {
+  const perPage = clampPerPage(opts.perPage, {
+    fallback: DEFAULT_PER_PAGE,
+    max: MAX_PER_PAGE,
+  });
+  const page = Math.max(0, Math.trunc(opts.page ?? 0));
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    logger.debug("list:no-memory", { agentId: opts.agent.id });
+    return { threads: [], page, perPage, total: 0, hasMore: false };
+  }
+  const startedAt = Date.now();
+  const result = await memory.listThreads({
+    filter: { resourceId: opts.resourceId },
+    page,
+    perPage,
+    orderBy: { field: "updatedAt", direction: "DESC" },
+  });
+  const threads = result.threads.map(toWireThread);
+  logger.debug("list:done", {
+    agentId: opts.agent.id,
+    resourceId: opts.resourceId,
+    page,
+    perPage,
+    returned: threads.length,
+    total: result.total,
+    hasMore: result.hasMore,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return {
+    threads,
+    page,
+    perPage,
+    total: result.total,
+    hasMore: result.hasMore,
+  };
+}
+
+/** Inputs accepted by {@link deleteThread}. */
+export interface DeleteThreadOptions {
+  agent: Agent;
+  threadId: string;
+  resourceId: string;
+}
+
+/**
+ * Delete a single named thread (and every message on it).
+ *
+ * Ownership is enforced: the thread is only removed when it belongs to
+ * the calling resource, so a client can't delete another user's
+ * conversation by guessing its id. A thread that doesn't exist (or
+ * isn't owned by the caller) is a successful no-op (`deleted: false`)
+ * so the UI can fire-and-forget.
+ */
+export async function deleteThread(opts: DeleteThreadOptions): Promise<{ deleted: boolean }> {
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    logger.debug("delete:no-memory", { agentId: opts.agent.id });
+    return { deleted: false };
+  }
+  // Confirm the thread exists and is owned by the caller before
+  // deleting; never let a guessed id touch another resource's data.
+  const existing = await memory.getThreadById({ threadId: opts.threadId });
+  if (!existing || existing.resourceId !== opts.resourceId) {
+    logger.debug("delete:not-owned", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      found: existing !== null,
+    });
+    return { deleted: false };
+  }
+  const startedAt = Date.now();
+  await memory.deleteThread(opts.threadId);
+  logger.info("delete:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return { deleted: true };
+}
+
+/** Inputs accepted by {@link renameThread}. */
+export interface RenameThreadOptions {
+  agent: Agent;
+  threadId: string;
+  resourceId: string;
+  title: string;
+}
+
+/**
+ * Rename a single thread, returning the updated wire thread.
+ *
+ * Ownership is enforced the same way {@link deleteThread} enforces it:
+ * the title is only changed when the thread belongs to the calling
+ * resource, so a client can't rename another user's conversation by
+ * guessing its id. Existing thread `metadata` is preserved untouched
+ * (Mastra's `updateThread` replaces the row, so it must be passed back
+ * in). Returns `null` when the thread doesn't exist, isn't owned by the
+ * caller, or the agent has no memory configured, letting the route map
+ * that to a 404.
+ */
+export async function renameThread(opts: RenameThreadOptions): Promise<MastraThread | null> {
+  const memory = await opts.agent.getMemory();
+  if (!memory) {
+    logger.debug("rename:no-memory", { agentId: opts.agent.id });
+    return null;
+  }
+  const existing = await memory.getThreadById({ threadId: opts.threadId });
+  if (!existing || existing.resourceId !== opts.resourceId) {
+    logger.debug("rename:not-owned", {
+      agentId: opts.agent.id,
+      threadId: opts.threadId,
+      found: existing !== null,
+    });
+    return null;
+  }
+  const startedAt = Date.now();
+  const updated = await memory.updateThread({
+    id: opts.threadId,
+    title: opts.title,
+    metadata: existing.metadata ?? {},
+  });
+  logger.info("rename:done", {
+    agentId: opts.agent.id,
+    threadId: opts.threadId,
+    elapsedMs: Date.now() - startedAt,
+  });
+  return toWireThread(updated);
+}
+
+/** Options accepted by {@link threadsRoute}. */
+export type ThreadsRouteOptions =
+  { path: `${string}:agentId${string}`; agent?: never } | { path: string; agent: string };
+
+/**
+ * Register the `<path>` Mastra custom API route. Handles three methods
+ * on the same mount:
+ *
+ *   - `GET`: a page of the resource's conversation threads
+ *     ({@link listThreads}).
+ *   - `DELETE`: remove the thread named by the thread-selection header
+ *     / `?threadId=` query ({@link deleteThread}). The id is read from
+ *     `RequestContext` (the auth middleware resolves it the same way it
+ *     does for streaming and history), so the client deletes any of its
+ *     threads by stamping the target id - no separate path param.
+ *   - `PATCH`: rename the thread named by the thread-selection header /
+ *     `?threadId=` query to the `{ title }` in the JSON body
+ *     ({@link renameThread}). Targets a thread the same way `DELETE`
+ *     does; 404s when the thread isn't owned by the caller.
+ *
+ * Follows the `@mastra/ai-sdk` agent-binding convention: pass `agent`
+ * for a fixed-agent mount, or include `:agentId` in the path for
+ * dynamic routing. The plugin registers both `/route/threads` (default
+ * agent) and `/route/threads/:agentId`.
+ */
+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",
+    );
+  }
+  // Shared by GET / DELETE: resolve the active agent and the caller's
+  // resource id, returning a JSON error response when either is
+  // missing. Keeps both handlers thin with identical validation.
+  const resolveContext = (c: ContextWithMastra) => {
+    const mastra = c.get("mastra");
+    const requestContext = c.get("requestContext");
+    const agentId = fixedAgent ?? c.req.param("agentId");
+    if (!agentId) {
+      return { error: c.json({ error: "agentId is required" }, 400) } as const;
+    }
+    const agent = mastra.getAgentById(agentId);
+    if (!agent) {
+      return {
+        error: c.json({ error: `Unknown agent "${agentId}"` }, 404),
+      } as const;
+    }
+    const resourceId = requestContext.get(MASTRA_RESOURCE_ID_KEY) as string | undefined;
+    if (!resourceId) {
+      return {
+        error: c.json({ error: "resource id missing from request context" }, 400),
+      } as const;
+    }
+    return { agentId, agent, requestContext, resourceId } as const;
+  };
+
+  return [
+    registerApiRoute(path, {
+      method: "GET",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const payload = await listThreads({
+          agent: ctx.agent,
+          resourceId: ctx.resourceId,
+          page: parseIntParam(c.req.query("page")),
+          perPage: parseIntParam(c.req.query("perPage")),
+        });
+        return c.json(payload);
+      },
+    }),
+    registerApiRoute(path, {
+      method: "DELETE",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const threadId = ctx.requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
+        if (!threadId) {
+          return c.json({ error: "thread id missing from request context" }, 400);
+        }
+        const { deleted } = await deleteThread({
+          agent: ctx.agent,
+          threadId,
+          resourceId: ctx.resourceId,
+        });
+        const payload: MastraDeleteThreadResponse = {
+          ok: true,
+          agentId: ctx.agentId,
+          threadId,
+          deleted,
+        };
+        return c.json(payload);
+      },
+    }),
+    registerApiRoute(path, {
+      method: "PATCH",
+      handler: async (c: ContextWithMastra) => {
+        const ctx = resolveContext(c);
+        if ("error" in ctx) return ctx.error;
+        const threadId = ctx.requestContext.get(MASTRA_THREAD_ID_KEY) as string | undefined;
+        if (!threadId) {
+          return c.json({ error: "thread id missing from request context" }, 400);
+        }
+        const body = wire.MastraUpdateThreadRequestSchema.safeParse(await c.req.json());
+        if (!body.success) {
+          return c.json({ error: body.error.message }, 400);
+        }
+        const thread = await renameThread({
+          agent: ctx.agent,
+          threadId,
+          resourceId: ctx.resourceId,
+          title: body.data.title,
+        });
+        if (!thread) {
+          return c.json({ error: `Unknown thread "${threadId}"` }, 404);
+        }
+        const payload: MastraUpdateThreadResponse = {
+          ok: true,
+          agentId: ctx.agentId,
+          thread,
+        };
+        return c.json(payload);
+      },
+    }),
+  ];
+}
+
+/** Coerce a Mastra `StorageThreadType` into the JSON-safe wire shape. */
+function toWireThread(thread: StorageThreadType): MastraThread {
+  return {
+    id: thread.id,
+    ...(thread.title ? { title: thread.title } : {}),
+    resourceId: thread.resourceId,
+    createdAt: toIso(thread.createdAt),
+    updatedAt: toIso(thread.updatedAt),
+    ...(thread.metadata ? { metadata: thread.metadata } : {}),
+  };
+}
+
+/** Render a storage timestamp as an ISO-8601 string for the wire. */
+function toIso(value: Date | string | number): string {
+  if (value instanceof Date) return value.toISOString();
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? new Date(0).toISOString() : parsed.toISOString();
+}

package/src/workspaces.ts

@@ -0,0 +1,346 @@
+/**
+ * Mastra workspace factory for Databricks Apps.
+ *
+ * Builds a per-request {@link Workspace} whose filesystem is a
+ * {@link CompositeFilesystem} over Databricks paths resolved from the
+ * OBO client on {@link MASTRA_USER_KEY}. Optional mount resolver
+ * contributions merge extra filesystems and skill scan roots; built-in
+ * Assistant skill trees are toggled with `assistantSkills` (on by default).
+ */
+
+import type { WorkspaceClient } from "@databricks/sdk-experimental";
+import type { RequestContext } from "@mastra/core/request-context";
+import {
+  CompositeFilesystem,
+  Workspace,
+  type SkillsContext,
+  type SkillsResolver,
+  type WorkspaceFilesystem,
+} from "@mastra/core/workspace";
+
+import { MASTRA_SCOPES_KEY, MASTRA_USER_EMAIL_KEY, MASTRA_USER_KEY, type User } from "./config";
+import { DatabricksWorkspaceFilesystem, emptyFilesystem } from "./filesystems";
+import { log, string, token } from "@dbx-tools/shared-core";
+
+/* ------------------------------ constants ------------------------------ */
+
+/** Shared Assistant skills tree in the workspace namespace. */
+const ASSISTANT_SHARED_SKILLS_PATH = "/Workspace/.assistant/skills";
+
+/** Composite mount for {@link ASSISTANT_SHARED_SKILLS_PATH}. */
+const ASSISTANT_WORKSPACE_SKILLS_MOUNT = "/workspace_skills";
+
+/** Composite mount for the caller's `/.assistant/skills` tree. */
+const ASSISTANT_USER_SKILLS_MOUNT = "/workspace_user_skills";
+
+/** OAuth scopes that gate Databricks workspace file mounts. */
+const WORKSPACE_FILE_SCOPES = ["workspace", "workspace.workspace", "all-apis"] as const;
+
+const logger = log.logger("mastra/workspaces");
+
+/* -------------------------------- types -------------------------------- */
+
+/** Per-request context for mount resolvers. */
+interface WorkspaceMountContext {
+  requestContext?: RequestContext;
+}
+
+/** Mount map plus optional Mastra skill scan roots for one resolver. */
+interface WorkspaceMountContribution {
+  mounts: Record<string, WorkspaceFilesystem>;
+  /** Paths within the composite namespace where `SKILL.md` files are scanned. */
+  skillPaths?: string[];
+}
+
+/** Contributes filesystem mounts (and optional skill paths) for one request. */
+type WorkspaceMountResolver = (
+  context: WorkspaceMountContext,
+) => WorkspaceMountContribution | Promise<WorkspaceMountContribution>;
+
+/** Options for {@link createWorkspace}. */
+export interface CreateWorkspaceOptions {
+  /** Workspace id; derived from `name` or `"workspace"` when omitted. */
+  id?: string;
+  /** Display name; derived from `id` when omitted. */
+  name?: string;
+  /**
+   * Mount read-only Assistant skill trees from `/Workspace/.assistant/skills`
+   * and `/Users/<email>/.assistant/skills`. Defaults to `true`.
+   */
+  assistantSkills?: boolean;
+  /** Extra per-request mount resolvers (run after built-in options). */
+  mounts?: WorkspaceMountResolver[];
+  /** Replace the auto-built dynamic skills resolver. */
+  skills?: SkillsResolver;
+  /** Forwarded to Mastra when skill discovery is enabled. */
+  checkSkillFileMtime?: boolean;
+  /** Enable BM25 keyword search over indexed workspace content. */
+  bm25?: boolean;
+}
+
+/**
+ * Create a Mastra {@link Workspace} with per-request Databricks mounts.
+ *
+ * @example Assistant skills only (default for agents in this plugin)
+ * ```ts
+ * createWorkspace()
+ * ```
+ *
+ * @example Assistant skills plus a custom mount resolver
+ * ```ts
+ * createWorkspace({
+ *   assistantSkills: true,
+ *   mounts: [
+ *     async ({ requestContext }) => ({
+ *       mounts: { "/data": myFilesystem },
+ *       skillPaths: [],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function createWorkspace(options: CreateWorkspaceOptions = {}): Workspace {
+  const { id, name } = resolveWorkspaceIdentity(options);
+  const resolvers = buildMountResolvers(options);
+  const skills =
+    options.skills ?? (resolvers.length > 0 ? buildWorkspaceSkillsResolver(resolvers) : undefined);
+  const checkSkillFileMtime = options.checkSkillFileMtime ?? options.assistantSkills !== false;
+  const bm25 = options.bm25 !== false;
+  logger.debug("workspace:create", {
+    id,
+    name,
+    resolverCount: resolvers.length,
+    assistantSkills: options.assistantSkills !== false,
+    customMountResolvers: options.mounts?.length ?? 0,
+    customSkillsResolver: Boolean(options.skills),
+    checkSkillFileMtime,
+    bm25,
+  });
+
+  return new Workspace({
+    id,
+    name,
+    filesystem: (context) => resolveWorkspaceFilesystem(resolvers, context),
+    ...(skills
+      ? {
+          skills,
+          checkSkillFileMtime,
+        }
+      : {}),
+    bm25,
+  });
+}
+
+/* ---------------------------- private helpers ---------------------------- */
+
+/**
+ * Map an OBO user email to their Assistant skills directory in the
+ * workspace namespace.
+ */
+function userAssistantSkillsPath(userEmail: string): string {
+  return `/Users/${userEmail.trim()}/.assistant/skills`;
+}
+
+/**
+ * Return whether the request token carries a scope that allows workspace
+ * file API access (`workspace` or `all-apis` on {@link MASTRA_SCOPES_KEY}).
+ */
+function hasWorkspaceFileScope(requestContext: RequestContext | undefined): boolean {
+  return token.includesAccessTokenScope(
+    requestContext?.get(MASTRA_SCOPES_KEY),
+    WORKSPACE_FILE_SCOPES,
+  );
+}
+
+/**
+ * Built-in mount resolver for Assistant `SKILL.md` trees.
+ *
+ * Mounts {@link ASSISTANT_SHARED_SKILLS_PATH} when scope checks pass and
+ * `/Users/<email>/.assistant/skills` when {@link MASTRA_USER_EMAIL_KEY} is
+ * set. Returns empty mounts when the OBO user or client is missing.
+ * Mastra owns filesystem initialization.
+ */
+function resolveAssistantSkillsMounts(context: WorkspaceMountContext): WorkspaceMountContribution {
+  const mounts: Record<string, DatabricksWorkspaceFilesystem> = {};
+  const requestContext = context.requestContext;
+
+  if (!shouldMountAssistantSkills(requestContext)) {
+    logger.debug("assistant-skills:skipped", {
+      reason: !requestContext ? "no-request-context" : "missing-workspace-scope",
+      nodeEnv: process.env.NODE_ENV,
+      scopes: context.requestContext?.get(MASTRA_SCOPES_KEY),
+    });
+    return { mounts, skillPaths: [] };
+  }
+
+  const user = requestContext!.get(MASTRA_USER_KEY) as User | undefined;
+  const client = user?.executionContext.client;
+  if (!client) {
+    logger.debug("assistant-skills:skipped", {
+      reason: "missing-obo-client",
+      userId: user?.id,
+    });
+    return { mounts, skillPaths: [] };
+  }
+
+  mounts[ASSISTANT_WORKSPACE_SKILLS_MOUNT] = databricksFilesystem(
+    client,
+    ASSISTANT_SHARED_SKILLS_PATH,
+  );
+
+  const email = resolveScopedEmail(requestContext);
+  if (email) {
+    mounts[ASSISTANT_USER_SKILLS_MOUNT] = databricksFilesystem(
+      client,
+      userAssistantSkillsPath(email),
+      false,
+    );
+  }
+
+  logger.debug("assistant-skills:mounted", {
+    sharedPath: ASSISTANT_SHARED_SKILLS_PATH,
+    sharedMount: ASSISTANT_WORKSPACE_SKILLS_MOUNT,
+    userMount: email ? ASSISTANT_USER_SKILLS_MOUNT : undefined,
+    userPath: email ? userAssistantSkillsPath(email) : undefined,
+    mountKeys: Object.keys(mounts),
+  });
+
+  return { mounts, skillPaths: Object.keys(mounts) };
+}
+
+/**
+ * Fill in `id` and `name` when either is omitted on {@link CreateWorkspaceOptions}.
+ * Slugifies `name` into `id`; tokenizes `id` into a display `name`.
+ */
+function resolveWorkspaceIdentity(options: CreateWorkspaceOptions): {
+  id: string;
+  name: string;
+} {
+  let id = options.id;
+  let name = options.name;
+  if (!id) {
+    id = name ? string.toSlug(name) : "workspace";
+  }
+  if (!name) {
+    name = Array.from(string.tokenize(id)).join(" ");
+  }
+  return { id, name };
+}
+
+/** Collect built-in and caller-supplied mount resolvers for one workspace. */
+function buildMountResolvers(options: CreateWorkspaceOptions): WorkspaceMountResolver[] {
+  const resolvers: WorkspaceMountResolver[] = [];
+  const { assistantSkills = true, mounts } = options;
+  if (assistantSkills) {
+    resolvers.push(resolveAssistantSkillsMounts);
+  }
+  if (mounts?.length) {
+    resolvers.push(...mounts);
+  }
+  logger.debug("mounts:resolvers", {
+    assistantSkills,
+    builtInResolver: assistantSkills,
+    customResolverCount: mounts?.length ?? 0,
+    totalResolverCount: resolvers.length,
+  });
+  return resolvers;
+}
+
+/**
+ * Gate Assistant skill mounts on request context.
+ *
+ * Always allows mounts in development; in other environments requires
+ * {@link hasWorkspaceFileScope}.
+ */
+function shouldMountAssistantSkills(
+  requestContext: RequestContext | undefined,
+): requestContext is RequestContext {
+  if (!requestContext) return false;
+  if (process.env.NODE_ENV === "development") return true;
+  return hasWorkspaceFileScope(requestContext);
+}
+
+/** Read the trimmed OBO user email stamped on {@link MASTRA_USER_EMAIL_KEY}. */
+function resolveScopedEmail(requestContext: RequestContext | undefined): string | undefined {
+  const email = requestContext?.get(MASTRA_USER_EMAIL_KEY) as string | undefined;
+  return email?.trim() || undefined;
+}
+
+/** Construct a read-only {@link DatabricksWorkspaceFilesystem} for `basePath`. */
+function databricksFilesystem(
+  client: WorkspaceClient,
+  basePath: string,
+  readOnly: boolean = true,
+): DatabricksWorkspaceFilesystem {
+  return new DatabricksWorkspaceFilesystem({
+    client,
+    basePath,
+    readOnly,
+  });
+}
+
+/**
+ * Run every mount resolver for one request and merge mounts plus skill paths.
+ * Later resolvers overwrite mount keys from earlier ones.
+ */
+async function resolveWorkspaceContribution(
+  resolvers: WorkspaceMountResolver[],
+  context: WorkspaceMountContext,
+): Promise<WorkspaceMountContribution> {
+  const mounts: Record<string, WorkspaceFilesystem> = {};
+  const skillPaths: string[] = [];
+
+  for (const [index, resolver] of resolvers.entries()) {
+    const contribution = await resolver(context);
+    logger.debug("mounts:resolver", {
+      index,
+      mountKeys: Object.keys(contribution.mounts),
+      skillPaths: contribution.skillPaths ?? [],
+    });
+    Object.assign(mounts, contribution.mounts);
+    if (contribution.skillPaths?.length) {
+      skillPaths.push(...contribution.skillPaths);
+    }
+  }
+
+  logger.debug("mounts:merged", {
+    mountKeys: Object.keys(mounts),
+    skillPaths,
+  });
+
+  return { mounts, skillPaths };
+}
+
+/**
+ * Dynamic filesystem resolver passed to Mastra {@link Workspace}.
+ *
+ * Returns a {@link CompositeFilesystem} when any mount resolved; otherwise
+ * {@link emptyFilesystem}.
+ */
+async function resolveWorkspaceFilesystem(
+  resolvers: WorkspaceMountResolver[],
+  context: WorkspaceMountContext,
+): Promise<WorkspaceFilesystem> {
+  const { mounts } = await resolveWorkspaceContribution(resolvers, context);
+  const mountKeys = Object.keys(mounts);
+  if (mountKeys.length === 0) {
+    logger.debug("filesystem:empty", {
+      hasRequestContext: Boolean(context.requestContext),
+    });
+    return emptyFilesystem();
+  }
+  logger.debug("filesystem:composite", { mountKeys });
+  return new CompositeFilesystem({ mounts });
+}
+
+/**
+ * Build the dynamic {@link SkillsResolver} that collects `skillPaths` from
+ * every mount resolver on each request.
+ */
+function buildWorkspaceSkillsResolver(resolvers: WorkspaceMountResolver[]): SkillsResolver {
+  return async (context: SkillsContext) => {
+    const { skillPaths } = await resolveWorkspaceContribution(resolvers, context);
+    logger.debug("skills:resolved", { skillPaths });
+    return skillPaths ?? [];
+  };
+}