Ai Laravel Package

Product Decisions This Supports

• Build vs. buy for the agent runtime layer. The package draws the boundary between orchestration (durable control flow, retries, waits, approvals, cancellation) and effects (LLM calls, tool calls, sandbox provisioning, snapshotting). That is precisely the layer most teams under-estimate when they estimate an "AI agent" feature. A PM can use it to price the difference between a demo agent and a production agent: if the feature needs approvals, multi-day waits, or resume-after-crash, the delta is a workflow engine, not more prompt work.
• Feature scoping: long-running agent sessions. It is directly relevant to any decision about whether the product supports: sessions spanning hours or days, multiple tool calls per run, human approval or rejection gates, spend/iteration/parallelism budgets, and resume after worker or deployment loss. Each of these is a user-visible capability, not an implementation detail — this package is the thing that lets you promise them.
• Sandbox lifecycle as a product surface. Sandboxes are expensive, stateful, and leak. The package's emphasis on snapshots, lease expiry, and reconcilers (cleanup that runs even after a worker dies) is the mechanism behind decisions about idle-sandbox cost, orphaned-resource ceilings, and "what happens if the agent dies mid-run." That maps to COGS, not just architecture.
• Roadmap sequencing for human-in-the-loop. Signals, updates, timers, and cooperative cancellation with bounded cleanup are named explicitly. If approval workflows, pause/resume, and operator intervention are on the roadmap, this determines whether they arrive as config or as a quarter of engineering work.
• Observability and audit as a differentiator. The skill documentation enumerates exactly what every run should expose: stable run identity plus business correlation key, current business phase, pending timer/message/activity, attempt count, last failure, next retry time, age in phase. That is a ready-made spec for an operator console and for audit/compliance asks in regulated buyers.
• Metering and entitlement design. Durable history gives you a per-run ledger of steps, attempts, and elapsed time — a credible basis for usage-based pricing, spend caps, and per-tenant budget enforcement rather than seat-only pricing.
• Idempotency policy as a business rule. The package forces an explicit answer to "what must never happen twice" (charges, emails, provisioned infrastructure) versus "what may happen at least once." That is a product-correctness decision with legal and support consequences, and it is much cheaper to make before launch than after the first duplicate charge incident.
• Use-case triage. Best-fit surfaces: coding/DevOps agents that execute commands in a sandbox, data-analysis agents with long-running jobs, document-processing pipelines, and internal ops automation with approval gates. Poor fit: single-shot classification or generation, chat that never touches a tool, and anything where recomputing is cheaper than persisting.

When to Consider This Package

Adopt when most of the following are true:

• You are building on PHP/Laravel and intend to stay there. The value here is native fit with your existing runtime and deployment model; the durable-execution concepts are portable, this implementation is not.
• Agent runs cross irreversible side effects — provisioning sandboxes, spending model credits, sending messages, mutating customer records — where a crash between "did the thing" and "recorded that we did the thing" produces a visible bug or a support ticket.
• Runs must outlive a request, worker, or deploy. Waiting on an approval, a long sandbox job, or an external callback is a first-class flow, not an edge case.
• You need operator intervention: inspect, pause, cancel, retry, or repair a live run without editing database rows.
• Sandbox cost and leakage are material — you want snapshot/restore plus lease expiry rather than hoping finally blocks fire.
• You expect volume of runs to be modest (internal tools, B2B agent workflows, per-tenant automation), not millions of short stateless executions per hour.

Look elsewhere or explicitly de-risk when:

• Maturity matters more than fit. 1 star, 0 dependents, and a single maintainer organization means no community validation, no third-party tutorials, no hiring pool, and no realistic external support contract. Treat this as a reference implementation you may adopt, not a vendor you can lean on.
• You are Python- or TypeScript-first. Temporal, Restate, Inngest, or the incumbent agent SDKs give you a far larger ecosystem; adopting a PHP orchestrator to supervise Python workers adds a language boundary you probably do not want.
• A single transaction or a single queued job is enough. The package's own guidance is blunt about this: do not introduce a workflow engine because code has several functions. One short idempotent job is not a workflow.
• The work is latency-critical. Adding a durable scheduling boundary to a sub-second path buys correctness you do not need and latency you cannot afford.
• Your team cannot honor the determinism and versioning model. Replay discipline — no unrecorded side effects, no branching on wall-clock time or fresh reads, no breaking changes to in-flight control flow — is an ongoing engineering obligation, not a one-time integration. Without it, you get a workflow engine that produces wrong answers under replay, which is worse than no engine.
• You need a hardened control plane. Sandbox-fleet scheduling, multi-region capacity, and secure isolation are the hard part of agent infrastructure. This package orchestrates lifecycle; it does not replace E2B, Daytona, Modal, or your own container platform, and it should not be evaluated as if it did.
• Throughput or fan-out is the primary problem. Durable fan-out still saturates downstream systems; if your roadmap is bulk parallel execution, concurrency and queue architecture dominate and orchestration is secondary.

Recommended posture if you proceed: timeboxed spike against a real, ugly failure case (kill the worker between sandbox creation and history write, then verify no duplicate sandbox and no duplicate charge), behind a thin internal interface so the orchestrator is swappable. Define exit criteria up front — replay correctness, operator visibility, and the cost of the runtime you now have to operate.

How to Pitch It (Stakeholders)

For executives: This is the difference between an agent demo and an agent product. Without durable orchestration, every restart, deploy, or timeout becomes a customer-visible failure: duplicate charges, orphaned cloud sandboxes, sessions that silently restart from scratch, and no way to answer "what actually happened on run 4,182." This package supplies that layer in our existing stack rather than adding a new language runtime — with a build-vs-buy saving in the range of a quarter of engineering effort for the durability, retry, approval, and audit plumbing we would otherwise hand-roll. It also produces the per-run record we need for spend caps, usage-based pricing, and enterprise audit requirements. The honest caveat: it is early-stage and unproven (negligible adoption, one maintainer org, no support contract), so the recommendation is a bounded pilot behind an internal abstraction — cheap to validate, cheap to reverse — not a platform-wide commitment.

For engineering: It encodes the model we would otherwise learn the hard way. Workflow code owns deterministic control flow; every LLM, tool, and sandbox call lives in an activity with a stable operation ID and a retry-safe effect. Replay rules are explicit: no unrecorded side effects, no branching on current time or fresh reads, recorded results are immutable history, version old runs before changing control flow. Sandbox lifecycle gets both workflow-level finalization and an external lease/reaper, because termination does not run cleanup. And it is opinionated about what not to use it for — one job, one transaction, latency-critical paths — which is the sign of a design we can trust on the parts it does claim. Our risk is not the concepts, it is the codebase: budget for reading the source, pinning versions, and writing our own conformance tests against representative failure cases before anything customer-facing depends on it.