@databricks/appkit 0.32.0 → 0.33.0

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

@@ -1 +1 @@
-{"version":3,"file":"function-tool.js","names":[],"sources":["../../../../src/core/agent/tools/function-tool.ts"],"sourcesContent":["import type { AgentToolDefinition, ToolAnnotations } from \"shared\";\n\nexport interface FunctionTool {\n  type: \"function\";\n  name: string;\n  description?: string | null;\n  parameters?: Record<string, unknown> | null;\n  strict?: boolean | null;\n  /**\n   * Behavioural hints that drive the agents plugin's approval gate and the\n   * client's approval-card styling. Prefer setting `effect` (one of\n   * `\"read\" | \"write\" | \"update\" | \"destructive\"`) — any mutating value\n   * forces HITL approval before `execute()` runs. Legacy `destructive: true`\n   * is still honoured. Must be preserved through {@link\n   * functionToolToDefinition} so the plugin sees them when building agent\n   * tool indexes.\n   */\n  annotations?: ToolAnnotations;\n  execute: (args: Record<string, unknown>) => Promise<string> | string;\n}\n\nexport function isFunctionTool(value: unknown): value is FunctionTool {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    obj.type === \"function\" &&\n    typeof obj.name === \"string\" &&\n    typeof obj.execute === \"function\"\n  );\n}\n\nexport function functionToolToDefinition(\n  tool: FunctionTool,\n): AgentToolDefinition {\n  return {\n    name: tool.name,\n    description: tool.description ?? tool.name,\n    parameters: (tool.parameters as AgentToolDefinition[\"parameters\"]) ?? {\n      type: \"object\",\n      properties: {},\n    },\n    ...(tool.annotations ? { annotations: tool.annotations } : {}),\n  };\n}\n"],"mappings":";AAqBA,SAAgB,eAAe,OAAuC;AACpE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,MAAM;AACZ,QACE,IAAI,SAAS,cACb,OAAO,IAAI,SAAS,YACpB,OAAO,IAAI,YAAY;;AAI3B,SAAgB,yBACd,MACqB;AACrB,QAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK,eAAe,KAAK;EACtC,YAAa,KAAK,cAAoD;GACpE,MAAM;GACN,YAAY,EAAE;GACf;EACD,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,aAAa,GAAG,EAAE;EAC9D"}
+{"version":3,"file":"function-tool.js","names":[],"sources":["../../../../src/core/agent/tools/function-tool.ts"],"sourcesContent":["import type { AgentToolDefinition, ToolAnnotations } from \"shared\";\n\nexport interface FunctionTool {\n  type: \"function\";\n  /**\n   * Optional. When this tool is placed in a keyed record\n   * (`tools: { my_tool: ... }` or the function form), the agents plugin\n   * overrides this with the record key at index-build time. Only set it\n   * explicitly when constructing a `FunctionTool` outside any\n   * keyed-record context.\n   */\n  name?: string;\n  description?: string | null;\n  parameters?: Record<string, unknown> | null;\n  strict?: boolean | null;\n  /**\n   * Behavioural hints that drive the agents plugin's approval gate and the\n   * client's approval-card styling. Prefer setting `effect` (one of\n   * `\"read\" | \"write\" | \"update\" | \"destructive\"`) — any mutating value\n   * forces HITL approval before `execute()` runs. Legacy `destructive: true`\n   * is still honoured. Must be preserved through {@link\n   * functionToolToDefinition} so the plugin sees them when building agent\n   * tool indexes.\n   */\n  annotations?: ToolAnnotations;\n  /**\n   * Returns any shape; downstream `normalizeToolResult` serializes to a\n   * string before handing the value to the LLM.\n   */\n  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>;\n}\n\nexport function isFunctionTool(value: unknown): value is FunctionTool {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  // `name` is intentionally not required: the agents plugin overrides it\n  // with the record key (`tools: { my_tool: tool({...}) }` -> \"my_tool\")\n  // so requiring it on the FunctionTool shape rejects perfectly-valid\n  // `tool({ description, schema, execute })` calls that omit the name.\n  return obj.type === \"function\" && typeof obj.execute === \"function\";\n}\n\nexport function functionToolToDefinition(\n  tool: FunctionTool,\n): AgentToolDefinition {\n  // `name` is guaranteed to be overridden downstream by the record key\n  // when the tool is registered through `AgentDefinition.tools`. Falling\n  // back to an empty string here keeps the type honest without\n  // surfacing a sentinel that could leak into a non-record context.\n  const name = tool.name ?? \"\";\n  return {\n    name,\n    description: tool.description ?? name,\n    parameters: (tool.parameters as AgentToolDefinition[\"parameters\"]) ?? {\n      type: \"object\",\n      properties: {},\n    },\n    ...(tool.annotations ? { annotations: tool.annotations } : {}),\n  };\n}\n"],"mappings":";AAgCA,SAAgB,eAAe,OAAuC;AACpE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,MAAM;AAKZ,QAAO,IAAI,SAAS,cAAc,OAAO,IAAI,YAAY;;AAG3D,SAAgB,yBACd,MACqB;CAKrB,MAAM,OAAO,KAAK,QAAQ;AAC1B,QAAO;EACL;EACA,aAAa,KAAK,eAAe;EACjC,YAAa,KAAK,cAAoD;GACpE,MAAM;GACN,YAAY,EAAE;GACf;EACD,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,aAAa,GAAG,EAAE;EAC9D"}

package/dist/core/agent/tools/index.d.ts

@@ -1,4 +1,4 @@
-import { AppKitMcpClient } from "../../../connectors/mcp/client.js";
+import { AppKitMcpClient, McpConnectAllResult } from "../../../connectors/mcp/client.js";
 import { FunctionTool, functionToolToDefinition, isFunctionTool } from "./function-tool.js";
 import { HostedTool, isHostedTool, mcpServer, resolveHostedTools } from "./hosted-tools.js";
 import { ToolEntry, ToolRegistry, defineTool, executeFromRegistry, toolsFromRegistry } from "./define-tool.js";

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

