@dbx-tools/appkit-mastra 0.9.118 → 0.9.119

package/lib/src/remote-skills.d.ts

@@ -5,7 +5,7 @@
  * {@link AITOOLS_SOURCE} constant, a GitHub `owner/repo`, any git / GitLab URL,
  * or a direct download URL - and optional per-source policy.
  * {@link provisionRemoteSkills} materializes every source into a local
- * `SKILL.md` tree at app boot and returns read-only backing directories plus
+ * `SKILL.md` tree at app boot and returns read-only filesystem backings plus
  * their stable virtual workspace mounts.
  *
  * Resolution per source, in order:
@@ -26,35 +26,29 @@
  * source (or the top-level call) sets `failOnError: false`, in which case it is
  * logged and skipped so one bad source never takes the app down.
  *
- * Every provisioned tree carries a {@link METADATA_FILE} recording when each
- * source was last downloaded, and a source is only re-downloaded once that
- * record is older than {@link DEFAULT_REFRESH_TTL_MS} (seven days). This runs at app
- * BOOT, so without it a container that restarts a dozen times an hour re-pulls
- * the whole AI Tools set a dozen times for content that changes rarely. The
- * record travels WITH the tree rather than in process memory, so the reuse
- * survives a restart - which is the only way it helps a Databricks App at all.
- * Pass `refreshTtlMs: 0` to download on every boot.
+ * AI Tools uses the shared `@dbx-tools/cache` project cache with a one-day TTL,
+ * then hydrates one process-memory filesystem mounted at
+ * {@link AITOOLS_SKILLS_MOUNT} for every default workspace. Other sources keep
+ * a {@link METADATA_FILE} beside their provisioned tree and default to a
+ * seven-day refresh window. Pass `refreshTtlMs: 0` to download on every boot.
  *
- * The default destination is the Databricks workspace Assistant skills tree
- * (`/Workspace/.assistant/skills`), so provisioned skills persist across restarts and are
- * discovered by the built-in Assistant-skills mount. Pass `userEmail` (or an
- * explicit `databricksBasePath`) to target `/Workspace/Users/<email>/.assistant/skills`
- * instead. When no Databricks client is resolvable at startup - or the resolved
- * identity cannot WRITE the destination, which is the normal case for a
- * Databricks App service principal against the admin-owned shared tree (see
- * {@link openWritableWorkspace}) - the tree is written under
- * {@link localFS.tmpFS} and exposed through a stable read-only virtual mount
- * for the current process. Storage location degrades; the skills themselves do not.
+ * For non-AI-Tools sources, the default destination is the Databricks workspace
+ * Assistant skills tree (`/Workspace/.assistant/skills`). Pass `userEmail` or
+ * `databricksBasePath` to select another destination. When it is unavailable,
+ * the tree is exposed through a stable read-only local mount instead.
  *
  * @module
  */
 import type { WorkspaceClientLike } from "@dbx-tools/appkit";
 import { net } from "@dbx-tools/shared-core";
 import type { OneOrMany } from "@dbx-tools/shared-core";
+import { type FileSystem } from "@dbx-tools/shared-fs";
 /** Virtual workspace path reserved for locally provisioned Databricks AI Tools. */
 export declare const AITOOLS_SKILLS_MOUNT = "/.databricks/skills";
 /** Virtual workspace root for every other locally provisioned remote source. */
 export declare const REMOTE_SKILLS_MOUNT = "/.skills";
+/** How long the shared Databricks AI Tools snapshot is reused. */
+export declare const AITOOLS_REFRESH_TTL_MS: number;
 /**
  * Source constant selecting Databricks' own AI Tools skill set.
  *
@@ -108,13 +102,22 @@ export type RemoteSkillSource = net.UrlLike | AiToolsSource | RemoteSkillSourceO
  * a {@link ProvisionRemoteSkillsOptions} bag when top-level policy is needed.
  */
 export type RemoteSkillsOption = RemoteSkillSource | OneOrMany<RemoteSkillSource> | ProvisionRemoteSkillsOptions;
-/** Read-only local backing storage exposed at a stable virtual workspace path. */
-export interface LocalSkillMount {
+/** Read-only local directory exposed at a stable virtual workspace path. */
+export interface LocalSkillDirectoryMount {
     /** Physical local directory containing the provisioned `SKILL.md` tree. */
     root: string;
     /** Virtual path agents see inside the composed Mastra workspace. */
     mountPath: string;
 }
+/** Read-only process-local filesystem exposed at a stable virtual workspace path. */
+export interface MemorySkillMount {
+    /** Process-shared filesystem containing the provisioned `SKILL.md` tree. */
+    filesystem: FileSystem;
+    /** Virtual path agents see inside the composed Mastra workspace. */
+    mountPath: string;
+}
+/** Local skill backing accepted by every auto-created workspace. */
+export type LocalSkillMount = LocalSkillDirectoryMount | MemorySkillMount;
 /** Top-level remote-skills provisioning options. */
 export interface ProvisionRemoteSkillsOptions {
     /** Sources to materialize at startup. */
@@ -137,17 +140,18 @@ export interface ProvisionRemoteSkillsOptions {
     maxDownloadBytes?: number;
     /**
      * How long a provisioned tree is reused before its source is downloaded
-     * again, in milliseconds. Defaults to seven days; `0` re-downloads on every
-     * boot. A per-source `refreshTtlMs` wins over this.
+     * again, in milliseconds. AI Tools defaults to one day and other sources to
+     * seven days; `0` re-downloads on every boot. A per-source `refreshTtlMs` wins.
      */
     refreshTtlMs?: number;
 }
 /** What {@link provisionRemoteSkills} resolved. */
 export interface ProvisionedRemoteSkills {
     /**
-     * Extra read-only LOCAL skill mounts to hand Mastra when a source couldn't
-     * be written to Databricks. Physical temp/cache paths remain hidden behind
-     * stable virtual workspace paths.
+     * Extra read-only local or process-memory skill mounts to hand Mastra. AI
+     * Tools always uses process memory; other sources use this fallback when
+     * they could not be written to Databricks. Physical paths remain hidden
+     * behind stable virtual workspace paths.
      */
     localSkillMounts: LocalSkillMount[];
     /** Absolute Databricks destination each source was written to, if any. */
@@ -159,8 +163,8 @@ export interface ProvisionedRemoteSkills {
     skillNames: string[];
 }
 /**
- * What one source's last download left behind, as recorded in
- * {@link METADATA_FILE}.
+ * Metadata for one resolved source snapshot. General remote sources store it
+ * in {@link METADATA_FILE}; AI Tools stores it with the cache-package value.
  */
 export interface RemoteSkillCacheEntry {
     /** The source string this entry was downloaded from, for readability. */