@databricks/appkit 0.66.1 → 0.67.0

package/dist/plugins/agents/agents.js

@@ -1,9 +1,13 @@
 import { createLogger } from "../../logging/logger.js";
+import { getWorkspaceClient } from "../../context/execution-context.js";
+import "../../context/index.js";
 import { Plugin } from "../../plugin/plugin.js";
 import { toPlugin } from "../../plugin/to-plugin.js";
 import "../../plugin/index.js";
 import { defineManifest } from "../../registry/manifest-loader.js";
 import "../../registry/index.js";
+import { FilesConnector } from "../../connectors/files/client.js";
+import "../../connectors/files/index.js";
 import { buildMcpHostPolicy } from "../../connectors/mcp/host-policy.js";
 import { AppKitMcpClient } from "../../connectors/mcp/client.js";
 import "../../connectors/mcp/index.js";
@@ -18,6 +22,12 @@ import "../../core/agent/tools/index.js";
 import { loadAgentsFromDir } from "../../core/agent/load-agents.js";
 import { CODE_AGENTS_SOURCE_DIR, loadCodeAgentsFromDir, resolveCodeAgentsDir } from "../../core/agent/load-code-agents.js";
 import { normalizeToolResult } from "../../core/agent/normalize-result.js";
+import { parseSkill } from "../../core/agent/skills/parse-skill.js";
+import { loadSkillsFromDir } from "../../core/agent/skills/load-skills.js";
+import { readSkillResource } from "../../core/agent/skills/read-resource.js";
+import { renderLoadedSkill, renderSkillCatalog } from "../../core/agent/skills/render.js";
+import { resolveSkill, resolveSkillCatalog } from "../../core/agent/skills/resolve-catalog.js";
+import "../../core/agent/skills/index.js";
 import { buildBaseSystemPrompt, composeSystemPrompt } from "../../core/agent/system-prompt.js";
 import { agentStreamDefaults } from "./defaults.js";
 import { EventChannel } from "./event-channel.js";
@@ -99,6 +109,12 @@ var AgentsPlugin = class extends Plugin {
 	* negative, or `NaN`) can't degrade into immediate auto-denial of every
 	* mutating tool call.
 	*/
