PHPackages                             waaseyaa/ai-agent - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. waaseyaa/ai-agent

ActiveLibrary[Utility & Helpers](/categories/utility)

waaseyaa/ai-agent
=================

AI agent orchestration and tool execution for Waaseyaa

v0.1.0-alpha.188(1mo ago)05.7k↓82.6%5GPL-2.0-or-laterPHPPHP >=8.5

Since Mar 14Pushed 1w agoCompare

[ Source](https://github.com/waaseyaa/ai-agent)[ Packagist](https://packagist.org/packages/waaseyaa/ai-agent)[ RSS](/packages/waaseyaa-ai-agent/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (16)Versions (186)Used By (5)

waaseyaa/ai-agent
=================

[](#waaseyaaai-agent)

**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
--------------

[](#where-to-start)

The canonical doctrine spec is **[`docs/specs/agent-executor.md`](../../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`](../ai-tools/README.md)**.

Surfaces
--------

[](#surfaces)

SurfaceEntry pointNotes**CLI**`packages/cli/src/Command/Ai/{AiRunCommand,AiPurgeRunsCommand,AiReapStalledRunsCommand}.php``bin/waaseyaa ai:run "" --inline` for sync; omit `--inline` for async enqueue.**HTTP**`packages/ai-agent/src/Controller/AgentRunController.php` (routes: `packages/ai-agent/src/Routing/AgentRouteServiceProvider.php`)`POST /api/ai/agent/run`, `GET /api/ai/agent/run/{id}`, `DELETE /api/ai/agent/run/{id}`, `POST /api/ai/agent/run/{id}/approve`. Per-route capability checks + initiator ownership via `AgentRunAccessPolicy`.**SSE**`BroadcastStorage` push on `agent.run.`Consume via `GET /broadcast?channels=agent.run.`. Events: `run_started`, `iteration`, `tool_call`, `tool_result`, `approval_required`, `run_completed`, `run_failed`, `run_cancelled`.**Messenger worker**`packages/ai-agent/src/Message/{RunAgent,RunAgentHandler}.php`Consumes the `RunAgent` message; CAS-guarded against duplicate delivery (NFR-015).**Scheduler**`packages/scheduler/src/Schedule/Ai/AgentScheduleEntries.php`Daily purge + 5-minute stalled-run reaper.Bimaaji-backed tools
--------------------

[](#bimaaji-backed-tools)

Four `#[AsAgentTool]` adapters expose [bimaaji](../bimaaji/README.md)'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()`.

Tool nameCapabilityClassPurpose`bimaaji_introspect_graph``bimaaji.read``Waaseyaa\AI\Agent\Tool\Bimaaji\IntrospectGraphTool`Full application-graph snapshot (six default sections).`bimaaji_introspect_section``bimaaji.read``Waaseyaa\AI\Agent\Tool\Bimaaji\IntrospectSectionTool`Section-scoped payload (`admin`, `entities`, `jsonapi`, `public_surface`, `routing`, `sovereignty`).`bimaaji_propose_mutation``bimaaji.mutate``Waaseyaa\AI\Agent\Tool\Bimaaji\ProposeMutationTool`Validate a proposed schema mutation against the current graph; returns the full `MutationResult` envelope (status + errors).`bimaaji_generate_patch``bimaaji.mutate``Waaseyaa\AI\Agent\Tool\Bimaaji\GeneratePatchTool`Re-validate the request and emit a `PatchSet` in memory (never touches the filesystem — the consuming agent loop decides what to do with the patches).**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/`](../../kitty-specs/ai-agent-bimaaji-tools-01KS5VKR/)
- Tool-shape contract (SC-004 surface map) — [`kitty-specs/ai-agent-bimaaji-tools-01KS5VKR/verification.md`](../../kitty-specs/ai-agent-bimaaji-tools-01KS5VKR/verification.md)
- Bimaaji subsystem spec — [`docs/specs/bimaaji.md`](../../docs/specs/bimaaji.md)

Extension points
----------------

[](#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
------------------

[](#persisted-entities)

EntityPurpose`Waaseyaa\AI\Agent\Entity\AgentRun`Run record: initiator, bundle snapshot, status, transcript (truncated at the configured cap), token/cost totals, approval state, timestamps.`Waaseyaa\AI\Agent\Entity\AgentAuditLog`Append-only event log: one row per provider call / tool call / tool result / approval. Purged only by `AiPurgeRunsCommand`.Repositories live in `packages/ai-agent/src/Repository/`. The legacy in-memory `Waaseyaa\AI\Agent\AgentAuditLog` value-object list inside `AgentExecutor` is removed.

Services
--------

[](#services)

ClassRole`AgentRunService``enqueue()` (async path) and `runInline()` (CLI/dev sync path).`AgentExecutor`Per-iteration loop: provider call, tool dispatch via `ToolRegistryInterface`, HITL gating, cancellation poll.`AgentDefinitionRegistry`Resolves `AgentDefinition` VOs by id.`StalledRunReaper`Transitions runs stuck past `max_runtime_seconds` to `failed`.`Mcp\McpClientToolSource` + `StreamableHttpMcpClient`Adapts remote MCP servers into the local tool registry; capability prefix `tool.mcp..`.Quality gates
-------------

[](#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/
```

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance96

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 60.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

185

Last Release

37d ago

PHP version history (3 changes)v0.1.0-alpha.2PHP >=8.3

v0.1.0-alpha.9PHP >=8.4

v0.1.0-alpha.176PHP >=8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/25d0ff572e93e3461e5180a920725d65691fd1e15e2d914b254dbbc2d6c393bd?d=identicon)[jonesrussell](/maintainers/jonesrussell)

---

Top Contributors

[![jonesrussell](https://avatars.githubusercontent.com/u/499552?v=4)](https://github.com/jonesrussell "jonesrussell (68 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (45 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/waaseyaa-ai-agent/health.svg)

```
[![Health](https://phpackages.com/badges/waaseyaa-ai-agent/health.svg)](https://phpackages.com/packages/waaseyaa-ai-agent)
```

###  Alternatives

[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M196](/packages/sulu-sulu)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1155.2k](/packages/rcsofttech-audit-trail-bundle)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

562565.8k42](/packages/ecotone-ecotone)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9317.2k55](/packages/open-dxp-opendxp)[chameleon-system/chameleon-base

The Chameleon System core.

1027.9k4](/packages/chameleon-system-chameleon-base)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)