@dbx-tools/appkit-mastra 0.9.5 → 0.9.7

package/src/genie.ts

@@ -44,9 +44,9 @@ import {
   ValidationError,
 } from "@databricks/appkit";
 import type { WorkspaceClient } from "@databricks/appkit";
-import { plugin } from "@dbx-tools/appkit";
+import { pluginRegistry } from "@dbx-tools/appkit";
 import { chat, space as genieSpace } from "@dbx-tools/genie";
-import { error, log, string } from "@dbx-tools/shared-core";
+import { errorUtils, log, stringUtils } from "@dbx-tools/shared-core";
 import { genieModel, type GenieMessage } from "@dbx-tools/shared-genie";
 import type { StartedEvent } from "@dbx-tools/shared-mastra";
 import type { RequestContext } from "@mastra/core/request-context";
@@ -245,7 +245,7 @@ async function readCachedConversationId(cacheKey: string | undefined): Promise<s
     return v ?? undefined;
   } catch (err) {
     logger.warn("conversation-cache:read-error", {
-      error: error.errorMessage(err),
+      error: errorUtils.errorMessage(err),
     });
     return undefined;
   }
@@ -269,7 +269,7 @@ async function saveCachedConversationId(
     });
   } catch (err) {
     logger.warn("conversation-cache:write-error", {
-      error: error.errorMessage(err),
+      error: errorUtils.errorMessage(err),
     });
   }
 }
@@ -281,7 +281,7 @@ async function evictCachedConversationId(cacheKey: string | undefined): Promise<
     await CacheManager.getInstanceSync().delete(cacheKey);
   } catch (err) {
     logger.warn("conversation-cache:delete-error", {
-      error: error.errorMessage(err),
+      error: errorUtils.errorMessage(err),
     });
   }
 }
