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 [email protected]

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

[pkosiec]

should we hide this plugin until all PRs are merged?

[pkosiec]

btw maybe we should rename this file as beta.gen.ts? so that we don't review an autogenerated file?

(and add "generated, do not edit" header)

[pkosiec]

Suggested change

	"js-yaml": "^4.1.1",
	"js-yaml": "4.1.1",

[pkosiec]

Agentic review:

Code Review: agent/v2/4-agents-plugin

Scope

Branch: agent/v2/4-agents-plugin (16 commits, 48 files, +5563/-32 lines)
Base: main at a7ebc57
Mode: report-only (plan mode)

Intent

Add a complete agents() plugin to AppKit: markdown-driven agent definitions with folder-based discovery (<id>/agent.md), code-defined agents via createAgent(), human-in-the-loop approval gate for destructive tool calls, sub-agent delegation with depth limiting, SSE streaming with Responses API-compatible event translation, pluggable ThreadStore, MCP tool integration, toolkit inheritance, DoS protection (concurrent stream limits, tool-call budgets), and refactoring of MCP client and utility extraction.

Review Team

• correctness (always)
• testing (always)
• maintainability (always)
• security -- tool approval gates, OBO token handling, user auth, input validation
• api-contract -- new REST routes, SSE events, Responses API compat
• reliability -- abort signals, timeouts, event channel, async error paths
• adversarial -- 5500+ line diff, external APIs, user input
• kieran-typescript -- large TypeScript codebase, discriminated unions, type guards

---

Findings

P1 -- Critical

#	File	Issue	Reviewer	Confidence
1	agents.ts:751	Approval gate ignores effect field. The gate checks entry.def.annotations?.destructive === true but never reads effect. A tool with effect: "destructive" (the new preferred API) and no legacy destructive: true boolean bypasses approval entirely. The JSDoc on tool.ts:13-16 and function-tool.ts:12-15 explicitly states "any mutating value forces the agents-plugin approval gate." The implementation contradicts the documented contract. Fix: check const isDestructive = ann?.destructive === true || ann?.effect === "destructive"; (or broaden to write/update if the JSDoc intent holds).	security, correctness	0.95
2	agents.ts:991-1023	Sub-agent childExecute bypasses tool-call budget. The toolCallsUsed counter and budget check live in the top-level executeTool closure (line 735-745). runSubAgent creates its own childExecute that never increments or checks the budget. A sub-agent can make unlimited tool calls, defeating limits.maxToolCalls. Fix: pass the budget counter (or a shared budget object) into runSubAgent and check on every child tool call.	correctness, adversarial	0.95
3	agents.ts:991-1023	Sub-agent childExecute bypasses approval gate. The top-level executeTool checks approvalPolicy.requireForDestructive (line 751) before executing destructive tools and emits approval_pending events. childExecute in runSubAgent does none of this. A sub-agent calling a destructive tool executes it without human approval. Fix: apply the same approval check in childExecute, or factor the gate logic into a shared helper.	security	0.90
4	agents.ts:661-707	/invocations bypasses concurrent stream limit. _handleChat checks countUserStreams(userId) >= limits.maxConcurrentStreamsPerUser before streaming. _handleInvocations calls _streamAgent without the same check. A client can bypass the rate limit by hitting /invocations instead of /chat. Fix: add the same guard to _handleInvocations.	security, reliability	0.92

P2 -- Moderate

