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, 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, default, maxSteps,
  maxTokens, baseSystemPrompt. 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: {...}) — synthesized as agent-<key>
     tools on the parent.
  2. Explicit tool record entries — ToolkitEntrys, inline
     FunctionTools, or HostedTools.
  3. Auto-inherit (if nothing explicit) — pulls every registered
     ToolProvider plugin's tools. Asymmetric default: markdown
     agents inherit (file: true), code-defined agents don't (code: false).
• Mounts POST /invocations (OpenAI Responses compatible) + POST /chat, POST /cancel, GET /threads/:id, DELETE /threads/:id,
  GET /info.
• SSE streaming via executeStream. Tool calls dispatch through
  PluginContext.executeTool(req, pluginName, localName, args, signal)
  for OBO, telemetry, and timeout.
• Exposes appkit.agent.{register, list, get, reload, getDefault, getThreads} runtime helpers.

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. Hosted/MCP tools and plugin toolkits
require the agents plugin and throw clear errors with guidance.

Event translation and thread storage

• AgentEventTranslator — stateful converter from internal
  AgentEvents to OpenAI Responses API ResponseStreamEvents with
  sequence numbers and output indices.
• InMemoryThreadStore — per-user conversation persistence. Nested
  Map<userId, Map<threadId, Thread>>. Implements ThreadStore from
  shared types.
• 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.

Plumbing

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

Test plan

• 60 new tests: agents plugin lifecycle, markdown loading, code-agent
  registration, auto-inherit asymmetry, sub-agent tool synthesis,
  cycle detection, event translator, thread store, system prompt
  composition, standalone runAgent.
• Full appkit vitest suite: 1297 tests passing.
• 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

This 6-PR stack is a redesign of the earlier 13-PR stack (#282-#286, #293-#300), reorganized to eliminate mid-stack API churn. Reviewers never see code in this stack that later PRs delete. The old 13 PRs have been closed with references back here.