Agents cleanup cont

Author: Dariusz Debowczyk

.beads/.local_version

@@ -1 +1 @@
-0.49.0
+0.49.3

.beads/bd.sock.startlock

@@ -24,13 +24,78 @@ Each package in `packages/` may contain:
 - Avoid exceptions for control flow - do not wrap everything in try/catch; either let exceptions bubble up or use monadic Cognesy\Utils\Result\Result for error handling if error needs to be handled on the same level
 - Use namespaces and PSR-4 autoloading
 
+## Agents Package Style
+
+- Data classes are `readonly final class` — all properties readonly, all mutations return new instances via `with*()` methods
+- Interfaces use `Can-` prefix (`CanUseTools`, `CanEmitAgentEvents`, `CanInterceptAgentLifecycle`)
+- Hooks use `Hook` suffix (`StepsLimitHook`, `ErrorPolicyHook`)
+- Accessors have no prefix: `state()`, `execution()`, `currentStep()` — not `getState()`
+- Mutators use `with` prefix and return `self`: `withState()`, `withCurrentStep()`
+- Named constructors for defaults: `::empty()`, `::fresh()`; for hydration: `::fromArray()`
+- Minimal docblocks — only on class/interface declarations; methods are self-documenting via types and naming
+- Method order: constructors → lifecycle/transitions → accessors → mutators → private helpers → serialization (`toArray`/`fromArray`)
+- Enums are string-backed for serialization; put logic (priority, comparison) as methods on the enum itself
+- Use `match(true) { ... }` for multi-condition branching
+- Use `$this->field ?? Default::empty()` pattern ("ensure pattern") to provide defaults instead of null-checking
+
 # Design Principles
 
 - Always start with extremely simple code, refactor when it is required - do not over-engineer solutions (YAGNI)
 - Use DDD (Domain Driven Design) principles - aggregate roots, value objects, entities, repositories, services
 - Use Clean Code and SOLID principles
 - Use interfaces for contracts, avoid concrete class dependencies
-- Early returns on errors, use monadic Cognesy\Utils\Result\Result for any complex error handling
+- Prefer using monadic designs for complex fragments of code - e.g. to avoid null checks and make the code cleaner and simpler.
+
+## Agents Package Architecture
+
+### Mental Model
+
+- **AgentLoop** is a step-based iterator: each step = one LLM inference + tool execution cycle
+- Loop lifecycle: `beforeExecution` → [`beforeStep` → `handleToolUse` → `afterStep` → check `shouldStop()`]* → `afterExecution`
+- The loop yields intermediate states via `iterate()` (generator pattern) — callers can observe/persist between steps
+
+### State Layering
+
+- **AgentState** = session-level (persistent across executions): agentId, messages, metadata, optional `ExecutionState`
+- **ExecutionState** = transient per-run: executionId, status, steps, continuation signals — null between executions
+- **AgentStep** = immutable snapshot of one step: input/output messages, inference response, tool executions, errors
+- **StepExecution** = wraps AgentStep with timing and continuation metadata — keeps step data immutable while tracking execution details
+- State updates are always atomic — `withCurrentStepCompleted()` chains through the layers to prevent partial/inconsistent states
+- `AgentState.forNextExecution()` clears execution data while preserving session state
+
+### Stop/Continuation
+
+- **StopSignal** = value object with reason (enum) + message + context + source
+- **StopReason** enum has priority ordering for conflict resolution (ErrorForbade > StopRequested > StepsLimitReached > ...)
+- **ExecutionContinuation** aggregates stop signals; `shouldStop()` = has signals AND no continuation override
+- **AgentStopException** is a control-flow exception (not an error) — caught in loop, converted to StopSignal
+
+### Invariant vs Variant Behavior
+
+The boundary between `\Core` and `\Hook` is **whether the behavior is optional**:
+
+- **Core state transitions** = invariant. Always happens, can't be removed, not configurable. Folded into `with*()` methods on state objects. Examples: `withCurrentStep()` routes step output to the correct message section; `forNextExecution()` clears the execution buffer; `withCurrentStepCompleted()` archives the step.
+- **Hooks** = variant. Configurable, optional, composable via builder. Examples: step limits, token limits, summarization, finish reason stopping. If you could imagine an agent that doesn't need it, it's a hook.
+
+**State transitions must be complete.** Every `with*()` call leaves the state fully consistent — no follow-up call required. If behavior always follows a transition, fold it into that transition. A separate "remember to also call X" method implies the behavior is optional; if it isn't optional, the separation is wrong.
+
+**The litmus test:** if you're writing a hook that always runs, can't be removed, and has ordering dependencies with other hooks — it's a missing state transition, not a hook.
+
+**AgentLoop is domain-agnostic.** It orchestrates lifecycle phases (beforeStep → handleToolUse → afterStep → shouldStop) but has zero knowledge of message sections, buffer routing, or output formats. Domain behavior lives in state objects (invariant) or hooks (variant), never in the loop.
+
+### Hooks
+
+- Hooks implement `CanInterceptAgentLifecycle` and receive/return `HookContext`
+- **HookContext** carries state + trigger type + tool data; hooks mutate context (block tools, add errors, emit stop signals)
+- Hook categories by convention: Guard hooks (priority 200, run first — check limits), Transform hooks (modify state), Block hooks (prevent tool execution), Decision hooks (policy-based retry/stop/ignore)
+- **HookStack** chains hooks in priority order (higher = earlier); immutable — `with()` returns new stack
+
+### Composition
+
+- AgentBuilder composes: Tools + Driver + EventEmitter + HookStack + ToolExecutor → AgentLoop
+- Many small interfaces (`CanUseTools`, `CanExecuteToolCalls`, `CanInterceptAgentLifecycle`, `CanEmitAgentEvents`) — one role each
+- Events are readonly DTOs dispatched via event bus; emitter is a thin wrapper creating event objects from state
+- Extend via hooks, not subclassing — AgentLoop is not designed for inheritance (test subclass `TestAgentLoop` is the sole exception)
 
 # Tests and Quality
 

