README

Layer 5 — AI

Waaseyaa agent runtime: the executor, the run service, the Messenger handler, and the in-process audit-log persistence. This package turns a registered AgentDefinition and an initiator account into a persisted AgentRun with real-time SSE progress, token / cost accounting, HITL approvals, and an append-only audit trail.

Where to start

The canonical doctrine spec is docs/specs/agent-executor.md. It owns the success criteria, NFR thresholds, audit invariants, SSE event vocabulary, HITL state machine, security posture, and the Waaseyaa\AI\Tools\ToolRegistryInterface contract.

For the tool catalogue (8 stock tools + remote MCP source) see packages/ai-tools/README.md.

Surfaces

Bimaaji-backed tools

Four #[AsAgentTool] adapters expose bimaaji's application-graph introspection and validated-mutation surface to the embedded agent runtime. Discovered via the package-manifest compiler; their dependencies (ApplicationGraphGenerator, MutationValidator, PatchGenerator) resolve from the container after BimaajiServiceProvider::register().

Capabilities: bimaaji.read is generally safe to grant; bimaaji.mutate is default-off per AD-02 and should be granted only to agents that need to propose schema changes. The mutation tools enforce the deny via AbstractAgentTool::requireCapability(); rejected calls surface as AgentToolResult::error(summary: 'forbidden') and are recorded in the audit log.

Example — run the reference demo agent inline:

bin/waaseyaa ai:run "Introspect the entities section, propose adding a 'nickname' field to User, then generate the patch." \
    --agent=bimaaji_demo --inline

bimaaji_demo (packages/ai-agent/tests/Fixture/BimaajiDemoAgent.php) is the test-only reference agent that wires the four tools into a single introspect → propose → generate workflow. Real production agents should mirror its shape — declare the four tool names in tools: and gate the agent on bimaaji.read; per-tool capabilities are enforced inside each tool.

See also:

• M2 mission spec — kitty-specs/ai-agent-bimaaji-tools-01KS5VKR/
• Tool-shape contract (SC-004 surface map) — kitty-specs/ai-agent-bimaaji-tools-01KS5VKR/verification.md
• Bimaaji subsystem spec — docs/specs/bimaaji.md

Extension points

Register agent bundles and tools via attribute discovery — the package-manifest compiler scans both.

use Waaseyaa\AI\Agent\Attribute\AsAgentDefinition;
#[AsAgentDefinition(id: 'my_agent', model: 'gpt-4o-mini')]
final class MyAgent { /* prompt, tools, system, max_iterations, destructive_default, requires_capability */ }

use Waaseyaa\AI\Tools\Attribute\AsAgentTool;
#[AsAgentTool(name: 'my_tool', capability: 'my.feature', destructive: false)]
final class MyTool extends \Waaseyaa\AI\Tools\AbstractAgentTool { /* execute() */ }

After adding new attributes run bin/waaseyaa optimize:manifest (or restart the dev server).

Persisted entities

Repositories live in packages/ai-agent/src/Repository/. The legacy in-memory Waaseyaa\AI\Agent\AgentAuditLog value-object list inside AgentExecutor is removed.

Services

Quality gates

Every change to this package MUST keep the following green:

• bin/check-package-layers — ai-agent imports only from layer ≤ 5 (entity, entity-storage, access, queue, ai-schema, ai-tools).
• bin/check-dead-code — no new findings beyond phpstan-dead-code-baseline.neon.
• composer check-composer-policy — CP002 / CP003 / CP-NEW.
• composer phpstan — level 5.
• composer cs-check — PHP-CS-Fixer dry-run.
• Bulk-edit gate — occurrence_map.yaml validates; zero BLOCK rows in the diff-compliance report.

Tests:

./vendor/bin/phpunit packages/ai-agent/tests/
./vendor/bin/phpunit tests/Integration/PhaseN/AgentRuntime/