agenvoy/Agenvoy

Agenvoy is a single Go binary that runs as a local daemon (cmd/app/daemon.go). The daemon boots, initialises filesystem/DB/ToriiDB, spawns a Gin HTTP server on 127.0.0.1:17989, and serves an embedded web dashboard (internal/runtime/webapp/) plus a TUI (internal/runtime/tui/). The agent execution loop lives in internal/agents/exec/execute.go::Execute(). A user request arrives via HTTP POST to /v1/send, which calls Execute() with an ExecuteMeta struct containing the agent config, content, session ID, tools, and skill. Inside Execute() there is a for range limit loop (max 256 iterations) that: assembles messages via compact.AssembleMessages(), streams the LLM call (via go-llm-router/core), handles tool calls via toolCall(), and feeds results back to the model. The LLM is wrapped as a provider.Agent from go-llm-router. Tools are executed through an Executor that dispatches by name to registered handler groups (tools/register.go registers built-in tools like run_command, read_files, edit_file, plus dynamic groups api_, script_, ext_ for API tools, script tools, and extension tools). The full pipeline: request → route handler → Execute() → streamSend() → LLM response → tool call → tool result → loop back to LLM → final text. The frontend has no separate server — the daemon serves the web UI from embedded assets (page/page.go) and all API endpoints are localhost-only except session chat and confirm endpoints, which CORS-restrict to local origins.

Agenvoy does not have dedicated API clients for email, calendar, or docs. Instead, external services are accessed through MCP servers — the built-in MCP client connects to arbitrary MCP servers over stdio or HTTP (internal/runtime/mcp/config.go). The MCP Client interface (internal/runtime/mcp/client.go) wraps the go-sdk to call ListTools and CallTool. Tools from connected MCP servers are registered at runtime under the mcp__<server>__<tool> prefix via toolRegister.Regist(). OAuth for HTTP MCP servers is handled by internal/runtime/mcp/oauth.go. Chatbot integrations (Telegram and Discord) are first-class: the daemon connects outbound to these platforms using bot tokens stored in the OS keychain (internal/runtime/chatbot/telegram/ and discord/), with full message loop, file attachment handling, and session management via session IDs prefixed tg- and dc-. There is no background sync daemon — data is fetched on demand when the LLM calls a tool. Sync vs on-demand: all external data flows through tool calls the LLM makes during a run — no polling or webhook ingestion exists beyond the Telegram/Discord long-poll loops. LLM providers themselves are integrated via go-llm-router which supports 14+ providers (internal/agents/keychain/keychain.go): API-key-based (OpenAI, Claude, Gemini, Grok, DeepSeek, Mistral, NVIDIA, OpenRouter, Cloudflare, Ollama Cloud), OAuth-based (GitHub Copilot, OpenAI Codex, Grok-OAuth), Claude Code as a subprocess, and a generic compat provider for any OpenAI-compatible endpoint. API keys are stored in the OS keychain. OAuth tokens are loaded and refreshed by go-llm-router's oauth helpers.

Agenvoy uses a multi-layered memory system. Persistent storage uses two backends: SQLite (via go-sqlkit) for structured data — session messages (store/migrate.sql creates messages, session, file_history, action_history tables with FTS5 full-text search), and ToriiDB (an embedded vector database) for tool cache, session history, error memory, and online markers (torii/torii.go defines four DBs: DBToolCache, DBSessionHist, DBErrorMemory, DBOnline). Tool error memory (internal/agents/exec/memory/) stores structured Record entries with tool name, symptom, cause, action, outcome, and keywords. Records are persisted via torii.DB(DBErrorMemory).SetVector() with vector embeddings for semantic search. On tool failure, memory.Search() is called to find up to 16 related past errors by vector similarity or keyword scan. Session conversation memory uses summarization: every 15 minutes a system cron runs app.GenerateSummary (internal/agents/exec/summary/generate.go::Generate()), which chunks new session history records, sends them to the summary model with a prompt (configs.SummaryPrompt), and stores a JSON summary dictionary per session in ~/.config/agenvoy/sessions/<id>/summary.json. Context injection happens in systemPrompt.go — the getSystemPrompt() function builds the full system prompt by templating {{.AvailableSkills}}, {{.OfficialGuide}} (model-specific capability docs), {{.PermissionMode}}, {{.GuardrailRules}}, {{.BotPersona}}, and agent guide files (CLAUDE.md/AGENTS.md). The compact/ package handles prompt assembly: AssembleMessages() builds the message array from system prompts, summary message, old histories, user input, and tool histories. Context window management is handled by compact.CheckThreshold() with an 80% ratio trigger, and compact.ExtractOldHistories() moves older messages into a compacted summary when token limits approach.

