@databricks/appkit 0.63.0 → 0.65.0

package/dist/tsdown/index.d.ts

@@ -0,0 +1,58 @@
+//#region src/tsdown/index.d.ts
+/**
+ * `@databricks/appkit/tsdown` — the server build preset.
+ *
+ * A scaffolded app's `tsdown.server.config.ts` is a single line:
+ *
+ * ```ts
+ * import { appkitServerConfig } from "@databricks/appkit/tsdown";
+ * export default appkitServerConfig();
+ * ```
+ *
+ * so the agent-discovery build wiring lives in the package and reaches existing
+ * apps on upgrade, instead of being hand-maintained in every scaffold. The
+ * returned object is a plain tsdown config (no `defineConfig` wrapper needed).
+ *
+ * This module is intentionally dependency-free (only `node:` builtins) — it is
+ * loaded at build time and must not pull in the runtime SDK.
+ */
+/** The tsdown options this preset sets. A structural subset of tsdown's config. */
+interface ServerBuildConfig {
+  entry?: string | string[];
+  unbundle?: boolean;
+  clean?: boolean;
+  external?: (id: string) => boolean;
+  outExtensions?: () => {
+    js: string;
+  };
+  tsconfig?: string;
+  /** Any other tsdown option passes through untouched. */
+  [key: string]: unknown;
+}
+/**
+ * Overrides accepted by {@link appkitServerConfig}: either a partial config
+ * (merged — `entry` is unioned, `external` composed, other keys win) or a
+ * function that receives AppKit's computed base config for full control.
+ */
+type ServerConfigOverrides = ServerBuildConfig | ((base: ServerBuildConfig) => ServerBuildConfig);
+/**
+ * The server tsdown config, merging AppKit's required wiring with `overrides`.
+ *
+ * Object overrides merge with intent, not a blind spread:
+ *   - `entry` is UNIONed — the agent glob can't be dropped by an override;
+ *   - `external` is COMPOSED — the caller's predicate runs alongside AppKit's;
+ *   - every other key wins.
+ * A function override instead receives the computed base and returns the final
+ * config, for callers that need full control (including removing the glob).
+ *
+ * The agent entry + `clean` are included only when `server/agents/` actually
+ * holds code agents, so the same call works for every app. Pass
+ * `opts.codeAgents` to force that decision (e.g. a non-standard layout).
+ */
+declare function appkitServerConfig(overrides?: ServerConfigOverrides, opts?: {
+  cwd?: string;
+  codeAgents?: boolean;
+}): ServerBuildConfig;
+//#endregion
+export { ServerBuildConfig, ServerConfigOverrides, appkitServerConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/tsdown/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/tsdown/index.ts"],"mappings":";;AAsBA;;;;;;;;;;;;;;;AAgBA;;UAhBiB,iBAAA;EACf,KAAA;EACA,QAAA;EACA,KAAA;EACA,QAAA,IAAY,EAAA;EACZ,aAAA;IAAwB,EAAA;EAAA;EACxB,QAAA;EAYgC;EAAA,CAV/B,GAAA;AAAA;AAkEH;;;;;AAAA,KA1DY,qBAAA,GACR,iBAAA,KACE,IAAA,EAAM,iBAAA,KAAsB,iBAAA;;;;;;;;;;;;;;;iBAwDlB,kBAAA,CACd,SAAA,GAAW,qBAAA,EACX,IAAA;EAAQ,GAAA;EAAc,UAAA;AAAA,IACrB,iBAAA"}

package/dist/tsdown/index.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { readdirSync } from "node:fs";
+
+//#region src/tsdown/index.ts
+const SERVER_ENTRY = "server/server.ts";
+const AGENT_ENTRY = "server/agents/*/agent.ts";
+/** AppKit default: keep anything resolving outside the project out of the bundle. */
+const defaultExternal = (id) => /^[^./]/.test(id) || id.includes("/node_modules/");
+function toEntryArray(entry) {
+	if (entry === void 0) return [];
+	return Array.isArray(entry) ? entry : [entry];
+}
+/** True when `server/agents/` holds at least one `<id>/agent.ts` (a code agent). */
+function hasCodeAgents(cwd) {
+	const root = path.join(cwd, "server", "agents");
+	try {
+		return readdirSync(root, { withFileTypes: true }).some((e) => {
+			if (!e.isDirectory() && !e.isSymbolicLink()) return false;
+			try {
+				return readdirSync(path.join(root, e.name)).includes("agent.ts");
+			} catch {
+				return false;
+			}
+		});
+	} catch {
+		return false;
+	}
+}
+/** AppKit's base server config, with the agent entry + `clean` only when needed. */
+function baseConfig(codeAgents) {
+	return {
+		entry: [SERVER_ENTRY, ...codeAgents ? [AGENT_ENTRY] : []],
+		unbundle: true,
+		external: defaultExternal,
+		outExtensions: () => ({ js: ".js" }),
+		...codeAgents ? { clean: true } : {}
+	};
+}
+/**
+* The server tsdown config, merging AppKit's required wiring with `overrides`.
+*
+* Object overrides merge with intent, not a blind spread:
+*   - `entry` is UNIONed — the agent glob can't be dropped by an override;
+*   - `external` is COMPOSED — the caller's predicate runs alongside AppKit's;
+*   - every other key wins.
+* A function override instead receives the computed base and returns the final
+* config, for callers that need full control (including removing the glob).
+*
+* The agent entry + `clean` are included only when `server/agents/` actually
+* holds code agents, so the same call works for every app. Pass
+* `opts.codeAgents` to force that decision (e.g. a non-standard layout).
+*/
+function appkitServerConfig(overrides = {}, opts = {}) {
+	const cwd = opts.cwd ?? process.cwd();
+	const base = baseConfig(opts.codeAgents ?? hasCodeAgents(cwd));
+	if (typeof overrides === "function") return overrides(base);
+	const baseEntries = toEntryArray(base.entry);
+	const entry = [...baseEntries, ...toEntryArray(overrides.entry).filter((e) => !baseEntries.includes(e))];
+	const userExternal = overrides.external;
+	const external = userExternal ? (id) => defaultExternal(id) || userExternal(id) : defaultExternal;
+	return {
+		...base,
+		...overrides,
+		entry,
+		external
+	};
+}
+
+//#endregion
+export { appkitServerConfig };
+//# sourceMappingURL=index.js.map

package/dist/tsdown/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/tsdown/index.ts"],"sourcesContent":["import { readdirSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/**\n * `@databricks/appkit/tsdown` — the server build preset.\n *\n * A scaffolded app's `tsdown.server.config.ts` is a single line:\n *\n * ```ts\n * import { appkitServerConfig } from \"@databricks/appkit/tsdown\";\n * export default appkitServerConfig();\n * ```\n *\n * so the agent-discovery build wiring lives in the package and reaches existing\n * apps on upgrade, instead of being hand-maintained in every scaffold. The\n * returned object is a plain tsdown config (no `defineConfig` wrapper needed).\n *\n * This module is intentionally dependency-free (only `node:` builtins) — it is\n * loaded at build time and must not pull in the runtime SDK.\n */\n\n/** The tsdown options this preset sets. A structural subset of tsdown's config. */\nexport interface ServerBuildConfig {\n  entry?: string | string[];\n  unbundle?: boolean;\n  clean?: boolean;\n  external?: (id: string) => boolean;\n  outExtensions?: () => { js: string };\n  tsconfig?: string;\n  /** Any other tsdown option passes through untouched. */\n  [key: string]: unknown;\n}\n\n/**\n * Overrides accepted by {@link appkitServerConfig}: either a partial config\n * (merged — `entry` is unioned, `external` composed, other keys win) or a\n * function that receives AppKit's computed base config for full control.\n */\nexport type ServerConfigOverrides =\n  | ServerBuildConfig\n  | ((base: ServerBuildConfig) => ServerBuildConfig);\n\nconst SERVER_ENTRY = \"server/server.ts\";\nconst AGENT_ENTRY = \"server/agents/*/agent.ts\";\n\n/** AppKit default: keep anything resolving outside the project out of the bundle. */\nconst defaultExternal = (id: string): boolean =>\n  /^[^./]/.test(id) || id.includes(\"/node_modules/\");\n\nfunction toEntryArray(entry: string | string[] | undefined): string[] {\n  if (entry === undefined) return [];\n  return Array.isArray(entry) ? entry : [entry];\n}\n\n/** True when `server/agents/` holds at least one `<id>/agent.ts` (a code agent). */\nfunction hasCodeAgents(cwd: string): boolean {\n  const root = path.join(cwd, \"server\", \"agents\");\n  try {\n    return readdirSync(root, { withFileTypes: true }).some((e) => {\n      if (!e.isDirectory() && !e.isSymbolicLink()) return false;\n      try {\n        return readdirSync(path.join(root, e.name)).includes(\"agent.ts\");\n      } catch {\n        return false;\n      }\n    });\n  } catch {\n    return false;\n  }\n}\n\n/** AppKit's base server config, with the agent entry + `clean` only when needed. */\nfunction baseConfig(codeAgents: boolean): ServerBuildConfig {\n  return {\n    entry: [SERVER_ENTRY, ...(codeAgents ? [AGENT_ENTRY] : [])],\n    unbundle: true,\n    external: defaultExternal,\n    outExtensions: () => ({ js: \".js\" }),\n    ...(codeAgents ? { clean: true } : {}),\n  };\n}\n\n/**\n * The server tsdown config, merging AppKit's required wiring with `overrides`.\n *\n * Object overrides merge with intent, not a blind spread:\n *   - `entry` is UNIONed — the agent glob can't be dropped by an override;\n *   - `external` is COMPOSED — the caller's predicate runs alongside AppKit's;\n *   - every other key wins.\n * A function override instead receives the computed base and returns the final\n * config, for callers that need full control (including removing the glob).\n *\n * The agent entry + `clean` are included only when `server/agents/` actually\n * holds code agents, so the same call works for every app. Pass\n * `opts.codeAgents` to force that decision (e.g. a non-standard layout).\n */\nexport function appkitServerConfig(\n  overrides: ServerConfigOverrides = {},\n  opts: { cwd?: string; codeAgents?: boolean } = {},\n): ServerBuildConfig {\n  const cwd = opts.cwd ?? process.cwd();\n  const codeAgents = opts.codeAgents ?? hasCodeAgents(cwd);\n  const base = baseConfig(codeAgents);\n\n  if (typeof overrides === \"function\") return overrides(base);\n\n  const baseEntries = toEntryArray(base.entry);\n  const entry = [\n    ...baseEntries,\n    ...toEntryArray(overrides.entry).filter((e) => !baseEntries.includes(e)),\n  ];\n\n  const userExternal = overrides.external;\n  const external = userExternal\n    ? (id: string): boolean => defaultExternal(id) || userExternal(id)\n    : defaultExternal;\n\n  return { ...base, ...overrides, entry, external };\n}\n"],"mappings":";;;;AA0CA,MAAM,eAAe;AACrB,MAAM,cAAc;;AAGpB,MAAM,mBAAmB,OACvB,SAAS,KAAK,GAAG,IAAI,GAAG,SAAS,iBAAiB;AAEpD,SAAS,aAAa,OAAgD;AACpE,KAAI,UAAU,OAAW,QAAO,EAAE;AAClC,QAAO,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM;;;AAI/C,SAAS,cAAc,KAAsB;CAC3C,MAAM,OAAO,KAAK,KAAK,KAAK,UAAU,SAAS;AAC/C,KAAI;AACF,SAAO,YAAY,MAAM,EAAE,eAAe,MAAM,CAAC,CAAC,MAAM,MAAM;AAC5D,OAAI,CAAC,EAAE,aAAa,IAAI,CAAC,EAAE,gBAAgB,CAAE,QAAO;AACpD,OAAI;AACF,WAAO,YAAY,KAAK,KAAK,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,WAAW;WAC1D;AACN,WAAO;;IAET;SACI;AACN,SAAO;;;;AAKX,SAAS,WAAW,YAAwC;AAC1D,QAAO;EACL,OAAO,CAAC,cAAc,GAAI,aAAa,CAAC,YAAY,GAAG,EAAE,CAAE;EAC3D,UAAU;EACV,UAAU;EACV,sBAAsB,EAAE,IAAI,OAAO;EACnC,GAAI,aAAa,EAAE,OAAO,MAAM,GAAG,EAAE;EACtC;;;;;;;;;;;;;;;;AAiBH,SAAgB,mBACd,YAAmC,EAAE,EACrC,OAA+C,EAAE,EAC9B;CACnB,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK;CAErC,MAAM,OAAO,WADM,KAAK,cAAc,cAAc,IAAI,CACrB;AAEnC,KAAI,OAAO,cAAc,WAAY,QAAO,UAAU,KAAK;CAE3D,MAAM,cAAc,aAAa,KAAK,MAAM;CAC5C,MAAM,QAAQ,CACZ,GAAG,aACH,GAAG,aAAa,UAAU,MAAM,CAAC,QAAQ,MAAM,CAAC,YAAY,SAAS,EAAE,CAAC,CACzE;CAED,MAAM,eAAe,UAAU;CAC/B,MAAM,WAAW,gBACZ,OAAwB,gBAAgB,GAAG,IAAI,aAAa,GAAG,GAChE;AAEJ,QAAO;EAAE,GAAG;EAAM,GAAG;EAAW;EAAO;EAAU"}

