Architecture

Module Overview

Leaf modules are grouped under three reactor-only aggregators (kairo-capabilities / kairo-transports / kairo-starters). Foundation modules stay flat at the top.

kairo-parent
├── kairo-bom                       — BOM for dependency version management
├── kairo-api                       — SPI interface layer (zero implementation deps)
├── kairo-core                      — Core runtime (ReAct, compaction, providers)
│
├── kairo-capabilities/             — vertical capability cohort (11 modules)
│   ├── kairo-tools                 — built-in tool suite
│   ├── kairo-mcp                   — MCP protocol integration
│   ├── kairo-skill                 — Markdown skill registry & loader
│   ├── kairo-evolution             — self-evolution pipeline + governance
│   ├── kairo-observability         — OpenTelemetry exporter
│   ├── kairo-security-pii          — PII redaction + JDBC audit + compliance
│   ├── kairo-plugin                — Plugin system (Codex-compatible components)
│   ├── kairo-cron                  — Scheduled task scheduler
│   ├── kairo-gateway               — Multi-channel routing / session / streaming / mirror
│   ├── kairo-lsp                   — LSP diagnostics subsystem (post-edit baseline diff)
│   └── kairo-acp                   — Agent Client Protocol (editor integration via JSON-RPC over stdio)
│
├── kairo-transports/               — I/O boundary cohort (4 modules)
│   ├── kairo-event-stream          — KairoEventBus filtering + backpressure
│   ├── kairo-event-stream-sse      — SSE transport
│   ├── kairo-event-stream-ws       — WebSocket transport
│   └── kairo-channel-dingtalk      — DingTalk webhook + signature verifier
│
├── kairo-starters/                 — Spring Boot starter cohort (11 modules)
│   ├── kairo-spring-boot-starter-core
│   ├── kairo-spring-boot-starter-mcp
│   ├── kairo-spring-boot-starter-evolution
│   ├── kairo-spring-boot-starter-event-stream
│   ├── kairo-spring-boot-starter-channel-dingtalk
│   ├── kairo-spring-boot-starter-observability
│   ├── kairo-spring-boot-starter-gateway
│   ├── kairo-spring-boot-starter-plugin
│   ├── kairo-spring-boot-starter-cron
│   ├── kairo-spring-boot-starter-lsp
│   └── kairo-spring-boot-starter-acp
│
└── kairo-examples                  — example applications

Each cohort aggregator carries zero <dependencies> and never appears on a runtime classpath; every leaf still inherits kairo-parent directly.

Module Descriptions

kairo-api

The SPI interface layer with zero implementation dependencies. Defines all extension points: ModelProvider, Tool, MemoryStore, Skill, Hook, and more. Depend on this module to write extensions without pulling in the full runtime.

kairo-core

The core runtime engine. Includes:

• ReAct Engine — DefaultReActAgent implementing the Thought→Action→Observation loop
• 6-Stage Context Compaction — Progressive pipeline (Snip → Micro → Collapse → Auto → Partial → CircuitBreaker)
• Model Providers — Native Anthropic integration + OpenAI-compatible adapter

kairo-tools

49 built-in tools organized by category:

• File ops — Read, Write, Edit, Glob, Grep, Tree, Diff, BatchRead, BatchWrite, SearchReplace, PatchApply, JsonQuery, TemplateRender
• Execution — Bash, Monitor, Mvn, Sleep, VerifyExecution
• Web — WebFetch, WebSearch, Http, OpenApiHttp
• Git — Git, Github
• Interaction — AskUser
• Skills — SkillList, SkillLoad, SkillManage
• Task and workflow — Task*, Todo*, Workflow
• Plan mode — EnterPlanMode, ExitPlanMode, ListPlans
• Memory — MemoryRead, MemoryWrite, MemoryDelete
• Cron — Cron*
• Code intelligence — Lsp

kairo-mcp

MCP (Model Context Protocol) integration via StreamableHTTP + Elicitation Protocol, enabling connectivity to external tool servers.

Agent collaboration

Kairo exposes stateless Agent Profiles through SubagentDefinition and SubagentRegistry. Task-scoped execution is owned by a live parent Agent runtime so child context, permissions, workspace isolation, cancellation, steering, and acceptance share one lifecycle. See ADR-031. A2A remains available for request-response invocation across separately hosted Agent boundaries.

kairo-observability

OpenTelemetry tracing integration centered on distributed tracing (span tree + attributes/events). Currently provides OTelTracer, OTelSpan, and GenAiSemanticAttributes for GenAI-standard span instrumentation. Metrics collection and dashboards are planned for v0.7.

kairo-spring-boot-starter-* (per-feature)

Spring Boot auto-configuration is split into eleven per-feature starters under kairo-starters/. Start with kairo-spring-boot-starter-core; add -mcp, -evolution, -event-stream, -channel-dingtalk, -observability, -gateway, -plugin, -cron, -lsp, or -acp as needed. Subagent execution is not a context-free singleton and therefore has no standalone starter.

kairo-plugin

Plugin system using Codex-compatible component formats (plugin.json / SKILL.md / hooks.json / .mcp.json). Supports 5 install sources: LocalPath, GitHub, GitUrl, GitSubdir, and Npm.

kairo-cron

Scheduled task scheduler with flexible scheduling support for recurring agent operations.

kairo-gateway

Multi-channel routing, session management, streaming, and mirroring via the Gateway SPI. Sits above individual Channel adapters.

kairo-lsp

LSP diagnostics subsystem. Provides snapshotBaseline + notifyChange + diagnosticsSince so tool implementations can report whether an edit introduced new errors (post-edit baseline diff).

kairo-acp

Agent Client Protocol server handler. Editors (e.g. Zed) drive a Kairo agent as a subprocess via JSON-RPC over stdio. MVP operations: initialize, session.new, session.prompt.