@databricks/appkit 0.48.0 → 0.50.0

package/dist/connectors/serving/client.js

@@ -39,34 +39,54 @@ async function invoke(client, endpointName, body) {
 	});
 }
 /**
-* Returns the raw SSE byte stream from a serving endpoint.
-* No parsing is performed — bytes are passed through as-is.
+* POSTs `body` as JSON to an arbitrary workspace API path and returns the raw
+* SSE byte stream. No parsing is performed — bytes are passed through as-is.
 *
-* Uses the SDK's low-level `apiClient.request({ raw: true })` because
-* the high-level `servingEndpoints.query()` returns `Promise<QueryEndpointResponse>`
-* and does not support SSE streaming.
+* Uses the SDK's low-level `apiClient.request({ raw: true })` so callers
+* inherit URL resolution, the SDK credential chain (PAT/OAuth/OIDC), and
+* any future retries/telemetry baked into the SDK transport.
+*
+* When `signal` is provided it is bridged to the SDK's `Context` /
+* `CancellationToken` so aborts cancel the outbound HTTP request.
+*
+* @internal
+*
+* Not part of the public AppKit surface. `path` is passed through to the
+* SDK without any allowlist — exposing this to user-controlled input would
+* turn it into workspace-credentialled SSRF (CWE-918). Internal callers
+* must hard-code the path (or build it from a closed enum). New callers
+* inside the package: keep this constraint, and do not re-export from
+* `beta.ts` or any other entry point.
 */
-async function stream(client, endpointName, body, signal) {
-	const { stream: _stream, ...cleanBody } = body;
-	logger.debug("Streaming from endpoint %s", endpointName);
+async function streamPath(client, path, body, signal) {
+	logger.debug("Streaming from path %s", path);
 	const context = signal ? new Context({ cancellationToken: cancellationTokenFromAbortSignal(signal) }) : void 0;
 	const response = await client.apiClient.request({
-		path: `/serving-endpoints/${encodeURIComponent(endpointName)}/invocations`,
+		path,
 		method: "POST",
 		headers: new Headers({
 			"Content-Type": "application/json",
 			Accept: "text/event-stream"
 		}),
-		payload: {
-			...cleanBody,
-			stream: true
-		},
+		payload: body,
 		raw: true
 	}, context);
 	if (!response.contents) throw new Error("Response body is null — streaming not supported");
 	return response.contents;
 }
+/**
+* Returns the raw SSE byte stream from a serving endpoint. Thin wrapper over
+* {@link streamPath} that handles serving-specific URL encoding and forces
+* `stream: true` in the payload.
+*/
+async function stream(client, endpointName, body, signal) {
+	const { stream: _stream, ...cleanBody } = body;
+	return streamPath(client, `/serving-endpoints/${encodeURIComponent(endpointName)}/invocations`, {
+		...cleanBody,
+		stream: true
+	}, signal);
+}
 
 //#endregion
-export { invoke, stream };
+export { invoke, stream, streamPath };
 //# sourceMappingURL=client.js.map

package/dist/connectors/serving/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/serving/client.ts"],"sourcesContent":["import type {\n  CancellationToken,\n  serving,\n  WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport { Context } from \"@databricks/sdk-experimental\";\nimport { createLogger } from \"../../logging/logger\";\n\nconst logger = createLogger(\"connectors:serving\");\n\n/**\n * Bridges {@link AbortSignal} to the SDK's {@link CancellationToken} so\n * `apiClient.request` can abort the outbound HTTP request (and stop pulling\n * the SSE body) when the agent run is cancelled.\n */\nfunction cancellationTokenFromAbortSignal(\n  signal: AbortSignal,\n): CancellationToken {\n  const listeners = new Set<() => void>();\n  const fire = () => {\n    for (const cb of listeners) {\n      try {\n        cb();\n      } catch {\n        // ignore listener failures — abort must stay best-effort\n      }\n    }\n  };\n  signal.addEventListener(\"abort\", fire, { passive: true });\n\n  return {\n    get isCancellationRequested() {\n      return signal.aborted;\n    },\n    onCancellationRequested(callback: (e?: unknown) => unknown) {\n      listeners.add(callback as () => void);\n      if (signal.aborted) {\n        void callback();\n      }\n    },\n  };\n}\n\n/**\n * Invokes a serving endpoint using the SDK's high-level query API.\n * Returns a typed QueryEndpointResponse.\n */\nexport async function invoke(\n  client: WorkspaceClient,\n  endpointName: string,\n  body: Record<string, unknown>,\n): Promise<serving.QueryEndpointResponse> {\n  // Strip `stream` from the body — the connector controls this\n  const { stream: _stream, ...cleanBody } = body;\n\n  logger.debug(\"Invoking endpoint %s\", endpointName);\n\n  return client.servingEndpoints.query({\n    name: endpointName,\n    ...cleanBody,\n  } as serving.QueryEndpointInput);\n}\n\n/**\n * Returns the raw SSE byte stream from a serving endpoint.\n * No parsing is performed — bytes are passed through as-is.\n *\n * Uses the SDK's low-level `apiClient.request({ raw: true })` because\n * the high-level `servingEndpoints.query()` returns `Promise<QueryEndpointResponse>`\n * and does not support SSE streaming.\n */\nexport async function stream(\n  client: WorkspaceClient,\n  endpointName: string,\n  body: Record<string, unknown>,\n  signal?: AbortSignal,\n): Promise<ReadableStream<Uint8Array>> {\n  const { stream: _stream, ...cleanBody } = body;\n\n  logger.debug(\"Streaming from endpoint %s\", endpointName);\n\n  const context = signal\n    ? new Context({\n        cancellationToken: cancellationTokenFromAbortSignal(signal),\n      })\n    : undefined;\n\n  const response = (await client.apiClient.request(\n    {\n      path: `/serving-endpoints/${encodeURIComponent(endpointName)}/invocations`,\n      method: \"POST\",\n      headers: new Headers({\n        \"Content-Type\": \"application/json\",\n        Accept: \"text/event-stream\",\n      }),\n      payload: { ...cleanBody, stream: true },\n      raw: true,\n    },\n    context,\n  )) as { contents: ReadableStream<Uint8Array> };\n\n  if (!response.contents) {\n    throw new Error(\"Response body is null — streaming not supported\");\n  }\n\n  return response.contents;\n}\n"],"mappings":";;;;AAQA,MAAM,SAAS,aAAa,qBAAqB;;;;;;AAOjD,SAAS,iCACP,QACmB;CACnB,MAAM,4BAAY,IAAI,KAAiB;CACvC,MAAM,aAAa;AACjB,OAAK,MAAM,MAAM,UACf,KAAI;AACF,OAAI;UACE;;AAKZ,QAAO,iBAAiB,SAAS,MAAM,EAAE,SAAS,MAAM,CAAC;AAEzD,QAAO;EACL,IAAI,0BAA0B;AAC5B,UAAO,OAAO;;EAEhB,wBAAwB,UAAoC;AAC1D,aAAU,IAAI,SAAuB;AACrC,OAAI,OAAO,QACT,CAAK,UAAU;;EAGpB;;;;;;AAOH,eAAsB,OACpB,QACA,cACA,MACwC;CAExC,MAAM,EAAE,QAAQ,SAAS,GAAG,cAAc;AAE1C,QAAO,MAAM,wBAAwB,aAAa;AAElD,QAAO,OAAO,iBAAiB,MAAM;EACnC,MAAM;EACN,GAAG;EACJ,CAA+B;;;;;;;;;;AAWlC,eAAsB,OACpB,QACA,cACA,MACA,QACqC;CACrC,MAAM,EAAE,QAAQ,SAAS,GAAG,cAAc;AAE1C,QAAO,MAAM,8BAA8B,aAAa;CAExD,MAAM,UAAU,SACZ,IAAI,QAAQ,EACV,mBAAmB,iCAAiC,OAAO,EAC5D,CAAC,GACF;CAEJ,MAAM,WAAY,MAAM,OAAO,UAAU,QACvC;EACE,MAAM,sBAAsB,mBAAmB,aAAa,CAAC;EAC7D,QAAQ;EACR,SAAS,IAAI,QAAQ;GACnB,gBAAgB;GAChB,QAAQ;GACT,CAAC;EACF,SAAS;GAAE,GAAG;GAAW,QAAQ;GAAM;EACvC,KAAK;EACN,EACD,QACD;AAED,KAAI,CAAC,SAAS,SACZ,OAAM,IAAI,MAAM,kDAAkD;AAGpE,QAAO,SAAS"}
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/serving/client.ts"],"sourcesContent":["import type {\n  CancellationToken,\n  serving,\n  WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport { Context } from \"@databricks/sdk-experimental\";\nimport { createLogger } from \"../../logging/logger\";\n\nconst logger = createLogger(\"connectors:serving\");\n\n/**\n * Bridges {@link AbortSignal} to the SDK's {@link CancellationToken} so\n * `apiClient.request` can abort the outbound HTTP request (and stop pulling\n * the SSE body) when the agent run is cancelled.\n */\nfunction cancellationTokenFromAbortSignal(\n  signal: AbortSignal,\n): CancellationToken {\n  const listeners = new Set<() => void>();\n  const fire = () => {\n    for (const cb of listeners) {\n      try {\n        cb();\n      } catch {\n        // ignore listener failures — abort must stay best-effort\n      }\n    }\n  };\n  signal.addEventListener(\"abort\", fire, { passive: true });\n\n  return {\n    get isCancellationRequested() {\n      return signal.aborted;\n    },\n    onCancellationRequested(callback: (e?: unknown) => unknown) {\n      listeners.add(callback as () => void);\n      if (signal.aborted) {\n        void callback();\n      }\n    },\n  };\n}\n\n/**\n * Structural shape of a Databricks SDK client we need for the low-level\n * `apiClient.request` call. Lets `streamPath` be reused by adapters that\n * don't want a hard dependency on the concrete `WorkspaceClient` type.\n */\nexport interface ApiClientLike {\n  apiClient: {\n    request(\n      options: Record<string, unknown>,\n      context?: unknown,\n    ): Promise<unknown>;\n  };\n}\n\n/**\n * Transport shim shared by the agent adapters: given a request body, returns\n * the raw SSE byte stream from a serving / AI-gateway endpoint. Injected at\n * adapter construction time so callers can swap in the workspace SDK (the\n * factory paths via {@link streamPath}), a bare `fetch` (a reverse proxy /\n * mock), or a test fake.\n */\nexport type StreamBody = (\n  body: Record<string, unknown>,\n  signal?: AbortSignal,\n) => Promise<ReadableStream<Uint8Array>>;\n\n/**\n * Invokes a serving endpoint using the SDK's high-level query API.\n * Returns a typed QueryEndpointResponse.\n */\nexport async function invoke(\n  client: WorkspaceClient,\n  endpointName: string,\n  body: Record<string, unknown>,\n): Promise<serving.QueryEndpointResponse> {\n  // Strip `stream` from the body — the connector controls this\n  const { stream: _stream, ...cleanBody } = body;\n\n  logger.debug(\"Invoking endpoint %s\", endpointName);\n\n  return client.servingEndpoints.query({\n    name: endpointName,\n    ...cleanBody,\n  } as serving.QueryEndpointInput);\n}\n\n/**\n * POSTs `body` as JSON to an arbitrary workspace API path and returns the raw\n * SSE byte stream. No parsing is performed — bytes are passed through as-is.\n *\n * Uses the SDK's low-level `apiClient.request({ raw: true })` so callers\n * inherit URL resolution, the SDK credential chain (PAT/OAuth/OIDC), and\n * any future retries/telemetry baked into the SDK transport.\n *\n * When `signal` is provided it is bridged to the SDK's `Context` /\n * `CancellationToken` so aborts cancel the outbound HTTP request.\n *\n * @internal\n *\n * Not part of the public AppKit surface. `path` is passed through to the\n * SDK without any allowlist — exposing this to user-controlled input would\n * turn it into workspace-credentialled SSRF (CWE-918). Internal callers\n * must hard-code the path (or build it from a closed enum). New callers\n * inside the package: keep this constraint, and do not re-export from\n * `beta.ts` or any other entry point.\n */\nexport async function streamPath(\n  client: ApiClientLike,\n  path: string,\n  body: Record<string, unknown>,\n  signal?: AbortSignal,\n): Promise<ReadableStream<Uint8Array>> {\n  logger.debug(\"Streaming from path %s\", path);\n\n  const context = signal\n    ? new Context({\n        cancellationToken: cancellationTokenFromAbortSignal(signal),\n      })\n    : undefined;\n\n  const response = (await client.apiClient.request(\n    {\n      path,\n      method: \"POST\",\n      headers: new Headers({\n        \"Content-Type\": \"application/json\",\n        Accept: \"text/event-stream\",\n      }),\n      payload: body,\n      raw: true,\n    },\n    context,\n  )) as { contents: ReadableStream<Uint8Array> | null };\n\n  if (!response.contents) {\n    throw new Error(\"Response body is null — streaming not supported\");\n  }\n\n  return response.contents;\n}\n\n/**\n * Returns the raw SSE byte stream from a serving endpoint. Thin wrapper over\n * {@link streamPath} that handles serving-specific URL encoding and forces\n * `stream: true` in the payload.\n */\nexport async function stream(\n  client: WorkspaceClient,\n  endpointName: string,\n  body: Record<string, unknown>,\n  signal?: AbortSignal,\n): Promise<ReadableStream<Uint8Array>> {\n  const { stream: _stream, ...cleanBody } = body;\n  return streamPath(\n    client as unknown as ApiClientLike,\n    `/serving-endpoints/${encodeURIComponent(endpointName)}/invocations`,\n    { ...cleanBody, stream: true },\n    signal,\n  );\n}\n"],"mappings":";;;;AAQA,MAAM,SAAS,aAAa,qBAAqB;;;;;;AAOjD,SAAS,iCACP,QACmB;CACnB,MAAM,4BAAY,IAAI,KAAiB;CACvC,MAAM,aAAa;AACjB,OAAK,MAAM,MAAM,UACf,KAAI;AACF,OAAI;UACE;;AAKZ,QAAO,iBAAiB,SAAS,MAAM,EAAE,SAAS,MAAM,CAAC;AAEzD,QAAO;EACL,IAAI,0BAA0B;AAC5B,UAAO,OAAO;;EAEhB,wBAAwB,UAAoC;AAC1D,aAAU,IAAI,SAAuB;AACrC,OAAI,OAAO,QACT,CAAK,UAAU;;EAGpB;;;;;;AAiCH,eAAsB,OACpB,QACA,cACA,MACwC;CAExC,MAAM,EAAE,QAAQ,SAAS,GAAG,cAAc;AAE1C,QAAO,MAAM,wBAAwB,aAAa;AAElD,QAAO,OAAO,iBAAiB,MAAM;EACnC,MAAM;EACN,GAAG;EACJ,CAA+B;;;;;;;;;;;;;;;;;;;;;;AAuBlC,eAAsB,WACpB,QACA,MACA,MACA,QACqC;AACrC,QAAO,MAAM,0BAA0B,KAAK;CAE5C,MAAM,UAAU,SACZ,IAAI,QAAQ,EACV,mBAAmB,iCAAiC,OAAO,EAC5D,CAAC,GACF;CAEJ,MAAM,WAAY,MAAM,OAAO,UAAU,QACvC;EACE;EACA,QAAQ;EACR,SAAS,IAAI,QAAQ;GACnB,gBAAgB;GAChB,QAAQ;GACT,CAAC;EACF,SAAS;EACT,KAAK;EACN,EACD,QACD;AAED,KAAI,CAAC,SAAS,SACZ,OAAM,IAAI,MAAM,kDAAkD;AAGpE,QAAO,SAAS;;;;;;;AAQlB,eAAsB,OACpB,QACA,cACA,MACA,QACqC;CACrC,MAAM,EAAE,QAAQ,SAAS,GAAG,cAAc;AAC1C,QAAO,WACL,QACA,sBAAsB,mBAAmB,aAAa,CAAC,eACvD;EAAE,GAAG;EAAW,QAAQ;EAAM,EAC9B,OACD"}

