MCP-Resident Agents — KYM-registered helpers inside the native MCPs

Put a small, rigorously-defined agent (pinned LLM + versioned tool inventory) INSIDE each native MCP so orchestrators and subagents use the tool more effectively. Register it as a KYM agent, run dogfooding hypotheses as KYM optimization-mode experiments, and keep the intelligence harness-independent — the same MCPs serve Kilo today, ABI Chat next, the native console after that.

Premise

1. Each native MCP (ozzydev-search, ozzydev-write) hosts a RESIDENT agent: a small LLM-backed policy that helps callers use the tool better — not a general agent, a tool-shaped one.
2. The resident agent is a first-class KYM agent whose definition is rigorous: pinned LLM (model id + version + sampling params), structured tool inventory WITH versions, per-skill versions, and an explicit MCP-residency declaration.
3. KYM optimization mode drives dogfooding: hypotheses are experiment variants (A/B → MAB) over agent-definition versions; rewards flow back as the Ed25519 receipts every MCP operation already emits (ADR-009).
4. At session start the cubicle runtime pulls the pinned agent definitions in (kym://agents/<slug>@<version>); the MCP hydrates its resident agent from the bundle — inside Kilo today, ABI Chat or the native console later, with zero MCP changes.
5. MCP-residency IS the sidecar architecture: the intelligence lives in the MCP process behind a stable stdio/HTTP contract, so Ozzy runs as a sidecar to ANY harness without re-porting the smarts.

Candidate resident-agent skills (ranked)

• write: ambiguity resolver ozzydev-write — Resolve splice_ambiguous_anchor classified failures (the 4/31 r5b residual) with a bounded LLM call that picks the correct anchor from the candidate set — a rung between splice and the full vendor apply. Direct successor to the REJECTED Osmosis local arm (ADR-008), but API-based and latency-bounded: the hypothesis is that a small hosted model resolves anchors in <2s at pennies, where Osmosis needed 27s locally.
  Reward: rung-verified merge rate on the ambiguous class · latency p95 · $ per resolved edit (r5 corpus is the fixture set)
• search: answer packet compressor ozzydev-search — Compress the 25 fused items into a pinpointed answer packet (top receipts + a 5-line synthesis) so the CALLING agent spends less context. Today every caller pays ~10-25KB per search; the resident agent returns the packet plus the full item list behind a flag.
  Reward: caller context-utilization delta (already self-reported per AGENTS §5) · answer-grounding spot-checks vs fixtures
• search: query reformulation ozzydev-search — Rewrite/expand the caller question per intent class before expert fan-out (identifier queries get symbol-shaped rewrites; conceptual queries get expansion). Measurable against the frozen IR fixture corpus (v1.4.0) — nDCG/Recall delta per variant.
  Reward: nDCG@10 / Recall@10 vs the 0.814/0.830 baseline on fixtures v1.4.0
• search: classifier escalation ozzydev-search — The rule classifier stays rank-0 (deterministic, 1ms); the resident LLM only takes LOW-CONFIDENCE classifications (the escalation branch ADR-007 designed but never implemented). Variants: escalation threshold × model choice.
  Reward: selection F1 on adversarial/ambiguous fixture classes · added latency p95 on the escalated share
• write: category classifier ozzydev-write — The D8 category=auto path gets a resident classifier that maps intent + diff shape to categories (a–h) better than heuristics; wrong-category routing is a measured KPI today.
  Reward: routing-accuracy vs orchestrator-labeled ground truth · verify-ladder failure rate per category

What the rigorous agent definition requires (survey-reconciled)

• Immutable card versioning — today: entities.version is one opaque string; agent-card fetch has no version pin (X-KYM-Git-Commit header is the closest thing).
  Delta: versionSemver + versionId per published revision; GET agent-card?version=…; SDK getAgentAtVersion + kym:// URI resolver (today kym:// exists in prose only).
• Structured tool inventory — today: entities.tools is a JSON blob of tool NAMES only.
  Delta: tool_inventory: Array<{ id, name, version, mcpServer?, mcpTransport? }> — the agent is defined by what it ships with, versions included.
• LLM pin — today: primaryModelId FK — an entity pointer, not a version.
  Delta: llmPin: { modelId, modelVersion, providerId, samplingParams } — the resident agent is meaningless as an experiment unit without it.
• MCP-residency declaration — today: Nothing — agents are assumed to be external A2A endpoints.
  Delta: mcpResidency: { mcpId, mcpVersion, entryPoint, role } — declares the agent lives INSIDE an MCP tool.
• Per-skill versions — today: entitySkills has no version column; SDK skills are unknown[].
  Delta: skill version + (entityId, skillId, version) uniqueness; SDK types follow.
• Receipt pinning tuple — today: SDK ReceiptPayload carries entity_id only — the roadmap claim that receipts carry (card, card_version, skill, skill_version) is aspirational, corrected 2026-07-16.
  Delta: Optional tuple fields on ReceiptPayload + usage_receipts columns so rewards attribute to a specific definition version.
• Optimization mode — today: KYM ab_tests is display-only (no write API, no allocator); the REAL experiment substrate (experiments / variants / runs / rewards / MAB-ready) lives in the ozzydev console D1.
  Delta: Phase C: KYM write API + allocator. Until then the console D1 IS the optimizer and KYM is the definition registry.

Phased plan

1. A — resident agents, console-optimized (no KYM schema changes) — Define resident agents as versioned config inside the MCPs (agent.json alongside config.json: llmPin, skills, version). Ship ONE skill first (write ambiguity-resolver is the highest value ÷ cost). Run hypotheses through the EXISTING console D1 experiment substrate (experiments/variants keyed on the definition version; experiment_turns.agent_card_ref carries a provisional ref). Every resident-agent action emits the standard signed receipt with the definition version in payload.common.
2. B — rigorous KYM registration + session-start pull-in — Land the schema deltas (versioning, tool inventory, llmPin, mcpResidency, skill versions) in knowyourmodel-ai + SDK; register ozzydev-search/helper and ozzydev-write/helper as KYM agents; ship the kym:// resolver and the @nexartis/cubicle-adapter-local-mac pullAgent primitive so MCP boot hydrates the pinned definition. Kilo, ABI Chat, and the native console all inherit this for free — the pull-in is below the harness boundary.
3. C — KYM optimization mode — KYM grows the write-experiments API + allocator (ε-greedy → Thompson); receipt verify endpoint upserts rewards keyed on the pinning tuple; the console D1 forwarder (run_receipts.kym_status is already designed for this) closes the loop. Dogfooding hypotheses then run AS KYM experiments across agent-definition versions.

Kilo MCP Catalog & Cubicle Runtime Suitability Matrix

Survey of installed Kilo / OpenCode MCP tools, categorized by function, provider, transport, and Cubicle-SDK runtime context.

Open questions

• Latency budget per resident-agent skill: the search router p50 is ~2.5s — a resident LLM call must be off the critical path (compressor) or bounded + classified (escalation, ambiguity). No silent degradation: an over-budget resident call is a loud classified skip.
• Model tier: do resident skills share one small pinned model (cheaper card, coarser optimization) or pin per-skill (finer experiments, more cards)? Start shared, split when a skill demonstrably wants a different tier.
• Key custody: resident-agent LLM keys ride the same console Secrets vault flow (ADR-006) — which integration card? Likely a generic "resident LLM" card rather than per-vendor sprawl.
• Definition-vs-config boundary: splice rungs and fast_apply_engine are ROUTER config; the resident agent is a KYM definition. The experiment substrate must key on both without conflating them (config_version × agent-definition version).
• Reward hygiene: several skills reward on operator-visible outcomes (context savings, routing accuracy) that need labeled ground truth — reuse the rubric/evaluations tables from migration 0003 rather than inventing a new scoring path.
• Compatibility with KYM beta clients is a hard constraint: every schema/SDK delta in G1–G15 ships additively (nullable columns, optional fields, new routes) — the breaking-change guidance table and the KYM-side sequencing live in knowyourmodel-ai/docs/ROADMAP.md §4; receipt pinning fields must land in SDK + platform in one wave because verify signs the exact JSON bytes.

References

• ADR-007 (native search MCP) · ADR-008 (native write MCP, Osmosis rejection) · ADR-009 (signed receipts)
• /research/harness-bandit-experiments — the experiment substrate this reuses
• /research/dynamic-workers-agent-composition — the sibling composition direction for cloud-deployed agents
• Roadmap: wave-kym-mcp-resident-agents (gap list G1–G15), wave-abi-chat-primary-surface, wave-ozzy-sidecar