package/docs/api/appkit/Function.createAgent.md

@@ -5,9 +5,7 @@ function createAgent(def: AgentDefinition): AgentDefinition;
 
 ```
 
-Pure factory for agent definitions. Returns the passed-in definition after cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape and is safe to call at module top-level.
-
-The returned value is a plain `AgentDefinition` — no adapter construction, no side effects. Register it with `agents({ agents: { name: def } })` or run it standalone via `runAgent(def, input)`.
+Pure factory for agent definitions: cycle-detects the sub-agent graph and returns the same object, stamped with a non-enumerable AGENT\_BRAND so discovery recognizes it. Safe at module top-level; no adapter is built. Don't `Object.freeze` the definition before passing it in — the brand is written onto the argument.
 
 ## Parameters[​](#parameters "Direct link to Parameters")
 

package/docs/api/appkit/Function.defineManifest.md

@@ -0,0 +1,32 @@
+# Function: defineManifest()
+
+```ts
+function defineManifest<TName>(manifest: unknown): PluginManifest<TName>;
+
+```
+
+Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md).
+
+Plugins declare `static manifest = defineManifest<"my-plugin">(manifestJson)` instead of casting. A plain `as PluginManifest` can't work: a JSON import widens every field to `string`, and `PluginManifest.resources[].type` is the nominal `ResourceType` enum, so the structural JSON shape never assigns. The single internal assertion here bridges that gap in one audited place — after `parse()` has confirmed the values are real `ResourceType`/permission strings — rather than every plugin repeating `as unknown as PluginManifest`.
+
+Pass the plugin name as `TName` so the literal is preserved: `toPlugin` derives the typed plugin key from `manifest.name`, and a widened `string` there would collapse the typed plugin registry.
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter             | Default type |
+| -------------------------- | ------------ |
+| `TName` *extends* `string` | `string`     |
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type      |
+| ---------- | --------- |
+| `manifest` | `unknown` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`PluginManifest`](./docs/api/appkit/Interface.PluginManifest.md)<`TName`>
+
+## Throws[​](#throws "Direct link to Throws")
+
+If the manifest doesn't match the schema.

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -24,6 +24,17 @@ Override the plugin's baseSystemPrompt for this agent only.
 
 ***
 
+### default?[​](#default "Direct link to default?")
+
+```ts
+optional default: boolean;
+
+```
+
+Marks this agent as the default one chosen when a client doesn't name an agent. Mirrors markdown frontmatter `default: true`. When several agents set it, a code (discovered) agent wins over a markdown one, then the lowest id; an explicit `agents({ defaultAgent })` always overrides it. Defaults to `false`.
+
+***
+
 ### ephemeral?[​](#ephemeral "Direct link to ephemeral?")
 
 ```ts