package/dist/core/agent/run-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-agent.d.ts","names":[],"sources":["../../../src/core/agent/run-agent.ts"],"mappings":";;;;;;UA4BiB,aAAA;;EAEf,QAAA,WAAmB,OAAA;;EAEnB,MAAA,GAAS,WAAA;EAJmB;;;;;;;EAY5B,OAAA,GAAU,UAAA,CAAW,iBAAA;AAAA;AAAA,UAGN,cAAA;EAXf;EAaA,IAAA;EALA;EAOA,MAAA,EAAQ,UAAA;AAAA;;;AAJV;;;;;;;;;AAmCA;;;;;;;;;;;;;;;;;iBAAsB,QAAA,CACpB,GAAA,EAAK,eAAA,EACL,KAAA,EAAO,aAAA,GACN,OAAA,CAAQ,cAAA"}
+{"version":3,"file":"run-agent.d.ts","names":[],"sources":["../../../src/core/agent/run-agent.ts"],"mappings":";;;;;;UAoCiB,aAAA;;EAEf,QAAA,WAAmB,OAAA;;EAEnB,MAAA,GAAS,WAAA;EAJmB;;;;;;;EAY5B,OAAA,GAAU,UAAA,CAAW,iBAAA;AAAA;AAAA,UAGN,cAAA;EAXf;EAaA,IAAA;EALA;EAOA,MAAA,EAAQ,UAAA;AAAA;;;AAJV;;;;;;;;;AAmCA;;;;;;;;;;;;;;;;;iBAAsB,QAAA,CACpB,GAAA,EAAK,eAAA,EACL,KAAA,EAAO,aAAA,GACN,OAAA,CAAQ,cAAA"}

package/dist/core/agent/run-agent.js

@@ -1,3 +1,5 @@
+import { createLogger } from "../../logging/logger.js";
+import { SUPERVISOR_EXTENSION_KEY, isSupervisorTool } from "../../agents/supervisor-api.js";
 import { consumeAdapterStream } from "./consume-adapter-stream.js";
 import { createPluginsProxy } from "./plugins-map.js";
 import { resolveToolkitFromProvider } from "./toolkit-resolver.js";
@@ -7,6 +9,7 @@ import { isToolkitEntry } from "./types.js";
 import { randomUUID } from "node:crypto";
 
 //#region src/core/agent/run-agent.ts
