@databricks/appkit 0.32.0 → 0.33.0

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

@@ -0,0 +1,44 @@
+//#region src/core/agent/plugins-map.ts
+/**
+* Wrap a plain `Record<string, PluginToolkitProvider>` so that accessing an
+* unknown plugin name throws with a named, actionable error instead of the
+* default `TypeError: Cannot read properties of undefined (reading 'toolkit')`
+* that surfaces from chained access on a missing key.
+*
+* The {@link Plugins} type is a `Record<string, PluginToolkitProvider>`
+* without `noUncheckedIndexedAccess` workspace-wide, so unknown keys type as
+* present at compile time but resolve to `undefined` at runtime. The proxy
+* closes that gap with a runtime error that names the missing plugin and
+* lists what's available — same shape as the agents plugin's pre-existing
+* "plugin is not registered" errors.
+*
+* @param entries - the resolved plugin map; the proxy serves these directly
+*   for known keys and throws for any other string key.
+* @param contextLabel - prefix included in the error message; differentiates
+*   the runtime context (e.g. `"runAgent: tools(plugins)"` vs
+*   `"AgentsPlugin: tools(plugins)"`) so users know which path to debug.
+*/
+function createPluginsProxy(entries, contextLabel) {
+	return new Proxy(entries, {
+		get(target, prop, receiver) {
+			if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+			if (prop in target) return Reflect.get(target, prop, receiver);
+			if (prop === "then" || prop === "toJSON" || prop === "constructor" || prop === "toString" || prop === "valueOf") return;
+			const available = Object.keys(target).join(", ") || "(none)";
+			throw new Error(`${contextLabel} referenced plugin '${prop}', but it is not registered. Available: ${available}.`);
+		},
+		has(target, prop) {
+			return Reflect.has(target, prop);
+		},
+		ownKeys(target) {
+			return Reflect.ownKeys(target);
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			return Reflect.getOwnPropertyDescriptor(target, prop);
+		}
+	});
+}
+
+//#endregion
+export { createPluginsProxy };
+//# sourceMappingURL=plugins-map.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugins-map.js","names":[],"sources":["../../../src/core/agent/plugins-map.ts"],"sourcesContent":["import type { Plugins, PluginToolkitProvider } from \"./types\";\n\n/**\n * Wrap a plain `Record<string, PluginToolkitProvider>` so that accessing an\n * unknown plugin name throws with a named, actionable error instead of the\n * default `TypeError: Cannot read properties of undefined (reading 'toolkit')`\n * that surfaces from chained access on a missing key.\n *\n * The {@link Plugins} type is a `Record<string, PluginToolkitProvider>`\n * without `noUncheckedIndexedAccess` workspace-wide, so unknown keys type as\n * present at compile time but resolve to `undefined` at runtime. The proxy\n * closes that gap with a runtime error that names the missing plugin and\n * lists what's available — same shape as the agents plugin's pre-existing\n * \"plugin is not registered\" errors.\n *\n * @param entries - the resolved plugin map; the proxy serves these directly\n *   for known keys and throws for any other string key.\n * @param contextLabel - prefix included in the error message; differentiates\n *   the runtime context (e.g. `\"runAgent: tools(plugins)\"` vs\n *   `\"AgentsPlugin: tools(plugins)\"`) so users know which path to debug.\n */\nexport function createPluginsProxy(\n  entries: Record<string, PluginToolkitProvider>,\n  contextLabel: string,\n): Plugins {\n  return new Proxy(entries, {\n    get(target, prop, receiver) {\n      // Symbols and well-known string accessors (e.g. `Symbol.toPrimitive`,\n      // `then` checked by Promise.resolve, `toJSON`) must pass through so\n      // host code that probes the object doesn't hit the missing-plugin\n      // error. Only named string-key access that misses is treated as a\n      // user error.\n      if (typeof prop !== \"string\") {\n        return Reflect.get(target, prop, receiver);\n      }\n      if (prop in target) {\n        return Reflect.get(target, prop, receiver);\n      }\n      // Probes from runtime tooling (e.g. utility inspection, JSON\n      // serialization, async-iterator detection) hit common property names\n      // that are clearly not plugin lookups. Pass those through silently.\n      if (\n        prop === \"then\" ||\n        prop === \"toJSON\" ||\n        prop === \"constructor\" ||\n        prop === \"toString\" ||\n        prop === \"valueOf\"\n      ) {\n        return undefined;\n      }\n      const available = Object.keys(target).join(\", \") || \"(none)\";\n      throw new Error(\n        `${contextLabel} referenced plugin '${prop}', but it is not registered. ` +\n          `Available: ${available}.`,\n      );\n    },\n    has(target, prop) {\n      return Reflect.has(target, prop);\n    },\n    ownKeys(target) {\n      return Reflect.ownKeys(target);\n    },\n    getOwnPropertyDescriptor(target, prop) {\n      return Reflect.getOwnPropertyDescriptor(target, prop);\n    },\n  }) as Plugins;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,mBACd,SACA,cACS;AACT,QAAO,IAAI,MAAM,SAAS;EACxB,IAAI,QAAQ,MAAM,UAAU;AAM1B,OAAI,OAAO,SAAS,SAClB,QAAO,QAAQ,IAAI,QAAQ,MAAM,SAAS;AAE5C,OAAI,QAAQ,OACV,QAAO,QAAQ,IAAI,QAAQ,MAAM,SAAS;AAK5C,OACE,SAAS,UACT,SAAS,YACT,SAAS,iBACT,SAAS,cACT,SAAS,UAET;GAEF,MAAM,YAAY,OAAO,KAAK,OAAO,CAAC,KAAK,KAAK,IAAI;AACpD,SAAM,IAAI,MACR,GAAG,aAAa,sBAAsB,KAAK,0CAC3B,UAAU,GAC3B;;EAEH,IAAI,QAAQ,MAAM;AAChB,UAAO,QAAQ,IAAI,QAAQ,KAAK;;EAElC,QAAQ,QAAQ;AACd,UAAO,QAAQ,QAAQ,OAAO;;EAEhC,yBAAyB,QAAQ,MAAM;AACrC,UAAO,QAAQ,yBAAyB,QAAQ,KAAK;;EAExD,CAAC"}

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

@@ -1,4 +1,5 @@
 import { AgentEvent, Message } from "../../shared/src/agent.js";
+import { PluginConstructor, PluginData } from "../../shared/src/plugin.js";
 import "../../shared/src/index.js";
 import { AgentDefinition } from "./types.js";
 
