pwn 0.5.668 → 0.5.670

data/documentation/pwn-ai-Agent.md

@@ -90,7 +90,7 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
 
 ## What the agent can call
 
-12 toolsets · **78 tools** - full table at
+12 toolsets · **82 tools** - full table at
 [Agent Tool Registry](Agent-Tool-Registry.md).
 
 The two that matter most:
@@ -113,12 +113,21 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
 
 ## Task summaries (long autonomous turns)
 
-`PWN::AI::Agent::TaskSummarizer` keeps the TUI readable during multi-step work:
+`PWN::AI::Agent::TaskSummarizer` keeps the TUI readable during multi-step work.
+First it classifies the request with `request_kind` (LLM when enabled, else
+heuristics / `request_intent`):
+
+| Kind | Example | Task breakdown |
+|---|---|---|
+| `statement` | "FYI the build is green." | None - brief ack only |
+| `question` | "what is the default GQRX port?" / "how to ...?" | None - concise answer only |
+| `autonomous_goal` | "refactor Loop.run and run rubocop" / "what is my hostname?" | **Required** ordered work units (each may use one or more tools) |
 
 | Surface | When | Content |
 |---|---|---|
-| `emit_plan!` | User submit | **Full** goal + ordered plain-English tangible tasks (each may need many tools) |
-| `about_to` | Before each tool batch | **Primary:** `task k/n: <english>`  -  **secondary:** `via shell×2 (search)` (not raw argv) |
+| `request_kind` | User submit | `statement` \| `question` \| `autonomous_goal` |
+| `emit_plan!` | Autonomous goals only | **Full** goal + ordered plain-English tangible tasks (each may need many tools) |
+| `about_to` | Before each tool batch | **Primary:** `task k/n: <english>` - **secondary:** `via shell×2 (search)` (not raw argv) |
 | `plan_context` / `active_task_prompt` | Into Loop messages | Same English tasks steer tool choice (not TUI-only) |
 | `record!` | After each tool | Advances `plan_idx`; emits English advancement brief when the index moves; verbose progress only if `task_summary_verbose` |
 | `flush!` | End of turn | Optional closing brief with active `task k/n` |
@@ -131,7 +140,7 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
 - Advancement needs a PRM +1 streak or a clear phase shift after tools on the active task (not a blind every-3-tools hop).
 - REPL contract: `on_tool.call('task', full_summary_text, '')` - result empty, no truncation.
 
-**Budget pressure:** when unresolved `agent_loop` / `assistant_answer` budget-exhaustion fingerprints dominate, `Loop.budget_exhaustion_hot?` tightens the live turn (stricter `max_iters` on local engines than remote), forces a text-only tail, skips counterfactual forks, and still flushes task state + Learning on the exhaust path.
+**Long-run pressure:** when recent turns keep hitting the iteration ceiling, the agent tightens the rest of the turn: lower `max_iters` (stricter on local engines than remote), a text-only finish, and no extra counterfactual forks. Task state and Learning still flush on the way out so the run ends with a real answer instead of thrashing.
 
 ![TaskSummarizer](diagrams/task-summarizer.svg)
 
@@ -142,6 +151,8 @@ task_summary: true              # master switch (default on)
 task_summary_every: 5           # verbose progress every N tools
 task_summary_interval_s: 8.0    # or every N seconds (verbose)
 task_summary_verbose: false     # mid-flight Progress: lines