#	File	Issue	Reviewer	Confidence
5	consume-adapter-stream.ts, normalize-result.ts	Extracted utilities are dead code. consumeAdapterStream and normalizeToolResult were extracted into core/agent/ (with tests), but no production code imports them. The same logic is still inlined in agents.ts:815-826 (result normalization), agents.ts:885-896 (stream consumption), run-agent.ts:97-105, and agents.ts:1058-1067. Three call sites duplicate the accumulation pattern. Either use the extracted functions or remove them.	maintainability	0.95
6	agents.ts:148-156	reload() is non-atomic. this.agents.clear() runs before await this.loadAgents(). If loadAgents throws (e.g. malformed markdown), the registry is empty and new requests get "No agent registered" errors. In-flight streams holding old references still work but new ones fail. Fix: build into a new Map, then swap on success.	reliability	0.85
7	agents.ts:1072	_handleCancel uses unsafe type assertion for streamId. Unlike /chat, /approve, and /invocations which use Zod schemas, the cancel route extracts streamId via req.body as { streamId?: string }. This is inconsistent and skips validation. Fix: add a small Zod schema (or validate inline).	api-contract, security	0.80
8	agents.ts:815-826	Tool result type inconsistency. When serialized.length > MAX, the return is a truncated string. When <= MAX, the return is the raw result (which may be an object). Adapters receive different types depending on length. The extracted normalizeToolResult has the same behavior (returns result not serialized). This is intentional (preserving structured data for short results), but consider documenting the contract or always returning strings.	correctness	0.70
9	event-channel.ts:23-31	EventChannel has no backpressure. push() accumulates into this.queue without bound. If the SSE consumer is slow (network backpressure, paused tab), the queue grows indefinitely. For typical chat streams this is fine; for high-throughput tool-calling agents it could cause memory pressure. Consider a max queue size with drop/error policy.	performance	0.65
10	load-agents.ts:106,141,145	Synchronous filesystem I/O in agent loader. fs.readFileSync, fs.existsSync, fs.readdirSync block the event loop. Acceptable during startup, but reload() can be called at runtime via the exported appkit.agents.reload() API, which would block the event loop while reading files.	performance	0.65

P3 -- Low

#	File	Issue	Reviewer	Confidence
11	agents.ts:1176-1188	printRegistry() uses console.log instead of logger. Inconsistent with the rest of the file which uses createLogger("agents"). The formatted output is intentionally styled with picocolors, so this may be deliberate for terminal aesthetics.	maintainability	0.60

---

Coverage

• Suppressed: 0 findings below 0.60 confidence.
• Untracked files: None.
• Testing: Test coverage is extensive (~1800 lines of tests across 7 test files). Tests cover plugin lifecycle, event translation, thread store, approval gate, DoS limits, and load-agents. The tool-call budget bypass in sub-agents (# 2) is not tested. The effect field interaction with the approval gate (chore: rework TelemetryManager to use Node SDK #1) is not tested.
• Residual risks: The InMemoryThreadStore has no eviction, bounds, or TTL. The code warns about this in both prod and dev, which is good. A follow-up for bounded eviction is mentioned in comments.

---

Verdict: Not ready -- fix P1 items before merge

Fix order:

1. # 1 (approval gate effect gap) -- security hole, contradicts documented API
2. # 2 + # 3 (sub-agent budget + approval bypass) -- these are the same code path; fix together
3. # 4 (/invocations rate-limit bypass) -- one-line fix
4. # 5 (dead code) -- either wire the extracted utilities or delete them

P2 items # 6-# 10 are lower priority and could be addressed in follow-ups, though # 6 (reload() atomicity) is worth fixing now since it's small.

[pkosiec]

You might consider using an external lib:

EventChannel (~70 lines) -- This is a basic unbounded async queue (push/consume as async iterable). Existing alternatives:

• @repeaterjs/repeater -- Almost exactly this API: push-based async iterable creation with close/error semantics and optional backpressure. Would replace EventChannel entirely.
• Node.js built-in events.on(emitter, event) -- Returns an AsyncIterator from an EventEmitter. Could work but is clunkier (requires wrapping in an EventEmitter, less clean close/error semantics).
• Web Streams ReadableStream -- The ReadableStream constructor with a controller gives push/pull with built-in backpressure. Slightly heavier API surface.

@repeaterjs/repeater is the cleanest drop-in. That said, 70 lines of zero-dependency code is defensible in an SDK -- adding a dependency has its own cost.