@@ -8,6 +9,14 @@ interface RunAgentInput {
   messages: string | Message[];
   /** Abort signal for cancellation. */
   signal?: AbortSignal;
+  /**
+   * Optional plugin list. Required when `def.tools` is the function form
+   * `(plugins) => Record<string, AgentTool>` and the function dereferences
+   * any plugins. `runAgent` constructs a fresh instance per plugin and
+   * dispatches tool calls against it as the service principal (no OBO —
+   * there is no HTTP request in standalone mode).
+   */
+  plugins?: PluginData<PluginConstructor, unknown, string>[];
 }
 interface RunAgentResult {
   /** Aggregated text output from all `message_delta` events. */
@@ -20,13 +29,28 @@ interface RunAgentResult {
  * inline tools, and drives the adapter's `run()` loop to completion.
  *
  * Limitations vs. running through the agents() plugin:
- * - No OBO: there is no HTTP request, so plugin tools run as the service
- *   principal (when they work at all).
- * - Plugin tools (`ToolkitEntry`) are not supported — they require a live
- *   `PluginContext` that only exists when registered in a `createApp`
- *   instance. This function throws a clear error if encountered.
- * - Sub-agents (`agents: { ... }` on the def) are executed as nested
- *   `runAgent` calls with no shared thread state.
+ * - **No OBO and no approval gate** — there is no HTTP request, so plugin
+ *   tools run as the service principal. The agents-plugin approval gate
+ *   that prompts for human confirmation on `effect: "write" | "update" |
+ *   "destructive"` tools is also absent. LLM-controlled tool arguments
+ *   flow straight through to the SP. Treat standalone runAgent as a
+ *   trusted-prompt environment (CI, batch eval, internal scripts) — not
+ *   as an exposed user-facing surface.
+ * - **Hosted tools (MCP) are not supported** — they require a live MCP
+ *   client that only exists inside the agents plugin's lifecycle.
+ *   `runAgent` rejects them at index-build time with a clear error.
+ * - **Sub-agents** (`agents: { ... }` on the def) are executed as nested
+ *   `runAgent` calls with no shared thread state. Plugin instances ARE
+ *   shared across the recursion (same cache as the parent).
+ * - **Plugin tools** (used inside the function form via
+ *   `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via
+ *   `RunAgentInput`. Each plugin in that array is constructed once,
+ *   `attachContext({})` and `await setup()` are called eagerly, and the
+ *   resulting instance is shared across the top-level run and all
+ *   sub-agent recursions. Plugins whose `setup()` requires runtime that
+ *   only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`,
+ *   `PluginContext`) throw at standalone-init time with a clear "use
+ *   createApp instead" message — not mid-stream.
  */
 declare function runAgent(def: AgentDefinition, input: RunAgentInput): Promise<RunAgentResult>;
 //#endregion

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":";;;;;UAiBiB,aAAA;;EAEf,QAAA,WAAmB,OAAA;EAFJ;EAIf,MAAA,GAAS,WAAA;AAAA;AAAA,UAGM,cAAA;EALf;EAOA,IAAA;EALA;EAOA,MAAA,EAAQ,UAAA;AAAA;;AAJV;;;;;;;;;AAoBA;;;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":";;;;;;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"}

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

@@ -1,4 +1,6 @@
 import { consumeAdapterStream } from "./consume-adapter-stream.js";
+import { createPluginsProxy } from "./plugins-map.js";
+import { resolveToolkitFromProvider } from "./toolkit-resolver.js";
 import { functionToolToDefinition, isFunctionTool } from "./tools/function-tool.js";
 import { isHostedTool } from "./tools/hosted-tools.js";
 import { isToolkitEntry } from "./types.js";
@@ -10,32 +12,54 @@ import { randomUUID } from "node:crypto";
 * inline tools, and drives the adapter's `run()` loop to completion.
 *
 * Limitations vs. running through the agents() plugin:
-* - No OBO: there is no HTTP request, so plugin tools run as the service
-*   principal (when they work at all).
-* - Plugin tools (`ToolkitEntry`) are not supported — they require a live
-*   `PluginContext` that only exists when registered in a `createApp`
-*   instance. This function throws a clear error if encountered.
-* - Sub-agents (`agents: { ... }` on the def) are executed as nested
-*   `runAgent` calls with no shared thread state.
+* - **No OBO and no approval gate** — there is no HTTP request, so plugin
+*   tools run as the service principal. The agents-plugin approval gate
+*   that prompts for human confirmation on `effect: "write" | "update" |
+*   "destructive"` tools is also absent. LLM-controlled tool arguments
+*   flow straight through to the SP. Treat standalone runAgent as a
+*   trusted-prompt environment (CI, batch eval, internal scripts) — not
+*   as an exposed user-facing surface.
+* - **Hosted tools (MCP) are not supported** — they require a live MCP
+*   client that only exists inside the agents plugin's lifecycle.
+*   `runAgent` rejects them at index-build time with a clear error.
+* - **Sub-agents** (`agents: { ... }` on the def) are executed as nested
+*   `runAgent` calls with no shared thread state. Plugin instances ARE
+*   shared across the recursion (same cache as the parent).
+* - **Plugin tools** (used inside the function form via
+*   `plugins.<name>.toolkit(...)`) require passing `plugins: [...]` via
+*   `RunAgentInput`. Each plugin in that array is constructed once,
+*   `attachContext({})` and `await setup()` are called eagerly, and the
+*   resulting instance is shared across the top-level run and all
+*   sub-agent recursions. Plugins whose `setup()` requires runtime that
+*   only `createApp` provides (e.g. `WorkspaceClient`, `ServiceContext`,
+*   `PluginContext`) throw at standalone-init time with a clear "use
+*   createApp instead" message — not mid-stream.
 */
 async function runAgent(def, input) {
+	const providerCache = /* @__PURE__ */ new Map();
+	await initStandalonePlugins(input.plugins ?? [], providerCache);
+	return runAgentInternal(def, input, providerCache);
+}
+async function runAgentInternal(def, input, providerCache) {
 	const adapter = await resolveAdapter(def);
 	const messages = normalizeMessages(input.messages, def.instructions);
-	const toolIndex = buildStandaloneToolIndex(def);
+	const toolIndex = buildStandaloneToolIndex(def, input.plugins ?? [], providerCache);
 	const tools = Array.from(toolIndex.values()).map((e) => e.def);
 	const signal = input.signal;
 	const executeTool = async (name, args) => {
 		const entry = toolIndex.get(name);
 		if (!entry) throw new Error(`Unknown tool: ${name}`);
 		if (entry.kind === "function") return entry.tool.execute(args);
+		if (entry.kind === "toolkit") return entry.provider.executeAgentTool(entry.localName, args, signal);
 		if (entry.kind === "subagent") {
 			const subInput = {
 				messages: typeof args === "object" && args !== null && typeof args.input === "string" ? args.input : JSON.stringify(args),
-				signal
+				signal,
+				plugins: input.plugins
 			};
-			return (await runAgent(entry.agentDef, subInput)).text;
+			return (await runAgentInternal(entry.agentDef, subInput, providerCache)).text;
 		}
-		throw new Error(`runAgent: tool "${name}" is a ${entry.kind} tool. Plugin toolkits and MCP tools are only usable via createApp({ plugins: [..., agents(...)] }).`);
+		throw new Error(`runAgent: tool "${name}" is a ${entry.kind} tool. Hosted/MCP tools are only usable via createApp({ plugins: [..., agents(...)] }).`);
 	};
 	const events = [];
 	return {
@@ -56,6 +80,40 @@ async function runAgent(def, input) {
 		events
 	};
 }
+/**
+* Eagerly construct every plugin in `input.plugins`, run the standard
+* AppKit lifecycle (`attachContext({})` + `await setup()`), and populate
+* `cache`. Failures here surface BEFORE any adapter work — mid-stream
+* `getWorkspaceClient is not initialised`-style errors become a clear
+* startup failure naming the plugin and pointing the user at `createApp`.
+*
+* Plugins that don't need runtime context (no overridden `setup`, or one
+* that doesn't dereference `createApp`-only state) initialise cleanly and
+* standalone runAgent works as documented. Plugins like analytics/files
+* that depend on `WorkspaceClient` will throw the underlying error wrapped
+* with the migration hint.
+*/
+async function initStandalonePlugins(plugins, cache) {
+	for (const data of plugins) {
+		if (cache.has(data.name)) continue;
+		const instance = new data.plugin({
+			...data.config ?? {},
+			name: data.name
+		});
+		if (!isStandaloneToolProvider(instance)) throw new Error(`runAgent: plugin '${data.name}' is not a ToolProvider (missing getAgentTools/executeAgentTool). Only ToolProvider plugins are supported in standalone runAgent.`);
+		if (typeof instance.attachContext === "function") try {
+			instance.attachContext({});
+		} catch (err) {
+			throw new Error(`runAgent: plugin '${data.name}' attachContext() failed in standalone mode. This plugin probably depends on createApp's runtime (WorkspaceClient, ServiceContext, PluginContext). Run via createApp({ plugins: [..., agents(...)] }) instead. Cause: ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
+		}
+		if (typeof instance.setup === "function") try {
+			await instance.setup();
+		} catch (err) {
+			throw new Error(`runAgent: plugin '${data.name}' setup() failed in standalone mode. This plugin probably depends on createApp's runtime (WorkspaceClient, ServiceContext, PluginContext). Run via createApp({ plugins: [..., agents(...)] }) instead. Cause: ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
+		}
+		cache.set(data.name, instance);
+	}
+}
 async function resolveAdapter(def) {
 	const { model } = def;
 	if (!model) {
@@ -83,9 +141,17 @@ function normalizeMessages(input, instructions) {
 	}];
 	return [systemMessage, ...input];
 }
-function buildStandaloneToolIndex(def) {
+/**
+* Resolves `def.tools` (object or function form) and `def.agents`
+* (sub-agents) into a flat dispatch index. The function form is invoked
+* once per call against a {@link Plugins} map drawn from the shared
+* `providerCache` populated by {@link initStandalonePlugins}. Missing
+* references throw a named "not registered" error via the proxy.
+*/
+function buildStandaloneToolIndex(def, plugins, providerCache) {
 	const index = /* @__PURE__ */ new Map();
-	for (const [key, tool] of Object.entries(def.tools ?? {})) index.set(key, classifyTool(key, tool));
+	const tools = resolveDefTools(def, plugins, providerCache);
+	for (const [key, tool] of Object.entries(tools)) index.set(key, classifyTool(key, tool, providerCache));
 	for (const [childKey, child] of Object.entries(def.agents ?? {})) {
 		const toolName = `agent-${childKey}`;
 		index.set(toolName, {
@@ -110,14 +176,49 @@ function buildStandaloneToolIndex(def) {
 	}
 	return index;
 }
-function classifyTool(key, tool) {
+/**
+* Resolves `def.tools` to a plain record. The function form is invoked
+* with a typed {@link Plugins} map drawn from the pre-populated
+* `providerCache`; each `plugins.foo.toolkit(opts)` lookup hits the cache
+* directly (no construction at toolkit-call time).
+*/
+function resolveDefTools(def, plugins, providerCache) {
+	if (typeof def.tools !== "function") return def.tools ?? {};
+	const pluginsMap = buildStandalonePluginsMap(plugins, providerCache);
+	try {
+		return def.tools(pluginsMap);
+	} catch (err) {
+		const name = def.name ?? "<anonymous>";
+		throw new Error(`runAgent: agent '${name}' tools(plugins) callback threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
+	}
+}
+/**
+* Builds the typed {@link Plugins} map passed to the function form of
+* `def.tools` in standalone mode. Reads pre-constructed instances from
+* `providerCache` (populated eagerly by {@link initStandalonePlugins})
+* and wraps the result in a Proxy so unknown plugin names produce a
+* named "not registered, Available: ..." error instead of bubbling up a
+* generic `TypeError: Cannot read properties of undefined`.
+*/
+function buildStandalonePluginsMap(plugins, providerCache) {
+	const out = {};
+	for (const data of plugins) {
+		const provider = providerCache.get(data.name);
+		if (!provider) continue;
+		out[data.name] = { toolkit: (opts) => resolveToolkitFromProvider(data.name, provider, opts) };
+	}
+	return createPluginsProxy(out, "runAgent: tools(plugins)");
+}
+function classifyTool(key, tool, providerCache) {
 	if (isToolkitEntry(tool)) return {
 		kind: "toolkit",
+		provider: providerCacheLookup(tool.pluginName, providerCache),
+		pluginName: tool.pluginName,
+		localName: tool.localName,
 		def: {
 			...tool.def,
 			name: key
-		},
-		entry: tool
+		}
 	};
 	if (isFunctionTool(tool)) return {
 		kind: "function",
@@ -127,19 +228,29 @@ function classifyTool(key, tool) {
 			name: key
 		}
 	};
-	if (isHostedTool(tool)) return {
-		kind: "hosted",
-		def: {
-			name: key,
-			description: `Hosted tool: ${tool.type}`,
-			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}"`);
 }
+function providerCacheLookup(pluginName, cache) {
+	const cached = cache.get(pluginName);
+	if (cached) return cached;
+	const available = Array.from(cache.keys()).join(", ") || "(none)";
+	throw new Error(`runAgent: tool refers to plugin '${pluginName}', but no instance was initialised for that name. Add it to RunAgentInput.plugins, or — if this came from a hand-rolled ToolkitEntry — go through plugins[name].toolkit() instead. Available: ${available}.`);
+}
+/**
+* Lightweight `ToolProvider` shape check used by standalone `runAgent`.
+*
+* Distinct from `core/plugin-context.isToolProvider` which also requires
+* `asUser` (request-scoped, only meaningful when running inside `createApp`
+* with a live HTTP context). Standalone plugins are constructed without a
+* `WorkspaceClient` and have no request to scope to, so checking only the
+* two `ToolProvider` methods is the right narrowing here.
+*/
+function isStandaloneToolProvider(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const obj = value;
+	return typeof obj.getAgentTools === "function" && typeof obj.executeAgentTool === "function";
+}
 
 //#endregion
 export { runAgent };

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} from \"shared\";\nimport { consumeAdapterStream } from \"./consume-adapter-stream\";\nimport {\n  type FunctionTool,\n  functionToolToDefinition,\n  isFunctionTool,\n} from \"./tools/function-tool\";\nimport { isHostedTool } from \"./tools/hosted-tools\";\nimport type { AgentDefinition, AgentTool, ToolkitEntry } 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\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: there is no HTTP request, so plugin tools run as the service\n *   principal (when they work at all).\n * - Plugin tools (`ToolkitEntry`) are not supported — they require a live\n *   `PluginContext` that only exists when registered in a `createApp`\n *   instance. This function throws a clear error if encountered.\n * - Sub-agents (`agents: { ... }` on the def) are executed as nested\n *   `runAgent` calls with no shared thread state.\n */\nexport async function runAgent(\n  def: AgentDefinition,\n  input: RunAgentInput,\n): Promise<RunAgentResult> {\n  const adapter = await resolveAdapter(def);\n  const messages = normalizeMessages(input.messages, def.instructions);\n  const toolIndex = buildStandaloneToolIndex(def);\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 === \"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      };\n      const res = await runAgent(entry.agentDef, subInput);\n      return res.text;\n    }\n    throw new Error(\n      `runAgent: tool \"${name}\" is a ${entry.kind} tool. ` +\n        \"Plugin toolkits and 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\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      entry: ToolkitEntry;\n    }\n  | {\n      kind: \"hosted\";\n      def: AgentToolDefinition;\n    };\n\nfunction buildStandaloneToolIndex(\n  def: AgentDefinition,\n): Map<string, StandaloneEntry> {\n  const index = new Map<string, StandaloneEntry>();\n\n  for (const [key, tool] of Object.entries(def.tools ?? {})) {\n    index.set(key, classifyTool(key, tool));\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\nfunction classifyTool(key: string, tool: AgentTool): StandaloneEntry {\n  if (isToolkitEntry(tool)) {\n    return { kind: \"toolkit\", def: { ...tool.def, name: key }, entry: tool };\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    return {\n      kind: \"hosted\",\n      def: {\n        name: key,\n        description: `Hosted tool: ${tool.type}`,\n        parameters: { type: \"object\", properties: {} },\n      },\n    };\n  }\n  throw new Error(`runAgent: unrecognized tool shape at key \"${key}\"`);\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 { 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,eAAsB,SACpB,KACA,OACyB;CAMzB,MAAM,gCAAgB,IAAI,KAA2B;AACrD,OAAM,sBAAsB,MAAM,WAAW,EAAE,EAAE,cAAc;AAC/D,QAAO,iBAAiB,KAAK,OAAO,cAAc;;AAGpD,eAAe,iBACb,KACA,OACA,eACyB;CACzB,MAAM,UAAU,MAAM,eAAe,IAAI;CACzC,MAAM,WAAW,kBAAkB,MAAM,UAAU,IAAI,aAAa;CACpE,MAAM,YAAY,yBAChB,KACA,MAAM,WAAW,EAAE,EACnB,cACD;CACD,MAAM,QAAQ,MAAM,KAAK,UAAU,QAAQ,CAAC,CAAC,KAAK,MAAM,EAAE,IAAI;CAE9D,MAAM,SAAS,MAAM;CAErB,MAAM,cAAc,OAAO,MAAc,SAAoC;EAC3E,MAAM,QAAQ,UAAU,IAAI,KAAK;AACjC,MAAI,CAAC,MAAO,OAAM,IAAI,MAAM,iBAAiB,OAAO;AACpD,MAAI,MAAM,SAAS,WACjB,QAAO,MAAM,KAAK,QAAQ,KAAgC;AAE5D,MAAI,MAAM,SAAS,UACjB,QAAO,MAAM,SAAS,iBACpB,MAAM,WACN,MACA,OACD;AAEH,MAAI,MAAM,SAAS,YAAY;GAC7B,MAAM,WAA0B;IAC9B,UACE,OAAO,SAAS,YAChB,SAAS,QACT,OAAQ,KAA6B,UAAU,WAC1C,KAA2B,QAC5B,KAAK,UAAU,KAAK;IAC1B;IACA,SAAS,MAAM;IAChB;AAQD,WALY,MAAM,iBAChB,MAAM,UACN,UACA,cACD,EACU;;AAEb,QAAM,IAAI,MACR,mBAAmB,KAAK,SAAS,MAAM,KAAK,yFAE7C;;CAGH,MAAM,SAAuB,EAAE;AAsB/B,QAAO;EAAE,MAPI,MAAM,qBAbJ,QAAQ,IACrB;GACE;GACA;GACA,UAAU,YAAY;GACtB;GACD,EACD;GAAE;GAAa;GAAQ,CACxB,EAK+C;GAC9C;GACA,UAAU,UAAU;AAClB,WAAO,KAAK,MAAM;;GAErB,CAAC;EAEa;EAAQ;;;;;;;;;;;;;;;AAgBzB,eAAe,sBACb,SACA,OACe;AACf,MAAK,MAAM,QAAQ,SAAS;AAC1B,MAAI,MAAM,IAAI,KAAK,KAAK,CAAE;EAC1B,MAAM,WAAW,IAAI,KAAK,OAAO;GAC/B,GAAI,KAAK,UAAU,EAAE;GACrB,MAAM,KAAK;GACZ,CAAC;AACF,MAAI,CAAC,yBAAyB,SAAS,CACrC,OAAM,IAAI,MACR,qBAAqB,KAAK,KAAK,mIAGhC;AAEH,MACE,OAAQ,SAAyC,kBACjD,WAEA,KAAI;AACF,GACE,SACA,cAAc,EAAE,CAAC;WACZ,KAAK;AACZ,SAAM,IAAI,MACR,qBAAqB,KAAK,KAAK,wNAInB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,IAC5D,EAAE,OAAO,eAAe,QAAQ,MAAM,QAAW,CAClD;;AAGL,MAAI,OAAQ,SAAiC,UAAU,WACrD,KAAI;AACF,SAAO,SAAmD,OAAO;WAC1D,KAAK;AACZ,SAAM,IAAI,MACR,qBAAqB,KAAK,KAAK,gNAInB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,IAC5D,EAAE,OAAO,eAAe,QAAQ,MAAM,QAAW,CAClD;;AAGL,QAAM,IAAI,KAAK,MAAM,SAAS;;;AAIlC,eAAe,eAAe,KAA6C;CACzE,MAAM,EAAE,UAAU;AAClB,KAAI,CAAC,OAAO;EACV,MAAM,EAAE,sBAAsB,MAAM,OAAO;AAC3C,SAAO,kBAAkB,kBAAkB;;AAE7C,KAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,EAAE,sBAAsB,MAAM,OAAO;AAC3C,SAAO,kBAAkB,iBAAiB,MAAM;;AAElD,QAAO,MAAM;;AAGf,SAAS,kBACP,OACA,cACW;CACX,MAAM,gBAAyB;EAC7B,IAAI;EACJ,MAAM;EACN,SAAS;EACT,2BAAW,IAAI,MAAM;EACtB;AACD,KAAI,OAAO,UAAU,SACnB,QAAO,CACL,eACA;EACE,IAAI,YAAY;EAChB,MAAM;EACN,SAAS;EACT,2BAAW,IAAI,MAAM;EACtB,CACF;AAEH,QAAO,CAAC,eAAe,GAAG,MAAM;;;;;;;;;AAiClC,SAAS,yBACP,KACA,SACA,eAC8B;CAC9B,MAAM,wBAAQ,IAAI,KAA8B;CAChD,MAAM,QAAQ,gBAAgB,KAAK,SAAS,cAAc;AAE1D,MAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,MAAM,CAC7C,OAAM,IAAI,KAAK,aAAa,KAAK,MAAM,cAAc,CAAC;AAGxD,MAAK,MAAM,CAAC,UAAU,UAAU,OAAO,QAAQ,IAAI,UAAU,EAAE,CAAC,EAAE;EAChE,MAAM,WAAW,SAAS;AAC1B,QAAM,IAAI,UAAU;GAClB,MAAM;GACN,UAAU;IAAE,GAAG;IAAO,MAAM,MAAM,QAAQ;IAAU;GACpD,KAAK;IACH,MAAM;IACN,aACE,MAAM,aAAa,MAAM,GAAG,IAAI,IAChC,mBAAmB,SAAS;IAC9B,YAAY;KACV,MAAM;KACN,YAAY,EACV,OAAO;MACL,MAAM;MACN,aAAa;MACd,EACF;KACD,UAAU,CAAC,QAAQ;KACpB;IACF;GACF,CAAC;;AAGJ,QAAO;;;;;;;;AAST,SAAS,gBACP,KACA,SACA,eACY;AACZ,KAAI,OAAO,IAAI,UAAU,WACvB,QAAO,IAAI,SAAS,EAAE;CAExB,MAAM,aAAa,0BAA0B,SAAS,cAAc;AACpE,KAAI;AACF,SAAO,IAAI,MAAM,WAAW;UACrB,KAAK;EACZ,MAAM,OAAO,IAAI,QAAQ;AACzB,QAAM,IAAI,MACR,oBAAoB,KAAK,mCACvB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,IAElD,EAAE,OAAO,eAAe,QAAQ,MAAM,QAAW,CAClD;;;;;;;;;;;AAYL,SAAS,0BACP,SACA,eACS;CACT,MAAM,MAA6C,EAAE;AACrD,MAAK,MAAM,QAAQ,SAAS;EAC1B,MAAM,WAAW,cAAc,IAAI,KAAK,KAAK;AAC7C,MAAI,CAAC,SAAU;AACf,MAAI,KAAK,QAAQ,EACf,UAAU,SAAS,2BAA2B,KAAK,MAAM,UAAU,KAAK,EACzE;;AAEH,QAAO,mBAAmB,KAAK,2BAA2B;;AAG5D,SAAS,aACP,KACA,MACA,eACiB;AACjB,KAAI,eAAe,KAAK,CAMtB,QAAO;EACL,MAAM;EACN,UAHe,oBAAoB,KAAK,YAAY,cAAc;EAIlE,YAAY,KAAK;EACjB,WAAW,KAAK;EAChB,KAAK;GAAE,GAAG,KAAK;GAAK,MAAM;GAAK;EAChC;AAEH,KAAI,eAAe,KAAK,CACtB,QAAO;EACL,MAAM;EACN;EACA,KAAK;GAAE,GAAG,yBAAyB,KAAK;GAAE,MAAM;GAAK;EACtD;AAEH,KAAI,aAAa,KAAK,CAMpB,OAAM,IAAI,MACR,mBAAmB,IAAI,4BAA4B,KAAK,KAAK,mHAC9D;AAEH,OAAM,IAAI,MAAM,6CAA6C,IAAI,GAAG;;AAGtE,SAAS,oBACP,YACA,OACc;CACd,MAAM,SAAS,MAAM,IAAI,WAAW;AACpC,KAAI,OAAQ,QAAO;CACnB,MAAM,YAAY,MAAM,KAAK,MAAM,MAAM,CAAC,CAAC,KAAK,KAAK,IAAI;AACzD,OAAM,IAAI,MACR,oCAAoC,WAAW,gMAGE,UAAU,GAC5D;;;;;;;;;;;AAYH,SAAS,yBAAyB,OAAuC;AACvE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,MAAM;AACZ,QACE,OAAO,IAAI,kBAAkB,cAC7B,OAAO,IAAI,qBAAqB"}

package/dist/core/agent/toolkit-options.js

@@ -0,0 +1,28 @@
+//#region src/core/agent/toolkit-options.ts
+/**
+* Filter / prefix / rename a tool's local name into its toolkit key, or
+* skip it entirely. Encapsulates the four-knob `ToolkitOptions` contract:
+*
+* - `only` — allowlist of local names; everything else is dropped.
+* - `except` — denylist of local names.
+* - `prefix` — string prepended to the local name; defaults to
+*   `${pluginName}.`. Pass `""` to drop the prefix entirely.
+* - `rename` — per-tool exact remapping; wins over `prefix`.
+*
+* Returns the final key, or `null` when the tool is filtered out.
+*
+* Single source of truth so {@link buildToolkitEntries} (registry path)
+* and {@link resolveToolkitFromProvider} (`getAgentTools()` fallback) stay
+* in lockstep — bug fixes here apply to both.
+*/
+function applyToolkitOptions(localName, pluginName, opts = {}) {
+	if (opts.only && !opts.only.includes(localName)) return null;
+	if (opts.except?.includes(localName)) return null;
+	const renamed = opts.rename?.[localName];
+	if (typeof renamed === "string" && renamed.length > 0) return renamed;
+	return `${opts.prefix ?? `${pluginName}.`}${localName}`;
+}
+
+//#endregion
+export { applyToolkitOptions };
+//# sourceMappingURL=toolkit-options.js.map

package/dist/core/agent/toolkit-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit-options.js","names":[],"sources":["../../../src/core/agent/toolkit-options.ts"],"sourcesContent":["import type { ToolkitOptions } from \"./types\";\n\n/**\n * Filter / prefix / rename a tool's local name into its toolkit key, or\n * skip it entirely. Encapsulates the four-knob `ToolkitOptions` contract:\n *\n * - `only` — allowlist of local names; everything else is dropped.\n * - `except` — denylist of local names.\n * - `prefix` — string prepended to the local name; defaults to\n *   `${pluginName}.`. Pass `\"\"` to drop the prefix entirely.\n * - `rename` — per-tool exact remapping; wins over `prefix`.\n *\n * Returns the final key, or `null` when the tool is filtered out.\n *\n * Single source of truth so {@link buildToolkitEntries} (registry path)\n * and {@link resolveToolkitFromProvider} (`getAgentTools()` fallback) stay\n * in lockstep — bug fixes here apply to both.\n */\nexport function applyToolkitOptions(\n  localName: string,\n  pluginName: string,\n  opts: ToolkitOptions = {},\n): string | null {\n  // `only`/`except` take precedence: filter first, then derive the key.\n  if (opts.only && !opts.only.includes(localName)) return null;\n  if (opts.except?.includes(localName)) return null;\n\n  // `rename` accepts string overrides; explicit `undefined` (e.g. from a\n  // ternary that didn't fire) and empty strings fall through to the prefix\n  // path so we never produce a tool keyed literally `\"undefined\"` or `\"\"`.\n  const renamed = opts.rename?.[localName];\n  if (typeof renamed === \"string\" && renamed.length > 0) return renamed;\n\n  const prefix = opts.prefix ?? `${pluginName}.`;\n  return `${prefix}${localName}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAkBA,SAAgB,oBACd,WACA,YACA,OAAuB,EAAE,EACV;AAEf,KAAI,KAAK,QAAQ,CAAC,KAAK,KAAK,SAAS,UAAU,CAAE,QAAO;AACxD,KAAI,KAAK,QAAQ,SAAS,UAAU,CAAE,QAAO;CAK7C,MAAM,UAAU,KAAK,SAAS;AAC9B,KAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,EAAG,QAAO;AAG9D,QAAO,GADQ,KAAK,UAAU,GAAG,WAAW,KACzB"}

package/dist/core/agent/toolkit-resolver.js

@@ -0,0 +1,44 @@
+import { applyToolkitOptions } from "./toolkit-options.js";
+
+//#region src/core/agent/toolkit-resolver.ts
+/**
+* Resolve a plugin's tools into a keyed record of {@link ToolkitEntry} markers
+* ready to be merged into an agent's tool index.
+*
+* Preferred path: call the plugin's own `.toolkit(opts)` method, which
+* typically delegates to `buildToolkitEntries` with full `ToolkitOptions`
+* support (prefix, only, except, rename).
+*
+* Fallback path: when the plugin doesn't expose `.toolkit()` (e.g. a
+* third-party `ToolProvider` built with plain `toPlugin`), walk
+* `getAgentTools()` and synthesize namespaced keys (`${pluginName}.${name}`)
+* while still honoring `only` / `except` / `rename` / `prefix`.
+*
+* This helper is the single source of truth for "turn a provider into a
+* toolkit entry record" and is used by `AgentsPlugin.buildToolIndex`
+* (the `tools(plugins)` resolution pass and auto-inherit) and by the
+* standalone `runAgent` executor.
+*/
+function resolveToolkitFromProvider(pluginName, provider, opts) {
+	const withToolkit = provider;
+	if (typeof withToolkit.toolkit === "function") return withToolkit.toolkit(opts);
+	const out = {};
+	for (const tool of provider.getAgentTools()) {
+		const key = applyToolkitOptions(tool.name, pluginName, opts);
+		if (key === null) continue;
+		out[key] = {
+			__toolkitRef: true,
+			pluginName,
+			localName: tool.name,
+			def: {
+				...tool,
+				name: key
+			}
+		};
+	}
+	return out;
+}
+
+//#endregion
+export { resolveToolkitFromProvider };
+//# sourceMappingURL=toolkit-resolver.js.map

package/dist/core/agent/toolkit-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit-resolver.js","names":[],"sources":["../../../src/core/agent/toolkit-resolver.ts"],"sourcesContent":["import type { ToolProvider } from \"shared\";\nimport { applyToolkitOptions } from \"./toolkit-options\";\nimport type { ToolkitEntry, ToolkitOptions } from \"./types\";\n\n/**\n * Internal interface: a `ToolProvider` that optionally exposes a typed\n * `.toolkit(opts)` method. Core plugins (analytics, files, genie, lakebase)\n * implement this; third-party `ToolProvider`s may not.\n */\ntype MaybeToolkitProvider = ToolProvider & {\n  toolkit?: (opts?: ToolkitOptions) => Record<string, ToolkitEntry>;\n};\n\n/**\n * Resolve a plugin's tools into a keyed record of {@link ToolkitEntry} markers\n * ready to be merged into an agent's tool index.\n *\n * Preferred path: call the plugin's own `.toolkit(opts)` method, which\n * typically delegates to `buildToolkitEntries` with full `ToolkitOptions`\n * support (prefix, only, except, rename).\n *\n * Fallback path: when the plugin doesn't expose `.toolkit()` (e.g. a\n * third-party `ToolProvider` built with plain `toPlugin`), walk\n * `getAgentTools()` and synthesize namespaced keys (`${pluginName}.${name}`)\n * while still honoring `only` / `except` / `rename` / `prefix`.\n *\n * This helper is the single source of truth for \"turn a provider into a\n * toolkit entry record\" and is used by `AgentsPlugin.buildToolIndex`\n * (the `tools(plugins)` resolution pass and auto-inherit) and by the\n * standalone `runAgent` executor.\n */\nexport function resolveToolkitFromProvider(\n  pluginName: string,\n  provider: ToolProvider,\n  opts?: ToolkitOptions,\n): Record<string, ToolkitEntry> {\n  const withToolkit = provider as MaybeToolkitProvider;\n  if (typeof withToolkit.toolkit === \"function\") {\n    return withToolkit.toolkit(opts);\n  }\n\n  const out: Record<string, ToolkitEntry> = {};\n  for (const tool of provider.getAgentTools()) {\n    const key = applyToolkitOptions(tool.name, pluginName, opts);\n    if (key === null) continue;\n\n    out[key] = {\n      __toolkitRef: true,\n      pluginName,\n      localName: tool.name,\n      def: { ...tool, name: key },\n    };\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,2BACd,YACA,UACA,MAC8B;CAC9B,MAAM,cAAc;AACpB,KAAI,OAAO,YAAY,YAAY,WACjC,QAAO,YAAY,QAAQ,KAAK;CAGlC,MAAM,MAAoC,EAAE;AAC5C,MAAK,MAAM,QAAQ,SAAS,eAAe,EAAE;EAC3C,MAAM,MAAM,oBAAoB,KAAK,MAAM,YAAY,KAAK;AAC5D,MAAI,QAAQ,KAAM;AAElB,MAAI,OAAO;GACT,cAAc;GACd;GACA,WAAW,KAAK;GAChB,KAAK;IAAE,GAAG;IAAM,MAAM;IAAK;GAC5B;;AAEH,QAAO"}

package/dist/core/agent/tools/define-tool.d.ts

@@ -20,10 +20,22 @@ interface ToolEntry<S extends z.ZodType = z.ZodType> {
    * consider it safe enough to appear in every agent's tool record without an
    * explicit `tools:` declaration. Destructive or privilege-sensitive tools
    * should leave this unset so that they only reach agents that wire them
-   * explicitly (via `tools:`, `toolkits:`, or `fromPlugin({ only: [...] })`).
+   * explicitly (via `tools:` object/function form, markdown `plugin:NAME`
+   * entries in the unified `tools:` list, or
+   * `plugins.<name>.toolkit({ only: [...] })`).
    */
   autoInheritable?: boolean;
-  handler: (args: z.infer<S>, signal?: AbortSignal) => unknown | Promise<unknown>;
+  /**
+   * Callback the agents plugin invokes after Zod validation succeeds.
+   *
+   * Named `execute` to match the public `tool({ execute })` form — both the
+   * agent-author surface and the plugin-author surface now spell their
+   * callback the same way. `args` is the inferred Zod output (so `T extends
+   * z.ZodType` flows through and `args` is fully typed). `signal` is the
+   * per-run AbortSignal: forward it to any awaited I/O so cancellation
+   * actually unwinds the call (analytics and lakebase both do this).
+   */
+  execute: (args: z.infer<S>, signal?: AbortSignal) => unknown | Promise<unknown>;
 }
 type ToolRegistry = Record<string, ToolEntry>;
 /**

package/dist/core/agent/tools/define-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/define-tool.ts"],"mappings":";;;;;;;;AAWA;;;UAAiB,SAAA,WAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA;EACjD,WAAA;EACA,MAAA,EAAQ,CAAA;EACR,WAAA,GAAc,eAAA;EAYE;;;;;;;;;EAFhB,eAAA;EACA,OAAA,GACE,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,GACd,MAAA,GAAS,WAAA,eACI,OAAA;AAAA;AAAA,KAGL,YAAA,GAAe,MAAA,SAAe,SAAA;;;;;;;;iBAS1B,UAAA,WAAqB,CAAA,CAAE,OAAA,CAAA,CACrC,MAAA,EAAQ,SAAA,CAAU,CAAA,IACjB,SAAA,CAAU,CAAA;;;;;;;iBAUS,mBAAA,CACpB,QAAA,EAAU,YAAA,EACV,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;;;;;AAjBH;;;iBAoCgB,iBAAA,CACd,QAAA,EAAU,YAAA,GACT,mBAAA"}
+{"version":3,"file":"define-tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/define-tool.ts"],"mappings":";;;;;;;;AAWA;;;UAAiB,SAAA,WAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA;EACjD,WAAA;EACA,MAAA,EAAQ,CAAA;EACR,WAAA,GAAc,eAAA;EAwBE;;;;;;;;;;;EAZhB,eAAA;EAbA;;;;;;;;;;EAwBA,OAAA,GACE,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,GACd,MAAA,GAAS,WAAA,eACI,OAAA;AAAA;AAAA,KAGL,YAAA,GAAe,MAAA,SAAe,SAAA;;;AAA1C;;;;;iBASgB,UAAA,WAAqB,CAAA,CAAE,OAAA,CAAA,CACrC,MAAA,EAAQ,SAAA,CAAU,CAAA,IACjB,SAAA,CAAU,CAAA;;;;;;;iBAUS,mBAAA,CACpB,QAAA,EAAU,YAAA,EACV,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;;;;;;;;iBAmBa,iBAAA,CACd,QAAA,EAAU,YAAA,GACT,mBAAA"}

package/dist/core/agent/tools/define-tool.js

@@ -23,7 +23,7 @@ async function executeFromRegistry(registry, name, args, signal) {
 	if (!entry) throw new Error(`Unknown tool: ${name}`);
 	const parsed = entry.schema.safeParse(args);
 	if (!parsed.success) return formatZodError(parsed.error, name);
-	return entry.handler(parsed.data, signal);
+	return entry.execute(parsed.data, signal);
 }
 /**
 * Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM,

package/dist/core/agent/tools/define-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-tool.js","names":[],"sources":["../../../../src/core/agent/tools/define-tool.ts"],"sourcesContent":["import type { AgentToolDefinition, ToolAnnotations } from \"shared\";\nimport type { z } from \"zod\";\nimport { toToolJSONSchema } from \"./json-schema\";\nimport { formatZodError } from \"./tool\";\n\n/**\n * Single-tool entry for a plugin's internal tool registry.\n *\n * Plugins collect these into a `Record<string, ToolEntry>` keyed by the tool's\n * public name and dispatch via `executeFromRegistry`.\n */\nexport interface ToolEntry<S extends z.ZodType = z.ZodType> {\n  description: string;\n  schema: S;\n  annotations?: ToolAnnotations;\n  /**\n   * Whether this tool is eligible for auto-inheritance into markdown or\n   * code-defined agents that enable `autoInheritTools`. Defaults to `false`\n   * (safe-by-default) — plugin authors must explicitly opt a tool in if they\n   * consider it safe enough to appear in every agent's tool record without an\n   * explicit `tools:` declaration. Destructive or privilege-sensitive tools\n   * should leave this unset so that they only reach agents that wire them\n   * explicitly (via `tools:`, `toolkits:`, or `fromPlugin({ only: [...] })`).\n   */\n  autoInheritable?: boolean;\n  handler: (\n    args: z.infer<S>,\n    signal?: AbortSignal,\n  ) => unknown | Promise<unknown>;\n}\n\nexport type ToolRegistry = Record<string, ToolEntry>;\n\n/**\n * Defines a single tool entry for a plugin's internal registry.\n *\n * The generic `S` flows from `schema` through to the `handler` callback so\n * `args` is fully typed from the Zod schema. Names are assigned by the\n * registry key, so they are not repeated inside the entry.\n */\nexport function defineTool<S extends z.ZodType>(\n  config: ToolEntry<S>,\n): ToolEntry<S> {\n  return config;\n}\n\n/**\n * Validates tool-call arguments against the entry's schema and invokes its\n * handler. On validation failure, returns an LLM-friendly error string\n * (matching the behavior of `tool()`) rather than throwing, so the model\n * can self-correct on its next turn.\n */\nexport async function executeFromRegistry(\n  registry: ToolRegistry,\n  name: string,\n  args: unknown,\n  signal?: AbortSignal,\n): Promise<unknown> {\n  const entry = registry[name];\n  if (!entry) {\n    throw new Error(`Unknown tool: ${name}`);\n  }\n  const parsed = entry.schema.safeParse(args);\n  if (!parsed.success) {\n    return formatZodError(parsed.error, name);\n  }\n  return entry.handler(parsed.data, signal);\n}\n\n/**\n * Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM,\n * deriving `parameters` JSON Schema from each entry's Zod schema.\n *\n * Tool names come from registry keys (supports dotted names like\n * `uploads.list` for dynamic plugins).\n */\nexport function toolsFromRegistry(\n  registry: ToolRegistry,\n): AgentToolDefinition[] {\n  return Object.entries(registry).map(([name, entry]) => {\n    const parameters = toToolJSONSchema(\n      entry.schema,\n    ) as unknown as AgentToolDefinition[\"parameters\"];\n    const def: AgentToolDefinition = {\n      name,\n      description: entry.description,\n      parameters,\n    };\n    if (entry.annotations) {\n      def.annotations = entry.annotations;\n    }\n    return def;\n  });\n}\n"],"mappings":";;;;;;;;;;;AAwCA,SAAgB,WACd,QACc;AACd,QAAO;;;;;;;;AAST,eAAsB,oBACpB,UACA,MACA,MACA,QACkB;CAClB,MAAM,QAAQ,SAAS;AACvB,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,iBAAiB,OAAO;CAE1C,MAAM,SAAS,MAAM,OAAO,UAAU,KAAK;AAC3C,KAAI,CAAC,OAAO,QACV,QAAO,eAAe,OAAO,OAAO,KAAK;AAE3C,QAAO,MAAM,QAAQ,OAAO,MAAM,OAAO;;;;;;;;;AAU3C,SAAgB,kBACd,UACuB;AACvB,QAAO,OAAO,QAAQ,SAAS,CAAC,KAAK,CAAC,MAAM,WAAW;EACrD,MAAM,aAAa,iBACjB,MAAM,OACP;EACD,MAAM,MAA2B;GAC/B;GACA,aAAa,MAAM;GACnB;GACD;AACD,MAAI,MAAM,YACR,KAAI,cAAc,MAAM;AAE1B,SAAO;GACP"}
+{"version":3,"file":"define-tool.js","names":[],"sources":["../../../../src/core/agent/tools/define-tool.ts"],"sourcesContent":["import type { AgentToolDefinition, ToolAnnotations } from \"shared\";\nimport type { z } from \"zod\";\nimport { toToolJSONSchema } from \"./json-schema\";\nimport { formatZodError } from \"./tool\";\n\n/**\n * Single-tool entry for a plugin's internal tool registry.\n *\n * Plugins collect these into a `Record<string, ToolEntry>` keyed by the tool's\n * public name and dispatch via `executeFromRegistry`.\n */\nexport interface ToolEntry<S extends z.ZodType = z.ZodType> {\n  description: string;\n  schema: S;\n  annotations?: ToolAnnotations;\n  /**\n   * Whether this tool is eligible for auto-inheritance into markdown or\n   * code-defined agents that enable `autoInheritTools`. Defaults to `false`\n   * (safe-by-default) — plugin authors must explicitly opt a tool in if they\n   * consider it safe enough to appear in every agent's tool record without an\n   * explicit `tools:` declaration. Destructive or privilege-sensitive tools\n   * should leave this unset so that they only reach agents that wire them\n   * explicitly (via `tools:` object/function form, markdown `plugin:NAME`\n   * entries in the unified `tools:` list, or\n   * `plugins.<name>.toolkit({ only: [...] })`).\n   */\n  autoInheritable?: boolean;\n  /**\n   * Callback the agents plugin invokes after Zod validation succeeds.\n   *\n   * Named `execute` to match the public `tool({ execute })` form — both the\n   * agent-author surface and the plugin-author surface now spell their\n   * callback the same way. `args` is the inferred Zod output (so `T extends\n   * z.ZodType` flows through and `args` is fully typed). `signal` is the\n   * per-run AbortSignal: forward it to any awaited I/O so cancellation\n   * actually unwinds the call (analytics and lakebase both do this).\n   */\n  execute: (\n    args: z.infer<S>,\n    signal?: AbortSignal,\n  ) => unknown | Promise<unknown>;\n}\n\nexport type ToolRegistry = Record<string, ToolEntry>;\n\n/**\n * Defines a single tool entry for a plugin's internal registry.\n *\n * The generic `S` flows from `schema` through to the `handler` callback so\n * `args` is fully typed from the Zod schema. Names are assigned by the\n * registry key, so they are not repeated inside the entry.\n */\nexport function defineTool<S extends z.ZodType>(\n  config: ToolEntry<S>,\n): ToolEntry<S> {\n  return config;\n}\n\n/**\n * Validates tool-call arguments against the entry's schema and invokes its\n * handler. On validation failure, returns an LLM-friendly error string\n * (matching the behavior of `tool()`) rather than throwing, so the model\n * can self-correct on its next turn.\n */\nexport async function executeFromRegistry(\n  registry: ToolRegistry,\n  name: string,\n  args: unknown,\n  signal?: AbortSignal,\n): Promise<unknown> {\n  const entry = registry[name];\n  if (!entry) {\n    throw new Error(`Unknown tool: ${name}`);\n  }\n  const parsed = entry.schema.safeParse(args);\n  if (!parsed.success) {\n    return formatZodError(parsed.error, name);\n  }\n  return entry.execute(parsed.data, signal);\n}\n\n/**\n * Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM,\n * deriving `parameters` JSON Schema from each entry's Zod schema.\n *\n * Tool names come from registry keys (supports dotted names like\n * `uploads.list` for dynamic plugins).\n */\nexport function toolsFromRegistry(\n  registry: ToolRegistry,\n): AgentToolDefinition[] {\n  return Object.entries(registry).map(([name, entry]) => {\n    const parameters = toToolJSONSchema(\n      entry.schema,\n    ) as unknown as AgentToolDefinition[\"parameters\"];\n    const def: AgentToolDefinition = {\n      name,\n      description: entry.description,\n      parameters,\n    };\n    if (entry.annotations) {\n      def.annotations = entry.annotations;\n    }\n    return def;\n  });\n}\n"],"mappings":";;;;;;;;;;;AAoDA,SAAgB,WACd,QACc;AACd,QAAO;;;;;;;;AAST,eAAsB,oBACpB,UACA,MACA,MACA,QACkB;CAClB,MAAM,QAAQ,SAAS;AACvB,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,iBAAiB,OAAO;CAE1C,MAAM,SAAS,MAAM,OAAO,UAAU,KAAK;AAC3C,KAAI,CAAC,OAAO,QACV,QAAO,eAAe,OAAO,OAAO,KAAK;AAE3C,QAAO,MAAM,QAAQ,OAAO,MAAM,OAAO;;;;;;;;;AAU3C,SAAgB,kBACd,UACuB;AACvB,QAAO,OAAO,QAAQ,SAAS,CAAC,KAAK,CAAC,MAAM,WAAW;EACrD,MAAM,aAAa,iBACjB,MAAM,OACP;EACD,MAAM,MAA2B;GAC/B;GACA,aAAa,MAAM;GACnB;GACD;AACD,MAAI,MAAM,YACR,KAAI,cAAc,MAAM;AAE1B,SAAO;GACP"}

package/dist/core/agent/tools/function-tool.d.ts

@@ -4,7 +4,14 @@ import "../../../shared/src/index.js";
 //#region src/core/agent/tools/function-tool.d.ts
 interface FunctionTool {
   type: "function";
-  name: string;
+  /**
+   * Optional. When this tool is placed in a keyed record
+   * (`tools: { my_tool: ... }` or the function form), the agents plugin
+   * overrides this with the record key at index-build time. Only set it
+   * explicitly when constructing a `FunctionTool` outside any
+   * keyed-record context.
+   */
+  name?: string;
   description?: string | null;
   parameters?: Record<string, unknown> | null;
   strict?: boolean | null;
@@ -18,7 +25,11 @@ interface FunctionTool {
    * tool indexes.
    */
   annotations?: ToolAnnotations;
-  execute: (args: Record<string, unknown>) => Promise<string> | string;
+  /**
+   * Returns any shape; downstream `normalizeToolResult` serializes to a
+   * string before handing the value to the LLM.
+   */
+  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>;
 }
 declare function isFunctionTool(value: unknown): value is FunctionTool;
 declare function functionToolToDefinition(tool: FunctionTool): AgentToolDefinition;

package/dist/core/agent/tools/function-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"function-tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/function-tool.ts"],"mappings":";;;;UAEiB,YAAA;EACf,IAAA;EACA,IAAA;EACA,WAAA;EACA,UAAA,GAAa,MAAA;EACb,MAAA;EADa;;;;;;;;;EAWb,WAAA,GAAc,eAAA;EACd,OAAA,GAAU,IAAA,EAAM,MAAA,sBAA4B,OAAA;AAAA;AAAA,iBAG9B,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA;AAAA,iBAUzC,wBAAA,CACd,IAAA,EAAM,YAAA,GACL,mBAAA"}
+{"version":3,"file":"function-tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/function-tool.ts"],"mappings":";;;;UAEiB,YAAA;EACf,IAAA;;AADF;;;;;;EASE,IAAA;EACA,WAAA;EACA,UAAA,GAAa,MAAA;EACb,MAAA;EAHA;;;;;;;;;EAaA,WAAA,GAAc,eAAA;EAKwC;;;AAGxD;EAHE,OAAA,GAAU,IAAA,EAAM,MAAA,gCAAsC,OAAA;AAAA;AAAA,iBAGxC,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA;AAAA,iBAUzC,wBAAA,CACd,IAAA,EAAM,YAAA,GACL,mBAAA"}

package/dist/core/agent/tools/function-tool.js

@@ -2,12 +2,13 @@
 function isFunctionTool(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const obj = value;
-	return obj.type === "function" && typeof obj.name === "string" && typeof obj.execute === "function";
+	return obj.type === "function" && typeof obj.execute === "function";
 }
 function functionToolToDefinition(tool) {
+	const name = tool.name ?? "";
 	return {
-		name: tool.name,
-		description: tool.description ?? tool.name,
+		name,
+		description: tool.description ?? name,
 		parameters: tool.parameters ?? {
 			type: "object",
 			properties: {}