.beads/issues.jsonl

@@ -44,7 +44,7 @@ $agent = AgentBuilder::new()
     })
 
     ->build();
-// @doctest id="4a0b"
+// @doctest id="f7c2"
 ```
 
 ## Lifecycle Events
@@ -104,7 +104,7 @@ HookOutcome::block('Dangerous command detected');
 
 // Stop the entire agent execution
 HookOutcome::stop('Budget exceeded');
-// @doctest id="645c"
+// @doctest id="d629"
 ```
 
 ### Semantic Differences
@@ -146,7 +146,7 @@ function afterTool(ToolHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="f8fe"
+// @doctest id="2c95"
 ```
 
 ### StepHookContext
@@ -167,7 +167,7 @@ function onStep(StepHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="a615"
+// @doctest id="e6d9"
 ```
 
 ### StopHookContext
@@ -187,7 +187,7 @@ function onStop(StopHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed(); // Allow stop
 }
-// @doctest id="5567"
+// @doctest id="1add"
 ```
 
 ### ExecutionHookContext
@@ -206,7 +206,7 @@ function onExecution(ExecutionHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="40b2"
+// @doctest id="7830"
 ```
 
 ### FailureHookContext
@@ -223,7 +223,7 @@ function onFailure(FailureHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 }
-// @doctest id="f253"
+// @doctest id="96aa"
 ```
 
 ## Matchers
@@ -247,7 +247,7 @@ new ToolNameMatcher('*');        // Match all
 
 // Regex patterns
 new ToolNameMatcher('/^(read|write)_.+$/');
-// @doctest id="b908"
+// @doctest id="3fd1"
 ```
 
 ### EventTypeMatcher
@@ -263,7 +263,7 @@ new EventTypeMatcher(HookEvent::PreToolUse);
 
 // Multiple events
 new EventTypeMatcher(HookEvent::BeforeStep, HookEvent::AfterStep);
-// @doctest id="8e88"
+// @doctest id="da63"
 ```
 
 ### CompositeMatcher
@@ -294,7 +294,7 @@ $matcher = CompositeMatcher::and(
     ),
     new CallableMatcher(fn($ctx) => $ctx->state()->metadata()->get('safe_mode')),
 );
-// @doctest id="52e7"
+// @doctest id="4d34"
 ```
 
 ### 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="fa02"
+// @doctest id="ff80"
 ```
 
 ## Priority
@@ -324,7 +324,7 @@ $builder
 
     // Logging hooks run last (low priority)
     ->onAfterToolUse($logger, priority: -100);
-// @doctest id="4918"
+// @doctest id="ec88"
 ```
 
 **Priority Guidelines:**
@@ -352,7 +352,7 @@ $builder->onAfterToolUse(
     priority: int = 0,
     matcher: string|HookMatcher|null = null,
 );
-// @doctest id="e2d1"
+// @doctest id="32c4"
 ```
 
 ### Step Hooks
@@ -367,7 +367,7 @@ $builder->onBeforeStep(
 $builder->onAfterStep(
     callback: callable,  // (AgentState) -> AgentState
 );
-// @doctest id="fddf"
+// @doctest id="7c77"
 ```
 
 ### Execution Hooks
@@ -384,7 +384,7 @@ $builder->onExecutionEnd(
     callback: callable,  // (ExecutionHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="7f22"
+// @doctest id="6412"
 ```
 
 ### Continuation Hooks
@@ -401,7 +401,7 @@ $builder->onSubagentStop(
     callback: callable,  // (StopHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="7cdd"
+// @doctest id="3a0c"
 ```
 
 ### Error Hooks
@@ -412,7 +412,7 @@ $builder->onAgentFailed(
     callback: callable,  // (FailureHookContext) -> HookOutcome|void
     priority: int = 0,
 );
-// @doctest id="64d1"
+// @doctest id="700a"
 ```
 
 ### Unified Registration
@@ -428,7 +428,7 @@ $builder->addHook(
     hook: new CallableHook($callback, $matcher),
     priority: 100,
 );
-// @doctest id="929b"
+// @doctest id="f22b"
 ```
 
 ## Creating Custom Hooks
@@ -457,7 +457,7 @@ class RateLimitHook implements Hook
         return $next($context);
     }
 }
