feat(appkit): agents() plugin, createAgent(def), and markdown-driven agents

[MarioCadenas]

The main product layer. Turns an AppKit app into an AI-agent host with
markdown-driven agent discovery, code-defined agents, sub-agents,
human-in-the-loop approval, zero-trust MCP, and a standalone
run-without-HTTP executor.

createAgent(def) — pure factory

packages/appkit/src/core/create-agent-def.ts. Returns the passed-in
definition after cycle-detecting the sub-agent graph. No adapter
construction, no side effects — safe at module top-level. The returned
AgentDefinition is plain data, consumable by either agents({ agents })
or runAgent(def, input).

agents() plugin

packages/appkit/src/plugins/agents/agents.ts. AgentsPlugin class:

• Loads markdown agents from config/agents/*.md (configurable dir)
  via real YAML frontmatter parsing (js-yaml). Frontmatter schema:
  endpoint, model, toolkits, tools, agents, default,
  maxSteps, maxTokens, baseSystemPrompt, ephemeral. Unknown
  keys logged, invalid YAML throws at boot.
• Merges code-defined agents passed via agents({ agents: { name: def } }).
  Code wins on key collision.
• For each agent, builds a per-agent tool index from:
  1. Sub-agents (agents: frontmatter or agents: code field) —
     synthesized as agent-<key> tools on the parent. Markdown
     agents: [...] resolves against both markdown siblings and
     code-defined agents passed via LoadContext.codeAgents, so a
     markdown orchestrator can delegate to a code-defined specialist.
  2. Explicit tool record entries — ToolkitEntrys, inline
     FunctionTools, or HostedTools.
  3. Auto-inherit (if nothing explicit) — pulls every registered
     ToolProvider plugin's tools whose author marked
     autoInheritable: true. Asymmetric default: markdown agents
     inherit (file: true), code-defined agents don't (code: false).
• Mounts POST /api/agents/invocations (OpenAI Responses compatible) +
  POST /api/agents/chat, POST /api/agents/cancel,
  POST /api/agents/approve, GET /api/agents/threads/:id,
  DELETE /api/agents/threads/:id, GET /api/agents/info.
• SSE streaming via executeStream. Tool calls dispatch through
  PluginContext.executeTool(req, pluginName, localName, args, signal)
  for OBO, telemetry, and timeout.
• Exposes appkit.agents.{register, list, get, reload, getDefault, getThreads}
  runtime helpers.

Human-in-the-loop approval gate

Any tool annotated destructive: true pauses the stream, emits an
appkit.approval_pending SSE event, and waits for a
POST /api/agents/approve decision from the same user who initiated
the run. A missing decision after approval.timeoutMs auto-denies.
Enabled by default (approval.requireForDestructive: true); opt out
for dev. Per-user ownership enforced (x-forwarded-user).

Zero-trust MCP host policy

tools/mcp-host-policy.ts enforces an allowlist on every MCP URL
before the first byte is sent. Same-origin Databricks workspace URLs
are admitted by default; any other host must be explicitly trusted
via agents({ mcp: { trustedHosts: [...] } }). Blocks link-local
(cloud metadata at 169.254/16), RFC1918, CGNAT, loopback,
ULA, multicast, and IPv4-mapped IPv6 equivalents at DNS-resolve
time. Workspace credentials (service-principal on initialize /
tools/list; caller OBO on tools/call) are never attached to
non-workspace hosts.

DoS caps

limits: { maxConcurrentStreamsPerUser, maxToolCalls, maxSubAgentDepth }
(defaults 5 / 50 / 3). Chat bodies are capped at 64k characters via
Zod schema; 6th concurrent stream for the same user returns 429; tool
budget exhaustion aborts the run with a clear error.

runAgent(def, input) — standalone executor

packages/appkit/src/core/run-agent.ts. Runs an AgentDefinition
without createApp or HTTP. Drives the adapter's event stream to
completion, executing inline tools + sub-agents along the way.
Aggregates events into { text, events }. Useful for tests, CLI
scripts, and offline pipelines.

Event translation and thread storage

• AgentEventTranslator — stateful converter from internal
  AgentEvents to OpenAI Responses API ResponseStreamEvents with
  strictly monotonic sequence_number and output_index.
• InMemoryThreadStore — per-user conversation persistence with
  explicit ephemeral: true opt-in on AgentDefinition for
  stateless agents (autocomplete, one-shot tools).
• buildBaseSystemPrompt + composeSystemPrompt — formats the
  AppKit base prompt (with plugin names and tool names) and layers
  the agent's instructions on top.

Frontmatter loader

load-agents.ts — reads *.md files, parses YAML frontmatter with
js-yaml, resolves toolkits: [...] entries against the plugin
provider index at load time, wraps ambient tools (from agents({ tools: {...} })) for tools: [...] frontmatter references.
loadAgentsFromDir runs a two-pass resolver so agents: references
can be resolved regardless of file-system iteration order; supports
markdown siblings + code-defined agents (via LoadContext.codeAgents)
with code precedence on collision.

Plumbing

• Adds js-yaml + @types/js-yaml deps.
• Manifest mounts routes at /api/agents/* (plural — matches the
  appkit.agents.* runtime handle).
• Exports from the main barrel: agents, createAgent, runAgent,
  AgentDefinition, AgentsPluginConfig, AgentTool, ToolkitEntry,
  ToolkitOptions, BaseSystemPromptOption, PromptContext,
  isToolkitEntry, loadAgentFromFile, loadAgentsFromDir.

Test plan

• Loader tests (25): parse errors, toolkits/tools resolution,
  agents: sibling resolution regardless of order, mutual delegation,
  missing/self/non-array refs, deduplication, loadAgentFromFile
  rejection of agents:, markdown → code references, code precedence
  on collision.
• Approval gate tests: HITL wait + decision, timeout auto-deny,
  stream-owner enforcement.
• DoS caps tests: body-size rejection, per-user concurrency 429,
  tool-call budget, sub-agent depth cap.
• Event translator tests: output-index monotonicity,
  message-interruption-by-tool-call, undefined-result coalescing.
• MCP host policy tests: URL allowlist, IP blocklist, IPv6 link-local
  full range, IPv4-mapped colon-hex normalization.
• Full appkit vitest suite: 1552 tests passing at stack tip.
• Typecheck clean across all 8 workspace projects.

Signed-off-by: MarioCadenas MarioCadenas@users.noreply.github.com

PR Stack

1. Shared agent types + LLM adapters — feat(appkit): shared agent types and LLM adapter implementations #301
2. Tool primitives + ToolProvider surfaces — feat(appkit): tool primitives and ToolProvider surfaces on core plugins #302
3. Plugin infrastructure (attachContext + PluginContext) — feat(appkit): plugin infrastructure — attachContext + PluginContext mediator #303
4. agents() plugin + createAgent(def) + markdown-driven agents (this PR)
5. fromPlugin() DX + runAgent plugins arg + toolkit-resolver — feat(appkit): fromPlugin() DX, runAgent plugins arg, shared toolkit-resolver #305
6. Reference app + dev-playground + docs — feat(appkit): reference agent-app, dev-playground chat UI, docs, and template #306

Demo

agent-demo.mp4