Agents Laravel Package

Technical Evaluation

Architecture fit This package sits as an application-level agent runtime inside a Laravel app: it owns turn orchestration, tool proposals, human decision capture, chat surfaces, an email channel, and tenant scoping, with Artisan entry points (agents:run, agents:embed). v1.10.0 keeps that shape and adds a clean seam: Packstub\Agents\Contracts\DecisionClassifier is now a first-class, container-resolvable extension point, selected by AGENT_DECISION_CLASSIFIER_DRIVER. For a TPM this is the most leverageable part of the release — it converts "can the agent read a free-text decision?" from a package-internal behavior into a product-configurable policy with three modes (agent, jev, or an app-owned class bound to the interface). No new infrastructure is introduced: the default path is unchanged, so existing deployments inherit nothing new unless they opt in.

Integration feasibility Environment-variable driven configuration (AGENT_DECISION_CLASSIFIER_DRIVER, AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE, TYPESAFE_API_KEY, optional TYPESAFE_BASE_URL / TYPESAFE_DEFAULT_MODEL) means adoption is a config change plus a secret, not a code change — deployable per-environment (e.g. jev in staging, default agent in regulated production). The custom-class option is the escape hatch for teams that cannot send proposal text to a third party; that is the single most important feasibility lever and should be scoped as an explicit decision, not a fallback. The new observability surface — AgentTurn::decisionDriver() and decisionConfidence() — is directly usable for product telemetry (which classifier read each reply, and how sure it was), which is what makes a confidence floor tunable rather than a guess.

Technical risk The material risk is data egress: with jev, the typed reply and the proposal questions are sent to TypeSafe, and TYPESAFE_API_KEY becomes a production dependency with a hard operational coupling (latency ~100 ms per choice question; one question per proposal). That needs a security/privacy review and a documented failure policy — note that a failed classification still degrades to "reply is a question," which is safe but user-visible, and there is no stated circuit-breaker or local fallback to agent on TypeSafe outage. Second risk is behavioral change: AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE defaults to 0.8, so any team adopting jev inherits a threshold they did not choose, and drivers that emit no confidence (agent) are exempt from the floor — meaning identical replies can be treated differently depending on driver. Third is execution-context semantics: v1.10.0 changes when typed decisions run (synchronously in the originating request via AgentRun, commands, or the email channel) while a click in chat still dispatches to the worker, so a single decision flow can now occupy two execution contexts; that is a correctness fix but a real thing to test.

Key questions

• Does TypeSafe processing of proposal text and user replies meet our data-handling posture, and is there a DPA / retention statement? If not, is a first-party DecisionClassifier the plan?
• What is the cost model per classified turn, and expected volume (turns × undecided proposals)?
• What is the fallback behavior and alerting when TYPESAFE_API_KEY is absent, rotated, or the API is degraded — do we get a loud failure or silent conversion of decisions into questions?
• Is 0.8 the right floor for our domain, and do we have the telemetry (via decisionConfidence()) to tune it after launch?
• Does any of our integration code assume decisions always resolve on a queue worker?

Integration Approach

Stack fit Standard Laravel: service provider + config + env, no new runtime (no Redis/queue/broker requirement added by this release). Postgres and MySQL are now exercised in the package's CI alongside SQLite, which materially improves fit for teams whose production database is not SQLite — previously AgentChat::search() was case-sensitive on Postgres and tenant slug lookups could hard-error there. If we run Postgres, this release is close to a prerequisite rather than an optional bump.

Migration path Low-risk, additive upgrade from 1.9. Default driver behavior is preserved (agent is the default, confidence floor does not apply to it), so the upgrade can be treated as a patch-and-verify release with no configuration change. Adopting jev should be a separate, later change behind its own flag, so a regression in decision handling is attributable to one variable.

Compatibility Two behavioral deltas to check against our code rather than our config: (a) AgentTurn::decisionDriver() now returns agent, jev, or an app class FQCN — anything persisting or displaying that value needs to tolerate a class name; (b) typed decisions and decision-completing replies now execute in the originating request for AgentRun, commands, and email, while chat clicks still go to the worker. Any test or downstream consumer that assumed "decisions are always async" needs review. decisionConfidence() is null for the side agent, so confidence-based UI or gating must handle null explicitly.

Sequencing

1. Upgrade to v1.10.0 on the default agent driver; verify against Postgres/MySQL (search case-insensitivity, tenant slug fallback in agents:run --tenant=acme, agents:embed, email channel).
2. Add regression coverage for the multi-proposal flow: reply typed after deciding one of two proposals is now answered rather than stuck; a question supersedes undecided proposals without emitting ProposalDecided.
3. Instrument decisionDriver() / decisionConfidence() and ship that telemetry dark.
4. Only then pilot jev in one non-critical tenant/environment with an explicit confidence floor, and decide on the outage fallback before widening.

Operational Impact

Maintenance Small ongoing surface: one new contract, one new env-selected driver, two new turn accessors, one new configurable threshold. The default path adds no maintenance. The jev path adds a third-party SDK/API relationship and a secret to rotate — that is a standing operational commitment, not a one-off. App-owned classifier classes become our code to maintain and test.

Support New first-line support questions appear: "why did my decision come back as a question?" (confidence below floor, classifier failure, or genuinely ambiguous reply) and "why did it answer immediately instead of when the worker ran?" Both are answerable from decisionDriver() / decisionConfidence(), which argues for surfacing them in admin/debug views rather than leaving them DB-only.

Scaling jev adds ~100 ms per choice question and one call per proposal, so a two-proposal turn is two calls — this multiplies with proposal count and turn volume, and puts our decision throughput on TypeSafe's availability curve. The synchronous execution change also shifts load: typed decisions sent through AgentRun, commands, and email now consume web/CLI request time rather than worker capacity, so request timeouts and PHP max_execution_time become relevant where they previously were not. Chat-click decisions remain worker-bound and scale as before.

Failure modes

• TypeSafe unavailable or key invalid → classification fails → reply becomes a question (safe, visible, but degrades the feature).
• Confidence below floor → reply becomes a question even when the classifier did answer, which can look like a regression to users.
• Two-proposal turns → previously a stuck conversation; now the reply is read against still-undecided proposals, and a question declines the rest with the "not decided" note and no ProposalDecided event, so audit/event consumers must not assume one event per proposal.
• Postgres tenant slug mismatch → previously an error on agents:run, agents:embed, and email; now resolves to the slug or matches nothing. Silent "matches nothing" is quieter than an error, so watch for tenant-scoping bugs surfacing as empty results.

Ramp-up Effectively zero for the default upgrade — no new concepts for the team. The jev path needs a short enablement pass: where the secret lives, what the floor means, how to read confidence in logs, and the documented answer to "what happens during a TypeSafe outage." Budget that as a half-day of engineering plus the privacy review, and treat the custom-classifier route as the plan-B that must be understood before the pilot, not during an incident.