Architecture Layers
Last updated
Each layer of Agenvoy, the package that implements it and what it is responsible for.
| Layer | Package | Responsibility |
|---|---|---|
| Entry | cmd/app | argv dispatch (stop / update / --daemon / -p one-shot client of POST /v1/send, v1.3.9; --enable-claude-code was Removed in v1.2.3); MCP server on non-TTY stdin; init sandbox, filesystem policy, MCP manager |
| App services | internal/app | agent registry build and the config.json watcher, used by both daemon and TUI; Telegram / Discord reload, session watcher, MCP setup, chat push hooks and skill runs, used by the daemon only (since v1.2.0 the TUI opens no MCP connections); daemon spawn, used by the TUI |
| Startup | internal/startup | start-on-login via a launchd plist (macOS) or systemd service (Linux), toggled from /config; moved from internal/runtime/startup, which no longer exists |
| Notes | — | operator notes (internal/note, the find_note tool, /v1/note* and the startup notes migration) were removed in v1.0.23; a note table left in an older history.db is no longer read |
| Runtime singleton | internal/runtime | ~/.config/agenvoy/runtime.uid lock (UID, PID, start time); a second daemon aborts while the recorded one is alive; since v1.3.7 agen stop stops every running daemon — each agen --daemon process found with ps (ListDaemons) plus the recorded PID — sending SIGTERM, then SIGKILL after a 3 s grace window |
| Engine | internal/agents/exec | Prepare / Run (skill match, named skill, model resolution; Start was renamed Run in v1.2.1); iteration loop; tool dispatch; dispatcher routing with tiers and priority in exec/model since v1.2.1 (Route with the dispatcher in select_with_llm.go and the decision-model dispatcher raced against it in select_with_decision.go since v1.3.1 (the TypeSafe beta dispatcher in select_with_jev.go was Removed in v1.3.1), Next for fallback with a health check; since v1.1.0 a session whose reasoning is auto gets its level from the dispatcher's work-kind pick, replacing the global auto_reasoning switch, and pass-tier models are never picked by the dispatcher or used as fallbacks); cooldown and retry (retryHandler); subagent host (exec/subagent.Exec, at most max(NumCPU / 2, 3) concurrent since v1.3.0, 3 before) |
| Decision | internal/agents/decision | added in v1.3.1. The configured decision model (typesafe or openrouter, built with router.NewDecision): Available lists the choices (cached 15 minutes, minus excluded models), Ready / Request / Decide / Batch / Confident are shared by dispatch, watch checks, search_web / fetch_page filtering, the turn-context tool-gap hint and skill filter, summary filtering (the cron pass, and since v1.3.7 the per-turn relevance check on summary entries) and context-overflow tool-step pruning |
| Compaction | internal/agents/exec/compact | per-model threshold, tool-history and old-history folding, trim and raw-tool fallbacks; since v1.3.0 the input limit learned from overflow errors (NoteOverflow) and the 80% overflow trim (TrimRatio), preceded since v1.3.1 by decision-model tool-step pruning |
| Providers | go-llm-router v0.10.2 (external module) | unified Agent.Send() across 14 provider entries plus any OpenAI-compatible endpoint; the claude-code provider (in this repo from v1.1.0, moved into go-llm-router in v1.1.4) drives the local claude CLI as a model and is enabled whenever the claude binary is found (the agen --enable-claude-code opt-in was Removed in v1.2.3); reasoning and fast-mode normalization. Speech-to-text and text-to-speech route separately, backed by OpenAI, Gemini and (since v1.0.17) OpenRouter |
| Tools | internal/tools + internal/runtime/toolAdapter | built-in / API / script / extension tool definitions |
| MCP | internal/runtime/mcp | client and server on the official modelcontextprotocol/go-sdk, one package |
| Sandbox | go-pkg/sandbox | OS-native isolation; Wrap() builds the command and, since v1.3.0, Run() executes it |
| Filesystem | go-pkg/filesystem (+ reader/) + internal/filesystem | policy-aware writes; ToriiDB pathing |
Session storage, the dashboard, pending routing, memory, the scheduler, IPC and the TUI are covered in Runtime Layers.