tools / registry.py

Single source of truth for every LLM-facing tool. Builds the active definition list per turn, dispatches calls, injects context.

Built-in tools

Tool name	Module	Purpose
`delegate_to_swarm`	swarm	Fire-and-forget background task dispatch with optional blocking await.
`system_utility`	system	Diagnostics / health / weather / location.
`file_system`	file_system	Unified read / write / search / list / find / download / move / delete.
`knowledge_base`	memory tools	Memory ingestion: insert_fact, ingest_document, forget, list_docs, reset_all.
`recall`	memory tools	Vector semantic search.
`execute`	execute	Code execution: Python / Node / Bash; stateful Jupyter.
`learn_skill`	memory tools	Persistent lesson storage.
`web_search`	search	Anonymous DDG search via Tor.
`deep_research`	search	Multi-source synthesis (falls back to web_search).
`fact_check`	search	Claim verification using deep_research.
`update_profile`	memory tools	Persistent user facts.
`manage_projects`	projects	Project lifecycle + tasks.
`manage_tasks`	tasks	Cron / interval background jobs.
`dream_mode`	memory tools	Active memory consolidation trigger.
`self_play`	memory tools	One synthetic self-training cycle (600 s wall-clock cap).
`self_play_loop`	memory tools	Continuous background self-play loop; stops on any user message or `stop_self_play`. Optional `max_cycles` and `model` override.
`stop_self_play`	memory tools	Stop the running self-play loop after its current cycle.
`list_lessons`	memory tools	Surface the LESSON playbook (mistakes-and-fixes the agent has internalized). `scope ∈ {today, week, all, self_play_only}`. Read-only; exempt from the meta-task compliance nudge. NOT for "show me your skills" — that is a TOOL list and routes to `manage_skills`.
`replan`	core/agent	Strategy reset signal.
`abort_attempt`	core/agent	Escape hatch for unsolvable tasks.
`scratchpad`	memory tools	Short-term KV: set / get / list / clear.
`postgres_admin`	database	SQL exec, schema dump, EXPLAIN ANALYZE, activity.
`create_skill`	acquired_skills	TDD-validated skill acquisition.
`manage_skills`	acquired_skills	List / delete the agent's acquired SKILLS (custom Python tools created via `create_skill`). This is the routing target for "show me your skills", "list your skills", "what skills do you have". Distinct from `list_lessons`: a SKILL is a tool, a LESSON is a mistake-and-fix.
`vision_analysis`	vision	Image / PDF analysis (auto-registered when vision-capable LLM available).
`image_generation`	image_gen	SDXL gen (auto-registered when `image_gen_clients` configured).

Plus dynamic tools added at runtime: every active acquired skill and every registered composed skill appears as its own LLM-facing tool definition.

Active list construction

get_active_tool_definitions(context, query) assembles the per-turn tool list:

Start with the static TOOL_DEFINITIONS array.
Append vision_analysis when the LLM client supports vision (line 234).
Append image_generation when context.llm_client.image_gen_clients exists (line 262).
If a query is provided, RAG-retrieve relevant acquired skills via memory_system.collection.query(query_texts=[query], where={"type": "acquired_skill"}) and inject only the matches (line 293-309).
Otherwise inject every active-status acquired skill that doesn't shadow a built-in (line 312-337).
register_composed_skills(active_tools, context) appends macro tools (line 345-348).
_intent_filter drops tools whose required configuration is missing (e.g. postgres_admin without a DSN).

Dispatch & handler binding

get_available_tools(context) returns a dict of tool_name → async lambda. Each lambda binds the live sandbox_dir, memory_system, llm_client, scheduler, and other context state to the underlying tool function so the tool implementations stay stateless.

Acquired skills run via tool_execute(filename=f"acquired_skills/{name}.py", args=[json_kwargs]) (line 436). Success / failure telemetry is recorded by manager.log_telemetry(name, success).

Fallback & failure routing

A failure raised by any tool is classified by tool_failure.classify(). RETRYABLE failures retry with exponential backoff (max 3 attempts). FATAL trigger replan. DIAGNOSTIC inject the full error so the LLM can self-correct. UNKNOWN inject a brief notice. Per-tool fallback chains in fallback_chains.py suggest alternatives.

Diagram

Figure 7 — Tool-call dispatch path through the registry.