+task_summary_llm: true          # LLM task decompose for autonomous goals (default on)
+request_kind_llm: null          # null = follow task_summary_llm; false = heuristic-only
 max_iters: 25                   # budget pressure may lower the effective cap (stricter on local engines)
 ```
 
@@ -157,18 +168,17 @@ max_iters: 25                   # budget pressure may lower the effective cap (s
 - Run `mistakes_list` before retrying something that failed last session -
   the fix may already be recorded.
 - `ai.agent.tool_router: true` + `ai.agent.plan_first: true` when running on
-  a local model - dramatically cuts mis-routing.
+  a local model - that cuts mis-routing a lot.
 - Set `ai.reflect_engine:` to a frontier provider so lessons written to
-  `~/.pwn/memory.json` are high-signal even when the *executing* engine is
+  `~/.pwn/memory.json` stay high-signal even when the executing engine is
   local.
-- `PWN::AI::Agent::Learning.export_finetune` + `Reward.export_dpo` turn every
-  successful session and every preference pair into supervised / DPO
-  datasets under `~/.pwn/finetune/` - `Curriculum.train_and_gate` then
-  LoRA-tunes the local model and promotes only under **gate v2** (resolved
-  margin + mean judge + frozen smoke set). Preference pairs prefer trajectory
-  geometry: revised answers and winning traces, not fix-commentary prose.
-  `scrub_preferences` and the export filter enforce that; practice lands
-  winning traces.
+- `PWN::AI::Agent::Learning.export_finetune` and `Reward.export_dpo` turn
+  successful sessions and preference pairs into supervised / preference
+  datasets under `~/.pwn/finetune/`. `Curriculum.train_and_gate` can then
+  fine-tune a local model and promote only when resolved-mistake margin,
+  mean judge score, and a frozen smoke set all look healthy. Preference
+  pairs should be real answer revisions and winning traces, not fix-commentary
+  prose. `scrub_preferences` and the export filter enforce that.
   See [Reinforcement Learning](Reinforcement-Learning.md).
 
 ## RL feature flags (`PWN::Env[:ai][:agent]`)
@@ -189,3 +199,31 @@ Full detail: [Reinforcement Learning](Reinforcement-Learning.md).
 [Extrospection](Extrospection.md) · [Swarm](Swarm.md) · [Cron](Cron.md)
 
 [← Home](Home.md)
+
+## Intent routing (kind + fine-grained intent)
+
+Every user turn is classified on two layers:
+
+1. **`request_kind`** - `statement` | `question` | `autonomous_goal` (TaskSummarizer is the
+   single source of truth; `Loop.request_kind` delegates). Classification order:
+   injected label (tests) → cheap `request_intent` short-circuits (greeting/howto/recall/recon) →
+   strong agent-do / host-evidence heuristics → **LLM classify** via `chat_for_kind`
+   (when `ai.agent.request_kind_llm` is on / follows `task_summary_llm`) → offline
+   `heuristic_request_kind`. Only autonomous goals receive a multi-step tangible-task plan.
+2. **`request_intent`** - fine-grained route for cheap short-circuits and recon guard.
+
+| Intent | Kind | Example | Behavior |
+|--------|------|---------|----------|
+| How-to | question | "how to do a ping sweep of a subnet using hping3?" | Short explanation with example commands only. No tools and no multi-step plan. |
+| Question | question | "what is the default GQRX remote-control port?" | Concise answer. No multi-step task breakdown. |
+| Host evidence | autonomous_goal | "what is my hostname?" / "excellent - what is my hostname?" | Needs a live local lookup (hostname, cwd, whoami, IP, ...). Treated as a goal so tools run; not text-only Q&A. |
+| Greeting | statement | "Howdy, it's cloudy." / "hi" | Fixed short ack that the system is ready. No tools, no LLM, and no weather echo such as "noted, cloudy out there." |
+| Statement | statement | "FYI the build is green." | Brief note. No multi-step task plan. |
+| Recall | question | "what did I just say?" / "how did you respond?" | Cheap prior-turn answer from the session transcript. No plan_first and no multi-tool archaeology. |
+| Live recon | autonomous_goal | "using hping3 what live hosts can you find in this subnet?" | Needs clear in-scope / authorized engagement wording, or set `ai.agent.recon_authorized=true`. Otherwise the agent refuses and points you at the how-to form. |
+| Act | autonomous_goal | "refactor Loop.run and run rubocop" | Normal multi-step agent work: decompose into ordered work units, each may use one or more tools. |
+
+The `shell` tool also blocks hping3 / nmap-style sweep commands when recon is
+not authorized. On how-to asks, memory SOPs about repo rubocop/rake hygiene are
+kept out of the prompt so the model does not pivot into unrelated verification.
+