Agent docs + cont cleanup

Author: ddebowczyk

docs-build/packages/addons/agent_hooks.mdx

@@ -44,7 +44,7 @@ $agent = AgentBuilder::new()
     })
 
     ->build();
-// @doctest id="d533"
+// @doctest id="0b6a"
 ```
 
 ## Lifecycle Events
@@ -104,7 +104,7 @@ HookOutcome::block('Dangerous command detected');
 
 // Stop the entire agent execution
 HookOutcome::stop('Budget exceeded');
-// @doctest id="5fcb"
+// @doctest id="c30c"
 ```
 
 ### Semantic Differences
@@ -146,7 +146,7 @@ function afterTool(ToolHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="3350"
+// @doctest id="c2c9"
 ```
 
 ### StepHookContext
@@ -167,7 +167,7 @@ function onStep(StepHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="5436"
+// @doctest id="a05b"
 ```
 
 ### StopHookContext
@@ -187,7 +187,7 @@ function onStop(StopHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed(); // Allow stop
 }
-// @doctest id="9ed0"
+// @doctest id="4b98"
 ```
 
 ### ExecutionHookContext
@@ -206,7 +206,7 @@ function onExecution(ExecutionHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="b895"
+// @doctest id="b2ba"
 ```
 
 ### FailureHookContext
@@ -223,7 +223,7 @@ function onFailure(FailureHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="4fb2"
+// @doctest id="d10a"
 ```
 
 ## Matchers
@@ -247,7 +247,7 @@ new ToolNameMatcher('*');        // Match all
 
 // Regex patterns
 new ToolNameMatcher('/^(read|write)_.+$/');
-// @doctest id="b8d2"
+// @doctest id="551f"
 ```
 
 ### EventTypeMatcher
@@ -263,7 +263,7 @@ new EventTypeMatcher(HookEvent::PreToolUse);
 
 // Multiple events
 new EventTypeMatcher(HookEvent::BeforeStep, HookEvent::AfterStep);
-// @doctest id="cdc1"
+// @doctest id="e7d1"
 ```
 
 ### CompositeMatcher
@@ -294,7 +294,7 @@ $matcher = CompositeMatcher::and(
     ),
     new CallableMatcher(fn($ctx) => $ctx->state()->metadata()->get('safe_mode')),
 );
-// @doctest id="1cbe"
+// @doctest id="3fa0"
 ```
 
 ### CallableMatcher
@@ -307,7 +307,7 @@ use Cognesy\Addons\Agent\Hooks\Matchers\CallableMatcher;
 $matcher = new CallableMatcher(function (HookContext $ctx): bool {
     return $ctx->state()->metadata()->get('priority') === 'high';
 });
-// @doctest id="206c"
+// @doctest id="11ff"
 ```
 
 ## Priority
@@ -324,7 +324,7 @@ $builder
 
     // Logging hooks run last (low priority)
     ->onAfterToolUse($logger, priority: -100);
-// @doctest id="8d5b"
+// @doctest id="cc4f"
 ```
 
 **Priority Guidelines:**
@@ -352,7 +352,7 @@ $builder->onAfterToolUse(
     priority: int = 0,
     matcher: string|HookMatcher|null = null,
 );
-// @doctest id="cf6b"
+// @doctest id="1890"
 ```
 
 ### Step Hooks
@@ -367,7 +367,7 @@ $builder->onBeforeStep(
 $builder->onAfterStep(
     callback: callable,  // (AgentState) -> AgentState
 );
-// @doctest id="1c3a"
+// @doctest id="1cde"
 ```
 
 ### Execution Hooks
@@ -384,7 +384,7 @@ $builder->onExecutionEnd(
     callback: callable,  // (ExecutionHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="764c"
+// @doctest id="03ea"
 ```
 
 ### Continuation Hooks
@@ -401,7 +401,7 @@ $builder->onSubagentStop(
     callback: callable,  // (StopHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="bc96"
+// @doctest id="e288"
 ```
 
 ### Error Hooks
@@ -412,7 +412,7 @@ $builder->onAgentFailed(
     callback: callable,  // (FailureHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="2105"
+// @doctest id="8753"
 ```
 
 ### Unified Registration
@@ -428,7 +428,7 @@ $builder->addHook(
     hook: new CallableHook($callback, $matcher),
     priority: 100,
 );
-// @doctest id="a2f3"
+// @doctest id="f4ae"
 ```
 
 ## Creating Custom Hooks
@@ -457,7 +457,7 @@ class RateLimitHook implements Hook
         return $next($context);
     }
 }
-// @doctest id="c4e8"
+// @doctest id="b8bf"
 ```
 
 ## Using HookStack Directly
@@ -482,7 +482,7 @@ if ($outcome->isBlocked()) {
 } elseif ($outcome->isStopped()) {
     // Handle stopped
 }
-// @doctest id="d55e"
+// @doctest id="0117"
 ```
 
 ## Backward Compatibility
@@ -498,7 +498,7 @@ use Cognesy\Addons\Agent\Hooks\Adapters\StateProcessorAdapter;
 
 $processor = new YourStateProcessor();
 $hook = new StateProcessorAdapter($processor, position: 'after');
-// @doctest id="7fc3"
+// @doctest id="cc72"
 ```
 
 ### ContinuationCriteriaAdapter
@@ -508,7 +508,7 @@ use Cognesy\Addons\Agent\Hooks\Adapters\ContinuationCriteriaAdapter;
 
 $criterion = new YourContinuationCriterion();
 $hook = new ContinuationCriteriaAdapter($criterion);
-// @doctest id="7f26"
+// @doctest id="3046"
 ```
 
 ## Common Patterns
@@ -533,7 +533,7 @@ $builder->onBeforeToolUse(
     priority: 100, // Run first
     matcher: 'bash',
 );
-// @doctest id="3218"
+// @doctest id="954f"
 ```
 
 ### Execution Timing
@@ -550,7 +550,7 @@ $builder
         $duration = microtime(true) - $started;
         $this->metrics->record('execution_duration', $duration);
     });
-// @doctest id="9c44"
+// @doctest id="b850"
 ```
 
 ### Conditional Continuation
@@ -573,7 +573,7 @@ $builder->onStop(function (StopHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 });
-// @doctest id="b9e6"
+// @doctest id="3ec4"
 ```
 
 ### Error Recovery Logging
@@ -599,7 +599,7 @@ $builder->onAgentFailed(function (FailureHookContext $ctx): void {
         $this->alerting->sendCritical($exception);
     }
 });
-// @doctest id="eafe"
+// @doctest id="973e"
 ```
 
 ## Architecture
@@ -631,7 +631,7 @@ $builder->onAgentFailed(function (FailureHookContext $ctx): void {
 │  │ execution│  │ action   │  │ entirely │                  │
 │  └──────────┘  └──────────┘  └──────────┘                  │
 └─────────────────────────────────────────────────────────────┘
-// @doctest id="e007"
+// @doctest id="d779"
 ```
 
 ## File Structure
@@ -672,5 +672,5 @@ packages/addons/src/Agent/Hooks/
 └── Adapters/
     ├── StateProcessorAdapter.php
     └── ContinuationCriteriaAdapter.php
-// @doctest id="d08d"
+// @doctest id="5d5f"
 ```

docs-build/packages/agents/01-introduction.mdx

@@ -0,0 +1,38 @@
+# Introduction
+
+The Agents package provides a minimal, composable foundation for building LLM-powered agents that reason and act through tool use.
+
+At its core, an agent is a **loop**: send messages to an LLM, receive a response (possibly with tool calls), execute those tools, feed results back, and repeat until done.
+
+## Key Design Principles
+
+- **Immutable state** - `AgentState` is a readonly value object. Every mutation returns a new instance.
+- **Pluggable drivers** - Swap between `ToolCallingDriver` (native function calling) and `ReActDriver` (Thought/Action/Observation) without changing your agent code.
+- **Lifecycle hooks** - Intercept any phase of execution to add guards, logging, or custom behavior.
+- **Testable by default** - `FakeAgentDriver` lets you script deterministic scenarios without LLM calls.
+
+## Package Structure
+
+```
+Core/           # AgentLoop, AgentState, tools, stop signals
+Context/        # AgentContext, message compilers
+Hooks/          # Lifecycle interceptors and guard hooks
+Drivers/        # ToolCallingDriver, ReActDriver, FakeAgentDriver
+Events/         # Agent event system
+Exceptions/     # Domain exceptions
+// @doctest id="60e4"
+```
+
+## Minimal Example
+
+```php
+use Cognesy\Agents\Core\AgentLoop;
+use Cognesy\Agents\Core\Data\AgentState;
+
+$loop = AgentLoop::default();
+$state = AgentState::empty()->withUserMessage('Hello!');
+$result = $loop->execute($state);
+
+echo $result->finalResponse()->toString();
+// @doctest id="a416"
+```

docs-build/packages/agents/02-basic-agent.mdx

@@ -0,0 +1,51 @@
+# Basic Agent
+
+The simplest agent uses `AgentLoop` to send a message and get a response.
+
+## Hello World
+
+```php
+use Cognesy\Agents\Core\AgentLoop;
+use Cognesy\Agents\Core\Data\AgentState;
+
+$loop = AgentLoop::default();
+$state = AgentState::empty()->withUserMessage('What is 2+2?');
+$result = $loop->execute($state);
+
+echo $result->finalResponse()->toString();
+// "2 + 2 equals 4."
+// @doctest id="635f"
+```
+
+## What Happens
+
+1. `AgentLoop::execute()` starts the loop
+2. The driver (`ToolCallingDriver`) sends messages to the LLM
+3. LLM responds with text (no tool calls)
+4. The loop detects no tool calls and stops
+5. Final response is available via `$result->finalResponse()`
+
+## Customizing the Loop
+
+Use `with()` to swap components on the default loop:
+
+```php
+use Cognesy\Agents\Core\Collections\Tools;
+use Cognesy\Agents\Drivers\ReAct\ReActDriver;
+
+// Add tools
+$loop = AgentLoop::default()->withTool($myTool);
+
+// Swap driver
+$loop = AgentLoop::default()->withDriver(new ReActDriver(model: 'gpt-4o'));
+// @doctest id="ded1"
+```
+
+## System Prompt
+
+```php
+$state = AgentState::empty()
+    ->withSystemPrompt('You are a helpful assistant.')
+    ->withUserMessage('Hello!');
+// @doctest id="aae4"
+```

docs-build/packages/agents/03-tools.mdx

@@ -0,0 +1,56 @@
+# Tools
+
+Tools let the agent take actions. The LLM decides which tool to call and with what arguments.
+
+## Registering Tools
+
+Pass tools to the `Tools` collection:
+
+```php
+use Cognesy\Agents\Core\Collections\Tools;
+use Cognesy\Agents\Core\Tools\MockTool;
+
+$calculator = MockTool::returning('calculator', 'Performs math', '42');
+$tools = new Tools($calculator);
+// @doctest id="6d99"
+```
+
+## Using FunctionTool
+
+Wrap any callable as a tool. Parameter schema is auto-generated from the function signature:
+
+```php
+use Cognesy\Agents\Core\Tools\FunctionTool;
+
+$tool = FunctionTool::fromCallable(
+    function (string $city): string {
+        return "Weather in {$city}: 72F, sunny";
+    }
+);
+
+$tools = new Tools($tool);
+// @doctest id="9675"
+```
+
+## Agent with Tools
+
+```php
+use Cognesy\Agents\Core\AgentLoop;
+use Cognesy\Agents\Core\Collections\Tools;
+use Cognesy\Agents\Core\Data\AgentState;
+
+$loop = AgentLoop::default()->withTool($tool);
+
+$state = AgentState::empty()->withUserMessage('What is the weather in Paris?');
+$result = $loop->execute($state);
+// LLM calls the weather tool, gets result, then responds
+// @doctest id="255a"
+```
+
+## How It Works
+
+1. LLM sees tool schemas and decides to call a tool
+2. `ToolExecutor` runs the tool with provided arguments
+3. Tool results are formatted as messages and fed back to the LLM
+4. LLM uses the results to formulate a final response
+5. Loop continues until LLM responds without tool calls