@@ -5,8 +5,29 @@ import { z } from "zod";
 
 //#region src/core/agent/tools/tool.d.ts
 interface ToolConfig<S extends z.ZodType> {
-  name: string;
-  description?: string;
+  /**
+   * Optional. When the tool is placed in a keyed record (the standard
+   * `tools: { my_tool: tool({...}) }` form, or the function form
+   * `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin
+   * overrides the tool's LLM-visible name with the record key. Set
+   * `name` explicitly only if you're constructing a `FunctionTool`
+   * outside any keyed-record context — otherwise the record key wins.
+   */
+  name?: string;
+  /**
+   * What the tool does, what it expects, and when the LLM should call it.
+   * The model reads this verbatim when deciding whether to invoke the tool,
+   * so write it for an LLM, not for a human reader of your code: spell out
+   * the inputs, the return shape, and any pre-conditions or side effects.
+   *
+   * Required. Earlier versions silently fell back to the tool's name when
+   * omitted, which surfaced cryptic identifiers like `"get_weather"` as the
+   * description — the model then had no signal about expected use and
+   * either skipped the tool or called it speculatively. Making this
+   * mandatory at the type level forces a real description at authoring
+   * time instead of debugging a confused agent later.
+   */
+  description: string;
   schema: S;
   /**
    * Behavioural hints forwarded to the resolved tool definition. Prefer
@@ -17,7 +38,15 @@ interface ToolConfig<S extends z.ZodType> {
    * added this field.
    */
   annotations?: ToolAnnotations;
-  execute: (args: z.infer<S>) => Promise<string> | string;
+  /**
+   * Returning a non-string value is fine: the agent runtime serializes
+   * the result via `normalizeToolResult` before handing it to the LLM
+   * (strings pass through; `null` becomes `"null"`; everything else gets
+   * `JSON.stringify`'d; `undefined` becomes `""`). Return whatever shape
+   * is most natural for your tool — typically an object — and let the
+   * runtime handle the wire format.
+   */
+  execute: (args: z.infer<S>) => unknown | Promise<unknown>;
 }
 /**
  * Factory for defining function tools with Zod schemas.

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

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"mappings":";;;;;;UAKiB,UAAA,WAAqB,CAAA,CAAE,OAAA;EACtC,IAAA;EACA,WAAA;EACA,MAAA,EAAQ,CAAA;EAHiB;;;;;;;;EAYzB,WAAA,GAAc,eAAA;EACd,OAAA,GAAU,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,MAAO,OAAA;AAAA;;;;;;;;;;iBAYjB,IAAA,WAAe,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,UAAA,CAAW,CAAA,IAAK,YAAA"}
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"mappings":";;;;;;UAKiB,UAAA,WAAqB,CAAA,CAAE,OAAA;;;AAAxC;;;;;;EASE,IAAA;EAiCkB;;;;;;;;;;;;;EAnBlB,WAAA;EACA,MAAA,EAAQ,CAAA;EAkBU;;;;;;AAYpB;;EArBE,WAAA,GAAc,eAAA;EAqBiB;;;;;;;;EAZ/B,OAAA,GAAU,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,gBAAiB,OAAA;AAAA;;;;;;;;;;iBAY3B,IAAA,WAAe,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,UAAA,CAAW,CAAA,IAAK,YAAA"}

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

@@ -12,15 +12,16 @@ import { toToolJSONSchema } from "./json-schema.js";
 */
 function tool(config) {
 	const parameters = toToolJSONSchema(config.schema);
+	const labelForErrors = config.name ?? "tool";
 	return {
 		type: "function",
-		name: config.name,
-		description: config.description ?? config.name,
+		...config.name !== void 0 ? { name: config.name } : {},
+		description: config.description,
 		parameters,
 		...config.annotations ? { annotations: config.annotations } : {},
 		execute: async (args) => {
 			const parsed = config.schema.safeParse(args);
-			if (!parsed.success) return formatZodError(parsed.error, config.name);
+			if (!parsed.success) return formatZodError(parsed.error, labelForErrors);
 			return config.execute(parsed.data);
 		}
 	};

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

@@ -1 +1 @@
-{"version":3,"file":"tool.js","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"sourcesContent":["import type { ToolAnnotations } from \"shared\";\nimport type { z } from \"zod\";\nimport type { FunctionTool } from \"./function-tool\";\nimport { toToolJSONSchema } from \"./json-schema\";\n\nexport interface ToolConfig<S extends z.ZodType> {\n  name: string;\n  description?: string;\n  schema: S;\n  /**\n   * Behavioural hints forwarded to the resolved tool definition. Prefer\n   * `effect` (`\"read\" | \"write\" | \"update\" | \"destructive\"`) — any mutating\n   * value forces the agents-plugin approval gate before `execute()` runs\n   * and the client's approval card will colour itself accordingly. Legacy\n   * `destructive: true` still gates. Dropped silently before the fix that\n   * added this field.\n   */\n  annotations?: ToolAnnotations;\n  execute: (args: z.infer<S>) => Promise<string> | string;\n}\n\n/**\n * Factory for defining function tools with Zod schemas.\n *\n * - Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.\n * - Infers the `execute` argument type from the schema.\n * - Validates tool call arguments at runtime. On validation failure, returns\n *   a formatted error string to the LLM instead of throwing, so the model\n *   can self-correct on its next turn.\n */\nexport function tool<S extends z.ZodType>(config: ToolConfig<S>): FunctionTool {\n  const parameters = toToolJSONSchema(config.schema) as unknown as Record<\n    string,\n    unknown\n  >;\n\n  return {\n    type: \"function\",\n    name: config.name,\n    description: config.description ?? config.name,\n    parameters,\n    ...(config.annotations ? { annotations: config.annotations } : {}),\n    execute: async (args: Record<string, unknown>) => {\n      const parsed = config.schema.safeParse(args);\n      if (!parsed.success) {\n        return formatZodError(parsed.error, config.name);\n      }\n      return config.execute(parsed.data as z.infer<S>);\n    },\n  };\n}\n\n/**\n * Formats a Zod validation error into an LLM-friendly string.\n *\n * Example: `Invalid arguments for get_weather: city: Invalid input: expected string, received undefined`\n */\nexport function formatZodError(error: z.ZodError, toolName: string): string {\n  const parts = error.issues.map((issue) => {\n    const field = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    return `${field}: ${issue.message}`;\n  });\n  return `Invalid arguments for ${toolName}: ${parts.join(\"; \")}`;\n}\n"],"mappings":";;;;;;;;;;;;AA8BA,SAAgB,KAA0B,QAAqC;CAC7E,MAAM,aAAa,iBAAiB,OAAO,OAAO;AAKlD,QAAO;EACL,MAAM;EACN,MAAM,OAAO;EACb,aAAa,OAAO,eAAe,OAAO;EAC1C;EACA,GAAI,OAAO,cAAc,EAAE,aAAa,OAAO,aAAa,GAAG,EAAE;EACjE,SAAS,OAAO,SAAkC;GAChD,MAAM,SAAS,OAAO,OAAO,UAAU,KAAK;AAC5C,OAAI,CAAC,OAAO,QACV,QAAO,eAAe,OAAO,OAAO,OAAO,KAAK;AAElD,UAAO,OAAO,QAAQ,OAAO,KAAmB;;EAEnD;;;;;;;AAQH,SAAgB,eAAe,OAAmB,UAA0B;AAK1E,QAAO,yBAAyB,SAAS,IAJ3B,MAAM,OAAO,KAAK,UAAU;AAExC,SAAO,GADO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,SAC7C,IAAI,MAAM;GAC1B,CACiD,KAAK,KAAK"}
+{"version":3,"file":"tool.js","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"sourcesContent":["import type { ToolAnnotations } from \"shared\";\nimport type { z } from \"zod\";\nimport type { FunctionTool } from \"./function-tool\";\nimport { toToolJSONSchema } from \"./json-schema\";\n\nexport interface ToolConfig<S extends z.ZodType> {\n  /**\n   * Optional. When the tool is placed in a keyed record (the standard\n   * `tools: { my_tool: tool({...}) }` form, or the function form\n   * `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin\n   * overrides the tool's LLM-visible name with the record key. Set\n   * `name` explicitly only if you're constructing a `FunctionTool`\n   * outside any keyed-record context — otherwise the record key wins.\n   */\n  name?: string;\n  /**\n   * What the tool does, what it expects, and when the LLM should call it.\n   * The model reads this verbatim when deciding whether to invoke the tool,\n   * so write it for an LLM, not for a human reader of your code: spell out\n   * the inputs, the return shape, and any pre-conditions or side effects.\n   *\n   * Required. Earlier versions silently fell back to the tool's name when\n   * omitted, which surfaced cryptic identifiers like `\"get_weather\"` as the\n   * description — the model then had no signal about expected use and\n   * either skipped the tool or called it speculatively. Making this\n   * mandatory at the type level forces a real description at authoring\n   * time instead of debugging a confused agent later.\n   */\n  description: string;\n  schema: S;\n  /**\n   * Behavioural hints forwarded to the resolved tool definition. Prefer\n   * `effect` (`\"read\" | \"write\" | \"update\" | \"destructive\"`) — any mutating\n   * value forces the agents-plugin approval gate before `execute()` runs\n   * and the client's approval card will colour itself accordingly. Legacy\n   * `destructive: true` still gates. Dropped silently before the fix that\n   * added this field.\n   */\n  annotations?: ToolAnnotations;\n  /**\n   * Returning a non-string value is fine: the agent runtime serializes\n   * the result via `normalizeToolResult` before handing it to the LLM\n   * (strings pass through; `null` becomes `\"null\"`; everything else gets\n   * `JSON.stringify`'d; `undefined` becomes `\"\"`). Return whatever shape\n   * is most natural for your tool — typically an object — and let the\n   * runtime handle the wire format.\n   */\n  execute: (args: z.infer<S>) => unknown | Promise<unknown>;\n}\n\n/**\n * Factory for defining function tools with Zod schemas.\n *\n * - Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.\n * - Infers the `execute` argument type from the schema.\n * - Validates tool call arguments at runtime. On validation failure, returns\n *   a formatted error string to the LLM instead of throwing, so the model\n *   can self-correct on its next turn.\n */\nexport function tool<S extends z.ZodType>(config: ToolConfig<S>): FunctionTool {\n  const parameters = toToolJSONSchema(config.schema);\n\n  // `name` is only used for the zod-validation error message and the\n  // FunctionTool's `name` field; the agents plugin overrides the latter\n  // with the record key (`tools: { my_tool: ... }` -> \"my_tool\") at\n  // index-build time. Fall back to a generic label so errors are still\n  // legible when `name` is omitted.\n  const labelForErrors = config.name ?? \"tool\";\n\n  return {\n    type: \"function\",\n    ...(config.name !== undefined ? { name: config.name } : {}),\n    description: config.description,\n    parameters,\n    ...(config.annotations ? { annotations: config.annotations } : {}),\n    execute: async (args: Record<string, unknown>) => {\n      const parsed = config.schema.safeParse(args);\n      if (!parsed.success) {\n        return formatZodError(parsed.error, labelForErrors);\n      }\n      return config.execute(parsed.data as z.infer<S>);\n    },\n  };\n}\n\n/**\n * Formats a Zod validation error into an LLM-friendly string.\n *\n * Example: `Invalid arguments for get_weather: city: Invalid input: expected string, received undefined`\n */\nexport function formatZodError(error: z.ZodError, toolName: string): string {\n  const parts = error.issues.map((issue) => {\n    const field = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    return `${field}: ${issue.message}`;\n  });\n  return `Invalid arguments for ${toolName}: ${parts.join(\"; \")}`;\n}\n"],"mappings":";;;;;;;;;;;;AA2DA,SAAgB,KAA0B,QAAqC;CAC7E,MAAM,aAAa,iBAAiB,OAAO,OAAO;CAOlD,MAAM,iBAAiB,OAAO,QAAQ;AAEtC,QAAO;EACL,MAAM;EACN,GAAI,OAAO,SAAS,SAAY,EAAE,MAAM,OAAO,MAAM,GAAG,EAAE;EAC1D,aAAa,OAAO;EACpB;EACA,GAAI,OAAO,cAAc,EAAE,aAAa,OAAO,aAAa,GAAG,EAAE;EACjE,SAAS,OAAO,SAAkC;GAChD,MAAM,SAAS,OAAO,OAAO,UAAU,KAAK;AAC5C,OAAI,CAAC,OAAO,QACV,QAAO,eAAe,OAAO,OAAO,eAAe;AAErD,UAAO,OAAO,QAAQ,OAAO,KAAmB;;EAEnD;;;;;;;AAQH,SAAgB,eAAe,OAAmB,UAA0B;AAK1E,QAAO,yBAAyB,SAAS,IAJ3B,MAAM,OAAO,KAAK,UAAU;AAExC,SAAO,GADO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,SAC7C,IAAI,MAAM;GAC1B,CACiD,KAAK,KAAK"}

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

