Download the PHP package rawphp/laravel-capabilities-ai without Composer

rawphp/laravel-capabilities-ai

Status: 0.x pre-stable — not Packagist-published.
Install: package VCS or monorepo path.

Conversation / turn / proposal runtime for the Laravel Capabilities bus.

Monorepo path: packages/laravel-capabilities-ai/ in laravel-capabilities-monorepo.

Scope (this package)

Requires rawphp/laravel-capabilities at the same version (self.version lockstep: this package at v0.Y.Z installs only with core v0.Y.Z). Consumers install this package repo, not the monorepo.

Install

Rawphp\CapabilitiesAi\CapabilitiesAiServiceProvider is auto-discovered (extra.laravel.providers).

Tests and contributions: the unit suite, phpunit.xml, and dev tooling live only in the monorepo; this package remote is a read-only split and ships no tests. Open issues and PRs against the monorepo and run composer test:ai there.

Config

Publish:

Key defaults (config/capabilities-ai.php):

Progress events live in array/Redis — not MySQL product tables.

Bus principal (tool + accept invokes): TurnRunner and ProposalService resolve the conversation’s Laravel user via user_model / auth provider and pass that user as actor on CapabilityBus::invoke. Turn tool calls use caller=agent (D-022), so the agent surface flag, per-capability surfaces narrowing and agent approval rules apply; proposal accept uses caller=job. Missing/unresolvable conversation.user_id fails closed (no silent default user). When CapabilityBus is bound, provider boot also fails closed if the user model is unset, missing, or has no query() (class check only, no DB). Tool invokes pass idempotency_key only when the model supplies it as a tool argument (D-005; stripped from capability input) — otherwise they carry no key. Each tool invoke also passes a 1-based agent_turn_tool_calls count, so core rate_limits.agent_turn.max_tool_calls (D-013) caps tool calls per turn; past it the model gets a rate_limited tool result.

Host integration (D-024 seams)

Happy-path AI-chat hosts configure — they do not rebind package runtime for queue or progress:

Full greenfield checklist, kill-list template, and extend snippet: docs/user-guide.md.

Host seams

Bind before running turns:

• Rawphp\CapabilitiesAi\Contracts\ConversationContextProvider — messages for the model
• Rawphp\CapabilitiesAi\Contracts\ToolCatalog — tools the model may call (names = capability names). TurnRunner resolves the list once per turn; a tool_call for a name outside it is answered with a capability_not_in_profile tool result and never reaches the bus (D-008). AnthropicLlmClient sends dotted names as __ (pane.list → pane__list) and decodes them on tool_use; a name that cannot round-trip (it contains __, or _ next to .) throws InvalidArgumentException and fails the turn rather than risk invoking a different capability. A tool definition may set terminal: true (default false) for a fire-and-forget tool such as play or seek. A round ends the turn without another LLM round when the model wrote non-empty text alongside its calls, every call in the round named a terminal tool, and every result was ok; the text the model wrote alongside the calls is stored as the reply, and its tool progress events still precede the terminal event. Empty text, a non-terminal tool in the round, or a failed result sends the tool results to the next round as before, so the model can tell the user about a failure. terminal is read by TurnRunner only: it removes the key before calling LlmClient::complete(), so no client sends it to a provider
• Rawphp\Capabilities\Contracts\CapabilityBus — already provided by core

Custom LlmClient: implement supportsToolRounds(). Prefer use LlmClientDefaults (returns false) and override to true only if the client accepts tool-result messages on the next complete() (OpenAI-style role=tool or Anthropic tool_result blocks). Lying opens a bus-then-crash path. (PHP interfaces still cannot ship method bodies on supported PHP; the trait is the fail-closed default for hosts.) Host upgrade callouts: CHANGELOG Breaking.

Turn time budget: a custom client can implement Contracts\DeadlineAwareLlmClient (withDeadline(): cap every request and retry to end before the turn deadline, and start none with under MIN_REQUEST_SECONDS left) so TurnRunner holds its rounds and retries to claim_ttl the way it does for AnthropicLlmClient. Clients without it get no turn budget: keep their total turn time under claim_ttl yourself.

Transient LLM errors: throw RetryableLlmException (rate limit, overload, 5xx, connection) from complete(); AnthropicLlmClient already does. The turn still ends failed, but its progress error event carries retryable: true (+ retry_after_seconds when the provider sent one) so callers can try again; other errors report retryable: false.