Actions are gated through a multi-level permission system in internal/agents/exec/toolCall.go. The toolNeedsConfirmation() function determines if a tool call requires user approval by checking: (1) whether reading sensitive paths (isSensitiveReadFile), (2) whether the tool is in destructive mode (remove/restore), (3) whether the tool is read-only (list/read/search), (4) whether the HTTP method is a GET, (5) whether the run_command is in the ReadOnlyCommand list, and (6) whether the tool is on the user's allowlist. If confirmation is needed, the runtime.Ask() function sends a runtime.Request{Kind: KindToolConfirm} to the TUI or web dashboard. The user can approve/deny, mark as "remember" (adds an allowlist rule), or "allow this turn". Restricted paths (outside work dir or on the sensitive path list from sensitive_path.json) trigger a password verification gate via boundary.Restricted(). The allowlist is session-level and tool-argument-aware: allow/tool/list.go loads work-dir specific allowlist entries. Sandboxing via bubblewrap (go_pkg_sandbox) wraps command execution: run_command.go and script_ tools execute in a sandbox that blocks sensitive paths and credentials. The configs/jsons/guardrail_rules.json embeds refusal rules, and configs/jsons/refusal_messages.json provides refusal response templates. File boundary enforcement (internal/tools/file/boundary/) includes the sensitive-path checker and the ExcludeList/DeniedPath lists. An audit trail is recorded: all tool calls are logged via sessionLog.Record() with full tool name, arguments, results, and errors. The action_history SQLite table stores every action per task hash with model, reasoning level, objective, tool results, and final reply, supporting replay and review.

LLM provider selection and configuration is handled by go-llm-router (a Go package github.com/pardnchiu/go-llm-router). The provider.Agent interface provides Send() and SendStream() methods. The keychain/keychain.go resolves provider config from the OS keychain: it supports API-key-based providers (claude, openai, gemini, grok, deepseek, mistral, nvidia, openrouter, cloudflare, ollama-cloud), OAuth-based providers (copilot, codex, grok-oauth with token refresh), Claude Code as a subprocess (claude-code), and a generic compat provider for OpenAI-compatible endpoints. Models are registered in ~/.config/agenvoy/config.json as a flat list of model names like [email protected]. Tiered routing (internal/session/config/tier.go) classifies model names into tiers S/A/B/C based on heuristics (e.g., claude-fable → S, claude-sonnet → A, claude-haiku → B, gemma → C), with a fallback priority rank. LLM-driven agent selection (internal/agents/exec/selectAgent.go) calls a dispatcher model with a prompt listing available agents and the user request, asking it to return which model(s) to use and a work type (code/research/work/chat/fetch). The work type determines the reasoning level (xhigh/high/medium/low/none). If no dispatcher model is configured, the first registered model is used. An optional dispatcher_beta mode uses a faster Jev classifier for the routing decision. Structured output / tool calling is handled by go-llm-router's native support — the agent sends tool definitions to the LLM, and tool calls are extracted from the response choices at execute.go:706-763. Reasoning effort is specified per-model through the provider.Reasoning enum (none/low/medium/high/xhigh) from the go-llm-router, and reasoning tags like </think> are parsed as a fallback. Context window management uses model-specific thresholds from compact.CheckThreshold() (based on 80% of the model's context window). Local models are supported via the compat provider pointing at a local endpoint (e.g., Ollama at http://localhost:11434/v1) and the ollama-cloud provider (which is Ollama's cloud offering, not local — but the compat provider covers truly local endpoints).

Agenvoy is deployed as a single Go binary (make build produces /usr/local/bin/agen). It has zero infrastructure dependencies: no Docker, PostgreSQL, Redis, or Celery. The binary embeds the web UI assets (page/page.go → page/public/) and all configuration JSON files and prompt text files via //go:embed directives. Storage uses SQLite (via go-sqlkit) for structured data and ToriiDB (an embedded vector DB) for vector search, caching, and session history — all stored under ~/.config/agenvoy/. The daemon listens on 127.0.0.1:17989. Installation is a one-liner (curl -fsSL https://agenvoy.com/scripts/install.sh | bash). Updates use agen update which downloads and runs a shell script. Startup integration supports Linux systemd user services (internal/startup/linux.service with ExecStart="/usr/local/bin/agen" --daemon) and macOS launchd (internal/startup/darwin.plist). The TUI (cmd/app/tui.go) and web dashboard are two UIs for the same daemon. Required external accounts depend on the LLM providers used: users need API keys for their chosen providers (OpenAI, Anthropic, etc.) or OAuth tokens (Copilot, Codex, Grok). For Telegram/Discord chatbots, a bot token is needed. The make dev command serves the web UI from disk for development. Sandboxing requires bubblewrap to be installed on the host. There is a built-in config watcher (app/watchConfig.go) and session watcher (app/watchSession.go). The daemon lifecycle includes system cron jobs for summary generation (every 15 min) and session cleaning (every 30 min).