@@ -43,6 +43,41 @@ interface ToolkitOptions {
   /** Remap specific local names to different keys (applied after prefix). */
   rename?: Record<string, string>;
 }
+/**
+ * Minimum shape every entry in the {@link Plugins} map must expose. Core
+ * plugins (analytics, files, genie, lakebase) implement this directly via
+ * their `.toolkit()` method. The agents plugin and standalone `runAgent`
+ * synthesize this shape for any registered plugin that doesn't implement
+ * `.toolkit()` directly (falling back to `getAgentTools()` walking).
+ */
+interface PluginToolkitProvider {
+  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;
+}
+/**
+ * Plugin map passed to the function form of {@link AgentDefinition.tools}.
+ * Each entry exposes a `.toolkit(opts?)` method that returns a record of
+ * {@link ToolkitEntry} markers ready to be spread into a tool record.
+ *
+ * AppKit does not statically know which plugins the surrounding
+ * `createApp` will register, so this is a plain string-keyed record.
+ * Refer to plugins by the name used in `createApp({ plugins: [...] })`;
+ * unknown names resolve to `undefined` at runtime.
+ *
+ * @example
+ * ```ts
+ * const support = createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       get_weather: tool({ ... }),
+ *       ...plugins.analytics.toolkit(),
+ *       ...plugins.files.toolkit({ only: ["uploads.read"] }),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+type Plugins = Record<string, PluginToolkitProvider>;
 /**
  * Context passed to `baseSystemPrompt` callbacks.
  */
