Agents Laravel Package

Product Decisions This Supports

• Build vs. buy on the "understand the human's reply" layer. v1.10.0 turns decision reading into a DecisionClassifier contract with three sources: the bundled agent side-agent (default, no extra vendor), a hosted jev driver (~100 ms, per-question confidence, no reasoning), or your own class. The product decision is reversible — you can ship on the default, measure, then switch drivers via AGENT_DECISION_CLASSIFIER_DRIVER without touching feature code. That de-risks the roadmap item instead of committing to a vendor up front.
• Setting an automation trust policy, not just a feature flag. AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE (default 0.8) means a low-confidence read becomes a clarifying question rather than an executed action. This is a policy knob you can tune per environment (conservative in prod, loose in staging) and defend to risk/compliance without an engineering sprint. Note the asymmetry: the agent driver returns no confidence and is exempt from the floor, so the policy only binds once you adopt jev or a custom classifier — decide deliberately which driver your risk posture assumes.
• Instrumentation for ship/no-ship and tiering. AgentTurn::decisionDriver() and decisionConfidence() persist which classifier read each reply and how sure it was. That gives you the raw material for an automation-rate / escalation-rate / low-confidence-rate dashboard, per driver and per model. It supports concrete decisions: is jev actually better than the side agent, what confidence floor maximizes completed approvals without misreads, and can confident auto-decisions be sold as a premium tier.
• Cost and latency budgeting. Word lists still run first; the classifier only sees what the lists can't. That keeps most decisions free and deterministic, and makes the ~100 ms hosted call an exception path rather than a per-message tax — a defensible answer to "what does this cost at 10x volume?"
• Data-handling and vendor-risk decisions. The jev driver sends the human's reply and the proposal questions to TypeSafe. For regulated or Enterprise buyers this is a gating product decision, not an implementation detail; the custom-classifier path is the escape hatch for self-hosting or an approved vendor. Worth capturing as an explicit supported deployment mode.
• Request vs. queue semantics as a UX decision. Decisions typed through AgentRun, a command, or the email channel now execute in the same request instead of waiting on a worker; a click that completes a held decision still goes to the worker. That's the difference between "instant" and "come back later" in an approval flow — a UX commitment you can now make.
• Multi-proposal workflows become viable. The fix for a reply typed after deciding one of two proposals removes a genuine deadlock. This unlocks batch approvals (one message clearing several queued proposals) as a roadmap item that previously wasn't safe to promise.
• Platform breadth for enterprise deals. Postgres/MySQL now in CI alongside SQLite, plus the case-insensitive chat search and the tenant-slug key lookup fix, removes two first-run failures (agents:run --tenant=acme, email channel) that would otherwise show up as a POC blocker. This supports "we support your database" in RFPs rather than a caveat.

When to Consider This Package

Adopt when:

• You're on Laravel/PHP and the product pattern is agent proposes, human disposes — tool calls or actions that need approval, decline, or clarification in natural language over chat, email, or an in-app command.
• You want decision capture, provenance, and confidence inside your own app and database rather than exporting the loop to an external orchestration platform.
• You need an audit trail per turn (which classifier, how confident) — e.g. approvals with a compliance or internal-controls audience.
• You need database portability across SQLite/MySQL/Postgres, or you're already seeing Postgres in enterprise environments.
• You want to start deterministic (word lists, bundled side agent) and grow into a hosted classifier later without a rewrite.

Look elsewhere or postpone when:

• You need a full agent observability/evaluation platform, not an in-app decision layer.
• You're not on PHP/Laravel, or you're standardizing on a managed agent runtime.
• You cannot send proposal text and end-user replies to a third party and won't implement DecisionClassifier yourself — in that case you're limited to the word lists plus the side agent, and the confidence-floor story doesn't apply.
• You need per-tenant or per-customer classifier selection and confidence floors. Driver and floor are configuration/env-level today; multi-tenant policy variance would require workarounds.
• You require strict API stability — this is a 1.x line with active iteration on decision semantics; budget for minor-version review.
• Determinism-only requirements: the classifier is optional, but the default agent driver still implies LLM cost and latency on the fallback path.

How to Pitch It (Stakeholders)

For executives: This release turns "the agent asks, a person answers" from a demo into an operable capability. We can now choose who interprets a human's typed decision — our own model, a fast hosted one, or ours later — and we can require a confidence threshold before the system acts, so uncertain reads become questions instead of mistakes. Every decision is recorded with its source and confidence, which gives us the numbers to prove it works and the audit trail to satisfy reviewers. No lock-in: the classifier is swappable, and the fixes for Postgres and multi-proposal conversations remove the blockers we'd hit in a customer pilot.

For engineering: Additive minor release, no breaking changes. Decision reading is now behind Packstub\Agents\Contracts\DecisionClassifier, selected by AGENT_DECISION_CLASSIFIER_DRIVER (agent default, jev, or your own class/binding). AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE (0.8) only binds drivers that return confidence — agent returns null and is exempt. Turn records expose decisionDriver() and decisionConfidence(). Word-list matching still runs first, and undecided proposals or classifier failures still fall back to a question. Also fixed: synchronous execution for typed decisions via AgentRun/command/email, Postgres case-insensitive chat search, tenant-slug lookups that previously errored on Postgres, and a stuck-conversation bug when a reply arrives after one of two proposals is decided. CI now covers Postgres and MySQL in addition to SQLite.