Usage and telemetry: LlmClient::complete() may return usage (input_tokens, output_tokens, and cache_creation_input_tokens / cache_read_input_tokens when the provider reports prompt caching). TurnRunner stores a usage list on the turn row, one {latency_ms, input_tokens?, output_tokens?} entry per round, on completed, failed and cancelled turns (run the add_usage_to_capabilities_ai_turns_table migration). When core Metrics / Tracer are bound, AnthropicLlmClient records capabilities_ai_llm_duration_ms, capabilities_ai_llm_tokens_total{type=input|output|cache_creation|cache_read}, capabilities_ai_llm_failures_total{reason=transport|http_<status>} and a capabilities_ai.llm.complete span (D-019).

MVS product default: multi-round tools are off until a client opts in. AnthropicLlmClient and FakeLlmClient opt in (supportsToolRounds() === true); hosts using LlmClientDefaults stay fail-closed until they override. Empty tool defs + refuse-before-bus is defense-in-depth for non-tool-round clients, not a second product surface.

Proposals (single accept/reject model): Gated by proposals.enabled (CAPABILITIES_AI_PROPOSALS_ENABLED). When false: accept/reject routes are not registered, TurnRunner skips fence → proposal extract, and history omits/empties proposals. When true: Accept returns typed AcceptOutcome for every known status (rejected/expired → refuse); HTTP maps outcomes + 404 when missing. Reject uses CAS + RuntimeException → 409 for non-pending. Greenfield: set false until you need proposals. Host upgrade callouts: CHANGELOG Breaking.

• Accept: atomic CAS pending → accepting, then target_capability must be in the host ToolCatalog list for the proposal's turn (D-008; checked on every execute, no catalog bound → refuse) or the proposal fails with 403 capability_not_in_profile and no invoke; a fenced proposal stamps schema_hash (sha256 of the target tool's parameters) at creation, and if the live tool schema no longer matches, accept fails with 409 conflict (reason: schema_changed) and no invoke, so schema drift is not reported as a malformed payload (null hash on legacy rows skips the check); then bus invoke with idempotency_key=proposal:{ulid} (D-005). Live StoreBoundIdempotencyReadiness probe of core IdempotencyStore (fail closed when unbound) — not a constructor stamp; AlwaysReadyIdempotency is unit-tests only. Branch isApprovalRequired() then isHardRefuse() then isRetryable(); approval/retry leave status accepting for host re-drive. Hard non-retryable → failed + last_error. Success → atomic accepting → accepted, clear last_error. Returns typed AcceptOutcome (accepted | approval_required | retryable | failed | refuse).
• Reject: atomic CAS pending → rejected only; already-rejected is idempotent; accepting/accepted/failed/expired refuse (HTTP 409).
• Recovery: stuck accepting is intentional (approval / retry / crash mid-accept). Package does not TTL-expire or reclaim; host re-drives accept under the same D-005 key (proposal:{ulid}). Hosts must wire core IdempotencyStore (not an AI-package store) so the bus actually dedupes; readiness not ready → 503 without invoke. Tool bus invokes carry an idempotency_key only when the model passes one as a tool argument; accept always sets the proposal key. Both tool and accept invokes still carry the job+user principal (above).
• Stale turns: schedule php artisan capabilities-ai:reap-stale-turns (host owns the schedule; package does not auto-schedule). Thresholds: reaper.stale_queued_minutes, reaper.stale_running_grace_seconds (running age uses max(claim_ttl, grace)). Each run increments capabilities_ai_reaped_turns_total{status=queued|running} on core's Metrics contract (D-019), so alert on its rate rather than console output.

Env: ANTHROPIC_API_KEY (never required in CI — tests use Http::fake / FakeLlmClient).

Flow

1. Cheap create — ConversationService::createUserMessage inserts message + queued turn, dispatches RunTurnJob (no LLM).
2. Claim + run — TurnClaim atomic update; TurnRunner loops LLM → tools via CapabilityBus::invoke only.
3. Proposals — ProposalService::accept / reject as above (bus-only side effects on accept).

ProgressStore

Package binds ProgressStore in register() when unbound (array or redis from config). Hosts that need side-effects (TTS, metrics, …) must wrap with extend in boot() so the package store is the $inner:

Forbidden: host singleton(ProgressStore::class, …) that replaces redis/array wiring (rebind, not extend).

Kinds: status | token | tool | proposal_invalid | error | terminal.

License

MIT

Non-chat / MVS host jobs

Hosts may resolve LlmClient without a Conversation (e.g. Macro Validation Suite jobs):

The LlmClient interface has no conversation-only dependency. Testing default is FakeLlmClient (no network).