@dbx-tools/appkit-mastra 0.9.196 → 0.9.200

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -36,23 +36,23 @@
36
36
  },
37
37
  "dependencies": {
38
38
  "@databricks/appkit": "0.81.0",
39
- "@dbx-tools/appkit": "0.9.196",
40
- "@dbx-tools/appkit-model-gateway": "0.9.196",
41
- "@dbx-tools/cache": "0.9.196",
42
- "@dbx-tools/core": "0.9.196",
43
- "@dbx-tools/databricks": "0.9.196",
44
- "@dbx-tools/fs": "0.9.196",
45
- "@dbx-tools/genie": "0.9.196",
46
- "@dbx-tools/model": "0.9.196",
47
- "@dbx-tools/model-protocol": "0.9.196",
48
- "@dbx-tools/path": "0.9.196",
49
- "@dbx-tools/postgres": "0.9.196",
50
- "@dbx-tools/shared-core": "0.9.196",
51
- "@dbx-tools/shared-fs": "0.9.196",
52
- "@dbx-tools/shared-genie": "0.9.196",
53
- "@dbx-tools/shared-mastra": "0.9.196",
54
- "@dbx-tools/shared-model": "0.9.196",
55
- "@dbx-tools/shared-model-gateway": "0.9.196",
39
+ "@dbx-tools/appkit": "0.9.200",
40
+ "@dbx-tools/appkit-model-gateway": "0.9.200",
41
+ "@dbx-tools/cache": "0.9.200",
42
+ "@dbx-tools/core": "0.9.200",
43
+ "@dbx-tools/databricks": "0.9.200",
44
+ "@dbx-tools/fs": "0.9.200",
45
+ "@dbx-tools/genie": "0.9.200",
46
+ "@dbx-tools/model": "0.9.200",
47
+ "@dbx-tools/model-protocol": "0.9.200",
48
+ "@dbx-tools/path": "0.9.200",
49
+ "@dbx-tools/postgres": "0.9.200",
50
+ "@dbx-tools/shared-core": "0.9.200",
51
+ "@dbx-tools/shared-fs": "0.9.200",
52
+ "@dbx-tools/shared-genie": "0.9.200",
53
+ "@dbx-tools/shared-mastra": "0.9.200",
54
+ "@dbx-tools/shared-model": "0.9.200",
55
+ "@dbx-tools/shared-model-gateway": "0.9.200",
56
56
  "@mastra/ai-sdk": "1.10.5",
57
57
  "@mastra/core": "1.71.0",
58
58
  "@mastra/express": "1.5.15",
@@ -90,7 +90,7 @@
90
90
  "./package.json": "./package.json"
91
91
  }
92
92
  },
93
- "version": "0.9.196",
93
+ "version": "0.9.200",
94
94
  "types": "./lib/index.d.ts",
