# Agent Tool Registry

`PWN::AI::Agent::Registry` (`lib/pwn/ai/agent/registry.rb`) collects every
LLM-callable function into named **toolsets**. A persona is granted a subset of
toolsets; the JSON-Schema for each tool is what the model actually sees.

![Tool registry](diagrams/agent-tool-registry.svg)

## Toolsets → Tools  (12 toolsets · 78 tools)

| Toolset | Tools | Backed by |
|---|---|---|
| `terminal` | `shell` | `Open3.capture3` on the host |
| `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
| `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |
| `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`reward_warm_sentinel`** · **`reward_scrub_preferences`** · **`reward_preference_balance`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** · **`curriculum_offline_judge`** · **`curriculum_preference_balance`** · **`learning_purge_noise`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` + `~/.pwn/finetune/` |
| `reward` | **`reward_generator_mix`** | `PWN::AI::Agent::Reward.generator_mix` → W1 online source-mix controller (`preferences.jsonl`) |
| `curriculum` | **`curriculum_practice_kpi`** | `PWN::AI::Agent::Curriculum.practice_kpi` → `~/.pwn/curriculum_kpi.jsonl` |
| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser/GQRX) → `~/.pwn/extrospection.json` |
| `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
| `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |

The `learning` toolset is deliberately fat: **Mistakes** (negative feedback),
**Reward** (ORM/PRM/sentinel/DPO ledger) and **Curriculum** (self-play, HER,
regression-gated LoRA) are all facets of the same self-improvement loop -
see [Reinforcement Learning](Reinforcement-Learning.md). The thin `reward` and
`curriculum` toolsets expose controller/KPI surfaces (`reward_generator_mix`,
`curriculum_practice_kpi`) so personas can grant just those without the full
learning surface.

## Dynamic tool-set slimming (`ai.agent.tool_router`)

Shipping every schema on every turn overwhelms a small local model - the
choice space is huge and it mis-routes (e.g. picks an RF tool for a git
question). When `ai.agent.tool_router: true` **and** `Loop.run` passes the
user request through as `relevance:`, `Registry.definitions` shrinks the
pool to:

```text
CORE_TOOLS  = shell · pwn_eval · memory_remember · memory_recall
              mistakes_record · mistakes_resolve · learning_note_outcome
            + top-K keyword-ranked matches for THIS request
              (ties break on Metrics per-engine success_rate → the router
               itself is a learned component)
```

```ruby
PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10.0.0.0/8', top_k: 10)
PWN::AI::Agent::Registry.rank(query: 'run a shell command')   # inspect ranking
PWN::AI::Agent::Registry.toolsets                              # → the 12 names above
PWN::AI::Agent::Registry.all.count                             # → 78
```

Frontier engines leave `tool_router` off and receive the full set.

## Adding a tool

```ruby
# lib/pwn/ai/agent/tools/my_thing.rb
PWN::AI::Agent::Registry.register(
  name: 'my_thing_do',
  toolset: 'my_thing',
  description: 'One-line summary the LLM will read.',
  parameters: {
    type: 'object',
    properties: { target: { type: 'string' } },
    required: ['target']
  }
) do |args|
  PWN::Plugins::MyThing.do(target: args['target'])
end
```

Drop the file in `lib/pwn/ai/agent/tools/`, it's auto-loaded on next launch.

## Restricting a persona

```yaml
# ~/.pwn/agents.yml
recon:
  role: "Passive OSINT only. Never touch the target directly."
  toolsets: [terminal, pwn, memory, extrospection]   # no swarm, no cron
  engine: ollama
```

**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) ·
[Reinforcement Learning](Reinforcement-Learning.md) · [Swarm](Swarm.md)

[← Home](Home.md)