better-dsh 0.2.5-c → 0.2.5-e

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/agent-loop.md

@@ -1,242 +0,0 @@
----
-sidebar_position: 3
-title: "Agent Loop Internals"
-description: "Detailed walkthrough of AIAgent execution, API modes, tools, callbacks, and fallback behavior"
----
-
-# Agent Loop Internals
-
-The core orchestration engine is the `AIAgent` class. `run_agent.py` is now a thin facade: the loop itself lives in `agent/conversation_loop.py`, each turn phase in `agent/turn_*.py` (iteration prep, API call, API error, overflow, truncation, recovery), constructor wiring in `agent/agent_init.py`, and everything from prompt assembly to tool dispatch to provider failover in focused `agent/*.py` modules mixed into `AIAgent`.
-
-## Core Responsibilities
-
-`AIAgent` is responsible for:
-
-- Assembling the effective system prompt and tool schemas via `prompt_builder.py`
-- Selecting the correct provider/API mode (chat_completions, codex_responses, anthropic_messages)
-- Making interruptible model calls with cancellation support
-- Executing tool calls (sequentially or concurrently via thread pool)
-- Maintaining conversation history in OpenAI message format
-- Handling compression, retries, and fallback model switching
-- Tracking iteration budgets across parent and child agents
-- Flushing persistent memory before context is lost
-
-## Two Entry Points
-
-```python
-# Simple interface — returns final response string
-response = agent.chat("Fix the bug in main.py")
-
-# Full interface — returns dict with messages, metadata, usage stats
-result = agent.run_conversation(
-    user_message="Fix the bug in main.py",
-    system_message=None,           # auto-built if omitted
-    conversation_history=None,      # auto-loaded from session if omitted
-    task_id="task_abc123"
-)
-```
-
-`chat()` is a thin wrapper around `run_conversation()` that extracts the `final_response` field from the result dict.
-
-## API Modes
-
-Hermes supports three API execution modes, resolved from provider selection, explicit args, and base URL heuristics:
-
-| API mode | Used for | Client type |
-|----------|----------|-------------|
-| `chat_completions` | OpenAI-compatible endpoints (OpenRouter, custom, most providers) | `openai.OpenAI` |
-| `codex_responses` | OpenAI Codex / Responses API | `openai.OpenAI` with Responses format |
-| `anthropic_messages` | Native Anthropic Messages API | `anthropic.Anthropic` via adapter |
-
-The mode determines how messages are formatted, how tool calls are structured, how responses are parsed, and how caching/streaming works. All three converge on the same internal message format (OpenAI-style `role`/`content`/`tool_calls` dicts) before and after API calls.
-
-**Mode resolution order:**
-1. Explicit `api_mode` constructor arg (highest priority)
-2. Provider-specific detection (e.g., `anthropic` provider → `anthropic_messages`)
-3. Base URL heuristics (e.g., `api.anthropic.com` → `anthropic_messages`)
-4. Default: `chat_completions`
-
-## Turn Lifecycle
-
-Each iteration of the agent loop follows this sequence:
-
-```text
-run_conversation()
-  1. Generate task_id if not provided
-  2. Append user message to conversation history
-  3. Build or reuse cached system prompt (prompt_builder.py)
-  4. Check if preflight compression is needed (>50% context)
-  5. Build API messages from conversation history
-     - chat_completions: OpenAI format as-is
-     - codex_responses: convert to Responses API input items
-     - anthropic_messages: convert via anthropic_adapter.py
-  6. Inject ephemeral prompt layers (budget warnings, context pressure)
-  7. Apply prompt caching markers if on Anthropic
-  8. Make interruptible API call (_interruptible_api_call)
-  9. Parse response:
-     - If tool_calls: execute them, append results, loop back to step 5
-     - If text response: persist session, flush memory if needed, return
-```
-
-### Message Format
-
-All messages use OpenAI-compatible format internally:
-
-```python
-{"role": "system", "content": "..."}
-{"role": "user", "content": "..."}
-{"role": "assistant", "content": "...", "tool_calls": [...]}
-{"role": "tool", "tool_call_id": "...", "content": "..."}
-```
-
-Reasoning content (from models that support extended thinking) is stored in `assistant_msg["reasoning"]` and optionally displayed via the `reasoning_callback`.
-
-### Message Alternation Rules
-
-The agent loop enforces strict message role alternation:
-
-- After the system message: `User → Assistant → User → Assistant → ...`
-- During tool calling: `Assistant (with tool_calls) → Tool → Tool → ... → Assistant`
-- **Never** two assistant messages in a row
-- **Never** two user messages in a row
-- **Only** `tool` role can have consecutive entries (parallel tool results)
-
-Providers validate these sequences and will reject malformed histories.
-
-## Interruptible API Calls
-
-API requests are wrapped in `_interruptible_api_call()` which runs the actual HTTP call in a background thread while monitoring an interrupt event:
-
-```text
-┌────────────────────────────────────────────────────┐
-│  Main thread                  API thread           │
-│                                                    │
-│   wait on:                     HTTP POST           │
-│    - response ready     ───▶   to provider         │
-│    - interrupt event                               │
-│    - timeout                                       │
-└────────────────────────────────────────────────────┘
-```
-
-When interrupted (user sends new message, `/stop` command, or signal):
-- The API thread is abandoned (response discarded)
-- The agent can process the new input or shut down cleanly
-- No partial response is injected into conversation history
-
-## Tool Execution
-
-### Sequential vs Concurrent
-
-When the model returns tool calls:
-
-- **Single tool call** → executed directly in the main thread
-- **Multiple tool calls** → executed concurrently via `ThreadPoolExecutor`
-  - Exception: tools marked as interactive (e.g., `clarify`) force sequential execution
-  - Results are reinserted in the original tool call order regardless of completion order
-
-### Execution Flow
-
-```text
-for each tool_call in response.tool_calls:
-    1. Resolve handler from tools/registry.py
-    2. Fire pre_tool_call plugin hook
-    3. Check if dangerous command (tools/approval.py)
-       - If dangerous: invoke approval_callback, wait for user
-    4. Execute handler with args + task_id
-    5. Fire post_tool_call plugin hook
-    6. Append {"role": "tool", "content": result} to history
-```
-
-### Agent-Level Tools
-
-Some tools are intercepted by `agent/tool_executor.py` (called from `agent/conversation_loop.py`) *before* reaching `handle_function_call()`:
-
-| Tool | Why intercepted |
-|------|--------------------|
-| `todo` | Reads/writes agent-local task state |
-| `memory` | Writes to persistent memory files with character limits |
-| `session_search` | Queries session history via the agent's session DB |
-| `delegate_task` | Spawns subagent(s) with isolated context |
-
-These tools modify agent state directly and return synthetic tool results without going through the registry.
-
-## Callback Surfaces
-
-`AIAgent` supports platform-specific callbacks that enable real-time progress in the CLI, gateway, and ACP integrations:
-
-| Callback | When fired | Used by |
-|----------|-----------|---------|
-| `tool_progress_callback` | Before/after each tool execution | CLI spinner, gateway progress messages |
-| `thinking_callback` | When model starts/stops thinking | CLI "thinking..." indicator |
-| `reasoning_callback` | When model returns reasoning content | CLI reasoning display, gateway reasoning blocks |
-| `clarify_callback` | When `clarify` tool is called | CLI input prompt, gateway interactive message |
-| `step_callback` | After each complete agent turn | Gateway step tracking, ACP progress |
-| `stream_delta_callback` | Each streaming token (when enabled) | CLI streaming display |
-| `tool_gen_callback` | When tool call is parsed from stream | CLI tool preview in spinner |
-| `status_callback` | State changes (thinking, executing, etc.) | ACP status updates |
-
-## Budget and Fallback Behavior
-
-### Iteration Budget
-
-The agent tracks iterations via `IterationBudget`:
-
-- Default: 500 iterations (configurable via `agent.max_turns`)
-- Each agent gets its own budget. Subagents get independent budgets capped at `delegation.max_iterations` (default 50) — total iterations across parent + subagents can exceed the parent's cap
-- At 100%, the agent stops and returns a summary of work done
-
-### Fallback Model
-
-When the primary model fails (429 rate limit, 5xx server error, 401/403 auth error):
-
-1. Check `fallback_providers` list in config
-2. Try each fallback in order
-3. On success, continue the conversation with the new provider
-4. On 401/403, attempt credential refresh before failing over
-
-The fallback system also covers auxiliary tasks independently — vision, compression, and web extraction each have their own fallback chain configurable via the `auxiliary.*` config section.
-
-## Compression and Persistence
-
-### When Compression Triggers
-
-- **Preflight** (before API call): If conversation exceeds 50% of model's context window
-- **Gateway auto-compression**: If conversation exceeds 85% (more aggressive, runs between turns)
-
-### What Happens During Compression
-
-1. Memory is flushed to disk first (preventing data loss)
-2. Middle conversation turns are summarized into a compact summary
-3. The last N messages are preserved intact (`compression.protect_last_n`, default: 20)
-4. Tool call/result message pairs are kept together (never split)
-5. A new session lineage ID is generated (compression creates a "child" session)
-
-### Session Persistence
-
-After each turn:
-- Messages are saved to the session store (SQLite via `hermes_state.py`)
-- Memory changes are flushed to `MEMORY.md` / `USER.md`
-- The session can be resumed later via `/resume` or `hermes chat --resume`
-
-## Key Source Files
-
-| File | Purpose |
-|------|---------|
-| `run_agent.py` | `AIAgent` facade — public entry points; loop and turn phases live in `agent/` |
-| `agent/conversation_loop.py` | The agent loop (`run_conversation()` body) |
-| `agent/turn_*.py` | Turn phases: iteration_prep, api_call, api_error, overflow, truncation, recovery |
-| `agent/tool_executor.py` | Tool-call execution and agent-level tool interception |
-| `agent/prompt_builder.py` | System prompt assembly from memory, skills, context files, personality |
-| `agent/context_engine.py` | ContextEngine ABC — pluggable context management |
-| `agent/context_compressor.py` | Default engine — lossy summarization algorithm |
-| `agent/prompt_caching.py` | Anthropic prompt caching markers and cache metrics |
-| `agent/auxiliary_client.py` | Auxiliary LLM client for side tasks (vision, summarization) |
-| `model_tools.py` | Tool schema collection, `handle_function_call()` dispatch |
-
-## Related Docs
-
-- [Provider Runtime Resolution](./provider-runtime.md)
-- [Prompt Assembly](./prompt-assembly.md)
-- [Context Compression & Prompt Caching](./context-compression-and-caching.md)
-- [Tools Runtime](./tools-runtime.md)
-- [Architecture Overview](./architecture.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/architecture.md

@@ -1,279 +0,0 @@
----
-sidebar_position: 1
-title: "Architecture"
-description: "Hermes Agent internals — major subsystems, execution paths, data flow, and where to read next"
----
-
-# Architecture
-
-This page is the top-level map of Hermes Agent internals. Use it to orient yourself in the codebase, then dive into subsystem-specific docs for implementation details.
-
-## System Overview
-
-```text
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Entry Points                                  │
-│                                                                      │
-│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)     │
-│  Batch Runner    API Server                  Python Library          │
-└──────────┬──────────────┬───────────────────────┬───────────────────┘
-           │              │                       │
-           ▼              ▼                       ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                     AIAgent (run_agent.py)                          │
-│                                                                     │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
-│  │ Prompt       │  │ Provider     │  │ Tool         │               │
-│  │ Builder      │  │ Resolution   │  │ Dispatch     │               │
-│  │ (prompt_     │  │ (runtime_    │  │ (model_      │               │
-│  │  builder.py) │  │  provider.py)│  │  tools.py)   │               │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
-│         │                 │                 │                       │
-│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
-│  │ Compression  │  │ 3 API Modes  │  │ Tool Registry│               │
-│  │ & Caching    │  │ chat_compl.  │  │ (registry.py)│               │
-│  │              │  │ codex_resp.  │  │ 70+ tools    │               │
-│  │              │  │ anthropic    │  │ 28 toolsets  │               │
-│  └──────────────┘  └──────────────┘  └──────────────┘               │
-└─────────┴─────────────────┴─────────────────┴───────────────────────┘
-           │                                    │
-           ▼                                    ▼
-┌───────────────────┐              ┌──────────────────────┐
-│ Session Storage   │              │ Tool Backends         │
-│ (SQLite + FTS5)   │              │ Terminal (7 backends) │
-│ hermes_state.py   │              │ Browser (5 backends)  │
-│ gateway/session.py│              │ Web (4 backends)      │
-└───────────────────┘              │ MCP (dynamic)         │
-                                   │ File, Vision, etc.    │
-                                   └──────────────────────┘
-```
-
-## Directory Structure
-
-```text
-hermes-agent/
-├── run_agent.py              # AIAgent facade — loop lives in agent/conversation_loop.py + agent/turn_*.py
-├── cli.py                    # HermesCLI facade — mixins in hermes_cli/cli_*_mixin.py
-├── model_tools.py            # Tool discovery, schema collection, dispatch
-├── toolsets.py               # Tool groupings and platform presets
-├── hermes_state.py           # SQLite session/state database facade (+ hermes_state_*.py siblings)
-├── hermes_constants.py       # HERMES_HOME, profile-aware paths
-├── batch_runner.py           # Batch trajectory generation
-│
-├── agent/                    # Agent internals
-│   ├── prompt_builder.py     # System prompt assembly
-│   ├── context_engine.py     # ContextEngine ABC (pluggable)
-│   ├── context_compressor.py # Default engine — lossy summarization
-│   ├── prompt_caching.py     # Anthropic prompt caching
-│   ├── auxiliary_client.py   # Auxiliary LLM for side tasks (vision, summarization)
-│   ├── model_metadata.py     # Model context lengths, token estimation
-│   ├── models_dev.py         # models.dev registry integration
-│   ├── anthropic_adapter.py  # Anthropic Messages API format conversion
-│   ├── display.py            # KawaiiSpinner, tool preview formatting
-│   ├── skill_commands.py     # Skill slash commands
-│   ├── memory_manager.py    # Memory manager orchestration
-│   ├── memory_provider.py   # Memory provider ABC
-│   └── trajectory.py         # Trajectory saving helpers
-│
-├── hermes_cli/               # CLI subcommands and setup
-│   ├── main.py               # Entry point — `hermes` subcommands (parsers in subcommands/, main_*.py)
-│   ├── config.py             # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
-│   ├── commands.py           # COMMAND_REGISTRY — central slash command definitions
-│   ├── auth.py               # PROVIDER_REGISTRY, credential resolution (+ auth_*.py siblings)
-│   ├── runtime_provider.py   # Provider → api_mode + credentials
-│   ├── models.py             # Model catalog, provider model lists
-│   ├── model_switch.py       # /model command logic (CLI + gateway shared)
-│   ├── setup.py              # Interactive setup wizard (+ setup_*.py siblings)
-│   ├── skin_engine.py        # CLI theming engine
-│   ├── skills_config.py      # hermes skills — enable/disable per platform
-│   ├── skills_hub.py         # /skills slash command
-│   ├── tools_config.py       # hermes tools — enable/disable per platform
-│   ├── plugins.py            # PluginManager — discovery, loading, hooks
-│   ├── callbacks.py          # Terminal callbacks (clarify, sudo, approval)
-│   └── gateway.py            # hermes gateway start/stop
-│
-├── tools/                    # Tool implementations (one file per tool)
-│   ├── registry.py           # Central tool registry
-│   ├── approval.py           # Dangerous command detection
-│   ├── terminal_tool.py      # Terminal orchestration
-│   ├── process_registry.py   # Background process management
-│   ├── file_tools.py         # read_file, write_file, patch, search_files
-│   ├── web_tools.py          # web_search, web_extract
-│   ├── browser_tool.py       # Browser automation tools facade (+ browser_tool_*.py siblings)
-│   ├── code_execution_tool.py # execute_code sandbox
-│   ├── delegate_tool.py      # Subagent delegation
-│   ├── mcp_tool.py           # MCP client facade (+ mcp_tool_*.py siblings)
-│   ├── credential_files.py   # File-based credential passthrough
-│   ├── env_passthrough.py    # Env var passthrough for sandboxes
-│   ├── ansi_strip.py         # ANSI escape stripping
-│   └── environments/         # Terminal backends (local, docker, ssh, modal, daytona, singularity)
-│
-├── gateway/                  # Messaging platform gateway
-│   ├── run.py                # GatewayRunner facade — message dispatch (+ run_*.py siblings)
-│   ├── session.py            # SessionStore — conversation persistence
-│   ├── delivery.py           # Outbound message delivery
-│   ├── pairing.py            # DM pairing authorization
-│   ├── hooks.py              # Hook discovery and lifecycle events
-│   ├── mirror.py             # Cross-session message mirroring
-│   ├── status.py             # Token locks, profile-scoped process tracking
-│   ├── builtin_hooks/        # Extension point for always-registered hooks (none shipped)
-│   └── platforms/            # Built-in adapters: signal, weixin, bluebubbles,
-│                             #   qqbot, whatsapp_cloud, yuanbao, webhook, api_server
-│
-├── plugins/platforms/        # Bundled platform plugins: telegram, discord, slack,
-│                             #   whatsapp, matrix, mattermost, email, sms, dingtalk,
-│                             #   feishu, wecom, homeassistant, irc, line, teams,
-│                             #   google_chat, buzz, ntfy, photon, raft, simplex
-│
-├── acp_adapter/              # ACP server (VS Code / Zed / JetBrains)
-├── cron/                     # Scheduler (jobs.py, scheduler.py)
-├── plugins/memory/           # Memory provider plugins
-├── plugins/context_engine/   # Context engine plugins
-├── skills/                   # Bundled skills (always available)
-├── optional-skills/          # Official optional skills (install explicitly)
-├── website/                  # Docusaurus documentation site
-└── tests/                    # Pytest suite (~25,000 tests across ~1,250 files)
-```
-
-## Data Flow
-
-### CLI Session
-
-```text
-User input → HermesCLI.process_input()
-  → AIAgent.run_conversation()
-    → prompt_builder.build_system_prompt()
-    → runtime_provider.resolve_runtime_provider()
-    → API call (chat_completions / codex_responses / anthropic_messages)
-    → tool_calls? → model_tools.handle_function_call() → loop
-    → final response → display → save to SessionDB
-```
-
-### Gateway Message
-
-```text
-Platform event → Adapter.on_message() → MessageEvent
-  → GatewayRunner._handle_message()
-    → authorize user
-    → resolve session key
-    → create AIAgent with session history
-    → AIAgent.run_conversation()
-    → deliver response back through adapter
-```
-
-### Cron Job
-
-```text
-Scheduler tick → load due jobs from jobs.json
-  → create fresh AIAgent (no history)
-  → inject attached skills as context
-  → run job prompt
-  → deliver response to target platform
-  → update job state and next_run
-```
-
-## Recommended Reading Order
-
-If you are new to the codebase:
-
-1. **This page** — orient yourself
-2. **[Agent Loop Internals](./agent-loop.md)** — how AIAgent works
-3. **[Prompt Assembly](./prompt-assembly.md)** — system prompt construction
-4. **[Provider Runtime Resolution](./provider-runtime.md)** — how providers are selected
-5. **[Adding Providers](./adding-providers.md)** — practical guide to adding a new provider
-6. **[Tools Runtime](./tools-runtime.md)** — tool registry, dispatch, environments
-7. **[Session Storage](./session-storage.md)** — SQLite schema, FTS5, session lineage
-8. **[Gateway Internals](./gateway-internals.md)** — messaging platform gateway
-9. **[Context Compression & Prompt Caching](./context-compression-and-caching.md)** — compression and caching
-10. **[ACP Internals](./acp-internals.md)** — IDE integration
-
-## Major Subsystems
-
-### Agent Loop
-
-The synchronous orchestration engine (`AIAgent`, exposed by the `run_agent.py` facade; the loop lives in `agent/conversation_loop.py` and `agent/turn_*.py`). Handles provider selection, prompt construction, tool execution, retries, fallback, callbacks, compression, and persistence. Supports three API modes for different provider backends.
-
-→ [Agent Loop Internals](./agent-loop.md)
-
-### Prompt System
-
-Prompt construction and maintenance across the conversation lifecycle:
-
-- **`system_prompt.py` + `prompt_builder.py`** — assembles the ordered system-prompt tiers (`stable` → `context` → `volatile`): identity/tool guidance/skills, context files, then memory/profile/timestamp blocks
-- **`prompt_caching.py`** — Applies Anthropic cache breakpoints for prefix caching
-- **`context_compressor.py`** — Summarizes middle conversation turns when context exceeds thresholds
-
-→ [Prompt Assembly](./prompt-assembly.md), [Context Compression & Prompt Caching](./context-compression-and-caching.md)
-
-### Provider Resolution
-
-A shared runtime resolver used by CLI, gateway, cron, ACP, and auxiliary calls. Maps `(provider, model)` tuples to `(api_mode, api_key, base_url)`. Handles 18+ providers, OAuth flows, credential pools, and alias resolution.
-
-→ [Provider Runtime Resolution](./provider-runtime.md)
-
-### Tool System
-
-Central tool registry (`tools/registry.py`) with 70+ registered tools across ~28 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 7 backends (local, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox).
-
-→ [Tools Runtime](./tools-runtime.md)
-
-### Session Persistence
-
-SQLite-based session storage with FTS5 full-text search. Sessions have lineage tracking (parent/child across compressions), per-platform isolation, and atomic writes with contention handling.
-
-→ [Session Storage](./session-storage.md)
-
-### Messaging Gateway
-
-Long-running process with 25+ platform adapters (built-in + bundled plugins), unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance.
-
-→ [Gateway Internals](./gateway-internals.md)
-
-### Plugin System
-
-Three discovery sources: `~/.hermes/plugins/` (user), `.hermes/plugins/` (project), and pip entry points. Plugins register tools, hooks, and CLI commands through a context API. Two specialized plugin types exist: memory providers (`plugins/memory/`) and context engines (`plugins/context_engine/`). Both are single-select — only one of each can be active at a time, configured via `hermes plugins` or `config.yaml`.
-
-→ [Plugin Guide](/developer-guide/plugins), [Memory Provider Plugin](./memory-provider-plugin.md)
-
-### Cron
-
-First-class agent tasks (not shell tasks). Jobs store in JSON, support multiple schedule formats, can attach skills and scripts, and deliver to any platform.
-
-→ [Cron Internals](./cron-internals.md)
-
-### ACP Integration
-
-Exposes Hermes as an editor-native agent over stdio/JSON-RPC for VS Code, Zed, and JetBrains.
-
-→ [ACP Internals](./acp-internals.md)
-
-### Trajectories
-
-Generates ShareGPT-format trajectories from agent sessions for training data generation.
-
-→ [Trajectories & Training Format](./trajectory-format.md)
-
-## Design Principles
-
-| Principle | What it means in practice |
-|-----------|--------------------------|
-| **Prompt stability** | System prompt doesn't change mid-conversation. No cache-breaking mutations except explicit user actions (`/model`). |
-| **Observable execution** | Every tool call is visible to the user via callbacks. Progress updates in CLI (spinner) and gateway (chat messages). |
-| **Interruptible** | API calls and tool execution can be cancelled mid-flight by user input or signals. |
-| **Platform-agnostic core** | One AIAgent class serves CLI, gateway, ACP, batch, and API server. Platform differences live in the entry point, not the agent. |
-| **Loose coupling** | Optional subsystems (MCP, plugins, memory providers, RL environments) use registry patterns and check_fn gating, not hard dependencies. |
-| **Profile isolation** | Each profile (`hermes -p <name>`) gets its own HERMES_HOME, config, memory, sessions, and gateway PID. Multiple profiles run concurrently. |
-
-## File Dependency Chain
-
-```text
-tools/registry.py  (no deps — imported by all tool files)
-       ↑
-tools/*.py  (each calls registry.register() at import time)
-       ↑
-model_tools.py  (imports tools/registry + triggers tool discovery)
-       ↑
-run_agent.py, cli.py, batch_runner.py, environments/
-```
-
-This chain means tool registration happens at import time, before any agent instance is created. Any `tools/*.py` file with a top-level `registry.register()` call is auto-discovered — no manual import list needed.