+const logger = createLogger("agent:run-agent");
 /**
 * Standalone agent execution without `createApp`. Resolves the adapter, binds
 * inline tools, and drives the adapter's `run()` loop to completion.
@@ -44,7 +47,8 @@ async function runAgentInternal(def, input, providerCache) {
 	const adapter = await resolveAdapter(def);
 	const messages = normalizeMessages(input.messages, def.instructions);
 	const toolIndex = buildStandaloneToolIndex(def, input.plugins ?? [], providerCache);
-	const tools = Array.from(toolIndex.values()).map((e) => e.def);
+	const tools = Array.from(toolIndex.values()).filter((e) => e.kind !== "hosted-supervisor").map((e) => e.def);
+	warnOnCapabilityMismatch(def.name ?? "<anonymous>", adapter, toolIndex);
 	const signal = input.signal;
 	const executeTool = async (name, args) => {
 		const entry = toolIndex.get(name);
@@ -59,6 +63,7 @@ async function runAgentInternal(def, input, providerCache) {
 			};
 			return (await runAgentInternal(entry.agentDef, subInput, providerCache)).text;
 		}
+		if (entry.kind === "hosted-supervisor") throw new Error(`runAgent: tool "${name}" is a hosted-supervisor tool, executed server-side by the Databricks AI Gateway. It must not be invoked from the Node process.`);
 		throw new Error(`runAgent: tool "${name}" is a ${entry.kind} tool. Hosted/MCP tools are only usable via createApp({ plugins: [..., agents(...)] }).`);
 	};
 	const events = [];
@@ -67,7 +72,8 @@ async function runAgentInternal(def, input, providerCache) {
 			messages,
 			tools,
 			threadId: randomUUID(),
-			signal
+			signal,
+			extensions: buildStandaloneExtensions(toolIndex)
 		}, {
 			executeTool,
 			signal
@@ -228,9 +234,52 @@ function classifyTool(key, tool, providerCache) {
 			name: key
 		}
 	};
+	if (isSupervisorTool(tool)) return {
+		kind: "hosted-supervisor",
+		spec: tool.spec,
+		def: {
+			name: key,
+			description: supervisorToolDescription(tool.spec),
+			parameters: {
+				type: "object",
+				properties: {}
+			}
+		}
+	};
 	if (isHostedTool(tool)) throw new Error(`runAgent: tool "${key}" is a hosted tool (type="${tool.type}") which is only supported via createApp({ plugins: [..., agents(...)] }). Standalone runAgent has no MCP client.`);
 	throw new Error(`runAgent: unrecognized tool shape at key "${key}"`);
 }
+/** Mirrors `agents.ts`'s `supervisorToolDescription`. */
+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;
+	}
+}
+/** Mirrors `agents.ts`'s `buildAdapterExtensions`. */
+function buildStandaloneExtensions(toolIndex) {
+	const supervisorSpecs = [];
+	for (const entry of toolIndex.values()) if (entry.kind === "hosted-supervisor") supervisorSpecs.push(entry.spec);
+	if (supervisorSpecs.length === 0) return void 0;
+	return { [SUPERVISOR_EXTENSION_KEY]: { hostedTools: supervisorSpecs } };
+}
+/**
+* Mirrors the agents-plugin capability warning so standalone `runAgent`
+* produces the same diagnostic when adapter capabilities don't match the
+* tool index. Warn-not-throw: doesn't abort batch evals.
+*/
+function warnOnCapabilityMismatch(agentName, adapter, toolIndex) {
+	const accepted = new Set(adapter.acceptsExtensions ?? []);
+	const hostedSupervisorKeys = [];
+	const inputToolKeys = [];
+	for (const [key, entry] of toolIndex) if (entry.kind === "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. Pair them with \`DatabricksAdapter.fromSupervisorApi(...)\`, or remove them.`);
+	if (adapter.consumesInputTools === false && inputToolKeys.length > 0) logger.warn(`Agent '${agentName}' declares function tools / sub-agents (${inputToolKeys.join(", ")}) but its model adapter does not consume input.tools. These tools will not be exposed to the model.`);
+}
 function providerCacheLookup(pluginName, cache) {
 	const cached = cache.get(pluginName);
 	if (cached) return cached;

package/dist/core/agent/run-agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-agent.js","names":[],"sources":["../../../src/core/agent/run-agent.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type {\n  AgentAdapter,\n  AgentEvent,\n  AgentToolDefinition,\n  Message,\n  PluginConstructor,\n  PluginData,\n  ToolProvider,\n} from \"shared\";\nimport { consumeAdapterStream } from \"./consume-adapter-stream\";\nimport { createPluginsProxy } from \"./plugins-map\";\nimport { resolveToolkitFromProvider } from \"./toolkit-resolver\";\nimport {\n  type FunctionTool,\n  functionToolToDefinition,\n  isFunctionTool,\n} from \"./tools/function-tool\";\nimport { isHostedTool } from \"./tools/hosted-tools\";\nimport type {\n  AgentDefinition,\n  AgentTool,\n  AgentTools,\n  Plugins,\n  PluginToolkitProvider,\n} from \"./types\";\nimport { isToolkitEntry } from \"./types\";\n\nexport interface RunAgentInput {\n  /** Seed messages for the run. Either a single user string or a full message list. */\n  messages: string | Message[];\n  /** Abort signal for cancellation. */\n  signal?: AbortSignal;\n  /**\n   * Optional plugin list. Required when `def.tools` is the function form\n   * `(plugins) => Record<string, AgentTool>` and the function dereferences\n   * any plugins. `runAgent` constructs a fresh instance per plugin and\n   * dispatches tool calls against it as the service principal (no OBO —\n   * there is no HTTP request in standalone mode).\n   */\n  plugins?: PluginData<PluginConstructor, unknown, string>[];\n}\n\nexport interface RunAgentResult {\n  /** Aggregated text output from all `message_delta` events. */\n  text: string;\n  /** Every event the adapter yielded, in order. Useful for inspection/tests. */\n  events: AgentEvent[];\n}\n\n/**\n * Standalone agent execution without `createApp`. Resolves the adapter, binds\n * inline tools, and drives the adapter's `run()` loop to completion.\n *\n * Limitations vs. running through the agents() plugin:\n * - **No OBO and no approval gate** — there is no HTTP request, so plugin\n *   tools run as the service principal. The agents-plugin approval gate\n *   that prompts for human confirmation on `effect: \"write\" | \"update\" |\n *   \"destructive\"` tools is also absent. LLM-controlled tool arguments\n *   flow straight through to the SP. Treat standalone runAgent as a\n *   trusted-prompt environment (CI, batch eval, internal scripts) — not\n *   as an exposed user-facing surface.\n * - **Hosted tools (MCP) are not supported** — they require a live MCP\n *   client that only exists inside the agents plugin's lifecycle.\n *   `runAgent` rejects them at index-build time with a clear error.\n * - **Sub-agents** (`agents: { ... }` on the def) are executed as nested\n *   `runAgent` calls with no shared thread state. Plugin instances ARE\n *   shared across the recursion (same cache as the parent).\n * - **Plugin tools** (used inside the function form via\n *   `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via\n *   `RunAgentInput`. Each plugin in that array is constructed once,\n *   `attachContext({})` and `await setup()` are called eagerly, and the\n *   resulting instance is shared across the top-level run and all\n *   sub-agent recursions. Plugins whose `setup()` requires runtime that\n *   only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`,\n *   `PluginContext`) throw at standalone-init time with a clear \"use\n *   createApp instead\" message — not mid-stream.\n */\nexport async function runAgent(\n  def: AgentDefinition,\n  input: RunAgentInput,\n): Promise<RunAgentResult> {\n  // Single shared cache for the whole call graph: parent + every nested\n  // sub-agent dispatch share constructed plugin instances. Without this,\n  // each nested `runAgent` would build its own cache, re-instantiate every\n  // plugin, and silently diverge in-instance state between parent and child\n  // (e.g. query result caches, connection pools).\n  const providerCache = new Map<string, ToolProvider>();\n  await initStandalonePlugins(input.plugins ?? [], providerCache);\n  return runAgentInternal(def, input, providerCache);\n}\n\nasync function runAgentInternal(\n  def: AgentDefinition,\n  input: RunAgentInput,\n  providerCache: Map<string, ToolProvider>,\n): Promise<RunAgentResult> {\n  const adapter = await resolveAdapter(def);\n  const messages = normalizeMessages(input.messages, def.instructions);\n  const toolIndex = buildStandaloneToolIndex(\n    def,\n    input.plugins ?? [],\n    providerCache,\n  );\n  const tools = Array.from(toolIndex.values()).map((e) => e.def);\n\n  const signal = input.signal;\n\n  const executeTool = async (name: string, args: unknown): Promise<unknown> => {\n    const entry = toolIndex.get(name);\n    if (!entry) throw new Error(`Unknown tool: ${name}`);\n    if (entry.kind === \"function\") {\n      return entry.tool.execute(args as Record<string, unknown>);\n    }\n    if (entry.kind === \"toolkit\") {\n      return entry.provider.executeAgentTool(\n        entry.localName,\n        args as Record<string, unknown>,\n        signal,\n      );\n    }\n    if (entry.kind === \"subagent\") {\n      const subInput: RunAgentInput = {\n        messages:\n          typeof args === \"object\" &&\n          args !== null &&\n          typeof (args as { input?: unknown }).input === \"string\"\n            ? (args as { input: string }).input\n            : JSON.stringify(args),\n        signal,\n        plugins: input.plugins,\n      };\n      // Reuse the same `providerCache` so sub-agent plugin tools dispatch\n      // through the same instances the parent constructed.\n      const res = await runAgentInternal(\n        entry.agentDef,\n        subInput,\n        providerCache,\n      );\n      return res.text;\n    }\n    throw new Error(\n      `runAgent: tool \"${name}\" is a ${entry.kind} tool. ` +\n        \"Hosted/MCP tools are only usable via createApp({ plugins: [..., agents(...)] }).\",\n    );\n  };\n\n  const events: AgentEvent[] = [];\n\n  const stream = adapter.run(\n    {\n      messages,\n      tools,\n      threadId: randomUUID(),\n      signal,\n    },\n    { executeTool, signal },\n  );\n\n  // Shared accumulation rule (deltas append, `message` replaces). The\n  // `events` array is filled via the `onEvent` side effect so callers that\n  // inspect the raw stream still get the full record.\n  const text = await consumeAdapterStream(stream, {\n    signal,\n    onEvent: (event) => {\n      events.push(event);\n    },\n  });\n\n  return { text, events };\n}\n\n/**\n * Eagerly construct every plugin in `input.plugins`, run the standard\n * AppKit lifecycle (`attachContext({})` + `await setup()`), and populate\n * `cache`. Failures here surface BEFORE any adapter work — mid-stream\n * `getWorkspaceClient is not initialised`-style errors become a clear\n * startup failure naming the plugin and pointing the user at `createApp`.\n *\n * Plugins that don't need runtime context (no overridden `setup`, or one\n * that doesn't dereference `createApp`-only state) initialise cleanly and\n * standalone runAgent works as documented. Plugins like analytics/files\n * that depend on `WorkspaceClient` will throw the underlying error wrapped\n * with the migration hint.\n */\nasync function initStandalonePlugins(\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  cache: Map<string, ToolProvider>,\n): Promise<void> {\n  for (const data of plugins) {\n    if (cache.has(data.name)) continue;\n    const instance = new data.plugin({\n      ...(data.config ?? {}),\n      name: data.name,\n    });\n    if (!isStandaloneToolProvider(instance)) {\n      throw new Error(\n        `runAgent: plugin '${data.name}' is not a ToolProvider ` +\n          \"(missing getAgentTools/executeAgentTool). Only ToolProvider plugins \" +\n          \"are supported in standalone runAgent.\",\n      );\n    }\n    if (\n      typeof (instance as { attachContext?: unknown }).attachContext ===\n      \"function\"\n    ) {\n      try {\n        (\n          instance as { attachContext: (deps: Record<string, unknown>) => void }\n        ).attachContext({});\n      } catch (err) {\n        throw new Error(\n          `runAgent: plugin '${data.name}' attachContext() failed in ` +\n            \"standalone mode. This plugin probably depends on createApp's \" +\n            \"runtime (WorkspaceClient, ServiceContext, PluginContext). Run \" +\n            \"via createApp({ plugins: [..., agents(...)] }) instead. \" +\n            `Cause: ${err instanceof Error ? err.message : String(err)}`,\n          { cause: err instanceof Error ? err : undefined },\n        );\n      }\n    }\n    if (typeof (instance as { setup?: unknown }).setup === \"function\") {\n      try {\n        await (instance as { setup: () => Promise<void> | void }).setup();\n      } catch (err) {\n        throw new Error(\n          `runAgent: plugin '${data.name}' setup() failed in standalone ` +\n            \"mode. This plugin probably depends on createApp's runtime \" +\n            \"(WorkspaceClient, ServiceContext, PluginContext). Run via \" +\n            \"createApp({ plugins: [..., agents(...)] }) instead. \" +\n            `Cause: ${err instanceof Error ? err.message : String(err)}`,\n          { cause: err instanceof Error ? err : undefined },\n        );\n      }\n    }\n    cache.set(data.name, instance);\n  }\n}\n\nasync function resolveAdapter(def: AgentDefinition): Promise<AgentAdapter> {\n  const { model } = def;\n  if (!model) {\n    const { DatabricksAdapter } = await import(\"../../agents/databricks\");\n    return DatabricksAdapter.fromModelServing();\n  }\n  if (typeof model === \"string\") {\n    const { DatabricksAdapter } = await import(\"../../agents/databricks\");\n    return DatabricksAdapter.fromModelServing(model);\n  }\n  return await model;\n}\n\nfunction normalizeMessages(\n  input: string | Message[],\n  instructions: string,\n): Message[] {\n  const systemMessage: Message = {\n    id: \"system\",\n    role: \"system\",\n    content: instructions,\n    createdAt: new Date(),\n  };\n  if (typeof input === \"string\") {\n    return [\n      systemMessage,\n      {\n        id: randomUUID(),\n        role: \"user\",\n        content: input,\n        createdAt: new Date(),\n      },\n    ];\n  }\n  return [systemMessage, ...input];\n}\n\ntype StandaloneEntry =\n  | {\n      kind: \"function\";\n      def: AgentToolDefinition;\n      tool: FunctionTool;\n    }\n  | {\n      kind: \"subagent\";\n      def: AgentToolDefinition;\n      agentDef: AgentDefinition;\n    }\n  | {\n      kind: \"toolkit\";\n      def: AgentToolDefinition;\n      provider: ToolProvider;\n      pluginName: string;\n      localName: string;\n    }\n  | {\n      kind: \"hosted\";\n      def: AgentToolDefinition;\n    };\n\n/**\n * Resolves `def.tools` (object or function form) and `def.agents`\n * (sub-agents) into a flat dispatch index. The function form is invoked\n * once per call against a {@link Plugins} map drawn from the shared\n * `providerCache` populated by {@link initStandalonePlugins}. Missing\n * references throw a named \"not registered\" error via the proxy.\n */\nfunction buildStandaloneToolIndex(\n  def: AgentDefinition,\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): Map<string, StandaloneEntry> {\n  const index = new Map<string, StandaloneEntry>();\n  const tools = resolveDefTools(def, plugins, providerCache);\n\n  for (const [key, tool] of Object.entries(tools)) {\n    index.set(key, classifyTool(key, tool, providerCache));\n  }\n\n  for (const [childKey, child] of Object.entries(def.agents ?? {})) {\n    const toolName = `agent-${childKey}`;\n    index.set(toolName, {\n      kind: \"subagent\",\n      agentDef: { ...child, name: child.name ?? childKey },\n      def: {\n        name: toolName,\n        description:\n          child.instructions.slice(0, 120) ||\n          `Delegate to the ${childKey} sub-agent`,\n        parameters: {\n          type: \"object\",\n          properties: {\n            input: {\n              type: \"string\",\n              description: \"Message to send to the sub-agent.\",\n            },\n          },\n          required: [\"input\"],\n        },\n      },\n    });\n  }\n\n  return index;\n}\n\n/**\n * Resolves `def.tools` to a plain record. The function form is invoked\n * with a typed {@link Plugins} map drawn from the pre-populated\n * `providerCache`; each `plugins.foo.toolkit(opts)` lookup hits the cache\n * directly (no construction at toolkit-call time).\n */\nfunction resolveDefTools(\n  def: AgentDefinition,\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): AgentTools {\n  if (typeof def.tools !== \"function\") {\n    return def.tools ?? {};\n  }\n  const pluginsMap = buildStandalonePluginsMap(plugins, providerCache);\n  try {\n    return def.tools(pluginsMap);\n  } catch (err) {\n    const name = def.name ?? \"<anonymous>\";\n    throw new Error(\n      `runAgent: agent '${name}' tools(plugins) callback threw: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n\n/**\n * Builds the typed {@link Plugins} map passed to the function form of\n * `def.tools` in standalone mode. Reads pre-constructed instances from\n * `providerCache` (populated eagerly by {@link initStandalonePlugins})\n * and wraps the result in a Proxy so unknown plugin names produce a\n * named \"not registered, Available: ...\" error instead of bubbling up a\n * generic `TypeError: Cannot read properties of undefined`.\n */\nfunction buildStandalonePluginsMap(\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): Plugins {\n  const out: Record<string, PluginToolkitProvider> = {};\n  for (const data of plugins) {\n    const provider = providerCache.get(data.name);\n    if (!provider) continue; // initStandalonePlugins should have set this\n    out[data.name] = {\n      toolkit: (opts) => resolveToolkitFromProvider(data.name, provider, opts),\n    };\n  }\n  return createPluginsProxy(out, \"runAgent: tools(plugins)\");\n}\n\nfunction classifyTool(\n  key: string,\n  tool: AgentTool,\n  providerCache: Map<string, ToolProvider>,\n): StandaloneEntry {\n  if (isToolkitEntry(tool)) {\n    // Toolkit entries inside the function form's returned record carry the\n    // provider name they came from, so we can resolve the provider on\n    // demand and dispatch through it. The cache is shared with the\n    // pluginsMap path so the same instance is reused.\n    const provider = providerCacheLookup(tool.pluginName, providerCache);\n    return {\n      kind: \"toolkit\",\n      provider,\n      pluginName: tool.pluginName,\n      localName: tool.localName,\n      def: { ...tool.def, name: key },\n    };\n  }\n  if (isFunctionTool(tool)) {\n    return {\n      kind: \"function\",\n      tool,\n      def: { ...functionToolToDefinition(tool), name: key },\n    };\n  }\n  if (isHostedTool(tool)) {\n    // Hosted tools (e.g. MCP `mcpServer(...)`) need a live MCP client that\n    // only exists inside the agents plugin's lifecycle. In standalone\n    // `runAgent` they would have errored at dispatch time with a confusing\n    // mid-conversation failure; reject them up front so misconfiguration\n    // surfaces before the adapter sees the tool list.\n    throw new Error(\n      `runAgent: tool \"${key}\" is a hosted tool (type=\"${tool.type}\") which is only supported via createApp({ plugins: [..., agents(...)] }). Standalone runAgent has no MCP client.`,\n    );\n  }\n  throw new Error(`runAgent: unrecognized tool shape at key \"${key}\"`);\n}\n\nfunction providerCacheLookup(\n  pluginName: string,\n  cache: Map<string, ToolProvider>,\n): ToolProvider {\n  const cached = cache.get(pluginName);\n  if (cached) return cached;\n  const available = Array.from(cache.keys()).join(\", \") || \"(none)\";\n  throw new Error(\n    `runAgent: tool refers to plugin '${pluginName}', but no instance was ` +\n      \"initialised for that name. Add it to RunAgentInput.plugins, or — if \" +\n      \"this came from a hand-rolled ToolkitEntry — go through \" +\n      `plugins[name].toolkit() instead. Available: ${available}.`,\n  );\n}\n\n/**\n * Lightweight `ToolProvider` shape check used by standalone `runAgent`.\n *\n * Distinct from `core/plugin-context.isToolProvider` which also requires\n * `asUser` (request-scoped, only meaningful when running inside `createApp`\n * with a live HTTP context). Standalone plugins are constructed without a\n * `WorkspaceClient` and have no request to scope to, so checking only the\n * two `ToolProvider` methods is the right narrowing here.\n */\nfunction isStandaloneToolProvider(value: unknown): value is ToolProvider {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.getAgentTools === \"function\" &&\n    typeof obj.executeAgentTool === \"function\"\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"run-agent.js","names":[],"sources":["../../../src/core/agent/run-agent.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type {\n  AgentAdapter,\n  AgentEvent,\n  AgentToolDefinition,\n  Message,\n  PluginConstructor,\n  PluginData,\n  ToolProvider,\n} from \"shared\";\nimport {\n  isSupervisorTool,\n  SUPERVISOR_EXTENSION_KEY,\n  type SupervisorTool,\n} from \"../../agents/supervisor-api\";\nimport { createLogger } from \"../../logging/logger\";\nimport { consumeAdapterStream } from \"./consume-adapter-stream\";\nimport { createPluginsProxy } from \"./plugins-map\";\nimport { resolveToolkitFromProvider } from \"./toolkit-resolver\";\nimport {\n  type FunctionTool,\n  functionToolToDefinition,\n  isFunctionTool,\n} from \"./tools/function-tool\";\nimport { isHostedTool } from \"./tools/hosted-tools\";\nimport type {\n  AgentDefinition,\n  AgentTool,\n  AgentTools,\n  Plugins,\n  PluginToolkitProvider,\n} from \"./types\";\nimport { isToolkitEntry } from \"./types\";\n\nconst logger = createLogger(\"agent:run-agent\");\n\nexport interface RunAgentInput {\n  /** Seed messages for the run. Either a single user string or a full message list. */\n  messages: string | Message[];\n  /** Abort signal for cancellation. */\n  signal?: AbortSignal;\n  /**\n   * Optional plugin list. Required when `def.tools` is the function form\n   * `(plugins) => Record<string, AgentTool>` and the function dereferences\n   * any plugins. `runAgent` constructs a fresh instance per plugin and\n   * dispatches tool calls against it as the service principal (no OBO —\n   * there is no HTTP request in standalone mode).\n   */\n  plugins?: PluginData<PluginConstructor, unknown, string>[];\n}\n\nexport interface RunAgentResult {\n  /** Aggregated text output from all `message_delta` events. */\n  text: string;\n  /** Every event the adapter yielded, in order. Useful for inspection/tests. */\n  events: AgentEvent[];\n}\n\n/**\n * Standalone agent execution without `createApp`. Resolves the adapter, binds\n * inline tools, and drives the adapter's `run()` loop to completion.\n *\n * Limitations vs. running through the agents() plugin:\n * - **No OBO and no approval gate** — there is no HTTP request, so plugin\n *   tools run as the service principal. The agents-plugin approval gate\n *   that prompts for human confirmation on `effect: \"write\" | \"update\" |\n *   \"destructive\"` tools is also absent. LLM-controlled tool arguments\n *   flow straight through to the SP. Treat standalone runAgent as a\n *   trusted-prompt environment (CI, batch eval, internal scripts) — not\n *   as an exposed user-facing surface.\n * - **Hosted tools (MCP) are not supported** — they require a live MCP\n *   client that only exists inside the agents plugin's lifecycle.\n *   `runAgent` rejects them at index-build time with a clear error.\n * - **Sub-agents** (`agents: { ... }` on the def) are executed as nested\n *   `runAgent` calls with no shared thread state. Plugin instances ARE\n *   shared across the recursion (same cache as the parent).\n * - **Plugin tools** (used inside the function form via\n *   `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via\n *   `RunAgentInput`. Each plugin in that array is constructed once,\n *   `attachContext({})` and `await setup()` are called eagerly, and the\n *   resulting instance is shared across the top-level run and all\n *   sub-agent recursions. Plugins whose `setup()` requires runtime that\n *   only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`,\n *   `PluginContext`) throw at standalone-init time with a clear \"use\n *   createApp instead\" message — not mid-stream.\n */\nexport async function runAgent(\n  def: AgentDefinition,\n  input: RunAgentInput,\n): Promise<RunAgentResult> {\n  // Single shared cache for the whole call graph: parent + every nested\n  // sub-agent dispatch share constructed plugin instances. Without this,\n  // each nested `runAgent` would build its own cache, re-instantiate every\n  // plugin, and silently diverge in-instance state between parent and child\n  // (e.g. query result caches, connection pools).\n  const providerCache = new Map<string, ToolProvider>();\n  await initStandalonePlugins(input.plugins ?? [], providerCache);\n  return runAgentInternal(def, input, providerCache);\n}\n\nasync function runAgentInternal(\n  def: AgentDefinition,\n  input: RunAgentInput,\n  providerCache: Map<string, ToolProvider>,\n): Promise<RunAgentResult> {\n  const adapter = await resolveAdapter(def);\n  const messages = normalizeMessages(input.messages, def.instructions);\n  const toolIndex = buildStandaloneToolIndex(\n    def,\n    input.plugins ?? [],\n    providerCache,\n  );\n  // Hosted-supervisor entries are routed via `extensions`, not as callable\n  // tools — exclude their placeholder `def` from the wire `tools` array.\n  const tools = Array.from(toolIndex.values())\n    .filter((e) => e.kind !== \"hosted-supervisor\")\n    .map((e) => e.def);\n\n  warnOnCapabilityMismatch(def.name ?? \"<anonymous>\", adapter, toolIndex);\n\n  const signal = input.signal;\n\n  const executeTool = async (name: string, args: unknown): Promise<unknown> => {\n    const entry = toolIndex.get(name);\n    if (!entry) throw new Error(`Unknown tool: ${name}`);\n    if (entry.kind === \"function\") {\n      return entry.tool.execute(args as Record<string, unknown>);\n    }\n    if (entry.kind === \"toolkit\") {\n      return entry.provider.executeAgentTool(\n        entry.localName,\n        args as Record<string, unknown>,\n        signal,\n      );\n    }\n    if (entry.kind === \"subagent\") {\n      const subInput: RunAgentInput = {\n        messages:\n          typeof args === \"object\" &&\n          args !== null &&\n          typeof (args as { input?: unknown }).input === \"string\"\n            ? (args as { input: string }).input\n            : JSON.stringify(args),\n        signal,\n        plugins: input.plugins,\n      };\n      // Reuse the same `providerCache` so sub-agent plugin tools dispatch\n      // through the same instances the parent constructed.\n      const res = await runAgentInternal(\n        entry.agentDef,\n        subInput,\n        providerCache,\n      );\n      return res.text;\n    }\n    if (entry.kind === \"hosted-supervisor\") {\n      // Defense-in-depth: should never fire. The placeholder def is\n      // filtered out of `tools` above, so the model never sees a callable\n      // schema for hosted-supervisor entries. If we ever reach here, the\n      // model was somehow handed the def and tried to invoke it directly.\n      throw new Error(\n        `runAgent: tool \"${name}\" is a hosted-supervisor tool, executed server-side by the Databricks AI Gateway. It must not be invoked from the Node process.`,\n      );\n    }\n    throw new Error(\n      `runAgent: tool \"${name}\" is a ${entry.kind} tool. ` +\n        \"Hosted/MCP tools are only usable via createApp({ plugins: [..., agents(...)] }).\",\n    );\n  };\n\n  const events: AgentEvent[] = [];\n\n  const stream = adapter.run(\n    {\n      messages,\n      tools,\n      threadId: randomUUID(),\n      signal,\n      extensions: buildStandaloneExtensions(toolIndex),\n    },\n    { executeTool, signal },\n  );\n\n  // Shared accumulation rule (deltas append, `message` replaces). The\n  // `events` array is filled via the `onEvent` side effect so callers that\n  // inspect the raw stream still get the full record.\n  const text = await consumeAdapterStream(stream, {\n    signal,\n    onEvent: (event) => {\n      events.push(event);\n    },\n  });\n\n  return { text, events };\n}\n\n/**\n * Eagerly construct every plugin in `input.plugins`, run the standard\n * AppKit lifecycle (`attachContext({})` + `await setup()`), and populate\n * `cache`. Failures here surface BEFORE any adapter work — mid-stream\n * `getWorkspaceClient is not initialised`-style errors become a clear\n * startup failure naming the plugin and pointing the user at `createApp`.\n *\n * Plugins that don't need runtime context (no overridden `setup`, or one\n * that doesn't dereference `createApp`-only state) initialise cleanly and\n * standalone runAgent works as documented. Plugins like analytics/files\n * that depend on `WorkspaceClient` will throw the underlying error wrapped\n * with the migration hint.\n */\nasync function initStandalonePlugins(\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  cache: Map<string, ToolProvider>,\n): Promise<void> {\n  for (const data of plugins) {\n    if (cache.has(data.name)) continue;\n    const instance = new data.plugin({\n      ...(data.config ?? {}),\n      name: data.name,\n    });\n    if (!isStandaloneToolProvider(instance)) {\n      throw new Error(\n        `runAgent: plugin '${data.name}' is not a ToolProvider ` +\n          \"(missing getAgentTools/executeAgentTool). Only ToolProvider plugins \" +\n          \"are supported in standalone runAgent.\",\n      );\n    }\n    if (\n      typeof (instance as { attachContext?: unknown }).attachContext ===\n      \"function\"\n    ) {\n      try {\n        (\n          instance as { attachContext: (deps: Record<string, unknown>) => void }\n        ).attachContext({});\n      } catch (err) {\n        throw new Error(\n          `runAgent: plugin '${data.name}' attachContext() failed in ` +\n            \"standalone mode. This plugin probably depends on createApp's \" +\n            \"runtime (WorkspaceClient, ServiceContext, PluginContext). Run \" +\n            \"via createApp({ plugins: [..., agents(...)] }) instead. \" +\n            `Cause: ${err instanceof Error ? err.message : String(err)}`,\n          { cause: err instanceof Error ? err : undefined },\n        );\n      }\n    }\n    if (typeof (instance as { setup?: unknown }).setup === \"function\") {\n      try {\n        await (instance as { setup: () => Promise<void> | void }).setup();\n      } catch (err) {\n        throw new Error(\n          `runAgent: plugin '${data.name}' setup() failed in standalone ` +\n            \"mode. This plugin probably depends on createApp's runtime \" +\n            \"(WorkspaceClient, ServiceContext, PluginContext). Run via \" +\n            \"createApp({ plugins: [..., agents(...)] }) instead. \" +\n            `Cause: ${err instanceof Error ? err.message : String(err)}`,\n          { cause: err instanceof Error ? err : undefined },\n        );\n      }\n    }\n    cache.set(data.name, instance);\n  }\n}\n\nasync function resolveAdapter(def: AgentDefinition): Promise<AgentAdapter> {\n  const { model } = def;\n  if (!model) {\n    const { DatabricksAdapter } = await import(\"../../agents/databricks\");\n    return DatabricksAdapter.fromModelServing();\n  }\n  if (typeof model === \"string\") {\n    const { DatabricksAdapter } = await import(\"../../agents/databricks\");\n    return DatabricksAdapter.fromModelServing(model);\n  }\n  return await model;\n}\n\nfunction normalizeMessages(\n  input: string | Message[],\n  instructions: string,\n): Message[] {\n  const systemMessage: Message = {\n    id: \"system\",\n    role: \"system\",\n    content: instructions,\n    createdAt: new Date(),\n  };\n  if (typeof input === \"string\") {\n    return [\n      systemMessage,\n      {\n        id: randomUUID(),\n        role: \"user\",\n        content: input,\n        createdAt: new Date(),\n      },\n    ];\n  }\n  return [systemMessage, ...input];\n}\n\ntype StandaloneEntry =\n  | {\n      kind: \"function\";\n      def: AgentToolDefinition;\n      tool: FunctionTool;\n    }\n  | {\n      kind: \"subagent\";\n      def: AgentToolDefinition;\n      agentDef: AgentDefinition;\n    }\n  | {\n      kind: \"toolkit\";\n      def: AgentToolDefinition;\n      provider: ToolProvider;\n      pluginName: string;\n      localName: string;\n    }\n  | {\n      kind: \"hosted\";\n      def: AgentToolDefinition;\n    }\n  | {\n      /**\n       * Adapter-side hosted tool. Standalone `runAgent` accepts these\n       * (unlike MCP hosted tools, which need a live MCP client) because\n       * the adapter has everything it needs to execute them server-side:\n       * the spec travels via `AgentInput.extensions` and the SA endpoint\n       * runs the tool loop. Enables batch-eval / CI use of supervisor\n       * agents without `createApp`.\n       */\n      kind: \"hosted-supervisor\";\n      def: AgentToolDefinition;\n      spec: SupervisorTool;\n    };\n\n/**\n * Resolves `def.tools` (object or function form) and `def.agents`\n * (sub-agents) into a flat dispatch index. The function form is invoked\n * once per call against a {@link Plugins} map drawn from the shared\n * `providerCache` populated by {@link initStandalonePlugins}. Missing\n * references throw a named \"not registered\" error via the proxy.\n */\nfunction buildStandaloneToolIndex(\n  def: AgentDefinition,\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): Map<string, StandaloneEntry> {\n  const index = new Map<string, StandaloneEntry>();\n  const tools = resolveDefTools(def, plugins, providerCache);\n\n  for (const [key, tool] of Object.entries(tools)) {\n    index.set(key, classifyTool(key, tool, providerCache));\n  }\n\n  for (const [childKey, child] of Object.entries(def.agents ?? {})) {\n    const toolName = `agent-${childKey}`;\n    index.set(toolName, {\n      kind: \"subagent\",\n      agentDef: { ...child, name: child.name ?? childKey },\n      def: {\n        name: toolName,\n        description:\n          child.instructions.slice(0, 120) ||\n          `Delegate to the ${childKey} sub-agent`,\n        parameters: {\n          type: \"object\",\n          properties: {\n            input: {\n              type: \"string\",\n              description: \"Message to send to the sub-agent.\",\n            },\n          },\n          required: [\"input\"],\n        },\n      },\n    });\n  }\n\n  return index;\n}\n\n/**\n * Resolves `def.tools` to a plain record. The function form is invoked\n * with a typed {@link Plugins} map drawn from the pre-populated\n * `providerCache`; each `plugins.foo.toolkit(opts)` lookup hits the cache\n * directly (no construction at toolkit-call time).\n */\nfunction resolveDefTools(\n  def: AgentDefinition,\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): AgentTools {\n  if (typeof def.tools !== \"function\") {\n    return def.tools ?? {};\n  }\n  const pluginsMap = buildStandalonePluginsMap(plugins, providerCache);\n  try {\n    return def.tools(pluginsMap);\n  } catch (err) {\n    const name = def.name ?? \"<anonymous>\";\n    throw new Error(\n      `runAgent: agent '${name}' tools(plugins) callback threw: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n\n/**\n * Builds the typed {@link Plugins} map passed to the function form of\n * `def.tools` in standalone mode. Reads pre-constructed instances from\n * `providerCache` (populated eagerly by {@link initStandalonePlugins})\n * and wraps the result in a Proxy so unknown plugin names produce a\n * named \"not registered, Available: ...\" error instead of bubbling up a\n * generic `TypeError: Cannot read properties of undefined`.\n */\nfunction buildStandalonePluginsMap(\n  plugins: PluginData<PluginConstructor, unknown, string>[],\n  providerCache: Map<string, ToolProvider>,\n): Plugins {\n  const out: Record<string, PluginToolkitProvider> = {};\n  for (const data of plugins) {\n    const provider = providerCache.get(data.name);\n    if (!provider) continue; // initStandalonePlugins should have set this\n    out[data.name] = {\n      toolkit: (opts) => resolveToolkitFromProvider(data.name, provider, opts),\n    };\n  }\n  return createPluginsProxy(out, \"runAgent: tools(plugins)\");\n}\n\nfunction classifyTool(\n  key: string,\n  tool: AgentTool,\n  providerCache: Map<string, ToolProvider>,\n): StandaloneEntry {\n  if (isToolkitEntry(tool)) {\n    // Toolkit entries inside the function form's returned record carry the\n    // provider name they came from, so we can resolve the provider on\n    // demand and dispatch through it. The cache is shared with the\n    // pluginsMap path so the same instance is reused.\n    const provider = providerCacheLookup(tool.pluginName, providerCache);\n    return {\n      kind: \"toolkit\",\n      provider,\n      pluginName: tool.pluginName,\n      localName: tool.localName,\n      def: { ...tool.def, name: key },\n    };\n  }\n  if (isFunctionTool(tool)) {\n    return {\n      kind: \"function\",\n      tool,\n      def: { ...functionToolToDefinition(tool), name: key },\n    };\n  }\n  // Supervisor-API hosted tools work in standalone mode: the adapter\n  // executes them server-side via `AgentInput.extensions`, no MCP client\n  // required. Must come BEFORE the `isHostedTool` MCP rejection — the two\n  // predicates classify disjoint values (`isSupervisorTool` matches the\n  // `__kind` tag; `isHostedTool` matches the wire-format `type` field),\n  // but the placement makes the intent explicit.\n  if (isSupervisorTool(tool)) {\n    return {\n      kind: \"hosted-supervisor\",\n      spec: tool.spec,\n      def: {\n        name: key,\n        description: supervisorToolDescription(tool.spec),\n        parameters: { type: \"object\", properties: {} },\n      },\n    };\n  }\n  if (isHostedTool(tool)) {\n    // Hosted tools (e.g. MCP `mcpServer(...)`) need a live MCP client that\n    // only exists inside the agents plugin's lifecycle. In standalone\n    // `runAgent` they would have errored at dispatch time with a confusing\n    // mid-conversation failure; reject them up front so misconfiguration\n    // surfaces before the adapter sees the tool list.\n    throw new Error(\n      `runAgent: tool \"${key}\" is a hosted tool (type=\"${tool.type}\") which is only supported via createApp({ plugins: [..., agents(...)] }). Standalone runAgent has no MCP client.`,\n    );\n  }\n  throw new Error(`runAgent: unrecognized tool shape at key \"${key}\"`);\n}\n\n/** Mirrors `agents.ts`'s `supervisorToolDescription`. */\nfunction supervisorToolDescription(spec: SupervisorTool): string {\n  switch (spec.type) {\n    case \"genie_space\":\n      return spec.genie_space.description;\n    case \"uc_function\":\n      return spec.uc_function.description;\n    case \"knowledge_assistant\":\n      return spec.knowledge_assistant.description;\n    case \"app\":\n      return spec.app.description;\n    case \"uc_connection\":\n      return spec.uc_connection.description;\n  }\n}\n\n/** Mirrors `agents.ts`'s `buildAdapterExtensions`. */\nfunction buildStandaloneExtensions(\n  toolIndex: Map<string, StandaloneEntry>,\n): Readonly<Record<string, unknown>> | undefined {\n  const supervisorSpecs: SupervisorTool[] = [];\n  for (const entry of toolIndex.values()) {\n    if (entry.kind === \"hosted-supervisor\") {\n      supervisorSpecs.push(entry.spec);\n    }\n  }\n  if (supervisorSpecs.length === 0) return undefined;\n  return {\n    [SUPERVISOR_EXTENSION_KEY]: { hostedTools: supervisorSpecs },\n  };\n}\n\n/**\n * Mirrors the agents-plugin capability warning so standalone `runAgent`\n * produces the same diagnostic when adapter capabilities don't match the\n * tool index. Warn-not-throw: doesn't abort batch evals.\n */\nfunction warnOnCapabilityMismatch(\n  agentName: string,\n  adapter: AgentAdapter,\n  toolIndex: Map<string, StandaloneEntry>,\n): void {\n  const accepted = new Set(adapter.acceptsExtensions ?? []);\n\n  const hostedSupervisorKeys: string[] = [];\n  const inputToolKeys: string[] = [];\n  for (const [key, entry] of toolIndex) {\n    if (entry.kind === \"hosted-supervisor\") {\n      hostedSupervisorKeys.push(key);\n    } else {\n      inputToolKeys.push(key);\n    }\n  }\n\n  if (\n    hostedSupervisorKeys.length > 0 &&\n    !accepted.has(SUPERVISOR_EXTENSION_KEY)\n  ) {\n    logger.warn(\n      `Agent '${agentName}' declares hosted-supervisor tools (${hostedSupervisorKeys.join(\", \")}) ` +\n        \"but its model adapter does not accept the 'databricks.supervisor' extension. \" +\n        \"Pair them with `DatabricksAdapter.fromSupervisorApi(...)`, or remove them.\",\n    );\n  }\n\n  if (adapter.consumesInputTools === false && inputToolKeys.length > 0) {\n    logger.warn(\n      `Agent '${agentName}' declares function tools / sub-agents (${inputToolKeys.join(\", \")}) ` +\n        \"but its model adapter does not consume input.tools. These tools will not be exposed to the model.\",\n    );\n  }\n}\n\nfunction providerCacheLookup(\n  pluginName: string,\n  cache: Map<string, ToolProvider>,\n): ToolProvider {\n  const cached = cache.get(pluginName);\n  if (cached) return cached;\n  const available = Array.from(cache.keys()).join(\", \") || \"(none)\";\n  throw new Error(\n    `runAgent: tool refers to plugin '${pluginName}', but no instance was ` +\n      \"initialised for that name. Add it to RunAgentInput.plugins, or — if \" +\n      \"this came from a hand-rolled ToolkitEntry — go through \" +\n      `plugins[name].toolkit() instead. Available: ${available}.`,\n  );\n}\n\n/**\n * Lightweight `ToolProvider` shape check used by standalone `runAgent`.\n *\n * Distinct from `core/plugin-context.isToolProvider` which also requires\n * `asUser` (request-scoped, only meaningful when running inside `createApp`\n * with a live HTTP context). Standalone plugins are constructed without a\n * `WorkspaceClient` and have no request to scope to, so checking only the\n * two `ToolProvider` methods is the right narrowing here.\n */\nfunction isStandaloneToolProvider(value: unknown): value is ToolProvider {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.getAgentTools === \"function\" &&\n    typeof obj.executeAgentTool === \"function\"\n  );\n}\n"],"mappings":"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"}

