@databricks/appkit 0.63.0 → 0.64.0

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

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

@@ -25,6 +25,10 @@ declare class AgentsPlugin extends Plugin implements ToolProvider {
   private mcpClient;
   private threadStore;
   private approvalGate;
+  /** Guards the `agents({ agents })` deprecation warning to once per instance. */
+  private agentsMapDeprecationWarned;
+  /** Guards the `config/agents` deprecation warning to once per instance. */
+  private configAgentsDeprecationWarned;
   constructor(config: AgentsPluginConfig);
   /**
    * Effective approval policy with defaults applied. Memoised so the
@@ -69,7 +73,32 @@ declare class AgentsPlugin extends Plugin implements ToolProvider {
    * registry once this resolves successfully (atomic reload).
    */
   private buildAgentRegistry;
+  /**
+   * Resolves the default agent. Precedence: explicit `config.defaultAgent` >
+   * a code/discovered agent flagged `default: true` (stable id order) >
+   * markdown `default: true` > first registered (insertion order).
+   */
+  private resolveDefaultAgent;
+  /**
+   * Emits the one-time deprecation warning for the `agents({ agents })` map.
+   * Guarded so `reload()` (which re-runs `buildAgentRegistry`) doesn't spam it.
+   */
+  private warnAgentsMapDeprecated;
+  /**
+   * One-time deprecation warning for markdown agents still living in
+   * `config/agents/`. Guarded so `reload()` doesn't spam it.
+   */
+  private warnConfigAgentsDeprecated;
   private resolvedAgentsDir;
+  /**
+   * Discovers code agents (see {@link resolveCodeAgentsDir} and
+   * {@link loadCodeAgentsFromDir}). Warns if sources exist but nothing was
+   * discovered — usually the build didn't emit the compiled agents — unless
+   * the deprecated `agents({ agents })` map is carrying them instead.
+   */
+  private loadCodeAgents;
+  /** True when `dir` holds at least one `<id>/agent.ts` folder. */
+  private hasCodeAgentSources;
   private loadFileDefinitions;
   /**
    * Builds the map of plugin-name → toolkit that the markdown loader consults
@@ -219,10 +248,12 @@ declare class AgentsPlugin extends Plugin implements ToolProvider {
   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 `POST /invocations` and `POST /responses` (aliased
- * non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable).
+ * Plugin factory for the agents plugin. Discovers agents from
+ * `server/agents/<id>/agent.{ts,md}` by default (markdown still in
+ * `config/agents/` is read as a deprecated fallback), resolves toolkits/tools
+ * from registered plugins, exposes the `appkit.agents.*` runtime API and mounts
+ * `POST /invocations` and `POST /responses` (aliased non-streaming invoke
+ * endpoints) plus `POST /chat` (streaming, HITL-capable).
  *
  * @example
  * ```ts

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

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","names":[],"sources":["../../../src/plugins/agents/agents.ts"],"mappings":";;;;;;;;;;cA+Ia,YAAA,SAAqB,MAAA,YAAkB,YAAA;EAAA,OAK3C,QAAA,EAAkC,cAAA;EAAA,OAClC,KAAA,EAAO,WAAA;EAAA,UAEI,MAAA,EAAQ,kBAAA;EAAA,QAElB,MAAA;EAAA,QACA,gBAAA;EAAA,QACA,aAAA;EAZgB;;;;;;EAAA,QAsBhB,gBAAA;EAAA,QACA,SAAA;EAAA,QACA,WAAA;EAAA,QACA,YAAA;cAEI,MAAA,EAAQ,kBAAA;EA+rBJ;;;;;;;;;;EAAA,QAhqBR,oBAAA;EAAA,YAKI,sBAAA,CAAA;EA/DoB;EAAA,YAyFpB,cAAA,CAAA;EApFL;EAAA,QAuGC,gBAAA;EAtGD;;;;;;EAAA,QAgHC,WAAA;EAhGA;;;;;EAAA,QAiHA,aAAA;EAYF,KAAA,CAAA,GAAK,OAAA;EAzFH;;;;;;EAwGF,MAAA,CAAA,GAAU,OAAA;EAfL;;;;;EAAA,QAyCG,kBAAA;EAAA,QAmEN,iBAAA;EAAA,QAMM,mBAAA;EAoEA;;;;;;EAAA,QA1CN,mBAAA;EAAA,QAmBM,oBAAA;EAAA,QAuBA,cAAA;EAyUY;;;;;EAAA,QA7RZ,cAAA;EAqWE;;;;;;;;;;;EAAA,QArPR,eAAA;EAynCM;;;;;;;;;;;;EAAA,QA7lCN,eAAA;EAAA,QAkBM,gBAAA;EAAA,QA0DA,kBAAA;EAiEd,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CAAA,GAAoB,OAAA;;;;;;;UAYlB,iBAAA;EAUR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAkDrB,YAAA,CAAA,GAAgB,MAAA;EAAA,QAOF,WAAA;;;;;;;;;;;;UA6EN,gCAAA;;;;;;;;;;;UAuBM,aAAA;EAAA,QA2FA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;UA2NA,qBAAA;;;;;;;;;;;;UA0KA,gBAAA;;;;;;;;;;;;;;;UAmIA,WAAA;EAAA,QAiGA,aAAA;EAAA,QA2BA,cAAA;EAAA,QAuCA,kBAAA;EAAA,QASA,gBAAA;EAAA,QAUA,mBAAA;EAAA,QAaN,YAAA;EAAA,QASA,aAAA;EAgBF,QAAA,CAAA,GAAY,OAAA;EAQlB,OAAA,CAAA;6BAE2B,GAAA,EAAO,eAAA,KAAe,OAAA;;2BAG3B,eAAA;;;oCAGS,OAAA,CAAA,MAAA;EAAA;EAAA,QAIjB,iBAAA;AAAA;;;;;;;;;;;;;;;;cAsJH,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,kBAAA"}
+{"version":3,"file":"agents.d.ts","names":[],"sources":["../../../src/plugins/agents/agents.ts"],"mappings":";;;;;;;;;;cAsJa,YAAA,SAAqB,MAAA,YAAkB,YAAA;EAAA,OAK3C,QAAA,EAAkC,cAAA;EAAA,OAClC,KAAA,EAAO,WAAA;EAAA,UAEI,MAAA,EAAQ,kBAAA;EAAA,QAElB,MAAA;EAAA,QACA,gBAAA;EAAA,QACA,aAAA;EAZgB;;;;;;EAAA,QAsBhB,gBAAA;EAAA,QACA,SAAA;EAAA,QACA,WAAA;EAAA,QACA,YAAA;EAqzBa;EAAA,QAnzBb,0BAAA;EA+wDU;EAAA,QA7wDV,6BAAA;cAEI,MAAA,EAAQ,kBAAA;EAwxDE;;;;;;;;;;EAAA,QAzvDd,oBAAA;EAAA,YAKI,sBAAA,CAAA;EA7DL;EAAA,YAuFK,cAAA,CAAA;EArFM;EAAA,QAwGV,gBAAA;EAtGA;;;;;;EAAA,QAgHA,WAAA;EA/FA;;;;;EAAA,QAgHA,aAAA;EAYF,KAAA,CAAA,GAAK,OAAA;EA1DC;;;;;;EAyEN,MAAA,CAAA,GAAU,OAAA;EAAA;;;;;EAAA,QA0BF,kBAAA;EAsKA;;;;;EAAA,QAjEN,mBAAA;EAsPM;;;;EAAA,QAxNN,uBAAA;EAifR;;;;EAAA,QAleQ,0BAAA;EAAA,QAUA,iBAAA;EAkfa;;;;;;EAAA,QAxeP,cAAA;EAguBA;EAAA,QAnsBN,mBAAA;EAAA,QAeM,mBAAA;EA4rCA;;;;;;EAAA,QAzoCN,mBAAA;EAAA,QAmBM,oBAAA;EAAA,QAuBA,cAAA;EA2zCI;;;;;EAAA,QA/wCJ,cAAA;EAyxCmC;;;;;;;;;;;EAAA,QAzqCzC,eAAA;EAmrCM;;;AAwJhB;;;;;;;;;EAxJgB,QAvpCN,eAAA;EAAA,QAkBM,gBAAA;EAAA,QA0DA,kBAAA;EAiEd,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CAAA,GAAoB,OAAA;;;;;;;UAYlB,iBAAA;EAUR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAkDrB,YAAA,CAAA,GAAgB,MAAA;EAAA,QAOF,WAAA;;;;;;;;;;;;UA6EN,gCAAA;;;;;;;;;;;UAuBM,aAAA;EAAA,QA2FA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;UA2NA,qBAAA;;;;;;;;;;;;UA0KA,gBAAA;;;;;;;;;;;;;;;UAmIA,WAAA;EAAA,QAiGA,aAAA;EAAA,QA2BA,cAAA;EAAA,QAuCA,kBAAA;EAAA,QASA,gBAAA;EAAA,QAUA,mBAAA;EAAA,QAaN,YAAA;EAAA,QASA,aAAA;EAgBF,QAAA,CAAA,GAAY,OAAA;EAQlB,OAAA,CAAA;6BAE2B,GAAA,EAAO,eAAA,KAAe,OAAA;;2BAG3B,eAAA;;;oCAGS,OAAA,CAAA,MAAA;EAAA;EAAA,QAIjB,iBAAA;AAAA;;;;;;;;;;;;;;;;;;cAwJH,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,kBAAA"}

package/dist/plugins/agents/agents.js

@@ -14,6 +14,7 @@ import { isHostedTool, resolveHostedTools } from "../../core/agent/tools/hosted-
 import { isToolkitEntry } from "../../core/agent/types.js";
 import "../../core/agent/tools/index.js";
 import { loadAgentsFromDir } from "../../core/agent/load-agents.js";
+import { CODE_AGENTS_SOURCE_DIR, loadCodeAgentsFromDir, resolveCodeAgentsDir } from "../../core/agent/load-code-agents.js";
 import { normalizeToolResult } from "../../core/agent/normalize-result.js";
 import { buildBaseSystemPrompt, composeSystemPrompt } from "../../core/agent/system-prompt.js";
 import { agentStreamDefaults } from "./defaults.js";
@@ -27,10 +28,12 @@ import { ToolApprovalGate } from "./tool-approval-gate.js";
 import { randomUUID } from "node:crypto";
 import pc from "picocolors";
 import path from "node:path";
+import { existsSync, readdirSync } from "node:fs";
 
 //#region src/plugins/agents/agents.ts
 const logger = createLogger("agents");
-const DEFAULT_AGENTS_DIR = "./config/agents";
+/** Deprecated markdown location, read as a fallback with a one-time warning. */
+const LEGACY_MARKDOWN_DIR = "config/agents";
 /**
 * Decide whether a tool call must traverse the approval gate. Honours both
 * the modern `effect` field (mutating values: write / update / destructive)
@@ -70,6 +73,10 @@ var AgentsPlugin = class extends Plugin {
 	mcpClient = null;
 	threadStore;
 	approvalGate = new ToolApprovalGate();
+	/** Guards the `agents({ agents })` deprecation warning to once per instance. */
+	agentsMapDeprecationWarned = false;
+	/** Guards the `config/agents` deprecation warning to once per instance. */
+	configAgentsDeprecationWarned = false;
 	constructor(config) {
 		super(config);
 		this.config = config;
@@ -172,62 +179,159 @@ var AgentsPlugin = class extends Plugin {
 	* registry once this resolves successfully (atomic reload).
 	*/
 	async buildAgentRegistry() {
-		const { defs: fileDefs, defaultAgent: fileDefault } = await this.loadFileDefinitions();
-		const codeDefs = this.config.agents ?? {};
-		for (const name of Object.keys(fileDefs)) if (codeDefs[name]) logger.warn("Agent '%s' defined in both code and a markdown file. Code definition takes precedence.", name);
+		const discovered = await this.loadCodeAgents();
+		const deprecatedMapRaw = this.config.agents ?? {};
+		if (Object.keys(deprecatedMapRaw).length > 0) this.warnAgentsMapDeprecated();
+		const deprecatedMap = {};
+		for (const [id, def] of Object.entries(deprecatedMapRaw)) {
+			if (discovered[id]) {
+				logger.warn("Agent '%s' is both discovered in %s and passed to agents({ agents }). Using the discovered file; ignoring the map entry.", id, CODE_AGENTS_SOURCE_DIR);
+				continue;
+			}
+			deprecatedMap[id] = def;
+		}
+		const codeAgents = {
+			...discovered,
+			...deprecatedMap
+		};
+		const { defs: fileDefs, defaultAgent: fileDefault } = await this.loadFileDefinitions(codeAgents);
 		const merged = {};
 		for (const [name, def] of Object.entries(fileDefs)) merged[name] = {
 			def,
 			src: { origin: "file" }
 		};
-		for (const [name, def] of Object.entries(codeDefs)) merged[name] = {
-			def,
-			src: { origin: "code" }
-		};
+		for (const [name, def] of Object.entries(discovered)) {
+			if (merged[name]?.src.origin === "file") throw new Error(`Agent '${name}' is defined as both a code agent (agent.ts) and a markdown agent (agent.md) — in one folder, or across server/agents and the deprecated config/agents fallback. Keep a single kind per id. Available: ${Object.keys(merged).sort().join(", ")}`);
+			merged[name] = {
+				def,
+				src: { origin: "code" }
+			};
+		}
+		for (const [name, def] of Object.entries(deprecatedMap)) {
+			if (merged[name]?.src.origin === "file") logger.warn("Agent '%s' defined in both code and a markdown file. Code definition takes precedence.", name);
+			merged[name] = {
+				def,
+				src: { origin: "code" }
+			};
+		}
 		const agents = /* @__PURE__ */ new Map();
-		let defaultAgentName = null;
 		if (Object.keys(merged).length === 0) {
-			logger.info("No agents registered (no files in %s, no code-defined agents)", this.resolvedAgentsDir() ?? "<disabled>");
+			logger.info("No agents registered (no files in %s, no discovered or code-defined agents)", this.resolvedAgentsDir());
 			return {
 				agents,
-				defaultAgentName
+				defaultAgentName: null
 			};
 		}
 		for (const [name, { def, src }] of Object.entries(merged)) try {
-			const registered = await this.buildRegisteredAgent(name, def, src);
-			agents.set(name, registered);
-			if (!defaultAgentName) defaultAgentName = name;
+			agents.set(name, await this.buildRegisteredAgent(name, def, src));
 		} catch (err) {
 			throw new Error(`Failed to register agent '${name}' (${src.origin}): ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
 		}
-		if (this.config.defaultAgent) {
-			if (!agents.has(this.config.defaultAgent)) throw new Error(`defaultAgent '${this.config.defaultAgent}' is not registered. Available: ${Array.from(agents.keys()).join(", ")}`);
-			defaultAgentName = this.config.defaultAgent;
-		} else if (fileDefault && agents.has(fileDefault)) defaultAgentName = fileDefault;
 		return {
 			agents,
-			defaultAgentName
+			defaultAgentName: this.resolveDefaultAgent(agents, merged, fileDefault)
 		};
 	}
+	/**
+	* Resolves the default agent. Precedence: explicit `config.defaultAgent` >
+	* a code/discovered agent flagged `default: true` (stable id order) >
+	* markdown `default: true` > first registered (insertion order).
+	*/
+	resolveDefaultAgent(agents, merged, fileDefault) {
+		if (this.config.defaultAgent) {
+			if (!agents.has(this.config.defaultAgent)) throw new Error(`defaultAgent '${this.config.defaultAgent}' is not registered. Available: ${Array.from(agents.keys()).join(", ")}`);
+			return this.config.defaultAgent;
+		}
+		const codeDefault = Object.keys(merged).filter((id) => merged[id].src.origin === "code" && merged[id].def.default).sort()[0];
+		if (codeDefault) return codeDefault;
+		if (fileDefault && agents.has(fileDefault)) return fileDefault;
+		return agents.keys().next().value ?? null;
+	}
+	/**
+	* Emits the one-time deprecation warning for the `agents({ agents })` map.
+	* Guarded so `reload()` (which re-runs `buildAgentRegistry`) doesn't spam it.
+	*/
+	warnAgentsMapDeprecated() {
+		if (this.agentsMapDeprecationWarned) return;
+		this.agentsMapDeprecationWarned = true;
+		logger.warn("agents({ agents: { ... } }) is deprecated. Put each code agent in its own folder under server/agents/<id>/agent.ts (export default createAgent({ ... })) and it is discovered automatically — the call collapses to agents({ ... }) with no agent map. The `agents` field still works but will be removed in a future minor. See docs/plugins/agents.md.");
+	}
+	/**
+	* One-time deprecation warning for markdown agents still living in
+	* `config/agents/`. Guarded so `reload()` doesn't spam it.
+	*/
+	warnConfigAgentsDeprecated() {
+		if (this.configAgentsDeprecationWarned) return;
+		this.configAgentsDeprecationWarned = true;
+		logger.warn("Markdown agents under config/agents/ are deprecated. Move each config/agents/<id>/agent.md to server/agents/<id>/agent.md — every agent now lives in one place (server/agents). config/agents is still read for now but will be removed in a future minor. See docs/plugins/agents.md.");
+	}
 	resolvedAgentsDir() {
-		if (this.config.dir === false) return null;
-		const dir = this.config.dir ?? DEFAULT_AGENTS_DIR;
-		return path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
+		return path.resolve(process.cwd(), CODE_AGENTS_SOURCE_DIR);
 	}
-	async loadFileDefinitions() {
-		const dir = this.resolvedAgentsDir();
-		if (!dir) return {
-			defs: {},
-			defaultAgent: null
-		};
-		const pluginToolProviders = this.pluginProviderIndex();
-		const ambient = this.config.tools ?? {};
-		return await loadAgentsFromDir(dir, {
+	/**
+	* Discovers code agents (see {@link resolveCodeAgentsDir} and
+	* {@link loadCodeAgentsFromDir}). Warns if sources exist but nothing was
+	* discovered — usually the build didn't emit the compiled agents — unless
+	* the deprecated `agents({ agents })` map is carrying them instead.
+	*/
+	async loadCodeAgents() {
+		const resolved = resolveCodeAgentsDir({
+			cwd: process.cwd(),
+			exists: existsSync
+		});
+		const discovered = await loadCodeAgentsFromDir(resolved.dir, { extensions: resolved.extensions });
+		const usingDeprecatedMap = Object.keys(this.config.agents ?? {}).length > 0;
+		const sourceDir = this.resolvedAgentsDir();
+		if (Object.keys(discovered).length === 0 && !usingDeprecatedMap && this.hasCodeAgentSources(sourceDir)) logger.warn("Found code-agent sources in %s but discovered no code agents (scanned %s). In a production build, ensure `<dir>/*/agent.ts` is included as tsdown entries so the compiled agents are emitted.", sourceDir, resolved.dir);
+		return discovered;
+	}
+	/** True when `dir` holds at least one `<id>/agent.ts` folder. */
+	hasCodeAgentSources(dir) {
+		try {
+			return readdirSync(dir, { withFileTypes: true }).some((e) => {
+				if (!e.isDirectory() && !e.isSymbolicLink()) return false;
+				try {
+					return readdirSync(path.join(dir, e.name)).includes("agent.ts");
+				} catch {
+					return false;
+				}
+			});
+		} catch {
+			return false;
+		}
+	}
+	async loadFileDefinitions(codeAgents) {
+		const primaryDir = this.resolvedAgentsDir();
+		const baseCtx = {
 			defaultModel: this.config.defaultModel,
-			availableTools: ambient,
-			plugins: pluginToolProviders,
-			codeAgents: this.config.agents
+			availableTools: this.config.tools ?? {},
+			plugins: this.pluginProviderIndex()
+		};
+		const legacyDir = path.resolve(process.cwd(), LEGACY_MARKDOWN_DIR);
+		if (!existsSync(legacyDir)) return loadAgentsFromDir(primaryDir, {
+			...baseCtx,
+			codeAgents
+		});
+		const legacy = await loadAgentsFromDir(legacyDir, {
+			...baseCtx,
+			codeAgents
 		});
+		const primary = await loadAgentsFromDir(primaryDir, {
+			...baseCtx,
+			codeAgents: {
+				...legacy.defs,
+				...codeAgents
+			}
+		});
+		if (Object.keys(legacy.defs).length === 0) return primary;
+		this.warnConfigAgentsDeprecated();
+		return {
+			defs: {
+				...legacy.defs,
+				...primary.defs
+			},
+			defaultAgent: primary.defaultAgent ?? legacy.defaultAgent
+		};
 	}
 	/**
 	* Builds the map of plugin-name → toolkit that the markdown loader consults
@@ -1207,10 +1311,12 @@ function warnOnCapabilityMismatch(agentName, adapter, toolIndex) {
 	if (adapter.consumesInputTools === false && inputToolKeys.length > 0) logger.warn(`Agent '${agentName}' declares function tools / sub-agents / MCP tools (${inputToolKeys.join(", ")}) but its model adapter does not consume input.tools (Supervisor API owns its own tool loop). These tools will not be exposed to the model. See docs/plugins/agents.md.`);
 }
 /**
-* Plugin factory for the agents plugin. Reads `config/agents/*.md` by default,
-* resolves toolkits/tools from registered plugins, exposes `appkit.agents.*`
-* runtime API and mounts `POST /invocations` and `POST /responses` (aliased
-* non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable).
+* Plugin factory for the agents plugin. Discovers agents from
+* `server/agents/<id>/agent.{ts,md}` by default (markdown still in
+* `config/agents/` is read as a deprecated fallback), resolves toolkits/tools
+* from registered plugins, exposes the `appkit.agents.*` runtime API and mounts
+* `POST /invocations` and `POST /responses` (aliased non-streaming invoke
+* endpoints) plus `POST /chat` (streaming, HITL-capable).
 *
 * @example
 * ```ts