@databricks/appkit 0.68.0 → 0.69.0

package/dist/plugins/agents/agents.js

@@ -6,12 +6,10 @@ 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";
-import { SUPERVISOR_EXTENSION_KEY, isSupervisorTool } from "../../agents/supervisor-api.js";
+import { isSupervisorTool } from "../../agents/supervisor-api.js";
 import { consumeAdapterStream } from "../../core/agent/consume-adapter-stream.js";
 import { createPluginsProxy } from "../../core/agent/plugins-map.js";
 import { resolveToolkitFromProvider } from "../../core/agent/toolkit-resolver.js";
@@ -20,68 +18,43 @@ import { isHostedTool, resolveHostedTools } from "../../core/agent/tools/hosted-
 import { isToolkitEntry } from "../../core/agent/types.js";
 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 { CODE_AGENTS_SOURCE_DIR } from "../../core/agent/load-code-agents.js";
+import { ActiveStreamTracker } from "./active-stream-tracker.js";
+import { buildAdapterExtensions, supervisorToolDescription, warnOnCapabilityMismatch } from "./adapter-extensions.js";
+import { requiresApproval } from "./approval.js";
+import { LOAD_SKILL_TOOL_DEF, READ_SKILL_FILE_TOOL_DEF } from "./builtin-tools.js";
 import { agentStreamDefaults } from "./defaults.js";
 import { EventChannel } from "./event-channel.js";
 import { AgentEventTranslator } from "./event-translator.js";
 import manifest_default from "./manifest.js";
-import { currentTraceId, initAgentTracing, linkTraceToRun, traceAgent, traceTool } from "./mlflow.js";
+import { currentTraceId, initAgentTracing, linkTraceToRun, traceAgent } from "./mlflow.js";
+import { composePromptForAgent } from "./prompt.js";
+import { loadCodeAgents, resolveDefaultAgent } from "./registry.js";
+import { resolveApprovalPolicy, resolveLimits } from "./resolve-config.js";
 import { approvalRequestSchema, cancelRequestSchema, chatRequestSchema, invocationsRequestSchema } from "./schemas.js";
+import { dispatchSkillTool, loadGlobalSkills, loadVolumeSkills, renderForcedSkill, resolveAgentSkills } from "./skill-loader.js";
 import { InMemoryThreadStore } from "./thread-store.js";
 import { ToolApprovalGate } from "./tool-approval-gate.js";
+import { dispatchToolCall } from "./tool-dispatch.js";
 import { randomUUID } from "node:crypto";
 import pc from "picocolors";
 import path from "node:path";
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 
 //#region src/plugins/agents/agents.ts
 const logger = createLogger("agents");
 /** Deprecated markdown location, read as a fallback with a one-time warning. */
 const LEGACY_MARKDOWN_DIR = "config/agents";