package/dist/core/agent/types.d.ts

@@ -1,6 +1,7 @@
 import { AgentAdapter, AgentToolDefinition, ThreadStore, ToolAnnotations } from "../../shared/src/agent.js";
 import { BasePluginConfig } from "../../shared/src/plugin.js";
 import "../../shared/src/index.js";
+import { HostedSupervisorTool, SupervisorTool } from "../../agents/supervisor-api.js";
 import { GenerationParams } from "../../agents/databricks.js";
 import { McpHostPolicyConfig } from "../../connectors/mcp/host-policy.js";
 import "../../connectors/mcp/index.js";
@@ -30,10 +31,11 @@ interface ToolkitEntry {
 }
 /**
  * Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP
- * tools (`mcpServer()` / raw hosted), or toolkit references from plugins
- * (`analytics().toolkit()`).
+ * tools (`mcpServer()` / raw hosted), toolkit references from plugins
+ * (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools
+ * (`supervisorTools.*`).
  */
-type AgentTool = FunctionTool | HostedTool | ToolkitEntry;
+type AgentTool = FunctionTool | HostedTool | ToolkitEntry | HostedSupervisorTool;
 interface ToolkitOptions {
   /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */
   prefix?: string;
@@ -286,6 +288,20 @@ type ResolvedToolEntry = {
   source: "subagent";
   agentName: string;
   def: AgentToolDefinition;
+} | {
+  /**
+   * Adapter-side hosted tool (executed by the model-host, not by the
+   * Node process). Today: Supervisor API hosted tools (Genie spaces,
+   * UC functions, etc.). The `spec` is opaque to the agents plugin —
+   * it routes the entry into `AgentInput.extensions` for the adapter
+   * that declared the matching `acceptsExtensions` key. `def` is a
+   * synthetic placeholder kept so the index has a uniform shape; it
+   * is intentionally NOT included in the `tools` array passed to
+   * `adapter.run()` (those entries are not callable functions).
+   */
+  source: "hosted-supervisor";
+  spec: SupervisorTool;
+  def: AgentToolDefinition;
 };
 interface RegisteredAgent {
   name: string;

package/dist/core/agent/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":";;;;;;;;;;;;;;;AAkBA;UAAiB,YAAA;EAAA,SACN,YAAA;EACT,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;EACL,WAAA,GAAc,eAAA;EADd;;;;;;EAQA,eAAA;AAAA;;;;;;KAQU,SAAA,GAAY,YAAA,GAAe,UAAA,GAAa,YAAA;AAAA,UAEnC,cAAA;EAFO;EAItB,MAAA;EAJkD;EAMlD,IAAA;EAN8D;EAQ9D,MAAA;EAN6B;EAQ7B,MAAA,GAAS,MAAA;AAAA;;;;;;;;UAUM,qBAAA;EACf,OAAA,CAAQ,IAAA,GAAO,cAAA,GAAiB,MAAA,SAAe,YAAA;AAAA;;;;;;;;;;;;;AA2BjD;;;;;AAKA;;;;;;;KALY,OAAA,GAAU,MAAA,SAAe,qBAAA;;AAWrC;;UANiB,aAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,KAGU,sBAAA,sBAGN,GAAA,EAAK,aAAA;;;AAiBX;;KAXY,UAAA,GAAa,MAAA,SAAe,SAAA;;;;;;;AAaxC;;;KAFY,YAAA,IAAgB,OAAA,EAAS,OAAA,KAAY,UAAA;AAAA,UAEhC,eAAA;EA2BQ;;;;;;;;;;;;;;;;;;EARvB,IAAA;EAsBS;EApBT,YAAA;EAsBA;;;;;EAhBA,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAmC/B;;;AAcF;;;;;AAOA;;;EA5CE,KAAA,GAAQ,UAAA,GAAa,YAAA;EAgDZ;EA9CT,MAAA,GAAS,MAAA,SAAe,eAAA;EAkDc;EAhDtC,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EAkD6B;;;;;;;EA1C7B,gBAAA,GAAmB,gBAAA;EAgCnB;;;;;;;;EAvBA,SAAA;AAAA;;;;;;;;;;;;UAce,sBAAA;EAgDb;EA9CF,IAAA;EA8DE;EA5DF,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;EAkFvB;EAhFnB,GAAA;EAqFU;EAnFV,MAAA,GAAS,MAAA,SAAe,eAAA;;EAExB,YAAA;EA0FkB;EAxFlB,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EA8F7B;EA5FT,KAAA,GAAQ,MAAA,SAAe,SAAA;EAiGK;EA/F5B,gBAAA,aAA6B,sBAAA;EA6EzB;EA3EJ,WAAA,GAAc,WAAA;EA6EV;EA3EJ,gBAAA,GAAmB,sBAAA;EA4EV;;;;;;EArET,GAAA,GAAM,mBAAA;EA8EF;;;;;;;;;EApEJ,QAAA;IA6E8B;;;;;IAvE5B,qBAAA,YAgFiB;IA9EjB,SAAA;EAAA;EAsEF;;;;;;;;EA5DA,MAAA;IAiEA;;;;;IA3DE,2BAAA;IAgEO;AAOX;;;;IAjEI,YAAA;IAiE4C;;;;;IA3D5C,gBAAA;;;;;;;;;;;;;IAaA,iBAAA;EAAA;AAAA;;KAKQ,iBAAA;EAEN,MAAA;EACA,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,YAAA,EAAc,YAAA;EACd,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,WAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;AAAA,UAGM,eAAA;EACf,IAAA;EACA,YAAA;EACA,OAAA,EAAS,YAAA;EACT,SAAA,EAAW,GAAA,SAAY,iBAAA;EACvB,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;;EAEA,gBAAA,GAAmB,gBAAA;;EAEnB,SAAA;AAAA;;;;;iBAOc,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":"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"}

package/dist/core/agent/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/core/agent/types.ts"],"sourcesContent":["import type {\n  AgentAdapter,\n  AgentToolDefinition,\n  BasePluginConfig,\n  ThreadStore,\n  ToolAnnotations,\n} from \"shared\";\nimport type { GenerationParams } from \"../../agents/databricks\";\nimport type { McpHostPolicyConfig } from \"../../connectors/mcp\";\nimport type { FunctionTool } from \"./tools/function-tool\";\nimport type { HostedTool } from \"./tools/hosted-tools\";\n\n/**\n * A tool reference produced by a plugin's `.toolkit()` call. The agents plugin\n * recognizes the `__toolkitRef` brand and dispatches tool invocations through\n * `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving\n * OBO (asUser) and telemetry spans.\n */\nexport interface ToolkitEntry {\n  readonly __toolkitRef: true;\n  pluginName: string;\n  localName: string;\n  def: AgentToolDefinition;\n  annotations?: ToolAnnotations;\n  /**\n   * Whether this tool is eligible for `autoInheritTools` spreading. Mirrors\n   * {@link ToolEntry.autoInheritable} from the source registry so the agents\n   * plugin can filter auto-inherited tools without re-walking the provider's\n   * internal registry.\n   */\n  autoInheritable?: boolean;\n}\n\n/**\n * Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP\n * tools (`mcpServer()` / raw hosted), or toolkit references from plugins\n * (`analytics().toolkit()`).\n */\nexport type AgentTool = FunctionTool | HostedTool | ToolkitEntry;\n\nexport interface ToolkitOptions {\n  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */\n  prefix?: string;\n  /** Only include tools whose local name matches one of these. */\n  only?: string[];\n  /** Exclude tools whose local name matches one of these. */\n  except?: string[];\n  /** Remap specific local names to different keys (applied after prefix). */\n  rename?: Record<string, string>;\n}\n\n/**\n * Minimum shape every entry in the {@link Plugins} map must expose. Core\n * plugins (analytics, files, genie, lakebase) implement this directly via\n * their `.toolkit()` method. The agents plugin and standalone `runAgent`\n * synthesize this shape for any registered plugin that doesn't implement\n * `.toolkit()` directly (falling back to `getAgentTools()` walking).\n */\nexport interface PluginToolkitProvider {\n  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;\n}\n\n/**\n * Plugin map passed to the function form of {@link AgentDefinition.tools}.\n * Each entry exposes a `.toolkit(opts?)` method that returns a record of\n * {@link ToolkitEntry} markers ready to be spread into a tool record.\n *\n * AppKit does not statically know which plugins the surrounding\n * `createApp` will register, so this is a plain string-keyed record.\n * Refer to plugins by the name used in `createApp({ plugins: [...] })`;\n * unknown names resolve to `undefined` at runtime.\n *\n * @example\n * ```ts\n * const support = createAgent({\n *   instructions: \"...\",\n *   tools(plugins) {\n *     return {\n *       get_weather: tool({ ... }),\n *       ...plugins.analytics.toolkit(),\n *       ...plugins.files.toolkit({ only: [\"uploads.read\"] }),\n *     };\n *   },\n * });\n * ```\n */\nexport type Plugins = Record<string, PluginToolkitProvider>;\n\n/**\n * Context passed to `baseSystemPrompt` callbacks.\n */\nexport interface PromptContext {\n  agentName: string;\n  pluginNames: string[];\n  toolNames: string[];\n}\n\nexport type BaseSystemPromptOption =\n  | false\n  | string\n  | ((ctx: PromptContext) => string);\n\n/**\n * Per-agent tool record. String keys map to inline tools, toolkit entries,\n * hosted tools, etc.\n */\nexport type AgentTools = Record<string, AgentTool>;\n\n/**\n * Function form of `AgentDefinition.tools`. Receives the typed\n * {@link Plugins} map and returns a tool record. Invoked exactly once at\n * setup (or once per `runAgent` call in standalone mode); the result is\n * cached as the agent's resolved tool record.\n *\n * Use the function form when an agent needs tools from registered plugins.\n * The bare object form is fine when an agent only uses inline tools.\n */\nexport type AgentToolsFn = (plugins: Plugins) => AgentTools;\n\nexport interface AgentDefinition {\n  /**\n   * Stable identifier for the agent. **Optional and informational** —\n   * when the definition is registered via `agents: { foo: def }` (code) or\n   * lives at `config/agents/<id>/agent.md` (markdown), the **registry key\n   * always wins** and `name` is ignored. The agent will be reachable as\n   * `foo` (or `<id>`) regardless of what this field contains.\n   *\n   * Set `name` when:\n   *   - Running standalone via `runAgent({ agent: def })`, where there is\n   *     no enclosing key. The runtime uses it for the agent's slot in\n   *     error messages and OTel spans.\n   *   - Building a definition that may be passed to either form and you\n   *     want a consistent fallback label.\n   *\n   * Setting `name` to a value that differs from the registry key is\n   * harmless but confusing — prefer keeping them aligned or omitting `name`\n   * entirely.\n   */\n  name?: string;\n  /** System prompt body. For markdown-loaded agents this is the file body. */\n  instructions: string;\n  /**\n   * Model adapter (or endpoint-name string sugar for\n   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —\n   * falls back to the plugin's `defaultModel`.\n   */\n  model?: AgentAdapter | Promise<AgentAdapter> | string;\n  /**\n   * Per-agent tool record. Key is the LLM-visible tool-call name.\n   *\n   * Accepts either a plain record (for agents that only use inline tools)\n   * or a function `(plugins) => Record<string, AgentTool>` that receives\n   * the typed {@link Plugins} map and returns a tool record (for agents\n   * that pull tools from registered plugins).\n   *\n   * The function is invoked once at agent setup; the result is cached.\n   * Don't put per-request logic in there.\n   */\n  tools?: AgentTools | AgentToolsFn;\n  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */\n  agents?: Record<string, AgentDefinition>;\n  /** Override the plugin's baseSystemPrompt for this agent only. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /**\n   * Optional generation parameters (`temperature`, `top_p`, `stop`,\n   * `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible\n   * serving request body. Only set keys are sent. Applied only when AppKit\n   * builds the adapter itself (string or omitted `model`); when you pass a\n   * pre-built `AgentAdapter`, configure generation params on it directly.\n   */\n  generationParams?: GenerationParams;\n  /**\n   * When true, the thread used for a chat request against this agent is\n   * deleted from `ThreadStore` after the stream completes (success or\n   * failure). Use for stateless one-shot agents — e.g. autocomplete, where\n   * each request is independent and retaining history would both poison\n   * future calls and accumulate unbounded state in the default\n   * `InMemoryThreadStore`. Defaults to `false`.\n   */\n  ephemeral?: boolean;\n}\n\n/**\n * Auto-inherit configuration. When enabled for a given agent origin, agents\n * with no explicit `tools:` declaration receive every registered ToolProvider\n * plugin tool whose author marked `autoInheritable: true`. Tools without that\n * flag — destructive, state-mutating, or privilege-sensitive — never spread\n * automatically and must be wired via `tools:` (object or function form in\n * code, `plugin:NAME` entries in markdown frontmatter).\n *\n * Defaults are `false` for both origins (safe-by-default): developers must\n * consciously opt an origin in to any auto-inherit behaviour.\n */\nexport interface AutoInheritToolsConfig {\n  /** Default for agents loaded from markdown files. Default: `false`. */\n  file?: boolean;\n  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */\n  code?: boolean;\n}\n\nexport interface AgentsPluginConfig extends BasePluginConfig {\n  /** Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable. */\n  dir?: string | false;\n  /** Code-defined agents, merged with file-loaded ones (code wins on key collision). */\n  agents?: Record<string, AgentDefinition>;\n  /** Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter. */\n  defaultAgent?: string;\n  /** Default model for agents that don't specify their own (in code or frontmatter). */\n  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string;\n  /** Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`. */\n  tools?: Record<string, AgentTool>;\n  /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */\n  autoInheritTools?: boolean | AutoInheritToolsConfig;\n  /** Persistent thread store. Default: in-memory. */\n  threadStore?: ThreadStore;\n  /** Customize or disable the AppKit base system prompt. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  /**\n   * MCP server host policy. By default only same-origin Databricks workspace\n   * URLs may be used as MCP endpoints; custom hosts must be explicitly\n   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded\n   * to non-workspace hosts.\n   */\n  mcp?: McpHostPolicyConfig;\n  /**\n   * Human-in-the-loop approval gate for mutating tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool whose annotation flags it as mutating —\n   * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n   * `destructive: true` boolean — and waits for a `POST /chat/approve`\n   * decision from the same user who initiated the stream. A missing decision\n   * after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /**\n     * Require human approval for tools that mutate state. Triggered by\n     * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n     * `destructive: true` boolean. Default: `true`.\n     */\n    requireForDestructive?: boolean;\n    /** Milliseconds to wait before auto-denying. Default: 60_000. */\n    timeoutMs?: number;\n  };\n  /**\n   * Runtime resource limits applied during agent execution. Defaults are\n   * tuned to protect a single-instance deployment from a misbehaving user or\n   * a runaway prompt injection; tighten or relax as appropriate for the\n   * deployment's scale and trust model. Request-body caps (chat message\n   * size, invocations input size / length) are enforced statically by the\n   * Zod schemas and are not configurable here.\n   */\n  limits?: {\n    /**\n     * Max concurrent chat streams a single user may have open. Subsequent\n     * `POST /chat` requests from that user while at-limit are rejected with\n     * HTTP 429. Default: `5`.\n     */\n    maxConcurrentStreamsPerUser?: number;\n    /**\n     * Max tool invocations per agent run (across the full tool-call graph,\n     * including sub-agent invocations). A run that exceeds the budget is\n     * aborted with a terminal error event. Default: `50`.\n     */\n    maxToolCalls?: number;\n    /**\n     * Max sub-agent recursion depth. Protects against a prompt-injected\n     * agent that delegates to a sub-agent which in turn delegates back to\n     * itself (directly or transitively). Default: `3`.\n     */\n    maxSubAgentDepth?: number;\n    /**\n     * Per-call timeout for tools dispatched through `PluginContext`\n     * (toolkit-routed tools — analytics SQL warehouse queries, Genie\n     * messages, Lakebase queries). Independent of `maxToolCalls`: the\n     * budget caps how many tools fire per run, this caps how long any\n     * single tool call may run. The signal handed to plugin tool\n     * implementations combines this timeout with the parent stream's\n     * abort signal via `AbortSignal.any`. Function and MCP tools have\n     * their own timeouts in their respective adapters and ignore this\n     * setting. Default: `300_000` (5 minutes) — generous enough for cold\n     * SQL Warehouse round-trips and long Genie conversations.\n     */\n    toolCallTimeoutMs?: number;\n  };\n}\n\n/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */\nexport type ResolvedToolEntry =\n  | {\n      source: \"toolkit\";\n      pluginName: string;\n      localName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"function\";\n      functionTool: FunctionTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"mcp\";\n      mcpToolName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"subagent\";\n      agentName: string;\n      def: AgentToolDefinition;\n    };\n\nexport interface RegisteredAgent {\n  name: string;\n  instructions: string;\n  adapter: AgentAdapter;\n  toolIndex: Map<string, ResolvedToolEntry>;\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /** Mirrors `AgentDefinition.generationParams`. */\n  generationParams?: GenerationParams;\n  /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */\n  ephemeral?: boolean;\n}\n\n/**\n * Type guard for `ToolkitEntry` — used by the agents plugin to differentiate\n * toolkit references from inline tools in a mixed `tools` record.\n */\nexport function isToolkitEntry(value: unknown): value is ToolkitEntry {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { __toolkitRef?: unknown }).__toolkitRef === true\n  );\n}\n"],"mappings":";;;;;AA0UA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/core/agent/types.ts"],"sourcesContent":["import type {\n  AgentAdapter,\n  AgentToolDefinition,\n  BasePluginConfig,\n  ThreadStore,\n  ToolAnnotations,\n} from \"shared\";\nimport type { GenerationParams } from \"../../agents/databricks\";\nimport type { McpHostPolicyConfig } from \"../../connectors/mcp\";\nimport type { FunctionTool } from \"./tools/function-tool\";\nimport type { HostedTool } from \"./tools/hosted-tools\";\n\n/**\n * A tool reference produced by a plugin's `.toolkit()` call. The agents plugin\n * recognizes the `__toolkitRef` brand and dispatches tool invocations through\n * `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving\n * OBO (asUser) and telemetry spans.\n */\nexport interface ToolkitEntry {\n  readonly __toolkitRef: true;\n  pluginName: string;\n  localName: string;\n  def: AgentToolDefinition;\n  annotations?: ToolAnnotations;\n  /**\n   * Whether this tool is eligible for `autoInheritTools` spreading. Mirrors\n   * {@link ToolEntry.autoInheritable} from the source registry so the agents\n   * plugin can filter auto-inherited tools without re-walking the provider's\n   * internal registry.\n   */\n  autoInheritable?: boolean;\n}\n\n/**\n * Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP\n * tools (`mcpServer()` / raw hosted), toolkit references from plugins\n * (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools\n * (`supervisorTools.*`).\n */\nexport type AgentTool =\n  | FunctionTool\n  | HostedTool\n  | ToolkitEntry\n  | import(\"../../agents/supervisor-api\").HostedSupervisorTool;\n\nexport interface ToolkitOptions {\n  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */\n  prefix?: string;\n  /** Only include tools whose local name matches one of these. */\n  only?: string[];\n  /** Exclude tools whose local name matches one of these. */\n  except?: string[];\n  /** Remap specific local names to different keys (applied after prefix). */\n  rename?: Record<string, string>;\n}\n\n/**\n * Minimum shape every entry in the {@link Plugins} map must expose. Core\n * plugins (analytics, files, genie, lakebase) implement this directly via\n * their `.toolkit()` method. The agents plugin and standalone `runAgent`\n * synthesize this shape for any registered plugin that doesn't implement\n * `.toolkit()` directly (falling back to `getAgentTools()` walking).\n */\nexport interface PluginToolkitProvider {\n  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;\n}\n\n/**\n * Plugin map passed to the function form of {@link AgentDefinition.tools}.\n * Each entry exposes a `.toolkit(opts?)` method that returns a record of\n * {@link ToolkitEntry} markers ready to be spread into a tool record.\n *\n * AppKit does not statically know which plugins the surrounding\n * `createApp` will register, so this is a plain string-keyed record.\n * Refer to plugins by the name used in `createApp({ plugins: [...] })`;\n * unknown names resolve to `undefined` at runtime.\n *\n * @example\n * ```ts\n * const support = createAgent({\n *   instructions: \"...\",\n *   tools(plugins) {\n *     return {\n *       get_weather: tool({ ... }),\n *       ...plugins.analytics.toolkit(),\n *       ...plugins.files.toolkit({ only: [\"uploads.read\"] }),\n *     };\n *   },\n * });\n * ```\n */\nexport type Plugins = Record<string, PluginToolkitProvider>;\n\n/**\n * Context passed to `baseSystemPrompt` callbacks.\n */\nexport interface PromptContext {\n  agentName: string;\n  pluginNames: string[];\n  toolNames: string[];\n}\n\nexport type BaseSystemPromptOption =\n  | false\n  | string\n  | ((ctx: PromptContext) => string);\n\n/**\n * Per-agent tool record. String keys map to inline tools, toolkit entries,\n * hosted tools, etc.\n */\nexport type AgentTools = Record<string, AgentTool>;\n\n/**\n * Function form of `AgentDefinition.tools`. Receives the typed\n * {@link Plugins} map and returns a tool record. Invoked exactly once at\n * setup (or once per `runAgent` call in standalone mode); the result is\n * cached as the agent's resolved tool record.\n *\n * Use the function form when an agent needs tools from registered plugins.\n * The bare object form is fine when an agent only uses inline tools.\n */\nexport type AgentToolsFn = (plugins: Plugins) => AgentTools;\n\nexport interface AgentDefinition {\n  /**\n   * Stable identifier for the agent. **Optional and informational** —\n   * when the definition is registered via `agents: { foo: def }` (code) or\n   * lives at `config/agents/<id>/agent.md` (markdown), the **registry key\n   * always wins** and `name` is ignored. The agent will be reachable as\n   * `foo` (or `<id>`) regardless of what this field contains.\n   *\n   * Set `name` when:\n   *   - Running standalone via `runAgent({ agent: def })`, where there is\n   *     no enclosing key. The runtime uses it for the agent's slot in\n   *     error messages and OTel spans.\n   *   - Building a definition that may be passed to either form and you\n   *     want a consistent fallback label.\n   *\n   * Setting `name` to a value that differs from the registry key is\n   * harmless but confusing — prefer keeping them aligned or omitting `name`\n   * entirely.\n   */\n  name?: string;\n  /** System prompt body. For markdown-loaded agents this is the file body. */\n  instructions: string;\n  /**\n   * Model adapter (or endpoint-name string sugar for\n   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —\n   * falls back to the plugin's `defaultModel`.\n   */\n  model?: AgentAdapter | Promise<AgentAdapter> | string;\n  /**\n   * Per-agent tool record. Key is the LLM-visible tool-call name.\n   *\n   * Accepts either a plain record (for agents that only use inline tools)\n   * or a function `(plugins) => Record<string, AgentTool>` that receives\n   * the typed {@link Plugins} map and returns a tool record (for agents\n   * that pull tools from registered plugins).\n   *\n   * The function is invoked once at agent setup; the result is cached.\n   * Don't put per-request logic in there.\n   */\n  tools?: AgentTools | AgentToolsFn;\n  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */\n  agents?: Record<string, AgentDefinition>;\n  /** Override the plugin's baseSystemPrompt for this agent only. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /**\n   * Optional generation parameters (`temperature`, `top_p`, `stop`,\n   * `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible\n   * serving request body. Only set keys are sent. Applied only when AppKit\n   * builds the adapter itself (string or omitted `model`); when you pass a\n   * pre-built `AgentAdapter`, configure generation params on it directly.\n   */\n  generationParams?: GenerationParams;\n  /**\n   * When true, the thread used for a chat request against this agent is\n   * deleted from `ThreadStore` after the stream completes (success or\n   * failure). Use for stateless one-shot agents — e.g. autocomplete, where\n   * each request is independent and retaining history would both poison\n   * future calls and accumulate unbounded state in the default\n   * `InMemoryThreadStore`. Defaults to `false`.\n   */\n  ephemeral?: boolean;\n}\n\n/**\n * Auto-inherit configuration. When enabled for a given agent origin, agents\n * with no explicit `tools:` declaration receive every registered ToolProvider\n * plugin tool whose author marked `autoInheritable: true`. Tools without that\n * flag — destructive, state-mutating, or privilege-sensitive — never spread\n * automatically and must be wired via `tools:` (object or function form in\n * code, `plugin:NAME` entries in markdown frontmatter).\n *\n * Defaults are `false` for both origins (safe-by-default): developers must\n * consciously opt an origin in to any auto-inherit behaviour.\n */\nexport interface AutoInheritToolsConfig {\n  /** Default for agents loaded from markdown files. Default: `false`. */\n  file?: boolean;\n  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */\n  code?: boolean;\n}\n\nexport interface AgentsPluginConfig extends BasePluginConfig {\n  /** Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable. */\n  dir?: string | false;\n  /** Code-defined agents, merged with file-loaded ones (code wins on key collision). */\n  agents?: Record<string, AgentDefinition>;\n  /** Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter. */\n  defaultAgent?: string;\n  /** Default model for agents that don't specify their own (in code or frontmatter). */\n  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string;\n  /** Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`. */\n  tools?: Record<string, AgentTool>;\n  /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */\n  autoInheritTools?: boolean | AutoInheritToolsConfig;\n  /** Persistent thread store. Default: in-memory. */\n  threadStore?: ThreadStore;\n  /** Customize or disable the AppKit base system prompt. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  /**\n   * MCP server host policy. By default only same-origin Databricks workspace\n   * URLs may be used as MCP endpoints; custom hosts must be explicitly\n   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded\n   * to non-workspace hosts.\n   */\n  mcp?: McpHostPolicyConfig;\n  /**\n   * Human-in-the-loop approval gate for mutating tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool whose annotation flags it as mutating —\n   * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n   * `destructive: true` boolean — and waits for a `POST /chat/approve`\n   * decision from the same user who initiated the stream. A missing decision\n   * after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /**\n     * Require human approval for tools that mutate state. Triggered by\n     * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n     * `destructive: true` boolean. Default: `true`.\n     */\n    requireForDestructive?: boolean;\n    /** Milliseconds to wait before auto-denying. Default: 60_000. */\n    timeoutMs?: number;\n  };\n  /**\n   * Runtime resource limits applied during agent execution. Defaults are\n   * tuned to protect a single-instance deployment from a misbehaving user or\n   * a runaway prompt injection; tighten or relax as appropriate for the\n   * deployment's scale and trust model. Request-body caps (chat message\n   * size, invocations input size / length) are enforced statically by the\n   * Zod schemas and are not configurable here.\n   */\n  limits?: {\n    /**\n     * Max concurrent chat streams a single user may have open. Subsequent\n     * `POST /chat` requests from that user while at-limit are rejected with\n     * HTTP 429. Default: `5`.\n     */\n    maxConcurrentStreamsPerUser?: number;\n    /**\n     * Max tool invocations per agent run (across the full tool-call graph,\n     * including sub-agent invocations). A run that exceeds the budget is\n     * aborted with a terminal error event. Default: `50`.\n     */\n    maxToolCalls?: number;\n    /**\n     * Max sub-agent recursion depth. Protects against a prompt-injected\n     * agent that delegates to a sub-agent which in turn delegates back to\n     * itself (directly or transitively). Default: `3`.\n     */\n    maxSubAgentDepth?: number;\n    /**\n     * Per-call timeout for tools dispatched through `PluginContext`\n     * (toolkit-routed tools — analytics SQL warehouse queries, Genie\n     * messages, Lakebase queries). Independent of `maxToolCalls`: the\n     * budget caps how many tools fire per run, this caps how long any\n     * single tool call may run. The signal handed to plugin tool\n     * implementations combines this timeout with the parent stream's\n     * abort signal via `AbortSignal.any`. Function and MCP tools have\n     * their own timeouts in their respective adapters and ignore this\n     * setting. Default: `300_000` (5 minutes) — generous enough for cold\n     * SQL Warehouse round-trips and long Genie conversations.\n     */\n    toolCallTimeoutMs?: number;\n  };\n}\n\n/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */\nexport type ResolvedToolEntry =\n  | {\n      source: \"toolkit\";\n      pluginName: string;\n      localName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"function\";\n      functionTool: FunctionTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"mcp\";\n      mcpToolName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"subagent\";\n      agentName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      /**\n       * Adapter-side hosted tool (executed by the model-host, not by the\n       * Node process). Today: Supervisor API hosted tools (Genie spaces,\n       * UC functions, etc.). The `spec` is opaque to the agents plugin —\n       * it routes the entry into `AgentInput.extensions` for the adapter\n       * that declared the matching `acceptsExtensions` key. `def` is a\n       * synthetic placeholder kept so the index has a uniform shape; it\n       * is intentionally NOT included in the `tools` array passed to\n       * `adapter.run()` (those entries are not callable functions).\n       */\n      source: \"hosted-supervisor\";\n      spec: import(\"../../agents/supervisor-api\").SupervisorTool;\n      def: AgentToolDefinition;\n    };\n\nexport interface RegisteredAgent {\n  name: string;\n  instructions: string;\n  adapter: AgentAdapter;\n  toolIndex: Map<string, ResolvedToolEntry>;\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /** Mirrors `AgentDefinition.generationParams`. */\n  generationParams?: GenerationParams;\n  /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */\n  ephemeral?: boolean;\n}\n\n/**\n * Type guard for `ToolkitEntry` — used by the agents plugin to differentiate\n * toolkit references from inline tools in a mixed `tools` record.\n */\nexport function isToolkitEntry(value: unknown): value is ToolkitEntry {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { __toolkitRef?: unknown }).__toolkitRef === true\n  );\n}\n"],"mappings":";;;;;AA8VA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}

