# Agent Pipeline

## Purpose

The agent pipeline is the Clean Architecture path for Teddy admin copilot turns.
It routes natural-language requests through domain tools with permission checks,
validation, approval previews for dangerous actions, audit logging, and response
composition.

## Current Scope

- Admin copilot only, behind `use_agent_pipeline`
- Domain tools for posts, media, system, and WooCommerce
- Dangerous-action dry-run and approval flow
- SSE chat streaming with chunked fallback
- Tool audit log and AI usage observability

## Main Classes

- `src/Application/UseCase/SendChatMessage.php`
- `src/Application/UseCase/ExecuteDomainTool.php`
- `src/Application/Agent/AgentOrchestrator.php`
- `src/Application/Agent/ToolExecutor.php`
- `src/Infrastructure/Tool/InMemoryToolRegistry.php`
- `src/Infrastructure/Logging/WpAuditLogger.php`

## Safety Boundary

The mandatory tool lifecycle is:

1. resolve tool from registry
2. check capability via policy
3. validate input against JSON Schema
4. return preview if dangerous and not approved
5. write audit log before execution
6. execute tool
7. write audit log after execution
8. dispatch event for observability/hooks

No domain tool should bypass this lifecycle.

## Feature Flag

- Setting key: `use_agent_pipeline`
- Default: `false`

Public chat and legacy features still use the legacy stack until later roadmap
milestones migrate them.

## Verification

- Unit tests in `tests/Unit/`
- E2E smoke script: `tests/e2e-agent-pipeline.php`
- Static analysis: `composer phpstan`

## Runtime Notes

The E2E smoke script loads full WordPress through `wp-load.php`, so the PHP CLI
environment must match the web runtime closely enough to boot WordPress.
At minimum, required database extensions such as `mysqli` must be enabled for
the CLI binary that runs the script.