@@ -96,7 +107,7 @@ optional name: string;
 
 ```
 
-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.
+Stable identifier for the agent. **Optional and informational** — when the definition is registered via `agents: { foo: def }` (code) or lives at `server/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:
 

package/docs/api/appkit/Interface.AgentsPluginConfig.md

@@ -15,14 +15,16 @@ Base configuration interface for AppKit plugins
 
 ## Properties[​](#properties "Direct link to Properties")
 
-### agents?[​](#agents "Direct link to agents?")
+### ~~agents?~~[​](#agents "Direct link to agents")
 
 ```ts
 optional agents: Record<string, AgentDefinition>;
 
 ```
 
-Code-defined agents, merged with file-loaded ones (code wins on key collision).
+#### Deprecated[​](#deprecated "Direct link to Deprecated")
+
+Put each code agent in its own folder under `server/agents/<id>/agent.ts` (`export default createAgent({ ... })`); it is discovered automatically at startup and the call collapses to `agents({ ... })` with no map. Still honored for backward compatibility (emits a one-time deprecation warning) but will be removed in a future minor. If both discovery and this map define the same id, discovery wins and the map entry is ignored.
 
 ***
 
@@ -36,7 +38,7 @@ optional approval: {
 
 ```
 
-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 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.
+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 whose annotation flags it as mutating — `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean — and waits for a `POST /api/agents/approve` decision from the same user who initiated the stream. A missing decision after `timeoutMs` auto-denies the call.
 
 #### requireForDestructive?[​](#requirefordestructive "Direct link to requireForDestructive?")
 
@@ -89,7 +91,7 @@ optional defaultAgent: string;
 
 ```
 
-Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter.
+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.
 
 ***
 
@@ -107,17 +109,6 @@ Default model for agents that don't specify their own (in code or frontmatter).
 
 ***
 
-### dir?[​](#dir "Direct link to dir?")
-
-```ts
-optional dir: string | false;
-
-```
-
-Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable.
-
-***
-
 ### host?[​](#host "Direct link to host?")
 
 ```ts

package/docs/api/appkit/TypeAlias.AgentEvent.md

@@ -296,4 +296,4 @@ type: "approval_pending";
 
 ```
 
-Emitted by the agents plugin (not adapters) when a mutating tool call is awaiting human approval — fires for tools annotated with `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean. Clients should render an approval prompt and POST to `/chat/approve` with the matching `approvalId` and a `decision` of `approve` or `deny`.
+Emitted by the agents plugin (not adapters) when a mutating tool call is awaiting human approval — fires for tools annotated with `effect: "write" | "update" | "destructive"` (preferred) or the legacy `destructive: true` boolean. Clients should render an approval prompt and POST to `/api/agents/approve` with the matching `approvalId` and a `decision` of `approve` or `deny`.

package/docs/api/appkit/Variable.agents.md

@@ -1,11 +1,11 @@
 # Variable: agents
 
 ```ts
-const agents: ToPlugin<typeof AgentsPlugin, AgentsPluginConfig, string>;
+const agents: ToPlugin<typeof AgentsPlugin, AgentsPluginConfig, "agents">;
 
 ```
 
-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[​](#example "Direct link to Example")
 

package/docs/api/appkit.md

@@ -124,52 +124,53 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 
 ## Variables[​](#variables "Direct link to Variables")
 
-| Variable                                                                                   | Description                                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [agents](./docs/api/appkit/Variable.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). |
-| [aiSearch](./docs/api/appkit/Variable.aiSearch.md)                                   | -                                                                                                                                                                                                                                                                                                              |
-| [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md)                          | Actions that only read data.                                                                                                                                                                                                                                                                                   |
-| [sql](./docs/api/appkit/Variable.sql.md)                                             | SQL helper namespace                                                                                                                                                                                                                                                                                           |
-| [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.                          |
-| [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md)                     | Concise factories for declaring Supervisor API tools.                                                                                                                                                                                                                                                          |
-| [WRITE\_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md)                        | Actions that mutate data.                                                                                                                                                                                                                                                                                      |
+| Variable                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [agents](./docs/api/appkit/Variable.agents.md)                                       | 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). |
+| [aiSearch](./docs/api/appkit/Variable.aiSearch.md)                                   | -                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md)                          | Actions that only read data.                                                                                                                                                                                                                                                                                                                                                                                           |
+| [sql](./docs/api/appkit/Variable.sql.md)                                             | SQL helper namespace                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.                                                                                                                                  |
+| [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md)                     | Concise factories for declaring Supervisor API tools.                                                                                                                                                                                                                                                                                                                                                                  |
+| [WRITE\_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md)                        | Actions that mutate data.                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ## Functions[​](#functions "Direct link to Functions")
 
-| Function                                                                                     | Description                                                                                                                                                                                                                                                                                   |
-| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [agentIdFromMarkdownPath](./docs/api/appkit/Function.agentIdFromMarkdownPath.md)       | Derives the logical agent id from a markdown path. When the file is named `agent.md`, the id is the parent directory name (folder-based layout); otherwise the id is the file stem (e.g. legacy single-file paths).                                                                           |
-| [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md)     | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.                                                                                                        |
-| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                                                                                                                                                                |
-| [createAgent](./docs/api/appkit/Function.createAgent.md)                               | Pure factory for agent definitions. Returns the passed-in definition after cycle-detecting the sub-agent graph. Accepts the full `AgentDefinition` shape and is safe to call at module top-level.                                                                                             |
-| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                                                                                                                                                                            |
-| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                                                                                               |
-| [createLakebasePoolManager](./docs/api/appkit/Function.createLakebasePoolManager.md)   | Create a pool manager that maintains per-key Lakebase connection pools.                                                                                                                                                                                                                       |
-| [createWorkspaceClient](./docs/api/appkit/Function.createWorkspaceClient.md)           | Construct an AppKit workspace client.                                                                                                                                                                                                                                                         |
-| [defineTool](./docs/api/appkit/Function.defineTool.md)                                 | Defines a single tool entry for a plugin's internal registry.                                                                                                                                                                                                                                 |
-| [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md)               | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn.                                       |
-| [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.                                                                 |
-| [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                                                                                              |
-| [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md)                   | Creates an [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).                                                                                                                           |
-| [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md)     | -                                                                                                                                                                                                                                                                                             |
-| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                                                                                    |
-| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                                                                                            |
-| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                                                                                            |
-| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                                                                                 |
-| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                                                                                      |
-| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                                                                                      |
-| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                                                                                   |
-| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                                                                                    |
-| [isFunctionTool](./docs/api/appkit/Function.isFunctionTool.md)                         | -                                                                                                                                                                                                                                                                                             |
-| [isHostedTool](./docs/api/appkit/Function.isHostedTool.md)                             | -                                                                                                                                                                                                                                                                                             |
-| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                                                                                           |
-| [isSupervisorTool](./docs/api/appkit/Function.isSupervisorTool.md)                     | Type guard for [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md). Used by the agents plugin (`buildToolIndex`) and standalone `runAgent` (`classifyTool`) to route supervisor-hosted tools to the extensions payload rather than the adapter's `tools` array. |
-| [isToolkitEntry](./docs/api/appkit/Function.isToolkitEntry.md)                         | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record.                                                                                                                                                    |
-| [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md)                   | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.                                                                                                                                                                    |
-| [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md)                   | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist.         |
-| [mcpServer](./docs/api/appkit/Function.mcpServer.md)                                   | Factory for declaring a custom MCP server tool.                                                                                                                                                                                                                                               |
-| [parseTextToolCalls](./docs/api/appkit/Function.parseTextToolCalls.md)                 | Parses text-based tool calls from model output.                                                                                                                                                                                                                                               |
-| [resolveHostedTools](./docs/api/appkit/Function.resolveHostedTools.md)                 | -                                                                                                                                                                                                                                                                                             |
-| [runAgent](./docs/api/appkit/Function.runAgent.md)                                     | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion.                                                                                                                                                |
-| [tool](./docs/api/appkit/Function.tool.md)                                             | Factory for defining function tools with Zod schemas.                                                                                                                                                                                                                                         |
-| [toolsFromRegistry](./docs/api/appkit/Function.toolsFromRegistry.md)                   | Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema.                                                                                                                                                       |
+| Function                                                                                     | Description                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [agentIdFromMarkdownPath](./docs/api/appkit/Function.agentIdFromMarkdownPath.md)       | Derives the logical agent id from a markdown path. When the file is named `agent.md`, the id is the parent directory name (folder-based layout); otherwise the id is the file stem (e.g. legacy single-file paths).                                                                                                          |
+| [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md)     | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.                                                                                                                                       |
+| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                                                                                                                                                                                               |
+| [createAgent](./docs/api/appkit/Function.createAgent.md)                               | Pure factory for agent definitions: cycle-detects the sub-agent graph and returns the same object, stamped with a non-enumerable AGENT\_BRAND so discovery recognizes it. Safe at module top-level; no adapter is built. Don't `Object.freeze` the definition before passing it in — the brand is written onto the argument. |
+| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                                                                                                                                                                                                           |
+| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                                                                                                                              |
+| [createLakebasePoolManager](./docs/api/appkit/Function.createLakebasePoolManager.md)   | Create a pool manager that maintains per-key Lakebase connection pools.                                                                                                                                                                                                                                                      |
+| [createWorkspaceClient](./docs/api/appkit/Function.createWorkspaceClient.md)           | Construct an AppKit workspace client.                                                                                                                                                                                                                                                                                        |
+| [defineManifest](./docs/api/appkit/Function.defineManifest.md)                         | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md).                                                                                                                             |
+| [defineTool](./docs/api/appkit/Function.defineTool.md)                                 | Defines a single tool entry for a plugin's internal registry.                                                                                                                                                                                                                                                                |
+| [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md)               | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn.                                                                      |
+| [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.                                                                                                |
+| [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                                                                                                                             |
+| [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md)                   | Creates an [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) backed by the Databricks AI Gateway Responses API (`/ai-gateway/mlflow/v1/responses`).                                                                                                                                                          |
+| [functionToolToDefinition](./docs/api/appkit/Function.functionToolToDefinition.md)     | -                                                                                                                                                                                                                                                                                                                            |
+| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                                                                                                                   |
+| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                                                                                                                           |
+| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                                                                                                                           |
+| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                                                                                                                |
+| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                                                                                                                     |
+| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                                                                                                                     |
+| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                                                                                                                  |
+| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                                                                                                                   |
+| [isFunctionTool](./docs/api/appkit/Function.isFunctionTool.md)                         | -                                                                                                                                                                                                                                                                                                                            |
+| [isHostedTool](./docs/api/appkit/Function.isHostedTool.md)                             | -                                                                                                                                                                                                                                                                                                                            |
+| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                                                                                                                          |
+| [isSupervisorTool](./docs/api/appkit/Function.isSupervisorTool.md)                     | Type guard for [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md). Used by the agents plugin (`buildToolIndex`) and standalone `runAgent` (`classifyTool`) to route supervisor-hosted tools to the extensions payload rather than the adapter's `tools` array.                                |
+| [isToolkitEntry](./docs/api/appkit/Function.isToolkitEntry.md)                         | Type guard for `ToolkitEntry` — used by the agents plugin to differentiate toolkit references from inline tools in a mixed `tools` record.                                                                                                                                                                                   |
+| [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md)                   | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.                                                                                                                                                                                                   |
+| [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md)                   | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist.                                        |
+| [mcpServer](./docs/api/appkit/Function.mcpServer.md)                                   | Factory for declaring a custom MCP server tool.                                                                                                                                                                                                                                                                              |
+| [parseTextToolCalls](./docs/api/appkit/Function.parseTextToolCalls.md)                 | Parses text-based tool calls from model output.                                                                                                                                                                                                                                                                              |
+| [resolveHostedTools](./docs/api/appkit/Function.resolveHostedTools.md)                 | -                                                                                                                                                                                                                                                                                                                            |
+| [runAgent](./docs/api/appkit/Function.runAgent.md)                                     | Standalone agent execution without `createApp`. Resolves the adapter, binds inline tools, and drives the adapter's `run()` loop to completion.                                                                                                                                                                               |
+| [tool](./docs/api/appkit/Function.tool.md)                                             | Factory for defining function tools with Zod schemas.                                                                                                                                                                                                                                                                        |
+| [toolsFromRegistry](./docs/api/appkit/Function.toolsFromRegistry.md)                   | Produces the `AgentToolDefinition[]` a ToolProvider exposes to the LLM, deriving `parameters` JSON Schema from each entry's Zod schema.                                                                                                                                                                                      |