@dbx-tools/appkit-mastra 0.6.9 → 0.6.11

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

@@ -1,19 +1,24 @@
 /**
  * Startup provisioning of remote Agent-Skill sources for a Mastra workspace.
  *
- * A {@link RemoteSkillSource} names WHERE a `SKILL.md` tree comes from - 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 the directories
- * to hand Mastra as extra skill scan paths.
+ * A {@link RemoteSkillSource} names WHERE a `SKILL.md` tree comes from - the
+ * {@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 the directories to hand Mastra as
+ * extra skill scan paths.
  *
  * Resolution per source, in order:
  *
- * 1. the OPTIONAL `skills` npm CLI (peer dep): if installed, each source is
+ * 1. the {@link AITOOLS_SOURCE} constant (`"aitools"`): Databricks' own skill
+ *    set, read straight from the public repo the `databricks aitools` CLI
+ *    sources from. No CLI, no Databricks auth - which is what makes it usable
+ *    inside a Databricks App container, where the CLI is not installed;
+ * 2. the OPTIONAL `skills` npm CLI (peer dep): if installed, each source is
  *    copied into a staging dir with `skills add <source> --agent <dir> --copy`,
  *    which understands every source format the ecosystem does (GitHub
  *    shorthand, git URLs, archive/download URLs);
- * 2. otherwise a plain {@link fetch} of the source URL (built with
+ * 3. otherwise a plain {@link fetch} of the source URL (built with
  *    {@link net.urlBuilder}), writing the downloaded `SKILL.md` to a staging
  *    dir.
  *
@@ -27,24 +32,39 @@
  * discovered by the built-in Assistant-skills mount. Pass `userEmail` (or an
  * explicit `databricksBasePath`) to target `/Users/<email>/.assistant/skills`
  * instead. When no Databricks client is resolvable at startup, the tree is
- * written to a local temp dir and returned as an extra local skill path for
- * the current process.
+ * written under {@link localFS.tmpFS} and returned as an extra local skill path
+ * for the current process.
  *
  * @module
  */
 import type { WorkspaceClientLike } from "@dbx-tools/appkit";
+import { net } from "@dbx-tools/shared-core";
+import type { OneOrMany } from "@dbx-tools/shared-core";
+/**
+ * Source constant selecting Databricks' own AI Tools skill set.
+ *
+ * @example
+ * mastra({ remoteSkills: "aitools" });
+ */
+export declare const AITOOLS_SOURCE = "aitools";
+/** The {@link AITOOLS_SOURCE} literal, for callers spelling the union out. */
+export type AiToolsSource = typeof AITOOLS_SOURCE;
 /**
  * One remote skill source and its per-source policy.
  *
- * `source` is anything the `skills` ecosystem understands: a GitHub
- * `owner/repo` shorthand, a full GitHub / GitLab / git URL, or a direct
- * download URL to a `SKILL.md` or archive.
+ * `source` is {@link AITOOLS_SOURCE} or anything the `skills` ecosystem
+ * understands: a GitHub `owner/repo` shorthand, a full GitHub / GitLab / git
+ * URL, or a direct download URL to a `SKILL.md` or archive.
  */
 export interface RemoteSkillSourceOptions {
-    /** GitHub shorthand, git / GitLab URL, or a direct download URL. */
-    source: string;
-    /** Install only these skill names from the source (CLI path only). */
+    /** `"aitools"`, a GitHub shorthand, a git / GitLab URL, or a download URL. */
+    source: net.UrlLike | AiToolsSource;
+    /** Install only these skill names from the source. */
     skills?: string | string[];
+    /** Include experimental skills. `"aitools"` only. */
+    experimental?: boolean;
+    /** Pin the repo ref (tag / branch / sha). `"aitools"` only; defaults to `main`. */
+    ref?: string;
     /** Override the byte ceiling on a direct-fetch download for this source. */
     maxDownloadBytes?: number;
     /**
@@ -54,19 +74,20 @@ export interface RemoteSkillSourceOptions {
     failOnError?: boolean;
 }
 /**
- * A remote skill source: a bare source string (GitHub shorthand / URL) or a
- * {@link RemoteSkillSourceOptions} with per-source policy.
+ * A remote skill source: the {@link AITOOLS_SOURCE} constant, a URL-like
+ * (string / `URL` / `{ url }`), or a {@link RemoteSkillSourceOptions} bag with
+ * per-source policy.
  */
-export type RemoteSkillSource = string | RemoteSkillSourceOptions;
+export type RemoteSkillSource = net.UrlLike | AiToolsSource | RemoteSkillSourceOptions;
 /**
- * The workspace `remoteSkills` option. A single source, a list, or a
- * {@link ProvisionRemoteSkillsOptions} bag when top-level policy is needed.
+ * The workspace `remoteSkills` option: one source, a non-empty list of them, or
+ * a {@link ProvisionRemoteSkillsOptions} bag when top-level policy is needed.
  */
-export type RemoteSkillsOption = RemoteSkillSource | RemoteSkillSource[] | ProvisionRemoteSkillsOptions;
+export type RemoteSkillsOption = RemoteSkillSource | OneOrMany<RemoteSkillSource> | ProvisionRemoteSkillsOptions;
 /** Top-level remote-skills provisioning options. */
 export interface ProvisionRemoteSkillsOptions {
     /** Sources to materialize at startup. */
-    sources: RemoteSkillSource | RemoteSkillSource[];
+    sources: RemoteSkillSource | OneOrMany<RemoteSkillSource>;
     /**
      * Fail app startup when a source can't be resolved. Defaults to `true`. A
      * per-source `failOnError` wins over this.
@@ -103,7 +124,7 @@ export declare function normalizeRemoteSkillsOption(option: RemoteSkillsOption |
  * Materialize every configured remote skill source at app startup.
  *
  * Writes each resolved `SKILL.md` tree to the Databricks user Assistant skills
- * folder when a writable workspace is available, else to a local temp dir
- * returned in {@link ProvisionedRemoteSkills.localSkillPaths}.
+ * folder when a writable workspace is available, else under
+ * {@link localFS.tmpFS} returned in {@link ProvisionedRemoteSkills.localSkillPaths}.
  */
 export declare function provisionRemoteSkills(option: RemoteSkillsOption | undefined): Promise<ProvisionedRemoteSkills>;