@@ -52,8 +87,40 @@ interface PromptContext {
   toolNames: string[];
 }
 type BaseSystemPromptOption = false | string | ((ctx: PromptContext) => string);
+/**
+ * Per-agent tool record. String keys map to inline tools, toolkit entries,
+ * hosted tools, etc.
+ */
+type AgentTools = Record<string, AgentTool>;
+/**
+ * Function form of `AgentDefinition.tools`. Receives the typed
+ * {@link Plugins} map and returns a tool record. Invoked exactly once at
+ * setup (or once per `runAgent` call in standalone mode); the result is
+ * cached as the agent's resolved tool record.
+ *
+ * Use the function form when an agent needs tools from registered plugins.
+ * The bare object form is fine when an agent only uses inline tools.
+ */
+type AgentToolsFn = (plugins: Plugins) => AgentTools;
 interface AgentDefinition {
-  /** Filled in from the enclosing key when used in `agents: { foo: def }`. */
+  /**
+   * Stable identifier for the agent. **Optional and informational** —
+   * when the definition is registered via `agents: { foo: def }` (code) or
+   * lives at `config/agents/<id>/agent.md` (markdown), the **registry key
+   * always wins** and `name` is ignored. The agent will be reachable as
+   * `foo` (or `<id>`) regardless of what this field contains.
+   *
+   * Set `name` when:
+   *   - Running standalone via `runAgent({ agent: def })`, where there is
+   *     no enclosing key. The runtime uses it for the agent's slot in
+   *     error messages and OTel spans.
+   *   - Building a definition that may be passed to either form and you
+   *     want a consistent fallback label.
+   *
+   * Setting `name` to a value that differs from the registry key is
+   * harmless but confusing — prefer keeping them aligned or omitting `name`
+   * entirely.
+   */
   name?: string;
   /** System prompt body. For markdown-loaded agents this is the file body. */
   instructions: string;
@@ -63,8 +130,18 @@ interface AgentDefinition {
    * falls back to the plugin's `defaultModel`.
    */
   model?: AgentAdapter | Promise<AgentAdapter> | string;
-  /** Per-agent tool record. Key is the LLM-visible tool-call name. */
-  tools?: Record<string, AgentTool>;
+  /**
+   * Per-agent tool record. Key is the LLM-visible tool-call name.
+   *
+   * Accepts either a plain record (for agents that only use inline tools)
+   * or a function `(plugins) => Record<string, AgentTool>` that receives
+   * the typed {@link Plugins} map and returns a tool record (for agents
+   * that pull tools from registered plugins).
+   *
+   * The function is invoked once at agent setup; the result is cached.
+   * Don't put per-request logic in there.
+   */
+  tools?: AgentTools | AgentToolsFn;
   /** Sub-agents, exposed as `agent-<key>` tools on this agent. */
   agents?: Record<string, AgentDefinition>;
   /** Override the plugin's baseSystemPrompt for this agent only. */
@@ -86,7 +163,8 @@ interface AgentDefinition {
  * with no explicit `tools:` declaration receive every registered ToolProvider
  * plugin tool whose author marked `autoInheritable: true`. Tools without that
  * flag — destructive, state-mutating, or privilege-sensitive — never spread
- * automatically and must be wired via `tools:`, `toolkits:`, or `fromPlugin`.
+ * automatically and must be wired via `tools:` (object or function form in
+ * code, `plugin:NAME` entries in markdown frontmatter).
  *
  * Defaults are `false` for both origins (safe-by-default): developers must
  * consciously opt an origin in to any auto-inherit behaviour.
@@ -122,14 +200,21 @@ interface AgentsPluginConfig extends BasePluginConfig {
    */
   mcp?: McpHostPolicyConfig;
   /**
-   * Human-in-the-loop approval gate for destructive tool calls. When enabled
+   * Human-in-the-loop approval gate for mutating tool calls. When enabled
    * (the default), the agents plugin emits an `appkit.approval_pending` SSE
-   * event before executing any tool annotated `destructive: true` and waits
-   * for a `POST /chat/approve` decision from the same user who initiated the
-   * stream. A missing decision after `timeoutMs` auto-denies the call.
+   * event before executing any tool whose annotation flags it as mutating —
+   * `effect: "write" | "update" | "destructive"` (preferred) or the legacy
+   * `destructive: true` boolean — and waits for a `POST /chat/approve`
+   * decision from the same user who initiated the stream. A missing decision
+   * after `timeoutMs` auto-denies the call.
    */
   approval?: {
-    /** Require human approval for tools annotated `destructive: true`. Default: `true`. */requireForDestructive?: boolean; /** Milliseconds to wait before auto-denying. Default: 60_000. */
+    /**
+     * Require human approval for tools that mutate state. Triggered by
+     * `effect: "write" | "update" | "destructive"` (preferred) or the legacy
+     * `destructive: true` boolean. Default: `true`.
+     */
+    requireForDestructive?: boolean; /** Milliseconds to wait before auto-denying. Default: 60_000. */
     timeoutMs?: number;
   };
   /**
@@ -210,5 +295,5 @@ interface RegisteredAgent {
  */
 declare function isToolkitEntry(value: unknown): value is ToolkitEntry;
 //#endregion
-export { AgentDefinition, AgentTool, AgentsPluginConfig, AutoInheritToolsConfig, BaseSystemPromptOption, PromptContext, RegisteredAgent, ResolvedToolEntry, ToolkitEntry, ToolkitOptions, isToolkitEntry };
+export { AgentDefinition, AgentTool, AgentTools, AgentToolsFn, AgentsPluginConfig, AutoInheritToolsConfig, BaseSystemPromptOption, PluginToolkitProvider, Plugins, PromptContext, RegisteredAgent, ResolvedToolEntry, ToolkitEntry, ToolkitOptions, isToolkitEntry };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":";;;;;;;;;;;;;;AAiBA;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;;;;UAMM,aAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,KAGU,sBAAA,sBAGN,GAAA,EAAK,aAAA;AAAA,UAEM,eAAA;EAXa;EAa5B,IAAA;EAXA;EAaA,YAAA;EAZS;;AAGX;;;EAeE,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAZT;EActB,KAAA,GAAQ,MAAA,SAAe,SAAA;EAZO;EAc9B,MAAA,GAAS,MAAA,SAAe,eAAA;EAJhB;EAMR,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EANQ;;;;;;;;EAeR,SAAA;AAAA;;;;;;;;;;;UAae,sBAAA;EAtBf;EAwBA,IAAA;EAfS;EAiBT,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;;EAE1C,GAAA;EALI;EAOJ,MAAA,GAAS,MAAA,SAAe,eAAA;EAJU;EAMlC,YAAA;EAFwB;EAIxB,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EAAvB;EAEf,KAAA,GAAQ,MAAA,SAAe,SAAA;EAFO;EAI9B,gBAAA,aAA6B,sBAAA;EAFrB;EAIR,WAAA,GAAc,WAAA;EAAA;EAEd,gBAAA,GAAmB,sBAAA;EAOb;;;;;;EAAN,GAAA,GAAM,mBAAA;EAnBG;;;;;;;EA2BT,QAAA;IArBQ,uFAuBN,qBAAA,YArBF;IAuBE,SAAA;EAAA;EArBY;;;;;;;;EA+Bd,MAAA;IAME;;;;;IAAA,2BAAA;IA8BQ;;;;;IAxBR,YAAA;IAuCO;;;;;IAjCP,gBAAA;IAsBE;;;;;;;;;;;;IATF,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;EAS4B;EAP5B,SAAA;AAAA;;;;;iBAOc,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":";;;;;;;;;;;;;;AAiBA;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;EAsBwB;EApBxB,YAAA;EAsBmB;;;;;EAhBnB,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAyChB;;;;;AAOjB;;;;;;EApCE,KAAA,GAAQ,UAAA,GAAa,YAAA;EA4CS;EA1C9B,MAAA,GAAS,MAAA,SAAe,eAAA;EA4ChB;EA1CR,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EAqDM;;;;;;;;EA5CN,SAAA;AAAA;;;;;;;;;;;;UAce,sBAAA;EAuBI;EArBnB,IAAA;EA4BM;EA1BN,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;EAmD1C;EAjDA,GAAA;EA6DE;EA3DF,MAAA,GAAS,MAAA,SAAe,eAAA;EA8EtB;EA5EF,YAAA;EA4EmB;EA1EnB,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EA+EX;EA7E3B,KAAA,GAAQ,MAAA,SAAe,SAAA;EAkFd;EAhFT,gBAAA,aAA6B,sBAAA;EAqFpB;EAnFT,WAAA,GAAc,WAAA;EA6FL;EA3FT,gBAAA,GAAmB,sBAAA;EA2FS;;;;;;EApF5B,GAAA,GAAM,mBAAA;EAyEF;;;;;;;;;EA/DJ,QAAA;IA0EI;;;;AAGN;IAvEI,qBAAA,YAuE4B;IArE5B,SAAA;EAAA;EAyES;;;;;;;;EA/DX,MAAA;IA+DW;;;;;IAzDT,2BAAA;IA8DF;;;AAOF;;IA/DI,YAAA;IA+DiE;;;;;IAzDjE,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,SAAA;AAAA;;;;;iBAOc,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA"}

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 { 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 * 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\nexport interface AgentDefinition {\n  /** Filled in from the enclosing key when used in `agents: { foo: def }`. */\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  /** Per-agent tool record. Key is the LLM-visible tool-call name. */\n  tools?: Record<string, AgentTool>;\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   * 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:`, `toolkits:`, or `fromPlugin`.\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 destructive tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool annotated `destructive: true` and waits\n   * for a `POST /chat/approve` decision from the same user who initiated the\n   * stream. A missing decision after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /** Require human approval for tools annotated `destructive: true`. Default: `true`. */\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.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":";;;;;AAuOA,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 { 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   * 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.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":";;;;;AA+TA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}

package/dist/plugin/index.d.ts

@@ -2,4 +2,4 @@ import { ToPlugin } from "../shared/src/plugin.js";
 import "../shared/src/index.js";
 import { ExecutionResult } from "./execution-result.js";
 import { Plugin } from "./plugin.js";
-import { NamedPluginFactory, toPlugin } from "./to-plugin.js";
+import { toPlugin } from "./to-plugin.js";

package/dist/plugin/to-plugin.d.ts

@@ -2,24 +2,14 @@ import { PluginConstructor, ToPlugin } from "../shared/src/plugin.js";
 import "../shared/src/index.js";
 
 //#region src/plugin/to-plugin.d.ts
-/**
- * Factory function produced by {@link toPlugin}. Carries a static
- * `pluginName` field so tooling (e.g. `fromPlugin`) can identify which
- * plugin a factory references without constructing an instance.
- */
-type NamedPluginFactory<Name extends string = string> = {
-  readonly pluginName: Name;
-};
 /**
  * Wraps a plugin class so it can be passed to `createApp` with optional
  * config. Infers the config type from the constructor and the plugin name
- * from the static `manifest.name` property, and stamps `pluginName` onto
- * the returned factory function so `fromPlugin` can identify the plugin
- * without needing to construct it.
+ * from the static `manifest.name` property.
  *
  * @internal
  */
-declare function toPlugin<T extends PluginConstructor>(plugin: T): ToPlugin<T, ConstructorParameters<T>[0], T["manifest"]["name"]> & NamedPluginFactory<T["manifest"]["name"]>;
+declare function toPlugin<T extends PluginConstructor>(plugin: T): ToPlugin<T, ConstructorParameters<T>[0], T["manifest"]["name"]>;
 //#endregion
-export { NamedPluginFactory, toPlugin };
+export { toPlugin };
 //# sourceMappingURL=to-plugin.d.ts.map

package/dist/plugin/to-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-plugin.d.ts","names":[],"sources":["../../src/plugin/to-plugin.ts"],"mappings":";;;;;;;AAOA;;KAAY,kBAAA;EAAA,SACD,UAAA,EAAY,IAAA;AAAA;;;;;AAYvB;;;;;iBAAgB,QAAA,WAAmB,iBAAA,CAAA,CACjC,MAAA,EAAQ,CAAA,GACP,QAAA,CAAS,CAAA,EAAG,qBAAA,CAAsB,CAAA,MAAO,CAAA,wBAC1C,kBAAA,CAAmB,CAAA"}
+{"version":3,"file":"to-plugin.d.ts","names":[],"sources":["../../src/plugin/to-plugin.ts"],"mappings":";;;;;;;AASA;;;;iBAAgB,QAAA,WAAmB,iBAAA,CAAA,CACjC,MAAA,EAAQ,CAAA,GACP,QAAA,CAAS,CAAA,EAAG,qBAAA,CAAsB,CAAA,MAAO,CAAA"}

package/dist/plugin/to-plugin.js

@@ -2,9 +2,7 @@
 /**
 * Wraps a plugin class so it can be passed to `createApp` with optional
 * config. Infers the config type from the constructor and the plugin name
-* from the static `manifest.name` property, and stamps `pluginName` onto
-* the returned factory function so `fromPlugin` can identify the plugin
-* without needing to construct it.
+* from the static `manifest.name` property.
 *
 * @internal
 */
@@ -15,11 +13,6 @@ function toPlugin(plugin) {
 		config,
 		name: pluginName
 	});
-	Object.defineProperty(factory, "pluginName", {
-		value: pluginName,
-		writable: false,
-		enumerable: true
-	});
 	return factory;
 }
 

package/dist/plugin/to-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"to-plugin.js","names":[],"sources":["../../src/plugin/to-plugin.ts"],"sourcesContent":["import type { PluginConstructor, PluginData, ToPlugin } from \"shared\";\n\n/**\n * Factory function produced by {@link toPlugin}. Carries a static\n * `pluginName` field so tooling (e.g. `fromPlugin`) can identify which\n * plugin a factory references without constructing an instance.\n */\nexport type NamedPluginFactory<Name extends string = string> = {\n  readonly pluginName: Name;\n};\n\n/**\n * Wraps a plugin class so it can be passed to `createApp` with optional\n * config. Infers the config type from the constructor and the plugin name\n * from the static `manifest.name` property, and stamps `pluginName` onto\n * the returned factory function so `fromPlugin` can identify the plugin\n * without needing to construct it.\n *\n * @internal\n */\nexport function toPlugin<T extends PluginConstructor>(\n  plugin: T,\n): ToPlugin<T, ConstructorParameters<T>[0], T[\"manifest\"][\"name\"]> &\n  NamedPluginFactory<T[\"manifest\"][\"name\"]> {\n  type Config = ConstructorParameters<T>[0];\n  type Name = T[\"manifest\"][\"name\"];\n  const pluginName = plugin.manifest.name as Name;\n  const factory = (\n    config: Config = {} as Config,\n  ): PluginData<T, Config, Name> => ({\n    plugin: plugin as T,\n    config: config as Config,\n    name: pluginName,\n  });\n  Object.defineProperty(factory, \"pluginName\", {\n    value: pluginName,\n    writable: false,\n    enumerable: true,\n  });\n  return factory as ToPlugin<T, Config, Name> & NamedPluginFactory<Name>;\n}\n"],"mappings":";;;;;;;;;;AAoBA,SAAgB,SACd,QAE0C;CAG1C,MAAM,aAAa,OAAO,SAAS;CACnC,MAAM,WACJ,SAAiB,EAAE,MACc;EACzB;EACA;EACR,MAAM;EACP;AACD,QAAO,eAAe,SAAS,cAAc;EAC3C,OAAO;EACP,UAAU;EACV,YAAY;EACb,CAAC;AACF,QAAO"}
+{"version":3,"file":"to-plugin.js","names":[],"sources":["../../src/plugin/to-plugin.ts"],"sourcesContent":["import type { PluginConstructor, PluginData, ToPlugin } from \"shared\";\n\n/**\n * Wraps a plugin class so it can be passed to `createApp` with optional\n * config. Infers the config type from the constructor and the plugin name\n * from the static `manifest.name` property.\n *\n * @internal\n */\nexport function toPlugin<T extends PluginConstructor>(\n  plugin: T,\n): ToPlugin<T, ConstructorParameters<T>[0], T[\"manifest\"][\"name\"]> {\n  type Config = ConstructorParameters<T>[0];\n  type Name = T[\"manifest\"][\"name\"];\n  const pluginName = plugin.manifest.name as Name;\n  const factory = (\n    config: Config = {} as Config,\n  ): PluginData<T, Config, Name> => ({\n    plugin: plugin as T,\n    config: config as Config,\n    name: pluginName,\n  });\n  return factory as ToPlugin<T, Config, Name>;\n}\n"],"mappings":";;;;;;;;AASA,SAAgB,SACd,QACiE;CAGjE,MAAM,aAAa,OAAO,SAAS;CACnC,MAAM,WACJ,SAAiB,EAAE,MACc;EACzB;EACA;EACR,MAAM;EACP;AACD,QAAO"}

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

@@ -1,4 +1,186 @@
+import { AgentToolDefinition, Thread, ToolProvider } from "../../shared/src/agent.js";
+import { IAppRouter, PluginPhase, ToPlugin } from "../../shared/src/plugin.js";
 import "../../shared/src/index.js";
-import "../../core/agent/types.js";
+import { AgentDefinition, AgentsPluginConfig, RegisteredAgent } from "../../core/agent/types.js";
+import { Plugin } from "../../plugin/plugin.js";
 import "../../plugin/index.js";
-import "../../registry/index.js";
+import { PluginManifest } from "../../registry/types.js";
+import "../../registry/index.js";
+
+//#region src/plugins/agents/agents.d.ts
+declare class AgentsPlugin extends Plugin implements ToolProvider {
+  static manifest: PluginManifest;
+  static phase: PluginPhase;
+  protected config: AgentsPluginConfig;
+  private agents;
+  private defaultAgentName;
+  private activeStreams;
+  /**
+   * Per-user stream count, kept in sync with `activeStreams` so the
+   * concurrent-stream rate limit check is O(1) instead of O(n) over every
+   * active stream on every request. Mutated only via {@link trackStream}
+   * and {@link untrackStream}.
+   */
+  private userStreamCounts;
+  private mcpClient;
+  private threadStore;
+  private approvalGate;
+  constructor(config: AgentsPluginConfig);
+  /**
+   * Effective approval policy with defaults applied. Memoised so the
+   * `timeoutMs` validation warning fires at most once per plugin instance —
+   * `resolvedApprovalPolicy` gets hit on every chat stream and a noisy
+   * misconfig would otherwise spam the logs.
+   *
+   * `timeoutMs` is clamped to a 1s floor so a misconfigured value (`0`,
+   * negative, or `NaN`) can't degrade into immediate auto-denial of every
+   * mutating tool call.
+   */
+  private cachedApprovalPolicy;
+  private get resolvedApprovalPolicy();
+  /** Effective DoS limits with defaults applied. */
+  private get resolvedLimits();
+  /** Count active streams owned by a given user. O(1). */
+  private countUserStreams;
+  /**
+   * Register a stream for `userId` and bump the per-user counter. Paired
+   * with {@link untrackStream}; the two helpers are the only writers to
+   * `activeStreams` + `userStreamCounts`, so the counter cannot drift from
+   * the map.
+   */
+  private trackStream;
+  /**
+   * Remove a stream from the active map and decrement the per-user
+   * counter. Idempotent — calling twice for the same `requestId` is a
+   * no-op (the second call sees no entry and returns early).
+   */
+  private untrackStream;
+  setup(): Promise<void>;
+  /**
+   * Reload agents from the configured directory, preserving code-defined
+   * agents. Builds a fresh registry first and only swaps on success — if
+   * `loadAgents` throws (malformed markdown, missing tool reference) the
+   * existing live registry stays in place and serving requests keep working.
+   */
+  reload(): Promise<void>;
+  /**
+   * Builds the agent registry into a fresh `Map` without touching live state.
+   * Called by both `setup` and `reload`; the latter only swaps the live
+   * registry once this resolves successfully (atomic reload).
+   */
+  private buildAgentRegistry;
+  private resolvedAgentsDir;
+  private loadFileDefinitions;
+  /**
+   * Builds the map of plugin-name → toolkit that the markdown loader consults
+   * when resolving `plugin:NAME` entries in the unified `tools:` frontmatter
+   * list (and, equivalently, that the code form passes as the `plugins`
+   * argument to `tools(plugins) => Record<...>`).
+   */
+  private pluginProviderIndex;
+  private buildRegisteredAgent;
+  private resolveAdapter;
+  /**
+   * Resolves an agent's tool record into a per-agent dispatch index. Connects
+   * hosted tools via MCP client. Applies `autoInheritTools` defaults when the
+   * definition has no declared tools/agents.
+   */
+  private buildToolIndex;
+  /**
+   * Resolves an `AgentDefinition.tools` field to a plain tool record. The
+   * function form is invoked exactly once at agent setup with the typed
+   * {@link Plugins} map; the result replaces the function reference for the
+   * remainder of the registered agent's lifetime.
+   *
+   * Plain object form is returned as-is; an undefined `tools` returns an
+   * empty record. The function form is wrapped in a try/catch so a thrown
+   * callback fails registration with a useful message instead of leaking
+   * the raw stack.
+   */
+  private resolveDefTools;
+  /**
+   * Builds the typed {@link Plugins} map passed to the function form of
+   * `AgentDefinition.tools`. Each entry exposes the plugin instance directly
+   * (so user code can call typed instance methods including `.toolkit()`);
+   * plugins missing `.toolkit()` get a synthesized fallback that walks
+   * `getAgentTools()` via `resolveToolkitFromProvider`.
+   *
+   * Wrapped in {@link createPluginsProxy} so that accessing an unknown
+   * plugin name throws a named "not registered, Available: ..." error
+   * instead of bubbling up a generic `Cannot read properties of undefined`
+   * from the agent's `tools(plugins)` callback.
+   */
+  private buildPluginsMap;
+  private applyAutoInherit;
+  private connectHostedTools;
+  getAgentTools(): AgentToolDefinition[];
+  executeAgentTool(): Promise<unknown>;
+  private mountInvocationsRoute;
+  injectRoutes(router: IAppRouter): void;
+  clientConfig(): Record<string, unknown>;
+  private _handleChat;
+  private _handleInvocations;
+  private _streamAgent;
+  /**
+   * Dispatch a single tool call from either the top-level adapter or a
+   * sub-agent. Centralising this in one method is what makes the budget
+   * counter, approval gate, and abort signal observe sub-agent activity:
+   * `runSubAgent` reuses the same `runState` and so increments the same
+   * counter and emits approval events through the same channel.
+   *
+   * `depth` is the current sub-agent recursion depth (0 at the top level).
+   * It is forwarded to `runSubAgent` when the dispatched entry is itself a
+   * sub-agent, so depth limits remain enforced.
+   */
+  private dispatchToolCall;
+  /**
+   * Runs a sub-agent in response to an `agent-<key>` tool call. Returns the
+   * concatenated text output to hand back to the parent adapter as the tool
+   * result.
+   *
+   * `depth` starts at 1 for a top-level sub-agent invocation (i.e. the
+   * outer `_streamAgent` calls `runSubAgent(..., 1)`) and increments on
+   * each nested `runSubAgent` call. Depths exceeding
+   * `limits.maxSubAgentDepth` are rejected before any adapter work.
+   *
+   * Sub-agent tool calls run through `dispatchToolCall` with the same
+   * `runState` as the parent — the budget counter and approval gate are
+   * therefore enforced for every nested call, not only at the top level.
+   */
+  private runSubAgent;
+  private _handleCancel;
+  private _handleApprove;
+  private _handleListThreads;
+  private _handleGetThread;
+  private _handleDeleteThread;
+  private resolveAgent;
+  private printRegistry;
+  shutdown(): Promise<void>;
+  exports(): {
+    register: (name: string, def: AgentDefinition) => Promise<void>;
+    list: () => string[];
+    get: (name: string) => RegisteredAgent | null;
+    reload: () => Promise<void>;
+    getDefault: () => string | null;
+    getThreads: (userId: string) => Promise<Thread[]>;
+  };
+  private registerCodeAgent;
+}
+/**
+ * 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 `/invocations`.
+ *
+ * @example
+ * ```ts
+ * import { agents, analytics, createApp, server } from "@databricks/appkit";
+ *
+ * await createApp({
+ *   plugins: [server(), analytics(), agents()],
+ * });
+ * ```
+ */
+declare const agents: ToPlugin<typeof AgentsPlugin, AgentsPluginConfig, string>;
+//#endregion
+export { AgentsPlugin, agents };
+//# sourceMappingURL=agents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","names":[],"sources":["../../../src/plugins/agents/agents.ts"],"mappings":";;;;;;;;;;cAkIa,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;EAgqBJ;;;;;;;;;;EAAA,QAjoBR,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;EAiEA;;;;;;EAAA,QAvCN,mBAAA;EAAA,QAmBM,oBAAA;EAAA,QAoBA,cAAA;EAmTY;;;;;EAAA,QA7QZ,cAAA;EAgVE;;;;;;;;;;;EAAA,QAhPR,eAAA;EA01BA;;;;;;;;;;;;EAAA,QA9zBA,eAAA;EAAA,QAkBM,gBAAA;EAAA,QA0DA,kBAAA;EAiEd,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CAAA,GAAoB,OAAA;EAAA,QAMlB,qBAAA;EAWR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAkDrB,YAAA,CAAA,GAAgB,MAAA;EAAA,QAOF,WAAA;EAAA,QAkEA,kBAAA;EAAA,QAqEA,YAAA;EA8jBH;;;;;;;;;;;EAAA,QArZG,gBAAA;EAqZG;;;;;;;;;;;;;;EAAA,QAxSH,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;;;;;;;;;;;;;;;cA8DH,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,kBAAA"}