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): tools(plugins) 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

[MarioCadenas]

Addressed P1 + cheap P2 findings in 233b388 and the cascaded sub-agent SSE forwarding in e365bda:

• 1 approval gate honours effect (write/update/destructive) → requiresApproval() in agents.ts:82
• 2 / 3 sub-agent budget + approval → shared RunState + dispatchToolCall (called by both _streamAgent and runSubAgent)
• 4 /invocations rate-limit guard → mirrors the /chat check in _handleInvocations
• 5 consumeAdapterStream / normalizeToolResult wired into all 4 call sites (top-level _streamAgent, dispatchToolCall, runSubAgent, standalone runAgent)
• 6 atomic reload() via buildAgentRegistry() (builds into a fresh Map, swaps on success)
• 7 Zod cancelRequestSchema in _handleCancel, drops the as cast
• 10 fs/promises in load-agents.ts so reload() doesn't block the event loop

Deferred (advisory):

• 8 hardcoded executeTool timeout — lives in core/plugin-context.ts, separate PR
• 9 tool result type inconsistency (short vs long) — intentional, preserves structured data for short results
• 11 printRegistry() uses console.log — intentional picocolors-styled startup banner

Happy to file follow-up issues for any of the deferred items if useful.

Inline replies on 1 (manifest hide) and 2 (beta rename) — left rationale on the threads; let me know if you'd prefer different framing. 5 (event-channel external lib) — kept the zero-dep 70-line implementation per the "defensible" note in your comment; happy to swap to @repeaterjs/repeater if you'd rather.

Tests added: dispatch-tool-call.test.ts covers the approval-gate effect matrix, the deny path, the shared budget across top-level + sub-agent dispatches, and the sub-agent event-forwarding contract. Plus /invocations rate-limit test in dos-limits.test.ts.

[MarioCadenas]

Follow-up: re-reviewed the deferred items and landed two of them in 4898f8cc.

• 8 Hardcoded 30s executeTool timeout → on closer look this was actually a latent bug, not just a maintainability concern: analytics SQL warehouse cold-starts and long Genie conversations routinely exceed 30s. Added agents({ limits: { toolCallTimeoutMs } }) (default 300_000 = 5 min), plumbed through RunState to PluginContext.executeTool (which now accepts an optional timeoutMs defaulting to the same 5 min). Tests cover the default, the override, and the runState → context plumbing.
• 9 Tool result type inconsistency → after tracing the consumers, every wire-boundary site (adapter, translator) was already stringifying via typeof === "string" ? : JSON.stringify(...), so the "preserves structured data for short results" rationale didn't hold. normalizeToolResult now returns string always; null becomes the literal "null" (matches JSON.stringify(null)). Adapter/translator defensive code stays for non-AppKit-mediated executeTool callbacks.
• 11 printRegistry() console.log → kept as-is, intentional picocolors-styled startup banner. Logger prefix would break column alignment and bypass log-level filtering. Could add a JSDoc note explaining the intent if you want it codified.