+	/**
+	* Shared global skill pool (bundle `skills/` + catalog volume), loaded once
+	* per registry build. Read by {@link buildRegisteredAgent} to resolve each
+	* agent's visible catalog and by the live `register` path.
+	*/
+	globalSkills = [];
 	cachedApprovalPolicy = null;
 	get resolvedApprovalPolicy() {
 		if (this.cachedApprovalPolicy) return this.cachedApprovalPolicy;
@@ -183,6 +199,8 @@ var AgentsPlugin = class extends Plugin {
 	async buildAgentRegistry() {
 		const discovered = await this.loadCodeAgents();
 		const deprecatedMapRaw = this.config.agents ?? {};
+		const [bundleSkills, volumeSkills] = await Promise.all([this.loadGlobalSkills(), this.loadVolumeSkills()]);
+		this.globalSkills = [...bundleSkills, ...volumeSkills];
 		if (Object.keys(deprecatedMapRaw).length > 0) this.warnAgentsMapDeprecated();
 		const deprecatedMap = {};
 		for (const [id, def] of Object.entries(deprecatedMapRaw)) {
@@ -352,7 +370,8 @@ var AgentsPlugin = class extends Plugin {
 	}
 	async buildRegisteredAgent(name, def, src) {
 		const adapter = await this.resolveAdapter(def, name);
-		const toolIndex = await this.buildToolIndex(name, def, src);
+		const skills = await this.resolveAgentSkills(name, def, src);
+		const toolIndex = await this.buildToolIndex(name, def, src, skills);
 		warnOnCapabilityMismatch(name, adapter, toolIndex);
 		return {
 			name,
@@ -363,9 +382,107 @@ var AgentsPlugin = class extends Plugin {
 			maxSteps: def.maxSteps,
 			maxTokens: def.maxTokens,
 			generationParams: def.generationParams,
-			ephemeral: def.ephemeral
+			ephemeral: def.ephemeral,
+			skills
 		};
 	}
+	/** Loads the shared global skill pool from `<agentsDir>/skills/`. */
+	async loadGlobalSkills() {
+		const dir = this.resolvedAgentsDir();
+		if (!dir) return [];
+		return loadSkillsFromDir(path.join(dir, "skills"), "bundle-global");
+	}
+	/** Configured catalog-skills volume path, or null when none is set. */
+	resolveSkillsVolume() {
+		const configured = this.config.skillsVolume ?? process.env.DATABRICKS_VOLUME_AGENT_SKILLS;
+		return configured && configured.trim() !== "" ? configured.trim() : null;
+	}
+	/**
+	* Workspace client used to read catalog skills. v1 reads as the app service
+	* principal; `getWorkspaceClient()` resolves to SP outside a user scope
+	* (boot and skill-tool dispatch are both unscoped). This is the single
+	* switch point for a future OBO mode.
+	*/
+	skillWorkspaceClient() {
+		return getWorkspaceClient();
+	}
+	/**
+	* Discovers catalog skills from the configured UC Volume, read as the
+	* service principal at boot (and on `reload()`). Each `<volume>/<name>/`
+	* folder with a `SKILL.md` becomes a `source: "volume"` skill. Best-effort:
+	* a missing volume, unavailable workspace client, or a malformed individual
+	* skill is logged and skipped rather than failing the whole registry build.
+	*/
+	async loadVolumeSkills() {
+		const volume = this.resolveSkillsVolume();
+		if (!volume) return [];
+		if ((this.config.skillCredentialMode ?? "sp") === "obo") logger.warn("skillCredentialMode 'obo' is not wired yet; reading catalog skills as the service principal.");
+		let client;
+		try {
+			client = this.skillWorkspaceClient();
+		} catch (err) {
+			logger.warn("Skipping catalog skills at '%s': no workspace client available (%s).", volume, err instanceof Error ? err.message : String(err));
+			return [];
+		}
+		const connector = new FilesConnector({ defaultVolume: volume });
+		let entries;
+		try {
+			entries = await connector.list(client, volume);
+		} catch (err) {
+			logger.warn("Failed to list catalog skills volume '%s': %s", volume, err instanceof Error ? err.message : String(err));
+			return [];
+		}
+		return (await Promise.all(entries.map(async (entry) => {
+			if (!entry.is_directory || !entry.name || !entry.path) return null;
+			const skillDir = entry.path;
+			const skillFile = `${skillDir}/SKILL.md`;
+			try {
+				const parsed = parseSkill(await connector.read(client, skillFile), skillFile);
+				const files = await this.listVolumeSkillFiles(connector, client, skillDir);
+				return {
+					name: parsed.name,
+					description: parsed.description,
+					body: parsed.body,
+					source: "volume",
+					dir: skillDir,
+					files,
+					allowedTools: parsed.allowedTools
+				};
+			} catch (err) {
+				logger.warn("Skipping catalog skill '%s': %s", skillDir, err instanceof Error ? err.message : String(err));
+				return null;
+			}
+		}))).filter((s) => s !== null);
+	}
+	/** Lists a volume skill's resource files (one level, excluding SKILL.md). */
+	async listVolumeSkillFiles(connector, client, skillDir) {
+		try {
+			return (await connector.list(client, skillDir)).filter((e) => !e.is_directory && e.name && e.name !== "SKILL.md").map((e) => e.name).sort();
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Resolves the per-agent skill catalog: loads this agent's private skills
+	* (`<agentsDir>/<id>/skills/`, file-origin only), then applies visibility
+	* (opt-in via `def.skills` or `autoInheritSkills`) and collision rules
+	* against the shared global pool. Returns `undefined` when nothing is
+	* visible so the prompt catalog and dispatch can cheaply skip skills.
+	*/
+	async resolveAgentSkills(name, def, src) {
+		const dir = this.resolvedAgentsDir();
+		const perAgentSkills = src.origin === "file" && dir ? await loadSkillsFromDir(path.join(dir, name, "skills"), "bundle-agent") : [];
+		const inherit = normalizeAutoInherit(this.config.autoInheritSkills);
+		const autoInherit = src.origin === "file" ? inherit.file : inherit.code;
+		const catalog = resolveSkillCatalog({
+			agentName: name,
+			agentSkillNames: def.skills,
+			perAgentSkills,
+			globalSkills: this.globalSkills,
+			autoInherit
+		});
+		return catalog.byAddress.size > 0 ? catalog : void 0;
+	}
 	async resolveAdapter(def, name) {
 		const source = def.model ?? this.config.defaultModel;
 		const adapterOptions = {};
@@ -391,7 +508,7 @@ var AgentsPlugin = class extends Plugin {
 	* hosted tools via MCP client. Applies `autoInheritTools` defaults when the
 	* definition has no declared tools/agents.
 	*/
-	async buildToolIndex(agentName, def, src) {
+	async buildToolIndex(agentName, def, src, skills) {
 		const index = /* @__PURE__ */ new Map();
 		const hasDeclaredTools = def.tools !== void 0;
 		const toolsRecord = this.resolveDefTools(agentName, def);
@@ -464,6 +581,20 @@ var AgentsPlugin = class extends Plugin {
 			throw new Error(`Agent '${agentName}' tool '${key}' has an unrecognized shape`);
 		}
 		if (hostedToCollect.length > 0) await this.connectHostedTools(hostedToCollect, index);
+		if (skills && skills.byAddress.size > 0) {
+			index.set("load_skill", {
+				source: "skill",
+				builtin: "load_skill",
+				catalog: skills,
+				def: LOAD_SKILL_TOOL_DEF
+			});
+			index.set("read_skill_file", {
+				source: "skill",
+				builtin: "read_skill_file",
+				catalog: skills,
+				def: READ_SKILL_FILE_TOOL_DEF
+			});
+		}
 		return index;
 	}
 	/**
@@ -644,9 +775,12 @@ var AgentsPlugin = class extends Plugin {
 		});
 	}
 	clientConfig() {
+		const skills = {};
+		for (const [name, agent] of this.agents) if (agent.skills) skills[name] = agent.skills.catalog;
 		return {
 			agents: Array.from(this.agents.keys()),
-			defaultAgent: this.defaultAgentName
+			defaultAgent: this.defaultAgentName,
+			skills
 		};
 	}
 	async _handleChat(req, res) {
@@ -658,7 +792,7 @@ var AgentsPlugin = class extends Plugin {
 			});
 			return;
 		}
-		const { message, threadId, agent: agentName, mlflowRunId } = parsed.data;
+		const { message, threadId, agent: agentName, mlflowRunId, skill } = parsed.data;
 		const registered = this.resolveAgent(agentName);
 		if (!registered) {
 			res.status(400).json({ error: agentName ? `Agent "${agentName}" not found` : "No agent registered" });
@@ -691,7 +825,7 @@ var AgentsPlugin = class extends Plugin {
 			res.status(500).json({ error: "Thread operation failed" });
 			return;
 		}
-		return this._streamAgent(req, res, registered, thread, userId, mlflowRunId);
+		return this._streamAgent(req, res, registered, thread, userId, mlflowRunId, skill);
 	}
 	/**
 	* Returns the names of tools in `registered.toolIndex` whose annotations
@@ -774,7 +908,7 @@ var AgentsPlugin = class extends Plugin {
 		}
 		return this._runAgentNonStreaming(req, res, registered, thread, userId, mlflowRunId);
 	}
-	async _streamAgent(req, res, registered, thread, userId, mlflowRunId) {
+	async _streamAgent(req, res, registered, thread, userId, mlflowRunId, forcedSkill) {
 		const abortController = new AbortController();
 		const signal = abortController.signal;
 		const requestId = randomUUID();
@@ -809,14 +943,19 @@ var AgentsPlugin = class extends Plugin {
 				})) }, async (span) => {
 					if (mlflowRunId) linkTraceToRun(mlflowRunId);
 					const pluginNames = this.context ? this.context.getPluginNames().filter((n) => n !== this.name && n !== "server") : [];
+					let fullPrompt = composePromptForAgent(registered, this.config.baseSystemPrompt, {
+						agentName: registered.name,
+						pluginNames,
+						toolNames: tools.map((t) => t.name)
+					});
+					if (forcedSkill) {
+						const addendum = this.renderForcedSkill(registered, forcedSkill);
+						if (addendum) fullPrompt = `${fullPrompt}\n\n${addendum}`;
+					}
 					const messagesWithSystem = [{
 						id: "system",
 						role: "system",
-						content: composePromptForAgent(registered, this.config.baseSystemPrompt, {
-							agentName: registered.name,
-							pluginNames,
-							toolNames: tools.map((t) => t.name)
-						}),
+						content: fullPrompt,
 						createdAt: /* @__PURE__ */ new Date()
 					}, ...thread.messages];
 					const fullContent = await consumeAdapterStream(registered.adapter.run({
@@ -1067,10 +1206,46 @@ var AgentsPlugin = class extends Plugin {
 				if (!childAgent) throw new Error(`Sub-agent not found: ${entry.agentName}`);
 				result = await this.runSubAgent(runState, childAgent, args, depth + 1);
 			} else if (entry.source === "hosted-supervisor") throw new Error(`Tool '${name}' is a hosted-supervisor tool and cannot be invoked from the Node process. It is executed server-side by the Databricks AI Gateway and is only reachable when the agent's model is a Supervisor API adapter.`);
+			else if (entry.source === "skill") result = await this.dispatchSkillTool(entry, args);
 			return result;
 		}));
 	}
 	/**
+	* Executes the built-in `load_skill` / `read_skill_file` tools against the
+	* agent's resolved skill catalog. `load_skill` returns a skill's body plus a
+	* manifest of bundled files; `read_skill_file` returns the contents of one
+	* of those files (bundle skills only in v1 — catalog-volume resource reads
+	* arrive with the volume source).
+	*/
+	async dispatchSkillTool(entry, args) {
+		const obj = typeof args === "object" && args !== null ? args : {};
+		const skillName = typeof obj.skill === "string" ? obj.skill.trim() : "";
+		if (!skillName) throw new Error(`'${entry.builtin}' requires a 'skill' argument naming the skill to use.`);
+		const skill = resolveSkill(entry.catalog, skillName);
+		if (entry.builtin === "load_skill") return renderLoadedSkill(skill);
+		const filePath = typeof obj.path === "string" ? obj.path.trim() : "";
+		if (!filePath) throw new Error("'read_skill_file' requires a 'path' argument.");
+		if (!skill.files.includes(filePath)) throw new Error(`Skill '${skill.name}' has no bundled file '${filePath}'. Available: ${skill.files.join(", ") || "<none>"}.`);
+		if (skill.source === "volume") return new FilesConnector({ defaultVolume: skill.dir }).read(this.skillWorkspaceClient(), `${skill.dir}/${filePath}`);
+		return readSkillResource(skill.dir, filePath);
+	}
+	/**
+	* Renders the prompt addendum for a force-loaded skill (`/skill-name`).
+	* Returns null when the agent has no catalog or the name doesn't resolve —
+	* an unusable request shouldn't fail the whole turn, so it's logged and the
+	* model proceeds with the catalog + `load_skill` still available.
+	*/
+	renderForcedSkill(registered, name) {
+		if (!registered.skills) return null;
+		try {
+			const skill = resolveSkill(registered.skills, name);
+			return `The user explicitly requested the "${skill.name}" skill for this turn. Its instructions:\n\n${renderLoadedSkill(skill)}`;
+		} catch (err) {
+			logger.warn("Ignoring forced skill '%s': %s", name, err instanceof Error ? err.message : String(err));
+			return null;
+		}
+	}
+	/**
 	* Runs a sub-agent in response to an `agent-<key>` tool call. Returns the
 	* concatenated text output to hand back to the parent adapter as the tool
 	* result.
@@ -1261,6 +1436,40 @@ function normalizeAutoInherit(value) {
 		code: value.code ?? false
 	};
 }
+/** Built-in tool the model calls to load a skill's full instructions on demand. */
+const LOAD_SKILL_TOOL_DEF = {
+	name: "load_skill",
+	description: "Load the full instructions for one of the available skills by name. Call this before acting on a task that matches a skill's description. Returns the skill's instructions plus a list of any bundled files you can read with read_skill_file.",
+	parameters: {
+		type: "object",
+		properties: { skill: {
+			type: "string",
+			description: "The exact skill name to load, as shown in the available-skills list."
+		} },
+		required: ["skill"]
+	},
+	annotations: { effect: "read" }
+};
+/** Built-in tool for reading a resource file that a loaded skill references. */
+const READ_SKILL_FILE_TOOL_DEF = {
+	name: "read_skill_file",
+	description: "Read a bundled resource file that a loaded skill references (e.g. a reference doc). Only files listed by load_skill for that skill are readable.",
+	parameters: {
+		type: "object",
+		properties: {
+			skill: {
+				type: "string",
+				description: "The skill that owns the file."
+			},
+			path: {
+				type: "string",
+				description: "Relative path of the file within the skill, as listed by load_skill."
+			}
+		},
+		required: ["skill", "path"]
+	},
+	annotations: { effect: "read" }
+};
 function composePromptForAgent(registered, pluginLevel, ctx) {
 	const perAgent = registered.baseSystemPrompt;
 	const resolved = perAgent !== void 0 ? perAgent : pluginLevel;
@@ -1269,7 +1478,10 @@ function composePromptForAgent(registered, pluginLevel, ctx) {
 	else if (typeof resolved === "string") base = resolved;
 	else if (typeof resolved === "function") base = resolved(ctx);
 	else base = buildBaseSystemPrompt(ctx);
-	return composeSystemPrompt(base, registered.instructions);
+	const composed = composeSystemPrompt(base, registered.instructions);
+	const catalog = registered.skills?.catalog;
+	if (!catalog || catalog.length === 0) return composed;
+	return `${composed}\n\n${renderSkillCatalog(catalog)}`;
 }
 /**
 * Pulls the LLM-readable description off any {@link SupervisorTool} kind.