@@ -324,7 +324,7 @@ const prepareChartRequestSchema = chartPlannerRequestSchema
       .string()
       .min(1, "statement_id is required")
       .describe(
-        string.toDescription(`
+        stringUtils.toDescription(`
           Genie \`statement_id\` to chart. Read from
           \`message.query_result.statement_id\` or
           \`message.attachments[*].query.statement_id\` returned by
@@ -345,7 +345,7 @@ const prepareChartRequestSchema = chartPlannerRequestSchema
  */
 function aliasSuffix(alias: string): string {
   if (alias === DEFAULT_GENIE_ALIAS) return "";
-  const slug = string.toIdentifier(alias);
+  const slug = stringUtils.toIdentifier(alias);
   return slug ? `_${slug}` : "";
 }
 
@@ -381,7 +381,7 @@ function buildAskGenieTool(opts: {
   const hintLine = hint ? ` (${hint})` : "";
   return createTool({
     id: toolId,
-    description: string.toDescription(`
+    description: stringUtils.toDescription(`
       Ask the Genie space "${alias}"${hintLine} ONE focused
       natural-language sub-question and wait for the turn to
       complete. Genie answers best when each call covers a
@@ -414,7 +414,7 @@ function buildAskGenieTool(opts: {
         .string()
         .min(1, "question is required")
         .describe(
-          string.toDescription(`
+          stringUtils.toDescription(`
             ONE focused natural-language question about the data in this
             space, covering a single metric / dimension / time window
             (e.g. "What was Q3 revenue by region?"). Decompose a
@@ -507,11 +507,11 @@ function buildAskGenieTool(opts: {
           // A rejected conversation id is stale or inaccessible. Reset this
           // lane and retry once with a fresh Genie conversation.
           const rejectedConversationId = conversationId;
-          if (rejectedConversationId && error.errorContext(err).notAccessible) {
+          if (rejectedConversationId && errorUtils.errorContext(err).notAccessible) {
             logger.warn("conversation-cache:stale, resetting", {
               spaceId,
               conversationId: rejectedConversationId,
-              error: error.errorMessage(err),
+              error: errorUtils.errorMessage(err),
             });
             if (ownsReusableConversation) {
               await evictCachedConversationId(cacheKey);
@@ -541,7 +541,7 @@ function buildSpaceDescriptionTool(opts: { spaceId: string; alias: string }) {
   const toolId = `get_space_description${aliasSuffix(alias)}`;
   return createTool({
     id: toolId,
-    description: string.toDescription(`
+    description: stringUtils.toDescription(`
       Return the Genie space "${alias}"'s title, description, and
       warehouse id. Cheap (single REST call, no LLM round-trip).
       Call this FIRST on any user turn that's going to touch
@@ -586,7 +586,7 @@ function buildSpaceSerializedTool(opts: { spaceId: string; alias: string }) {
   const toolId = `get_space_serialized${aliasSuffix(alias)}`;
   return createTool({
     id: toolId,
-    description: string.toDescription(`
+    description: stringUtils.toDescription(`
       Return the full \`GenieSpace\` JSON for the "${alias}" space.
       Use only when you need exact column / table identifiers
       \`get_space_description\` doesn't expose. Larger payload, so
@@ -625,7 +625,7 @@ function buildGetStatementTool() {
   const toolId = "get_statement";
   return createTool({
     id: toolId,
-    description: string.toDescription(`
+    description: stringUtils.toDescription(`
       Fetch the rows of a Genie statement by its \`statement_id\` (the
       value at \`message.query_result.statement_id\` or
       \`message.attachments[*].query.statement_id\` returned from
@@ -645,7 +645,7 @@ function buildGetStatementTool() {
         .string()
         .min(1, "statement_id is required")
         .describe(
-          string.toDescription(`
+          stringUtils.toDescription(`
             Genie \`statement_id\` whose rows to read. Take it from
             \`message.query_result.statement_id\` or
             \`message.attachments[*].query.statement_id\` on an
@@ -710,7 +710,7 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
   const toolId = "prepare_chart";
   return createTool({
     id: toolId,
-    description: string.toDescription([
+    description: stringUtils.toDescription([
       `
         Queue a chart for the rows of a Genie statement. Mints a
         \`chartId\` plus its complete \`marker\` synchronously and
@@ -782,7 +782,7 @@ function buildPrepareChartTool(opts: { config: MastraPluginConfig }) {
  * variant that names the suffixed per-space tools
  * (e.g. `ask_genie_sales`).
  */
-export const GENIE_INSTRUCTIONS = string.toDescription([
+export const GENIE_INSTRUCTIONS = stringUtils.toDescription([
   "Genie orchestration. For every user question that needs SQL-backed data:",
   {
     numbered: [
@@ -975,7 +975,7 @@ type AppKitGenieConfig = NonNullable<Parameters<typeof genie>[0]>;
  */
 export function resolveGenieSpaces(
   config: MastraPluginConfig,
-  context: plugin.PluginContextLike | undefined,
+  context: pluginRegistry.PluginContextLike | undefined,
 ): Record<string, GenieSpaceConfig> {
   const merged: Record<string, GenieSpaceConfig> = {};
 
@@ -988,7 +988,7 @@ export function resolveGenieSpaces(
   // Source 2: AppKit `genie()` plugin instance config. Use a
   // structural cast - `Plugin.config` is `protected` in TS only,
   // and the runtime layout is plain object property access.
-  const geniePlugin = plugin.instance(context, genie);
+  const geniePlugin = pluginRegistry.instance(context, genie);
   if (geniePlugin) {
     const pluginSpaces = (geniePlugin as unknown as { config?: AppKitGenieConfig }).config?.spaces;
     if (pluginSpaces) {
@@ -1142,7 +1142,7 @@ export async function collectSpaceSuggestions(opts: {
       } catch (err) {
         logger.warn("suggestions:fetch-error", {
           spaceId,
-          error: error.errorMessage(err),
+          error: errorUtils.errorMessage(err),
         });
         questions = [];
       }

package/src/memory.ts

@@ -33,7 +33,8 @@
  */
 
 import { getUsernameWithApiLookup } from "@databricks/appkit";
-import { error, hash, log } from "@dbx-tools/shared-core";
+import { migration as appkitMigration } from "@dbx-tools/appkit";
+import { hash, log } from "@dbx-tools/shared-core";
 import { fastembed } from "@mastra/fastembed";
 import { Memory } from "@mastra/memory";
 import { PgVector, PostgresStore } from "@mastra/pg";
@@ -46,19 +47,6 @@ import { summaryModel, TITLE_INSTRUCTIONS } from "./summarize.ts";
 
 const logger = log.logger("mastra/memory");
 
-/** Process-wide dedupe so instance + per-agent stores share one ownership log. */
-const loggedMigrationErrors = new Set<string>();
-
-/** Whether `LOG_LEVEL` is currently at or below debug. */
-function isDebugEnabled(): boolean {
-  return log.isLevelEnabled("debug");
-}
-
-/** Whether a migration failed only because this role does not own an existing object. */
-function isOwnershipMigrationError(err: unknown): boolean {
-  return error.errorContext(err).hasMessage("must be owner");
-}
-
 /**
  * Soften {@link PostgresStore.init} so a failed migration (e.g. Lakebase
  * `must be owner of table …` on `ALTER`) is logged once instead of rethrown
@@ -87,19 +75,15 @@ export function withSoftStorageInit(store: PostgresStore): PostgresStore {
       try {
         await originalInit();
       } catch (err) {
-        if (!isOwnershipMigrationError(err)) throw err;
-        const message = error.errorMessage(err);
-        if (!loggedMigrationErrors.has(message)) {
-          loggedMigrationErrors.add(message);
-          if (isDebugEnabled()) {
-            logger.error("mastra storage migration failed", err);
-          } else {
-            logger.warn("mastra storage migration failed", {
-              error: message,
-              storeId: soft.id,
-              schema: soft.schema,
-            });
-          }
+        if (
+          !appkitMigration.handleOwnershipMigrationError(err, {
+            scope: "mastra-storage",
+            logger,
+            event: "mastra storage migration failed",
+            context: { storeId: soft.id, schema: soft.schema },
+          })
+        ) {
+          throw err;
         }
       }
     })();

package/src/mlflow.ts

@@ -22,7 +22,7 @@
  */
 
 import { appkit } from "@dbx-tools/appkit";
-import { async, error, log } from "@dbx-tools/shared-core";
+import { asyncUtils, errorUtils, log } from "@dbx-tools/shared-core";
 import { feedback } from "@dbx-tools/shared-mastra";
 import { databricksFetch, readResponseJson, readResponseText } from "./rest.ts";
 
@@ -125,7 +125,7 @@ export async function logFeedback(
     } catch (err) {
       logger.warn("feedback request failed", {
         traceId: params.traceId,
-        error: error.errorMessage(err),
+        error: errorUtils.errorMessage(err),
       });
       return undefined;
     }
@@ -139,7 +139,7 @@ export async function logFeedback(
     // Trace export is async; a fresh trace may not exist yet. Retry a
     // few times with a short backoff before giving up softly.
     if (res.status === 404 && attempt < NOT_FOUND_RETRIES) {
-      await async.sleep(NOT_FOUND_BACKOFF_MS * (attempt + 1));
+      await asyncUtils.sleep(NOT_FOUND_BACKOFF_MS * (attempt + 1));
       continue;
     }
     logger.warn("feedback not recorded", {

package/src/model.ts

@@ -26,7 +26,7 @@
 import { getExecutionContext } from "@databricks/appkit";
 import { classes, invoke, resolve } from "@dbx-tools/model";
 import { ModelServingApi, modelServingApi } from "@dbx-tools/model-rs";
-import { functionModule, json, log, net } from "@dbx-tools/shared-core";
+import { functionUtils, json, log, net } from "@dbx-tools/shared-core";
 import { model, type ServingEndpointSummary } from "@dbx-tools/shared-model";
 import type { MastraModelConfig } from "@mastra/core/llm";
 import type { RequestContext } from "@mastra/core/request-context";
@@ -193,12 +193,12 @@ const CHAT_COMPLETIONS_PATH = `/${invoke.CHAT_COMPLETIONS_PATH}`;
  *      `choices[].message.content` or `choices[].delta.content` as a parts
  *      array that the AI SDK's OpenAI schema rejects.
  *
- * Safe to call from any hot path: {@link functionModule.memoize} ensures
+ * Safe to call from any hot path: {@link functionUtils.memoize} ensures
  * the wrapper is installed at most once per process, so subsequent
  * calls are a no-op even when {@link buildModel} fires on every agent
  * step.
  */
-const setupFetchInterceptor = functionModule.memoize((): void => {
+const setupFetchInterceptor = functionUtils.memoize((): void => {
   globalThis.fetch = createServingFetchInterceptor(globalThis.fetch.bind(globalThis));
 });
 

package/src/monty-sandbox.ts

@@ -8,7 +8,7 @@
  * @module
  */
 
-import { error, functionModule } from "@dbx-tools/shared-core";
+import { errorUtils, functionUtils } from "@dbx-tools/shared-core";
 import type {
   CommandResult,
   ExecuteCommandOptions,
@@ -20,8 +20,8 @@ import type { CheckoutOptions, Monty as MontyPool, MontySession } from "@pydanti
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_MEMORY_BYTES = 10_000_000;
 
-const montyModule = functionModule.memoize(() => import("@pydantic/monty/node"));
-const montyPool = functionModule.memoize(async (): Promise<MontyPool> => {
+const montyModule = functionUtils.memoize(() => import("@pydantic/monty/node"));
+const montyPool = functionUtils.memoize(async (): Promise<MontyPool> => {
   const { Monty } = await montyModule();
   return Monty.create({
     minProcesses: 1,
@@ -76,7 +76,7 @@ export class MontySandbox implements WorkspaceSandbox {
       this.status = "running";
     } catch (caught) {
       this.status = "error";
-      this.error = error.errorMessage(caught);
+      this.error = errorUtils.errorMessage(caught);
       throw caught;
     }
   }
@@ -181,7 +181,7 @@ export class MontySandbox implements WorkspaceSandbox {
       if (aborted || options.abortSignal?.aborted) {
         throw abortReason(options.abortSignal);
       }
-      const message = error.errorMessage(caught);
+      const message = errorUtils.errorMessage(caught);
       output.emit("stderr", output.stderr.value ? `\n${message}` : message);
       const { MontyCrashedError } = await montyModule();
       const timedOut = caught instanceof MontyCrashedError && caught.timedOut;

package/src/observability.ts

@@ -42,7 +42,7 @@
  * @module
  */
 
-import { project } from "@dbx-tools/core";
+import { projectUtils } from "@dbx-tools/core";
 import { log } from "@dbx-tools/shared-core";
 import { Observability } from "@mastra/observability";
 import { OtelBridge } from "@mastra/otel-bridge";
@@ -122,7 +122,7 @@ export async function buildObservability(
     return undefined;
   }
 
-  const serviceName = options?.serviceName ?? (await project.name()) ?? DEFAULT_SERVICE_NAME;
+  const serviceName = options?.serviceName ?? (await projectUtils.name()) ?? DEFAULT_SERVICE_NAME;
   const requestContextKeys = [...(options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS)];
 
   // The OTel HTTP exporter treats `OTEL_EXPORTER_OTLP_ENDPOINT` as a

package/src/plugin.ts

@@ -56,9 +56,9 @@ import {
   type PluginManifest,
   type ResourceRequirement,
 } from "@databricks/appkit";
-import { plugin } from "@dbx-tools/appkit";
-import { serving as modelServing } from "@dbx-tools/model";
-import { async, error, log, object, string } from "@dbx-tools/shared-core";
+import { pluginRegistry } from "@dbx-tools/appkit";
+import { modelCatalog } from "@dbx-tools/model";
+import { asyncUtils, errorUtils, log, object, stringUtils } from "@dbx-tools/shared-core";
 import {
   feedback,
   routes,
@@ -77,7 +77,12 @@ import type { Pool } from "pg";
 import { buildAgents, FALLBACK_AGENT_ID, type BuiltAgents } from "./agents.ts";
 import { fetchChart } from "./chart.ts";
 import { agentChatRoutes } from "./chat.ts";
-import { attributedUserId, MASTRA_CONFIG_SCHEMA, type MastraPluginConfig } from "./config.ts";
+import {
+  attributedUserId,
+  executionContextUserId,
+  MASTRA_CONFIG_SCHEMA,
+  type MastraPluginConfig,
+} from "./config.ts";
 import {
   chartFetchDefaults,
   feedbackWriteDefaults,
@@ -109,8 +114,8 @@ import { fetchStatementData, STATEMENT_ROW_CAP } from "./statement.ts";
 import { attachChatTurnTraceIo } from "./trace-io.ts";
 import { invalidFields } from "./validation.ts";
 
-const GENIE_MANIFEST = plugin.data(genie).plugin.manifest;
-const LAKEBASE_MANIFEST = plugin.data(lakebase).plugin.manifest;
+const GENIE_MANIFEST = pluginRegistry.data(genie).plugin.manifest;
+const LAKEBASE_MANIFEST = pluginRegistry.data(lakebase).plugin.manifest;
 
 /**
  * Budget for draining the memory service-principal pool on shutdown. Well
@@ -278,7 +283,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
    * already in the registry by the time this fires.
    */
   private applyLakebaseAutoDefaults(): void {
-    const hasLakebase = plugin.instance(this.context, lakebase) !== undefined;
+    const hasLakebase = pluginRegistry.instance(this.context, lakebase) !== undefined;
     if (!hasLakebase) return;
     if (this.config.storage === undefined) this.config.storage = true;
     if (this.config.memory === undefined) this.config.memory = true;
@@ -300,10 +305,10 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // early cannot hold the event loop open for the rest of the window.
     const budget = new AbortController();
     try {
-      await Promise.race([pool.end(), async.sleep(POOL_DRAIN_TIMEOUT_MS, budget.signal)]);
+      await Promise.race([pool.end(), asyncUtils.sleep(POOL_DRAIN_TIMEOUT_MS, budget.signal)]);
     } catch (err) {
       this.logger.error("error closing memory SP pool", {
-        error: error.errorMessage(err),
+        error: errorUtils.errorMessage(err),
       });
     } finally {
       budget.abort();
@@ -411,7 +416,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
        * Returns the underlying `CacheManager.delete`/`clear` promise.
        */
       clearModelsCache: (host?: string): Promise<void> =>
-        modelServing.clearServingEndpointsCache(host),
+        modelCatalog.clearServingEndpointsCache(host),
     };
   }
 
@@ -517,7 +522,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       req: express.Request,
       res: express.Response,
     ): Promise<void> => {
-      const requested = string.firstNonEmpty(req.params.agentId);
+      const requested = stringUtils.firstNonEmpty(req.params.agentId);
       if (requested !== null && !this.built?.agents[requested]) {
         res.status(404).json({ error: this.unknownAgentMessage(requested) });
         return;
@@ -611,8 +616,8 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
       method: "get",
       path: `${routes.MASTRA_ROUTES.embed}/:type/:id`,
       handler: async (req, res) => {
-        const type = string.firstNonEmpty(req.params.type) ?? "";
-        const id = string.firstNonEmpty(req.params.id);
+        const type = stringUtils.firstNonEmpty(req.params.type) ?? "";
+        const id = stringUtils.firstNonEmpty(req.params.id);
         const resolve = embedResolvers[type];
         if (!resolve) {
           this.logger.warn("embed:unsupported", {
@@ -874,7 +879,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     if (Object.keys(spaces).length === 0) return { ok: true, data: [] };
     const client = getExecutionContext().client;
     return this.execute((executeSignal) => {
-      const combined = async.combineAbortSignals(signal, executeSignal);
+      const combined = asyncUtils.combineAbortSignals(signal, executeSignal);
       return collectSpaceSuggestions({
         spaces,
         client,
@@ -931,7 +936,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     const limit = Math.min(options.limit ?? STATEMENT_ROW_CAP, STATEMENT_ROW_CAP);
     return this.execute(
       async (executeSignal) => {
-        const combined = async.combineAbortSignals(options.signal, executeSignal);
+        const combined = asyncUtils.combineAbortSignals(options.signal, executeSignal);
         try {
           const data = await fetchStatementData(client, statementId, {
             limit,
@@ -946,7 +951,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         } catch (err) {
           // The Databricks SDK throws on 404; surface as `undefined`
           // so the route maps to a clean HTTP 404 instead of a 500.
-          if (error.errorContext(err).notAccessible) return undefined;
+          if (errorUtils.errorContext(err).notAccessible) return undefined;
           throw err;
         }
       },
@@ -990,7 +995,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
         fetchChart(chartId, {
           userKey,
           ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-          signal: async.combineAbortSignals(options.signal, executeSignal) ?? options.signal,
+          signal: asyncUtils.combineAbortSignals(options.signal, executeSignal) ?? options.signal,
         }),
       chartFetchDefaults,
     );
@@ -1003,10 +1008,15 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
    */
   private async listModelsResult(): Promise<ExecutionResult<ServingEndpointSummary[]>> {
     return this.execute(async () => {
-      const client = getExecutionContext().client;
+      const context = getExecutionContext();
+      const client = context.client;
+      const cacheIdentity = executionContextUserId(context);
       const host = (await client.config.getHost()).toString();
       const serving = resolveServingConfig(this.config);
-      return modelServing.listServingEndpoints(client, host, { ttlMs: serving.ttlMs });
+      return modelCatalog.listServingEndpoints(client, host, {
+        ttlMs: serving.ttlMs,
+        cacheIdentity,
+      });
     }, modelCatalogueDefaults);
   }
 
@@ -1037,7 +1047,7 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // `PgVector` singleton so registering N agents stays cheap. See
     // `./memory.js`.
     if (needsLakebase(this.config)) {
-      const spPgConfig = plugin
+      const spPgConfig = pluginRegistry
         .require(this.context, lakebase, this.config)
         .exports()
         .getPgConfig();

package/src/remote-skills.ts

@@ -57,10 +57,19 @@ import type { WorkspaceClient } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
 import type { WorkspaceClientLike } from "@dbx-tools/appkit";
 import { exec } from "@dbx-tools/core";
-import { DatabricksFileSystem, workspace as databricksWorkspace } from "@dbx-tools/databricks";
+import { DatabricksFileSystem, workspaceClient } from "@dbx-tools/databricks";
 import { localFS, type LocalFileSystem } from "@dbx-tools/fs";
 import { find } from "@dbx-tools/path";
-import { error, hash, json, log, net, object, string } from "@dbx-tools/shared-core";
+import {
+  asyncUtils,
+  errorUtils,
+  hash,
+  json,
+  log,
+  net,
+  object,
+  stringUtils,
+} from "@dbx-tools/shared-core";
 import type { OneOrMany } from "@dbx-tools/shared-core";
 import type { FileSystem } from "@dbx-tools/shared-fs";
 
@@ -312,11 +321,11 @@ function isAiToolsSource(source: string): boolean {
  * not what a success produces.
  */
 function cachePolicy(sourceOptions: NormalizedSource): RemoteSkillCacheEntry["policy"] {
-  const skills = string.parseList(sourceOptions.skills);
+  const skills = stringUtils.parseList(sourceOptions.skills);
   const policy = {
     ...(skills.length > 0 ? { skills: [...skills].sort() } : {}),
     ...(sourceOptions.experimental === true ? { experimental: true } : {}),
-    ...(string.trimToNull(sourceOptions.ref) ? { ref: sourceOptions.ref!.trim() } : {}),
+    ...(stringUtils.trimToNull(sourceOptions.ref) ? { ref: sourceOptions.ref!.trim() } : {}),
   };
   return Object.keys(policy).length > 0 ? policy : undefined;
 }
@@ -359,7 +368,7 @@ async function readMetadata(fs: FileSystem): Promise<RemoteSkillsMetadata | unde
     if (!object.isRecord(parsed) || parsed.version !== METADATA_VERSION) return undefined;
     return object.isRecord(parsed.sources) ? parsed : undefined;
   } catch (err) {
-    logger.debug("cache:unreadable", { error: error.errorMessage(err) });
+    logger.debug("cache:unreadable", { error: errorUtils.errorMessage(err) });
     return undefined;
   }
 }
@@ -490,13 +499,13 @@ export async function provisionRemoteSkills(
       } catch (err) {
         if (failOnError) {
           throw new Error(
-            `failed to provision remote skill source "${sourceOptions.source}": ${error.errorMessage(err)}`,
-            { cause: error.toError(err) },
+            `failed to provision remote skill source "${sourceOptions.source}": ${errorUtils.errorMessage(err)}`,
+            { cause: errorUtils.toError(err) },
           );
         }
         logger.warn("source:skipped", {
           source: sourceOptions.source,
-          error: error.errorMessage(err),
+          error: errorUtils.errorMessage(err),
         });
       }
     }
@@ -533,7 +542,7 @@ async function openWritableWorkspace(
   client: WorkspaceClient,
 ): Promise<DatabricksFileSystem | undefined> {
   const fs = new DatabricksFileSystem({
-    client: databricksWorkspace.toLegacyWorkspaceClient(client),
+    client: workspaceClient.toLegacyWorkspaceClient(client),
     root: basePath,
     readOnly: false,
     createRoot: true,
@@ -544,7 +553,7 @@ async function openWritableWorkspace(
   } catch (err) {
     logger.warn("destination:unwritable", {
       destination: basePath,
-      error: error.errorMessage(err),
+      error: errorUtils.errorMessage(err),
     });
     return undefined;
   }
@@ -559,7 +568,7 @@ function resolveDatabricksBasePath(
 ): string | undefined {
   if (!client) return undefined;
   if (options.databricksBasePath) return options.databricksBasePath.trim() || undefined;
-  const email = string.trimToNull(options.userEmail);
+  const email = stringUtils.trimToNull(options.userEmail);
   // A named user targets their personal Assistant tree (the "save a skill"
   // target); otherwise the shared workspace Assistant tree, which the built-in
   // Assistant-skills mount already scans.
@@ -598,13 +607,13 @@ async function stageAiTools(
   options: ProvisionRemoteSkillsOptions,
 ): Promise<string> {
   const maxBytes = resolveMaxBytes(sourceOptions, options);
-  const ref = string.trimToNull(sourceOptions.ref) ?? AITOOLS_REF;
+  const ref = stringUtils.trimToNull(sourceOptions.ref) ?? AITOOLS_REF;
   const manifest = json.parse(
     (await download(aiToolsRawUrl(ref, "manifest.json"), maxBytes)).toString("utf8"),
     undefined,
   ) as AiToolsManifest | undefined;
 
-  const wanted = new Set(string.parseList(sourceOptions.skills));
+  const wanted = new Set(stringUtils.parseList(sourceOptions.skills));
   const selected = Object.entries(manifest?.skills ?? {}).filter(([name, entry]) =>
     wanted.size > 0
       ? wanted.has(name)
@@ -620,11 +629,15 @@ async function stageAiTools(
       path: join(target, name, ...file.split("/")),
     })),
   );
-  await mapConcurrent(files, AITOOLS_CONCURRENCY, async (item) => {
-    const body = await download(item.url, maxBytes);
-    await mkdir(dirname(item.path), { recursive: true });
-    await writeFile(item.path, body);
-  });
+  await asyncUtils.mapConcurrent(
+    files,
+    async (item) => {
+      const body = await download(item.url, maxBytes);
+      await mkdir(dirname(item.path), { recursive: true });
+      await writeFile(item.path, body);
+    },
+    { concurrency: AITOOLS_CONCURRENCY },
+  );
 
   logger.debug("aitools:staged", { ref, skills: selected.length, files: files.length });
   return target;
@@ -635,21 +648,6 @@ function aiToolsRawUrl(ref: string, path: string): string {
   return `https://raw.githubusercontent.com/${AITOOLS_REPO}/${ref}/${path}`;
 }
 
-/** Run `worker` over `items`, at most `limit` in flight. */
-async function mapConcurrent<T>(
-  items: readonly T[],
-  limit: number,
-  worker: (item: T) => Promise<void>,
-): Promise<void> {
-  let cursor = 0;
-  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
-    while (cursor < items.length) {
-      await worker(items[cursor++]!);
-    }
-  });
-  await Promise.all(runners);
-}
-
 /**
  * Copy a source into `target` with the `skills` CLI when it is installed.
  * Returns the dir holding the copied `SKILL.md` trees, or `undefined` when the
@@ -671,10 +669,10 @@ async function stageViaSkillsCli(
     "--copy",
     "-y",
   ];
-  for (const skill of string.parseList(sourceOptions.skills)) {
+  for (const skill of stringUtils.parseList(sourceOptions.skills)) {
     args.push("--skill", skill);
   }
-  if (string.parseList(sourceOptions.skills).length === 0) args.push("--skill", "*");
+  if (stringUtils.parseList(sourceOptions.skills).length === 0) args.push("--skill", "*");
 
   const result = await exec.spawn(cli.command, args, {
     cwd: target,
@@ -723,7 +721,7 @@ async function stageViaFetch(
     );
   }
   const buffer = await download(url.toString(), resolveMaxBytes(sourceOptions, options));
-  const name = string.toSlug(deriveSkillName(url.toString())) || "remote-skill";
+  const name = stringUtils.toSlug(deriveSkillName(url.toString())) || "remote-skill";
   const skillDir = join(target, name);
   await mkdir(skillDir, { recursive: true });
   await writeFile(join(skillDir, "SKILL.md"), buffer);
@@ -743,8 +741,8 @@ async function download(url: string, maxBytes: number): Promise<Buffer> {
   const response = await fetch(url, {
     signal: AbortSignal.timeout(DEFAULT_DOWNLOAD_TIMEOUT_MS),
   }).catch((err) => {
-    throw new Error(`download failed (${url}): ${error.errorMessage(err)}`, {
-      cause: error.toError(err),
+    throw new Error(`download failed (${url}): ${errorUtils.errorMessage(err)}`, {
+      cause: errorUtils.toError(err),
     });
   });
   if (!response.ok) {