-// @doctest id="b5bd"
+// @doctest id="7cb4"
 ```
 
 ## Using HookStack Directly
@@ -482,7 +482,7 @@ if ($outcome->isBlocked()) {
 } elseif ($outcome->isStopped()) {
     // Handle stopped
 }
-// @doctest id="f2f0"
+// @doctest id="1d82"
 ```
 
 ## Backward Compatibility
@@ -498,7 +498,7 @@ use Cognesy\Addons\Agent\Hooks\Adapters\StateProcessorAdapter;
 
 $processor = new YourStateProcessor();
 $hook = new StateProcessorAdapter($processor, position: 'after');
-// @doctest id="1638"
+// @doctest id="7351"
 ```
 
 ### ContinuationCriteriaAdapter
@@ -508,7 +508,7 @@ use Cognesy\Addons\Agent\Hooks\Adapters\ContinuationCriteriaAdapter;
 
 $criterion = new YourContinuationCriterion();
 $hook = new ContinuationCriteriaAdapter($criterion);
-// @doctest id="b2da"
+// @doctest id="7a88"
 ```
 
 ## Common Patterns
@@ -533,7 +533,7 @@ $builder->onBeforeToolUse(
     priority: 100, // Run first
     matcher: 'bash',
 );
-// @doctest id="fb43"
+// @doctest id="4e5e"
 ```
 
 ### Execution Timing
@@ -550,7 +550,7 @@ $builder
         $duration = microtime(true) - $started;
         $this->metrics->record('execution_duration', $duration);
     });
-// @doctest id="882e"
+// @doctest id="06f6"
 ```
 
 ### Conditional Continuation
@@ -573,7 +573,7 @@ $builder->onStop(function (StopHookContext $ctx): HookOutcome {
 
     return HookOutcome::proceed();
 });
-// @doctest id="f7b5"
+// @doctest id="aab6"
 ```
 
 ### Error Recovery Logging
@@ -599,7 +599,7 @@ $builder->onAgentFailed(function (FailureHookContext $ctx): void {
         $this->alerting->sendCritical($exception);
     }
 });
-// @doctest id="0505"
+// @doctest id="68fb"
 ```
 
 ## Architecture
@@ -631,7 +631,7 @@ $builder->onAgentFailed(function (FailureHookContext $ctx): void {
 │  │ execution│  │ action   │  │ entirely │                  │
 │  └──────────┘  └──────────┘  └──────────┘                  │
 └─────────────────────────────────────────────────────────────┘
-// @doctest id="e86c"
+// @doctest id="2fab"
 ```
 
 ## File Structure
@@ -672,5 +672,5 @@ packages/addons/src/Agent/Hooks/
 └── Adapters/
     ├── StateProcessorAdapter.php
     └── ContinuationCriteriaAdapter.php
-// @doctest id="3f06"
+// @doctest id="b442"
 ```

AGENTS.md

@@ -94,7 +94,7 @@ HttpClient
   └── withRequest() - Create pending request for execution
   └── pool() - Execute multiple requests concurrently
   └── withPool() - Create pending pool for deferred execution
-// @doctest id="d05c"
+// @doctest id="0504"
 ```
 
 ### Middleware Layer
@@ -105,7 +105,7 @@ The middleware system allows for processing requests and responses through a cha
 Request -> Middleware 1 -> Middleware 2 -> ... -> Driver -> External API
                                                    ↓
 Response <- Middleware 1 <- Middleware 2 <- ... <- Driver <- HTTP Response
-// @doctest id="7ebd"
+// @doctest id="5825"
 ```
 
 Key components:
@@ -123,7 +123,7 @@ CanHandleHttpRequest (interface)
   ├── SymfonyDriver
   ├── LaravelDriver
   └── MockHttpDriver (for testing)
-// @doctest id="07e0"
+// @doctest id="e4dd"
 ```
 
 ### Adapter Layer
@@ -136,7 +136,7 @@ HttpResponse (interface)
   ├── SymfonyHttpResponse
   ├── LaravelHttpResponse
   └── MockHttpResponse
-// @doctest id="5438"
+// @doctest id="74e3"
 ```
 
 ## Supported HTTP Clients