package/dist/plugins/agents/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","names":[],"sources":["../../../src/plugins/agents/agents.ts"],"mappings":";;;;;;;;;;cAiIa,YAAA,SAAqB,MAAA,YAAkB,YAAA;EAAA,OAC3C,QAAA,EAAuB,cAAA;EAAA,OACvB,KAAA,EAAO,WAAA;EAAA,UAEI,MAAA,EAAQ,kBAAA;EAAA,QAElB,MAAA;EAAA,QACA,gBAAA;EAAA,QACA,aAAA;EARgB;;;;;;EAAA,QAkBhB,gBAAA;EAAA,QACA,SAAA;EAAA,QACA,WAAA;EAAA,QACA,YAAA;cAEI,MAAA,EAAQ,kBAAA;EA4qBJ;;;;;;;;;;EAAA,QA7oBR,oBAAA;EAAA,YAKI,sBAAA,CAAA;EA3DoB;EAAA,YAqFpB,cAAA,CAAA;EApFL;EAAA,QAuGC,gBAAA;EAtGD;;;;;;EAAA,QAgHC,WAAA;EAhGA;;;;;EAAA,QAiHA,aAAA;EAYF,KAAA,CAAA,GAAK,OAAA;EAzFH;;;;;;EAuGF,MAAA,CAAA,GAAU,OAAA;EAdL;;;;;EAAA,QAwCG,kBAAA;EAAA,QAmEN,iBAAA;EAAA,QAMM,mBAAA;EAkEA;;;;;;EAAA,QAxCN,mBAAA;EAAA,QAmBM,oBAAA;EAAA,QAqBA,cAAA;EAyTY;;;;;EAAA,QA7QZ,cAAA;EAqVE;;;;;;;;;;;EAAA,QArPR,eAAA;EAmhCM;;;;;;;;;;;;EAAA,QAv/BN,eAAA;EAAA,QAkBM,gBAAA;EAAA,QA0DA,kBAAA;EAiEd,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CAAA,GAAoB,OAAA;;;;;;;UAYlB,iBAAA;EAUR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAkDrB,YAAA,CAAA,GAAgB,MAAA;EAAA,QAOF,WAAA;;;;;;;;;;;;UA6EN,gCAAA;;;;;;;;;;;UAuBM,aAAA;EAAA,QAoFA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;UAqLA,qBAAA;;;;;;;;;;;;UA6IA,gBAAA;;;;;;;;;;;;;;;UA6GA,WAAA;EAAA,QA2FA,aAAA;EAAA,QA2BA,cAAA;EAAA,QAuCA,kBAAA;EAAA,QASA,gBAAA;EAAA,QAUA,mBAAA;EAAA,QAaN,YAAA;EAAA,QASA,aAAA;EAgBF,QAAA,CAAA,GAAY,OAAA;EAQlB,OAAA,CAAA;6BAE2B,GAAA,EAAO,eAAA,KAAe,OAAA;;2BAG3B,eAAA;;;oCAGS,OAAA,CAAA,MAAA;EAAA;EAAA,QAIjB,iBAAA;AAAA;;;;;;;;;;;;;;;;cA+DH,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,kBAAA"}
+{"version":3,"file":"agents.d.ts","names":[],"sources":["../../../src/plugins/agents/agents.ts"],"mappings":";;;;;;;;;;cAsIa,YAAA,SAAqB,MAAA,YAAkB,YAAA;EAAA,OAC3C,QAAA,EAAuB,cAAA;EAAA,OACvB,KAAA,EAAO,WAAA;EAAA,UAEI,MAAA,EAAQ,kBAAA;EAAA,QAElB,MAAA;EAAA,QACA,gBAAA;EAAA,QACA,aAAA;EARgB;;;;;;EAAA,QAkBhB,gBAAA;EAAA,QACA,SAAA;EAAA,QACA,WAAA;EAAA,QACA,YAAA;cAEI,MAAA,EAAQ,kBAAA;EA8rBJ;;;;;;;;;;EAAA,QA/pBR,oBAAA;EAAA,YAKI,sBAAA,CAAA;EA3DoB;EAAA,YAqFpB,cAAA,CAAA;EApFL;EAAA,QAuGC,gBAAA;EAtGD;;;;;;EAAA,QAgHC,WAAA;EAhGA;;;;;EAAA,QAiHA,aAAA;EAYF,KAAA,CAAA,GAAK,OAAA;EAzFH;;;;;;EAuGF,MAAA,CAAA,GAAU,OAAA;EAdL;;;;;EAAA,QAwCG,kBAAA;EAAA,QAmEN,iBAAA;EAAA,QAMM,mBAAA;EAoEA;;;;;;EAAA,QA1CN,mBAAA;EAAA,QAmBM,oBAAA;EAAA,QAuBA,cAAA;EAyUY;;;;;EAAA,QA7RZ,cAAA;EAqWE;;;;;;;;;;;EAAA,QArPR,eAAA;EA6iCM;;;;;;;;;;;;EAAA,QAjhCN,eAAA;EAAA,QAkBM,gBAAA;EAAA,QA0DA,kBAAA;EAiEd,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CAAA,GAAoB,OAAA;;;;;;;UAYlB,iBAAA;EAUR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAkDrB,YAAA,CAAA,GAAgB,MAAA;EAAA,QAOF,WAAA;;;;;;;;;;;;UA6EN,gCAAA;;;;;;;;;;;UAuBM,aAAA;EAAA,QAoFA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;UA6LA,qBAAA;;;;;;;;;;;;UA6IA,gBAAA;;;;;;;;;;;;;;;UAyHA,WAAA;EAAA,QAiGA,aAAA;EAAA,QA2BA,cAAA;EAAA,QAuCA,kBAAA;EAAA,QASA,gBAAA;EAAA,QAUA,mBAAA;EAAA,QAaN,YAAA;EAAA,QASA,aAAA;EAgBF,QAAA,CAAA,GAAY,OAAA;EAQlB,OAAA,CAAA;6BAE2B,GAAA,EAAO,eAAA,KAAe,OAAA;;2BAG3B,eAAA;;;oCAGS,OAAA,CAAA,MAAA;EAAA;EAAA,QAIjB,iBAAA;AAAA;;;;;;;;;;;;;;;;cAsJH,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,kBAAA"}

