feat(appkit): auto-discover code agents from server/agents/

[MarioCadenas]

What

Every agent is now a folder under server/agents/<id>/, discovered at startup — agent.md for a markdown agent, agent.ts (export default createAgent(...)) for a code agent. The folder name is the id, so the plugin call collapses to agents() with no map and no imports, and neither form restates its id.

- // server/agents/helper.ts
- export const helper = createAgent({ name: 'helper', instructions, tools });
- // server/server.ts
- import { helper } from './agents/helper';
- agents({ agents: { helper } })            // id restated; hand-built map
+ // server/agents/helper/agent.ts          ← id IS the folder name
+ export default createAgent({ instructions, tools });
+ // server/server.ts
+ agents()                                  // no import, no map

Markdown and code agents live side by side under the same root; a markdown agent.md and code agent.ts are just two entry-file kinds.

How

• server/agents is a fixed convention, not a config knob. There is no dir option to relocate the root — the build glob and the runtime scan reference the same constant, so they can't disagree about where agents live. (Discovery has no disable toggle either; a map-only app simply has no server/agents/ folder.)
• Code: built-first resolution (NODE_ENV-independent). Compiled output wins over source, so a bundled server never import()s a .ts (plain Node can't). Dev (tsx) loads server/agents/<id>/agent.ts; a build loads the compiled dist/agents/<id>/agent.js (or build/agents).
• Markdown: read from source in both dev and prod (it's data, not compiled).
• Branded detection. createAgent stamps a non-enumerable Symbol.for("appkit.agent"); the loader keeps branded exports and skips helpers/chunks. A folder is an agent iff it holds agent.md or agent.ts; one holding both errors at boot (one kind per id).
• Prod bundling (the trap this avoids). A runtime scan of a dynamic path is dropped by the bundler, so the build lists server/agents/*/agent.ts as entries and the compiled dist/agents/*/agent.js exist for the scan. That wiring now ships in the package (below), not hand-copied into every scaffold.

New: @databricks/appkit/tsdown build preset

A scaffolded app's tsdown.server.config.ts is a one-liner:

import { appkitServerConfig } from '@databricks/appkit/tsdown';
export default appkitServerConfig();

appkitServerConfig() auto-detects server/agents/ and adds the entry glob + clean only when code agents exist; object overrides merge with intent (entry unioned so the glob can't be dropped, external composed), and a function form gives full control. The build wiring lives in the package, so it reaches existing apps on upgrade instead of being maintained per-scaffold.

Backward compatibility

• Markdown still under config/agents/ is read as a deprecated fallback — merged per-agent with server/agents (new location wins on an id clash), with a one-time deprecation warning. Cross-location sub-agent refs resolve one direction (a parent moved to server/agents can reference a child still in config/agents).
• agents({ agents: { ... } }) map still works, one-time deprecation warning; discovery wins on an id clash.
• createAgent({ name }) still honored (the registry key wins).
• Cross-kind sub-agents: a markdown parent can delegate to a code sibling folder and vice versa, resolved by folder id.

Also in this PR

• Migrates the dev-playground (8 agents → server/agents/<id>/ folders) and the template (helper/agent.ts + planner/agent.md, tsdown one-liner).
• Docs: rewrites the agents plugin page for the folder model and adds an "Adding agents to an existing app" section (markdown = no build change; code = adopt the preset).
• Removes the dir config option entirely — server/agents is a fixed convention (this also retires the never-shipped codeAgentsDir knob). config/agents remains a read-only deprecated fallback.

Verification

• pnpm -r typecheck clean · oxlint + oxfmt clean · appkit 3246 tests pass · pnpm build + pnpm docs:build succeed.
• E2E against the packed tarball (databricks-appkit-0.62.0.tgz) in a fresh app installed from the .tgz:
  • preset build emits dist/agents/<id>/agent.js exactly where the runtime probes;
  • dev (tsx, source .ts) and prod (node, compiled .js — no TS loader) both discover the code agent, the markdown agent, and the config/agents fallback (deprecation warning fires);
  • dir is absent from the published types.d.ts; ./tsdown + ./beta exports resolve.

Notes

• agents is a beta plugin (@databricks/appkit/beta) — the config-surface changes ride the beta stability tier.
• The Agent Skills PR (feat(appkit): Agent Skills (v1) — SKILL.md progressive disclosure for agents #532) is stacked on this branch and merges after it.

[github-actions]

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 887 KB (+14 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	905 KB (+13 KB)	317 KB (+5.1 KB)
Type declarations	344 KB (+4.3 KB)	120 KB (+1.8 KB)
Source maps	1.8 MB (+25 KB)	596 KB (+9.5 KB)
Other	11 KB	3.7 KB
Total	3.0 MB (+42 KB)	1.0 MB (+16 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	88 KB	2.5 KB	91 KB	external	288 KB
./beta	50 KB (+1.7 KB)	457 B	51 KB (+1.7 KB)	external	147 KB (+4.3 KB)
./testing	17 KB	0 B	17 KB	external	50 KB
./tsdown	520 B	0 B	520 B	external	813 B
./type-generator	21 KB	0 B	21 KB	external	61 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	84 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	34 KB
./beta	stream-manager.js	initial	5.8 KB
./beta	wide-event-emitter.js	initial	3.2 KB
./beta	databricks.js	initial	3.0 KB
./beta	configuration.js	initial	2.1 KB
./beta	service-context.js	initial	1.3 KB
./beta	client.js	initial	434 B
./beta	client-options.js	initial	220 B
./beta	supervisor-api.js	lazy	192 B
./beta	databricks.js	lazy	142 B
./beta	index.js	lazy	123 B
./testing	index.js	initial	17 KB
./tsdown	index.js	initial	520 B
./type-generator	index.js	initial	21 KB

@databricks/appkit-ui

npm tarball (packed): 348 KB (+2 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	394 KB	132 KB
Type declarations	228 KB	83 KB
Source maps	764 KB	252 KB
CSS	16 KB	3.2 KB
Total	1.4 MB	471 KB

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	5.3 KB	49 KB	55 KB	208 KB	14 KB
./js/beta	20 B	0 B	20 B	0 B	0 B
./react	432 KB	49 KB	481 KB	1.3 MB	177 KB
./react/beta	1.0 KB	0 B	1.0 KB	0 B	1.9 KB

Chunks:

Entry	Chunk	Load	Size (gz)
./js	index.js	initial	5.2 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	20 B
./react	index.js	initial	430 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	1.0 KB

[github-actions]

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 32393214595 -R databricks/appkit -n appkit-template-0.63.0-pr.440c3a5-agents-discovery-dx-533 -D appkit-pr-533 \
  && unzip -o "appkit-pr-533/appkit-template-0.63.0-pr.440c3a5-agents-discovery-dx-533.zip" -d "appkit-pr-533" \
  && databricks apps init --template "appkit-pr-533"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.