95
95
  "dbxToolsConfig": {
96
96
  "tags": [
@@ -10,7 +10,7 @@
10
10
  */
11
11
 
12
12
  import { scratchFS } from "@dbx-tools/fs";
13
- import { FileSystemError, dirname, normalize } from "@dbx-tools/shared-fs";
13
+ import { FileSystemError, basename, dirname, normalize } from "@dbx-tools/shared-fs";
14
14
  import type {
15
15
  FileEntry as SharedFileEntry,
16
16
  FileStat as SharedFileStat,
@@ -73,6 +73,9 @@ export interface MastraFileSystemAdapterOptions extends MastraFilesystemOptions
73
73
  readOnly?: boolean;
74
74
  }
75
75
 
76
+ /** Shared virtual skill aliases used by composite filesystems for one request. */
77
+ export type SkillAliasRegistry = Map<string, { sourcePath: string; skillContent: string }>;
78
+
76
79
  /**
77
80
  * Wrap a portable {@link FileSystem} as a Mastra {@link MastraFilesystem}.
78
81
  *
@@ -326,18 +329,91 @@ export class MastraFileSystemAdapter extends MastraFilesystem {
326
329
  * virtual-root lookup into an unrelated mount.
327
330
  */
328
331
  export class MountedCompositeFilesystem extends CompositeFilesystem {
329
- constructor(config: CompositeFilesystemConfig) {
332
+ private readonly skillAliases: SkillAliasRegistry;
333
+
334
+ constructor(config: CompositeFilesystemConfig, skillAliases: SkillAliasRegistry = new Map()) {
330
335
  super(config);
336
+ this.skillAliases = skillAliases;
337
+ }
338
+
339
+ /** Register a read-only virtual skill path backed by an existing source directory. */
340
+ registerSkillAlias(aliasPath: string, sourcePath: string, skillContent: string): void {
341
+ const alias = normalizeWorkspacePath(aliasPath);
342
+ const source = normalizeWorkspacePath(sourcePath);
343
+ this.skillAliases.set(alias, { sourcePath: source, skillContent });
331
344
  }
332
345
 
333
346
  override async readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer> {
347
+ const resolved = this.resolveSkillAlias(inputPath);
348
+ if (resolved?.relativePath === "SKILL.md") {
349
+ return options?.encoding ? resolved.skillContent : Buffer.from(resolved.skillContent, "utf8");
350
+ }
334
351
  if (
335
352
  (inputPath === ".gitignore" || inputPath === "/.gitignore") &&
336
353
  !this.getFilesystemForPath(inputPath)
337
354
  ) {
338
355
  return options?.encoding ? "" : Buffer.alloc(0);
339
356
  }
340
- return super.readFile(inputPath, options);
357
+ return super.readFile(resolved?.sourcePath ?? inputPath, options);
358
+ }
359
+
360
+ override async readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]> {
361
+ const resolved = this.resolveSkillAlias(inputPath);
362
+ return super.readdir(resolved?.sourcePath ?? inputPath, options);
363
+ }
364
+
365
+ override async exists(inputPath: string): Promise<boolean> {
366
+ const resolved = this.resolveSkillAlias(inputPath);
367
+ return super.exists(resolved?.sourcePath ?? inputPath);
368
+ }
369
+
370
+ override async stat(inputPath: string): Promise<FileStat> {
371
+ const resolved = this.resolveSkillAlias(inputPath);
372
+ const stat = await super.stat(resolved?.sourcePath ?? inputPath);
373
+ if (!resolved) return stat;
374
+ const path = normalizeWorkspacePath(inputPath);
375
+ return { ...stat, name: basename(path), path };
376
+ }
377
+
378
+ override async isFile(inputPath: string): Promise<boolean> {
379
+ const resolved = this.resolveSkillAlias(inputPath);
380
+ return super.isFile(resolved?.sourcePath ?? inputPath);
381
+ }
382
+
383
+ override async isDirectory(inputPath: string): Promise<boolean> {
384
+ const resolved = this.resolveSkillAlias(inputPath);
385
+ return super.isDirectory(resolved?.sourcePath ?? inputPath);
386
+ }
387
+
388
+ private resolveSkillAlias(inputPath: string):
389
+ | {
390
+ sourcePath: string;
391
+ relativePath: string;
392
+ skillContent: string;
393
+ }
394
+ | undefined {
395
+ const path = normalizeWorkspacePath(inputPath);
396
+ let selected:
397
+ | {
398
+ aliasPath: string;
399
+ sourcePath: string;
400
+ skillContent: string;
401
+ }
402
+ | undefined;
403
+ for (const [aliasPath, alias] of this.skillAliases) {
404
+ if (path !== aliasPath && !path.startsWith(`${aliasPath}/`)) continue;
405
+ if (!selected || aliasPath.length > selected.aliasPath.length) {
406
+ selected = { aliasPath, ...alias };
407
+ }
408
+ }
409
+ if (!selected) return undefined;
410
+ const relativePath =
411
+ path === selected.aliasPath ? "" : path.slice(selected.aliasPath.length + 1);
412
+ return {
413
+ sourcePath: relativePath ? `${selected.sourcePath}/${relativePath}` : selected.sourcePath,
414
+ relativePath,
415
+ skillContent: selected.skillContent,
416
+ };
341
417
  }
342
418
  }
343
419
 
package/src/workspaces.ts CHANGED
@@ -62,6 +62,7 @@ import {
62
62
  type WorkspaceSandboxResolver,
63
63
  type WorkspaceToolsConfig,
64
64
  } from "@mastra/core/workspace";
65
+ import { stringify as stringifyYaml } from "yaml";
65
66
 
66
67
  import {
67
68
  MASTRA_SCOPES_KEY,
@@ -74,6 +75,7 @@ import {
74
75
  filesystems,
75
76
  MountedCompositeFilesystem,
76
77
  type MastraFileSystemAdapterOptions,
78
+ type SkillAliasRegistry,
77
79
  } from "./filesystems.ts";
78
80
  import { MontySandbox } from "./monty-sandbox.ts";
79
81
  import type { LocalSkillMount } from "./remote-skills.ts";
@@ -181,6 +183,8 @@ interface WorkspaceMountContribution {
181
183
  mounts: Record<string, WorkspaceFilesystem>;
182
184
  /** Paths within the composite namespace where `SKILL.md` files are scanned. */
183
185
  skillPaths?: string[];
186
+ /** Shared aliases visible to every composite resolved for this request. */
187
+ skillAliases?: SkillAliasRegistry;
184
188
  }
185
189
 
186
190
  /** Internal filesystem contribution resolver. */
@@ -847,17 +851,26 @@ export async function inlineSkillsFromLocalMounts(
847
851
  const filesystem = await inMemorySkillFilesystem(mount);
848
852
  const entries = await filesystem.readdir("/");
849
853
  for (const entry of entries) {
850
- if (entry.type !== "directory" || selected.has(entry.name)) continue;
854
+ if (entry.type !== "directory") continue;
851
855
  const skillPath = entry.name;
852
856
  const skillFile = `${skillPath}/SKILL.md`;
853
857
  if (!(await filesystem.exists(skillFile))) continue;
854
858
  const content = await filesystem.readFile(skillFile, { encoding: "utf8" });
855
- const parsed = validateSkillContent({
856
- content: String(content),
857
- directoryName: entry.name,
858
- });
859
- if (!parsed.valid || !parsed.metadata || parsed.instructions === undefined) {
860
- throw new Error(`Invalid local skill ${entry.name}: ${parsed.errors.join("; ")}`);
859
+ const resolved = resolveSkillContent(String(content), entry.name);
860
+ if (!resolved.ok) {
861
+ logger.warn("local-skill:skipped", {
862
+ path: skillFile,
863
+ errors: resolved.errors,
864
+ });
865
+ continue;
866
+ }
867
+ if (selected.has(resolved.name)) continue;
868
+ if (resolved.normalized) {
869
+ logger.warn("local-skill:normalized", {
870
+ path: skillFile,
871
+ name: resolved.originalName,
872
+ normalizedName: resolved.name,
873
+ });
861
874
  }
862
875
  const references: Record<string, string> = {};
863
876
  for (const file of await filesystem.readdir(skillPath, { recursive: true })) {
@@ -867,17 +880,20 @@ export async function inlineSkillsFromLocalMounts(
867
880
  await filesystem.readFile(`${skillPath}/${file.name}`, { encoding: "utf8" }),
868
881
  );
869
882
  }
870
- const metadata = parsed.metadata;
883
+ const metadata = resolved.metadata;
871
884
  selected.set(
872
- entry.name,
885
+ resolved.name,
873
886
  createSkill({
874
- name: String(metadata.name),
887
+ name: resolved.name,
875
888
  description: String(metadata.description),
876
- instructions: parsed.instructions,
889
+ instructions: resolved.instructions,
877
890
  ...(typeof metadata.license === "string" ? { license: metadata.license } : {}),
878
891
  ...(metadata.compatibility !== undefined
879
892
  ? { compatibility: metadata.compatibility }
880
893
  : {}),
894
+ ...(typeof metadata["user-invocable"] === "boolean"
895
+ ? { "user-invocable": metadata["user-invocable"] }
896
+ : {}),
881
897
  ...(isRecord(metadata.metadata) ? { metadata: metadata.metadata } : {}),
882
898
  ...(Object.keys(references).length > 0 ? { references } : {}),
883
899
  }),
@@ -887,6 +903,90 @@ export async function inlineSkillsFromLocalMounts(
887
903
  return [...selected.values()];
888
904
  }
889
905
 
906
+ type ResolvedSkillContent =
907
+ | {
908
+ ok: true;
909
+ name: string;
910
+ originalName: unknown;
911
+ metadata: Record<string, unknown>;
912
+ instructions: string;
913
+ content: string;
914
+ normalized: boolean;
915
+ }
916
+ | { ok: false; errors: string[] };
917
+
918
+ /** Validate one skill and normalize failures limited to its identifier. */
919
+ function resolveSkillContent(content: string, directoryName: string): ResolvedSkillContent {
920
+ const parsed = validateSkillContent({ content, directoryName });
921
+ if (parsed.valid && parsed.metadata && parsed.instructions !== undefined) {
922
+ return {
923
+ ok: true,
924
+ name: String(parsed.metadata.name),
925
+ originalName: parsed.metadata.name,
926
+ metadata: parsed.metadata as Record<string, unknown>,
927
+ instructions: parsed.instructions,
928
+ content,
929
+ normalized: false,
930
+ };
931
+ }
932
+ if (
933
+ !parsed.metadata ||
934
+ parsed.instructions === undefined ||
935
+ parsed.errors.some((error) => !isRecoverableSkillNameError(error))
936
+ ) {
937
+ return { ok: false, errors: parsed.errors };
938
+ }
939
+ const originalName = parsed.metadata.name;
940
+ const normalizedName = normalizeSkillName(
941
+ typeof originalName === "string" ? originalName : directoryName,
942
+ );
943
+ if (!normalizedName) return { ok: false, errors: parsed.errors };
944
+ const metadata = parsed.metadata as Record<string, unknown>;
945
+ const normalizedContent = renderSkillContent(metadata, parsed.instructions, normalizedName);
946
+ const normalized = validateSkillContent({
947
+ content: normalizedContent,
948
+ directoryName: normalizedName,
949
+ });
950
+ if (!normalized.valid || !normalized.metadata || normalized.instructions === undefined) {
951
+ return { ok: false, errors: [...parsed.errors, ...normalized.errors] };
952
+ }
953
+ return {
954
+ ok: true,
955
+ name: normalizedName,
956
+ originalName,
957
+ metadata: normalized.metadata as Record<string, unknown>,
958
+ instructions: normalized.instructions,
959
+ content: normalizedContent,
960
+ normalized: true,
961
+ };
962
+ }
963
+
964
+ function isRecoverableSkillNameError(error: string): boolean {
965
+ return error.startsWith("name:") || error.startsWith("Skill name ");
966
+ }
967
+
968
+ function normalizeSkillName(value: string): string {
969
+ return toSlug(value).slice(0, 64).replace(/-+$/, "");
970
+ }
971
+
972
+ function renderSkillContent(
973
+ metadata: Record<string, unknown>,
974
+ instructions: string,
975
+ name: string,
976
+ ): string {
977
+ const frontmatter = {
978
+ name,
979
+ description: metadata.description,
980
+ ...(typeof metadata.license === "string" ? { license: metadata.license } : {}),
981
+ ...(metadata.compatibility !== undefined ? { compatibility: metadata.compatibility } : {}),
982
+ ...(typeof metadata["user-invocable"] === "boolean"
983
+ ? { "user-invocable": metadata["user-invocable"] }
984
+ : {}),
985
+ ...(isRecord(metadata.metadata) ? { metadata: metadata.metadata } : {}),
986
+ };
987
+ return `---\n${stringifyYaml(frontmatter).trimEnd()}\n---\n\n${instructions.trim()}\n`;
988
+ }
989
+
890
990
  function inMemorySkillFilesystem(mount: LocalSkillMount): Promise<FileSystem> {
891
991
  const key = "root" in mount ? `root:${mount.root}` : `filesystem:${mount.filesystem.id}`;
892
992
  const existing = sharedSkillFilesystems.get(key);
@@ -1094,6 +1194,7 @@ async function resolveWorkspaceContribution(
1094
1194
  return {
1095
1195
  mounts,
1096
1196
  skillPaths,
1197
+ skillAliases: new Map(),
1097
1198
  };
1098
1199
  }
1099
1200
 
@@ -1109,7 +1210,7 @@ async function resolveWorkspaceFilesystem(
1109
1210
  filesCache?: FilesCacheExports,
1110
1211
  sourceKey?: string,
1111
1212
  ): Promise<WorkspaceFilesystem> {
1112
- const { mounts } = await resolveContribution(context);
1213
+ const { mounts, skillAliases } = await resolveContribution(context);
1113
1214
  const mountKeys = Object.keys(mounts);
1114
1215
  if (mountKeys.length === 0) {
1115
1216
  logger.debug("filesystem:empty", {
@@ -1120,7 +1221,7 @@ async function resolveWorkspaceFilesystem(
1120
1221
  });
1121
1222
  }
1122
1223
  logger.debug("filesystem:composite", { mountKeys });
1123
- const load = () => new MountedCompositeFilesystem({ mounts });
1224
+ const load = () => new MountedCompositeFilesystem({ mounts }, skillAliases);
1124
1225
  if (!filesCache) return load();
1125
1226
  const scoped = await resolveFilesCacheScope(context);
1126
1227
  if (!scoped) return load();
@@ -1128,9 +1229,9 @@ async function resolveWorkspaceFilesystem(
1128
1229
  }
1129
1230
 
1130
1231
  /**
1131
- * Expand configured skill paths into concrete skill directories and keep the first
1132
- * same-named directory. Mastra still owns parsing, indexing, and refreshes,
1133
- * while earlier configured roots retain precedence over later roots.
1232
+ * Expand configured skill paths into validated skill directories. Malformed
1233
+ * skills are skipped, identifier-only failures receive virtual normalized paths,
1234
+ * and earlier configured roots retain precedence over later roots.
1134
1235
  */
1135
1236
  async function resolveDistinctSkillPaths(
1136
1237
  filesystem: WorkspaceFilesystem,
@@ -1141,20 +1242,50 @@ async function resolveDistinctSkillPaths(
1141
1242
  for (const path of paths) {
1142
1243
  try {
1143
1244
  const entries = await filesystem.readdir(path);
1144
- if (entries.some((entry) => entry.type === "file" && entry.name === "SKILL.md")) {
1145
- const name = basename(path);
1146
- if (!excludedSkillNames.has(name) && !selected.has(name)) selected.set(name, path);
1147
- continue;
1148
- }
1149
- for (const entry of entries) {
1150
- if (
1151
- entry.type !== "directory" ||
1152
- excludedSkillNames.has(entry.name) ||
1153
- selected.has(entry.name)
1154
- ) {
1245
+ const candidates = entries.some((entry) => entry.type === "file" && entry.name === "SKILL.md")
1246
+ ? [path]
1247
+ : entries
1248
+ .filter((entry) => entry.type === "directory")
1249
+ .map((entry) => posixPath.join(path, entry.name));
1250
+ for (const candidate of candidates) {
1251
+ const skillFile = posixPath.join(candidate, "SKILL.md");
1252
+ if (!(await filesystem.exists(skillFile))) continue;
1253
+ const content = await filesystem.readFile(skillFile, { encoding: "utf8" });
1254
+ const resolved = resolveSkillContent(String(content), basename(candidate));
1255
+ if (!resolved.ok) {
1256
+ logger.warn("workspace-skill:skipped", {
1257
+ path: skillFile,
1258
+ errors: resolved.errors,
1259
+ });
1155
1260
  continue;
1156
1261
  }
1157
- selected.set(entry.name, posixPath.join(path, entry.name));
1262
+ if (excludedSkillNames.has(resolved.name) || selected.has(resolved.name)) continue;
1263
+ let selectedPath = candidate;
1264
+ if (resolved.normalized) {
1265
+ if (!(filesystem instanceof MountedCompositeFilesystem)) {
1266
+ logger.warn("workspace-skill:skipped", {
1267
+ path: skillFile,
1268
+ errors: ["Skill identifier requires normalization on an unsupported filesystem"],
1269
+ });
1270
+ continue;
1271
+ }
1272
+ const aliasPath = posixPath.join(posixPath.dirname(candidate), resolved.name);
1273
+ if (aliasPath !== candidate && (await filesystem.exists(aliasPath))) {
1274
+ logger.warn("workspace-skill:skipped", {
1275
+ path: skillFile,
1276
+ errors: [`Normalized skill path already exists: ${aliasPath}`],
1277
+ });
1278
+ continue;
1279
+ }
1280
+ filesystem.registerSkillAlias(aliasPath, candidate, resolved.content);
1281
+ selectedPath = aliasPath;
1282
+ logger.warn("workspace-skill:normalized", {
1283
+ path: skillFile,
1284
+ name: resolved.originalName,
1285
+ normalizedName: resolved.name,
1286
+ });
1287
+ }
1288
+ selected.set(resolved.name, selectedPath);
1158
1289
  }
1159
1290
  } catch (error) {
1160
1291
  logger.debug("skill-path:skipped", {