package/dist/plugins/agents/agents.js

@@ -5,6 +5,7 @@ import "../../plugin/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 { consumeAdapterStream } from "../../core/agent/consume-adapter-stream.js";
 import { createPluginsProxy } from "../../core/agent/plugins-map.js";
 import { resolveToolkitFromProvider } from "../../core/agent/toolkit-resolver.js";
@@ -244,6 +245,7 @@ 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);
+		warnOnCapabilityMismatch(name, adapter, toolIndex);
 		return {
 			name,
 			instructions: def.instructions,
@@ -332,6 +334,21 @@ var AgentsPlugin = class extends Plugin {
 				});
 				continue;
 			}
+			if (isSupervisorTool(tool)) {
+				index.set(key, {
+					source: "hosted-supervisor",
+					spec: tool.spec,
+					def: {
+						name: key,
+						description: supervisorToolDescription(tool.spec),
+						parameters: {
+							type: "object",
+							properties: {}
+						}
+					}
+				});
+				continue;
+			}
 			if (isHostedTool(tool)) {
 				hostedToCollect.push(tool);
 				continue;
@@ -654,7 +671,7 @@ var AgentsPlugin = class extends Plugin {
 		const signal = abortController.signal;
 		const requestId = randomUUID();
 		this.trackStream(requestId, userId, abortController);
-		const tools = Array.from(registered.toolIndex.values()).map((e) => e.def);
+		const tools = Array.from(registered.toolIndex.values()).filter((e) => e.source !== "hosted-supervisor").map((e) => e.def);
 		const approvalPolicy = this.resolvedApprovalPolicy;
 		const limits = this.resolvedLimits;
 		const outboundEvents = new EventChannel();
@@ -693,7 +710,8 @@ var AgentsPlugin = class extends Plugin {
 					messages: messagesWithSystem,
 					tools,
 					threadId: thread.id,
-					signal
+					signal,
+					extensions: buildAdapterExtensions(registered.toolIndex)
 				}, {
 					executeTool,
 					signal
@@ -906,7 +924,7 @@ var AgentsPlugin = class extends Plugin {
 			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.`);
 		return normalizeToolResult(result);
 	}
 	/**
@@ -926,7 +944,7 @@ var AgentsPlugin = class extends Plugin {
 	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()).map((e) => e.def);
+		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,
@@ -952,7 +970,8 @@ var AgentsPlugin = class extends Plugin {
 			messages,
 			tools: childTools,
 			threadId: randomUUID(),
-			signal: runState.signal
+			signal: runState.signal,
+			extensions: buildAdapterExtensions(child.toolIndex)
 		}, runContext), {
 			signal: runState.signal,
 			onEvent: (event) => {
@@ -1110,6 +1129,47 @@ function composePromptForAgent(registered, pluginLevel, ctx) {
 	return composeSystemPrompt(base, registered.instructions);
 }
 /**
+* 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. Reads `config/agents/*.md` by default,
 * resolves toolkits/tools from registered plugins, exposes `appkit.agents.*`
 * runtime API and mounts `POST /invocations` and `POST /responses` (aliased