-/**
-* Decide whether a tool call must traverse the approval gate. Honours both
-* the modern `effect` field (mutating values: write / update / destructive)
-* and the legacy `destructive: true` boolean. The contract is documented on
-* `ToolAnnotations.effect` in shared/agent.ts.
-*
-* Without this, a tool authored only with `effect: "destructive"` (the
-* preferred API) bypassed the gate entirely.
-*/
-function requiresApproval(annotations) {
-	if (!annotations) return false;
-	if (annotations.destructive === true) return true;
-	switch (annotations.effect) {
-		case "write":
-		case "update":
-		case "destructive": return true;
-		case "read":
-		case void 0: return false;
-		default:
-			annotations.effect;
-			return false;
-	}
-}
 var AgentsPlugin = class extends Plugin {
 	static manifest = defineManifest(manifest_default);
 	static phase = "deferred";
 	agents = /* @__PURE__ */ new Map();
 	defaultAgentName = null;
-	activeStreams = /* @__PURE__ */ new Map();
 	/**
-	* Per-user stream count, kept in sync with `activeStreams` so the
-	* concurrent-stream rate limit check is O(1) instead of O(n) over every
-	* active stream on every request. Mutated only via {@link trackStream}
-	* and {@link untrackStream}.
+	* Active SSE streams + per-user counts (the O(1) concurrency-limit check).
+	* Mutated only via {@link trackStream} / {@link untrackStream}.
 	*/
-	userStreamCounts = /* @__PURE__ */ new Map();
+	streams = new ActiveStreamTracker();
 	mcpClient = null;
 	threadStore;
 	approvalGate = new ToolApprovalGate();
@@ -118,59 +91,22 @@ var AgentsPlugin = class extends Plugin {
 	cachedApprovalPolicy = null;
 	get resolvedApprovalPolicy() {
 		if (this.cachedApprovalPolicy) return this.cachedApprovalPolicy;
-		const cfg = this.config.approval ?? {};
-		const APPROVAL_TIMEOUT_FLOOR_MS = 1e3;
-		const APPROVAL_TIMEOUT_DEFAULT_MS = 6e4;
-		let timeoutMs = cfg.timeoutMs ?? APPROVAL_TIMEOUT_DEFAULT_MS;
-		if (!Number.isFinite(timeoutMs) || timeoutMs < APPROVAL_TIMEOUT_FLOOR_MS) {
-			logger.warn("approval.timeoutMs=%s is below the %sms floor; using default %sms instead. Mutating tool calls would otherwise auto-deny before any UI could respond.", cfg.timeoutMs, APPROVAL_TIMEOUT_FLOOR_MS, APPROVAL_TIMEOUT_DEFAULT_MS);
-			timeoutMs = APPROVAL_TIMEOUT_DEFAULT_MS;
-		}
-		this.cachedApprovalPolicy = {
-			requireForDestructive: cfg.requireForDestructive ?? true,
-			timeoutMs
-		};
+		this.cachedApprovalPolicy = resolveApprovalPolicy(this.config);
 		return this.cachedApprovalPolicy;
 	}
 	/** Effective DoS limits with defaults applied. */
 	get resolvedLimits() {
-		const cfg = this.config.limits ?? {};
-		return {
-			maxConcurrentStreamsPerUser: cfg.maxConcurrentStreamsPerUser ?? 5,
-			maxToolCalls: cfg.maxToolCalls ?? 50,
-			maxSubAgentDepth: cfg.maxSubAgentDepth ?? 3,
-			toolCallTimeoutMs: cfg.toolCallTimeoutMs ?? 3e5
-		};
+		return resolveLimits(this.config);
 	}
 	/** Count active streams owned by a given user. O(1). */
 	countUserStreams(userId) {
-		return this.userStreamCounts.get(userId) ?? 0;
+		return this.streams.count(userId);
 	}
-	/**
-	* Register a stream for `userId` and bump the per-user counter. Paired
-	* with {@link untrackStream}; the two helpers are the only writers to
-	* `activeStreams` + `userStreamCounts`, so the counter cannot drift from
-	* the map.
-	*/
 	trackStream(requestId, userId, controller) {
-		this.activeStreams.set(requestId, {
-			controller,
-			userId
-		});
-		this.userStreamCounts.set(userId, (this.userStreamCounts.get(userId) ?? 0) + 1);
+		this.streams.track(requestId, userId, controller);
 	}
-	/**
-	* Remove a stream from the active map and decrement the per-user
-	* counter. Idempotent — calling twice for the same `requestId` is a
-	* no-op (the second call sees no entry and returns early).
-	*/
 	untrackStream(requestId) {
-		const entry = this.activeStreams.get(requestId);
-		if (!entry) return;
-		this.activeStreams.delete(requestId);
-		const next = (this.userStreamCounts.get(entry.userId) ?? 0) - 1;
-		if (next <= 0) this.userStreamCounts.delete(entry.userId);
-		else this.userStreamCounts.set(entry.userId, next);
+		this.streams.untrack(requestId);
 	}
 	async setup() {
 		await initAgentTracing();
@@ -258,14 +194,7 @@ var AgentsPlugin = class extends Plugin {
 	* markdown `default: true` > first registered (insertion order).
 	*/
 	resolveDefaultAgent(agents, merged, fileDefault) {
-		if (this.config.defaultAgent) {
-			if (!agents.has(this.config.defaultAgent)) throw new Error(`defaultAgent '${this.config.defaultAgent}' is not registered. Available: ${Array.from(agents.keys()).join(", ")}`);
-			return this.config.defaultAgent;
-		}
-		const codeDefault = Object.keys(merged).filter((id) => merged[id].src.origin === "code" && merged[id].def.default).sort()[0];
-		if (codeDefault) return codeDefault;
-		if (fileDefault && agents.has(fileDefault)) return fileDefault;
-		return agents.keys().next().value ?? null;
+		return resolveDefaultAgent(agents, merged, fileDefault, this.config.defaultAgent);
 	}
 	/**
 	* Emits the one-time deprecation warning for the `agents({ agents })` map.
@@ -288,37 +217,11 @@ var AgentsPlugin = class extends Plugin {
 	resolvedAgentsDir() {
 		return path.resolve(process.cwd(), CODE_AGENTS_SOURCE_DIR);
 	}
-	/**
-	* Discovers code agents (see {@link resolveCodeAgentsDir} and
-	* {@link loadCodeAgentsFromDir}). Warns if sources exist but nothing was
-	* discovered — usually the build didn't emit the compiled agents — unless
-	* the deprecated `agents({ agents })` map is carrying them instead.
-	*/
-	async loadCodeAgents() {
-		const resolved = resolveCodeAgentsDir({
-			cwd: process.cwd(),
-			exists: existsSync
+	loadCodeAgents() {
+		return loadCodeAgents({
+			agentsDir: this.resolvedAgentsDir(),
+			hasDeprecatedMap: Object.keys(this.config.agents ?? {}).length > 0
 		});
-		const discovered = await loadCodeAgentsFromDir(resolved.dir, { extensions: resolved.extensions });
-		const usingDeprecatedMap = Object.keys(this.config.agents ?? {}).length > 0;
-		const sourceDir = this.resolvedAgentsDir();
-		if (Object.keys(discovered).length === 0 && !usingDeprecatedMap && this.hasCodeAgentSources(sourceDir)) logger.warn("Found code-agent sources in %s but discovered no code agents (scanned %s). In a production build, ensure `<dir>/*/agent.ts` is included as tsdown entries so the compiled agents are emitted.", sourceDir, resolved.dir);
-		return discovered;
-	}
-	/** True when `dir` holds at least one `<id>/agent.ts` folder. */
-	hasCodeAgentSources(dir) {
-		try {
-			return readdirSync(dir, { withFileTypes: true }).some((e) => {
-				if (!e.isDirectory() && !e.isSymbolicLink()) return false;
-				try {
-					return readdirSync(path.join(dir, e.name)).includes("agent.ts");
-				} catch {
-					return false;
-				}
-			});
-		} catch {
-			return false;
-		}
 	}
 	async loadFileDefinitions(codeAgents) {
 		const primaryDir = this.resolvedAgentsDir();
@@ -387,15 +290,8 @@ var AgentsPlugin = class extends Plugin {
 		};
 	}
 	/** 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;
+	loadGlobalSkills() {
+		return loadGlobalSkills(this.resolvedAgentsDir());
 	}
 	/**
 	* Workspace client used to read catalog skills. v1 reads as the app service
@@ -406,82 +302,20 @@ var AgentsPlugin = class extends Plugin {
 	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 [];
-		}
+	/** Discovers catalog skills from the configured UC Volume (best-effort). */
+	loadVolumeSkills() {
+		return loadVolumeSkills(this.config, () => this.skillWorkspaceClient());
 	}
-	/**
-	* 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 resolveAgentSkills({
+			name,
+			def,
+			agentsDir: this.resolvedAgentsDir(),
+			isFileOrigin: src.origin === "file",
+			autoInherit: src.origin === "file" ? inherit.file : inherit.code,
+			globalSkills: this.globalSkills
 		});
-		return catalog.byAddress.size > 0 ? catalog : void 0;
 	}
 	async resolveAdapter(def, name) {
 		const source = def.model ?? this.config.defaultModel;
@@ -930,7 +764,8 @@ var AgentsPlugin = class extends Plugin {
 			outboundEvents,
 			toolCallsUsed: { count: 0 }
 		};
-		const executeTool = (name, args) => this.dispatchToolCall(runState, registered.toolIndex, name, args, 0);
+		const deps = this.toolDispatchDeps();
+		const executeTool = (name, args) => dispatchToolCall(deps, runState, registered.toolIndex, name, args, 0);
 		const driver = (async () => {
 			try {
 				for (const evt of translator.translate({
@@ -1071,7 +906,8 @@ var AgentsPlugin = class extends Plugin {
 			outboundEvents: new EventChannel(),
 			toolCallsUsed: { count: 0 }
 		};
-		const executeTool = (name, args) => this.dispatchToolCall(runState, registered.toolIndex, name, args, 0);
+		const deps = this.toolDispatchDeps();
+		const executeTool = (name, args) => dispatchToolCall(deps, runState, registered.toolIndex, name, args, 0);
 		let fullContent = "";
 		try {
 			await traceAgent(registered.name ?? "agent", { messages: thread.messages.map((m) => ({
@@ -1152,82 +988,8 @@ var AgentsPlugin = class extends Plugin {
 			output: [message]
 		});
 	}
-	/**
-	* Dispatch a single tool call from either the top-level adapter or a
-	* sub-agent. Centralising this in one method is what makes the budget
-	* counter, approval gate, and abort signal observe sub-agent activity:
-	* `runSubAgent` reuses the same `runState` and so increments the same
-	* counter and emits approval events through the same channel.
-	*
-	* `depth` is the current sub-agent recursion depth (0 at the top level).
-	* It is forwarded to `runSubAgent` when the dispatched entry is itself a
-	* sub-agent, so depth limits remain enforced.
-	*/
-	async dispatchToolCall(runState, toolIndex, name, args, depth) {
-		if (runState.toolCallsUsed.count >= runState.limits.maxToolCalls) {
-			runState.abortController.abort(/* @__PURE__ */ new Error(`Tool-call budget exhausted (limit ${runState.limits.maxToolCalls}).`));
-			throw new Error(`Tool-call budget exhausted (limit ${runState.limits.maxToolCalls}). Raise agents({ limits: { maxToolCalls } }) or review the agent's tool-selection logic.`);
-		}
-		runState.toolCallsUsed.count++;
-		const entry = toolIndex.get(name);
-		if (!entry) throw new Error(`Unknown tool: ${name}`);
-		if (runState.approvalPolicy.requireForDestructive && requiresApproval(entry.def.annotations)) {
-			const approvalId = randomUUID();
-			for (const ev of runState.translator.translate({
-				type: "approval_pending",
-				approvalId,
-				streamId: runState.requestId,
-				toolName: name,
-				args,
-				annotations: entry.def.annotations
-			})) runState.outboundEvents.push(ev);
-			if (await this.approvalGate.wait({
-				approvalId,
-				streamId: runState.requestId,
-				userId: runState.userId,
-				timeoutMs: runState.approvalPolicy.timeoutMs
-			}) === "deny") return `Tool execution denied by user approval gate (tool: ${name}).`;
-		}
-		return normalizeToolResult(await traceTool(name, args, async () => {
-			let result;
-			if (entry.source === "toolkit") {
-				if (!this.context) throw new Error("Plugin tool execution requires PluginContext; this should never happen through createApp");
-				result = await this.context.executeTool(runState.req, entry.pluginName, entry.localName, args, runState.signal, runState.limits.toolCallTimeoutMs);
-			} else if (entry.source === "function") {
-				if (typeof args !== "object" || args === null || Array.isArray(args)) throw new Error(`Function tool '${name}' received non-object arguments (got ${args === null ? "null" : Array.isArray(args) ? "array" : typeof args}); expected a JSON object.`);
-				result = await entry.functionTool.execute(args);
-			} else if (entry.source === "mcp") {
-				if (!this.mcpClient) throw new Error("MCP client not connected");
-				const oboToken = runState.req.headers["x-forwarded-access-token"];
-				const mcpAuth = typeof oboToken === "string" ? { Authorization: `Bearer ${oboToken}` } : void 0;
-				result = await this.mcpClient.callTool(entry.mcpToolName, args, mcpAuth);
-			} else if (entry.source === "subagent") {
-				const childAgent = this.agents.get(entry.agentName);
-				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);
+	dispatchSkillTool(entry, args) {
+		return dispatchSkillTool(entry, args, () => this.skillWorkspaceClient());
 	}
 	/**
 	* Renders the prompt addendum for a force-loaded skill (`/skill-name`).
@@ -1236,67 +998,19 @@ var AgentsPlugin = class extends Plugin {
 	* 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;
-		}
+		return renderForcedSkill(registered, name);
 	}
-	/**
-	* 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.
-	*
-	* `depth` starts at 1 for a top-level sub-agent invocation (i.e. the
-	* outer `_streamAgent` calls `runSubAgent(..., 1)`) and increments on
-	* each nested `runSubAgent` call. Depths exceeding
-	* `limits.maxSubAgentDepth` are rejected before any adapter work.
-	*
-	* Sub-agent tool calls run through `dispatchToolCall` with the same
-	* `runState` as the parent — the budget counter and approval gate are
-	* therefore enforced for every nested call, not only at the top level.
-	*/
-	async runSubAgent(runState, child, args, depth) {
-		if (depth > runState.limits.maxSubAgentDepth) throw new Error(`Sub-agent depth exceeded (limit ${runState.limits.maxSubAgentDepth}). Raise agents({ limits: { maxSubAgentDepth } }) or break the delegation cycle.`);
-		const input = typeof args === "object" && args !== null && typeof args.input === "string" ? args.input : JSON.stringify(args);
-		const childTools = Array.from(child.toolIndex.values()).filter((e) => e.source !== "hosted-supervisor").map((e) => e.def);
-		const childExecute = (name, childArgs) => this.dispatchToolCall(runState, child.toolIndex, name, childArgs, depth);
-		const runContext = {
-			executeTool: childExecute,
-			signal: runState.signal
+	/** Collaborators the tool-dispatch path needs, bound to this instance. */
+	toolDispatchDeps() {
+		return {
+			approvalGate: this.approvalGate,
+			context: this.context,
+			getMcpClient: () => this.mcpClient,
+			agents: this.agents,
+			dispatchSkillTool: (entry, args) => this.dispatchSkillTool(entry, args),
+			pluginName: this.name,
+			baseSystemPrompt: this.config.baseSystemPrompt
 		};
-		const pluginNames = this.context ? this.context.getPluginNames().filter((n) => n !== this.name && n !== "server") : [];
-		const messages = [{
-			id: "system",
-			role: "system",
-			content: composePromptForAgent(child, this.config.baseSystemPrompt, {
-				agentName: child.name,
-				pluginNames,
-				toolNames: childTools.map((t) => t.name)
-			}),
-			createdAt: /* @__PURE__ */ new Date()
-		}, {
-			id: randomUUID(),
-			role: "user",
-			content: input,
-			createdAt: /* @__PURE__ */ new Date()
-		}];
-		return consumeAdapterStream(child.adapter.run({
-			messages,
-			tools: childTools,
-			threadId: randomUUID(),
-			signal: runState.signal,
-			extensions: buildAdapterExtensions(child.toolIndex)
-		}, runContext), {
-			signal: runState.signal,
-			onEvent: (event) => {
-				if (event.type === "metadata") return;
-				for (const translated of runState.translator.translate(event)) runState.outboundEvents.push(translated);
-			}
-		});
 	}
 	async _handleCancel(req, res) {
 		const parsed = cancelRequestSchema.safeParse(req.body);
@@ -1308,7 +1022,7 @@ var AgentsPlugin = class extends Plugin {
 			return;
 		}
 		const { streamId } = parsed.data;
-		const entry = this.activeStreams.get(streamId);
+		const entry = this.streams.get(streamId);
 		if (!entry) {
 			res.json({ cancelled: true });
 			return;
@@ -1333,7 +1047,7 @@ var AgentsPlugin = class extends Plugin {
 			return;
 		}
 		const { streamId, approvalId, decision } = parsed.data;
-		const streamEntry = this.activeStreams.get(streamId);
+		const streamEntry = this.streams.get(streamId);
 		if (!streamEntry) {
 			res.status(404).json({ error: "Stream not found or already completed" });
 			return;
@@ -1436,94 +1150,6 @@ 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;
-	let base = "";
-	if (resolved === false) base = "";
-	else if (typeof resolved === "string") base = resolved;
-	else if (typeof resolved === "function") base = resolved(ctx);
-	else base = buildBaseSystemPrompt(ctx);
-	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.
-* Used to populate the synthetic placeholder `def.description` on
-* hosted-supervisor tool-index entries.
-*/
-function supervisorToolDescription(spec) {
-	switch (spec.type) {
-		case "genie_space": return spec.genie_space.description;
-		case "uc_function": return spec.uc_function.description;
-		case "knowledge_assistant": return spec.knowledge_assistant.description;
-		case "app": return spec.app.description;
-		case "uc_connection": return spec.uc_connection.description;
-	}
-}
-/**
-* Builds the `AgentInput.extensions` payload from a tool index, aggregating
-* the hosted-supervisor specs under {@link SUPERVISOR_EXTENSION_KEY}. Returns
-* `undefined` when there are no adapter-side hosted tools so the field stays
-* absent on the wire — adapters that don't read extensions never see it.
-*/
-function buildAdapterExtensions(toolIndex) {
-	const supervisorSpecs = [];
-	for (const entry of toolIndex.values()) if (entry.source === "hosted-supervisor") supervisorSpecs.push(entry.spec);
-	if (supervisorSpecs.length === 0) return void 0;
-	return { [SUPERVISOR_EXTENSION_KEY]: { hostedTools: supervisorSpecs } };
-}
-/**
-* Compares the adapter's declared capabilities against the tool index and
-* logs a warning when the agent's tool declarations would be silently
-* dropped at runtime. Warn-not-throw: misconfiguration is loud enough to
-* notice without taking the whole app down.
-*/
-function warnOnCapabilityMismatch(agentName, adapter, toolIndex) {
-	const accepted = new Set(adapter.acceptsExtensions ?? []);
-	const hostedSupervisorKeys = [];
-	const inputToolKeys = [];
-	for (const [key, entry] of toolIndex) if (entry.source === "hosted-supervisor") hostedSupervisorKeys.push(key);
-	else inputToolKeys.push(key);
-	if (hostedSupervisorKeys.length > 0 && !accepted.has(SUPERVISOR_EXTENSION_KEY)) logger.warn(`Agent '${agentName}' declares hosted-supervisor tools (${hostedSupervisorKeys.join(", ")}) but its model adapter does not accept the 'databricks.supervisor' extension. These tools will not reach the model. Pair them with \`DatabricksAdapter.fromSupervisorApi(...)\`, or remove them.`);
-	if (adapter.consumesInputTools === false && inputToolKeys.length > 0) logger.warn(`Agent '${agentName}' declares function tools / sub-agents / MCP tools (${inputToolKeys.join(", ")}) but its model adapter does not consume input.tools (Supervisor API owns its own tool loop). These tools will not be exposed to the model. See docs/plugins/agents.md.`);
-}
 /**
 * Plugin factory for the agents plugin. Discovers agents from
 * `server/agents/<id>/agent.{ts,md}` by default (markdown still in