🧬 feat(agents): add bee.Evolver autonomous self-improvement agent

[zaebee]

What

Introduces bee.Evolver — an autonomous agent that runs on parasitic compute (GitHub Actions free tier + Google Colab) and improves the Hive by generating code patches, prompt updates, docs, and GitHub Issues/PRs.

Architecture

Follows the existing ATCG pattern, lives at agents/bee-evolver/:

Nucleotide	File	Responsibility
A	src/hive/aggregator/	Reads git log, HIVE_STATE.md, open Issues/PRs, filesystem, keeper prompt
T	src/hive/transformer/	LLM analysis → EvolutionPlan with typed Improvement items
G	src/hive/generator/	Creates evolver/cycle-{timestamp} branch, applies patches via git apply, commits [skip ci] + pushes
C	src/hive/connector/	Opens GitHub Issues + PR (label: evolver), sends Telegram pulse via Bot API

Triggers

• Scheduled: every Monday 06:00 UTC (cron: '0 6 * * 1')
• Manual: workflow_dispatch with optional focus input (e.g. "improve prompts", "fix heresies")

Telegram metabolic pulse

After each cycle, sends a message to AURA_BEE_KEEPER__ADMIN_CHAT_ID:

🧬 bee.Evolver Pulse — 20260417-060012

Improvements generated: 3
🔧 Fix raw os.getenv usage in aggregator (code)
🧠 Sharpen bee.Keeper diagnosis prompt (prompt)
📋 Implement NATS Bloodstream Visualization (issue)

Tokens consumed: 1842
PR: https://github.com/zaebee/aura/pull/...
Status: ✅ Cycle complete

Key design decisions

• No NATS dependency — Telegram goes directly via https://api.telegram.org. The evolver runs in CI without cluster access.
• [skip ci] on all commits — prevents the evolver's own push from triggering the main pipeline in a loop.
• Patch safety — code patches run git apply --check first; failures are collected and reported in the Telegram pulse rather than aborting the cycle.
• issue type as safe fallback — the LLM prompt instructs the model to prefer type: "issue" over a potentially broken code patch when uncertain.

Google Colab

tools/evolver_colab.ipynb — 7-cell notebook for manual heavy-inference runs on Colab T4 GPU. Not auto-triggered.

Secrets required

Add to GitHub repo secrets if not already present:

• AURA_TELEGRAM_TOKEN
• AURA_BEE_KEEPER__ADMIN_CHAT_ID (already used by bee.Keeper)

MISTRAL_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN are already configured.

[gemini-code-assist]

Code Review

This pull request introduces bee.Evolver, an autonomous self-improvement agent for the Aura Hive. The agent follows the ATCG (Aggregator, Transformer, Connector, Generator) architecture to analyze the repository's state, propose mutations via an LLM, apply code or documentation patches, and communicate results through GitHub and Telegram. The review feedback focuses on enhancing the robustness and configurability of the agent. Key suggestions include implementing recursive filesystem scanning to provide better context to the LLM, avoiding global git configuration side effects in CI environments, and externalizing hardcoded parameters such as API pagination limits and truncation thresholds into the settings module.

[zaebee]

All four review comments addressed in e57fab3:

[high] Recursive filesystem scan (r3103113462)
Switched _scan_filesystem from iterdir (top-level only) to rglob("*"). Exclusions are now driven by settings.exclude_dirs (configurable via EVOLVER_EXCLUDE_DIRS; defaults to .git, .venv, __pycache__, gen-proto, gen, .mypy_cache, .ruff_cache).

[high] Local git config, no silent failures (r3103113478)
Removed --global flag — config is now scoped to the repository. Both calls use check=True so a failure raises CalledProcessError immediately. The error handler logs stderr and re-raises, surfacing the failure in CI logs rather than silently continuing.

[medium] GitHub Issues fetch params (r3103113487)
Removed the labels="" parameter (was inadvertently filtering for unlabelled issues only). per_page is now read from settings.issues_per_page (EVOLVER_ISSUES_PER_PAGE, default 20).

[medium] Issue body truncation limit (r3103113497)
Hardcoded 500 replaced with settings.issue_body_limit (EVOLVER_ISSUE_BODY_LIMIT, default 500). Also switched from .get("body") to direct i["body"] access as suggested — the GitHub API guarantees the key is present.

[zaebee]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces bee.Evolver, an autonomous self-improvement agent for the Aura Hive. The agent follows the ATCG (Aggregator, Transformer, Connector, Generator) architecture to analyze the repository's state, propose mutations via an LLM, apply code or documentation patches, and communicate results through GitHub and Telegram. The review feedback suggests several technical refinements: using git checkout -B for more robust branch management, switching to a more reliable Telegram message format (HTML or MarkdownV2) to prevent parsing failures, optimizing filesystem traversal by pruning excluded directories early, and implementing pagination for GitHub API requests to ensure full context is captured.