Laravel Swarm Laravel Package

Product Decisions This Supports

• Build vs. buy for agent orchestration. This package keeps multi-agent orchestration, durable checkpoints, and retries inside the Laravel codebase you already own, rather than adding a hosted orchestration vendor. The v0.28.1 fixes show the runtime is being hardened against real model traffic ("found against a live model"), which is the signal you want before committing a roadmap dependency to it.
• Memory architecture and tenancy. The new opt-in agent scope (swarm.memory.tools.agent_scope + swarmMemoryTools(agentScope: true)) is a product decision, not a plumbing detail: agent memory is keyed by agent class and shared across runs and tenants of that class. If you ship agent-scoped memory, decide deliberately whether cross-run learning is a feature or a data-leak risk, and keep the flag on the safe default until you have an isolation story.
• Read/write asymmetry as a design primitive. A bound Remember stores under any propagation policy, but a bound Recall only returns the entry under a policy that includes the agent scope. That lets you ship "write now, promote later" behaviour (e.g. per-run notes that only become durable team knowledge when a policy says so) without a second storage system.
• Reliability and cost of retries. v0.28.1 changes default behaviour so memory writes made through a frozen_view replay view are now saved after a successful retry, before the durable checkpoint. This raises real product questions: is a retried step allowed to re-emit memory events, and are you prepared for the write not being atomic? If your UX or billing assumes a retried step is invisible, that assumption is now wrong.
• Observability and metric integrity. Declined Remember writes and capture-policy Skiped writes now report as failed instead of succeeded. Any dashboard, success-rate SLO, or cost model built on nativeResult->tools / SwarmToolResult events will move. Treat this as a data-contract change to plan comms around, not a bug fix to absorb silently.
• Throughput features via parallel fan-out. Helper-typed parallel fan-outs and terminal workers now validate, and a plain branch may name its group's join. That unlocks roadmap items like "run N research workers in parallel then synthesise" using schema-generated plans instead of hand-authored PHP.
• Vendor-agnostic, model-constrained planning. RoutePlanSchema is a JSON-schema contract for planners. Fixes to with_outputs (now required on worker()) and next (string-or-null) make model-generated plans validate like PHP-authored ones, which reduces lock-in to a specific model and lets you A/B providers behind the same product behaviour.
• Upgrade cadence as a roadmap input. This is a pre-1.0 package that ships documented behaviour changes with no kill switch. Budget an explicit "upgrade tax" line per quarter rather than assuming drop-in patch upgrades.

When to Consider This Package

Consider it when:

• You are on Laravel/PHP and want orchestration, retries, and agent memory as first-class app code you can debug, test, and deploy with your existing pipeline.
• Your product needs durable, resumable agent workflows (checkpoint + replay) rather than fire-and-forget prompt chains.
• You need structured, schema-validated plans so a model — not a human — can compose multi-step or parallel work, and you want the same plan shape to validate whether authored by a model or by PHP.
• You want policy hooks over memory (MemoryCapturePolicy, propagation scopes) so "what the agent remembers" is a product lever, not an opaque vector store.
• Your team is comfortable pinning versions and reading UPGRADING.md before each bump; you have (or will write) tests over tool-result outcomes and events.

Look elsewhere when:

• You need a stable, semver-guaranteed API today. v0.28.1 changes documented default behaviour with no switch (retry memory writes are now persisted), and changes the reported outcome of existing tool calls from succeeded to failed. If you cannot absorb that on short notice, this is not yet a low-risk dependency.
• You require atomic memory persistence. The release explicitly states the retry-time save is not atomic, and a save skipped by the capture policy fails the step.
• You require strict per-tenant isolation from agent memory: it is keyed by agent class and shared across runs and tenants of that class. If tenant isolation is a compliance requirement, either avoid the agent scope or build a wrapper you control.
• You depend on MemoryStore::put() returning a persisted entry — it returns a prospective entry whose outcome metadata is explicitly unsupported; MemoryWriteSkipped is the only supported signal.
• Snapshot tests pin RoutePlanSchema::worker() — the next type changed from string to string-or-null, and with_outputs joined the required set.
• You are not on Laravel/PHP, or you would rather rent a managed agent runtime than own orchestration semantics and their upgrade path.

How to Pitch It (Stakeholders)

For executives (one paragraph). We can run multi-agent AI workflows on the Laravel stack we already operate — orchestration, retries with durable checkpoints, and agent memory included — instead of adding a managed vendor. The latest release is hardening work from live model traffic: plans produced by our schema helpers now validate in the planner, and the memory tools no longer report success for writes that stored nothing, which means our dashboards will finally reflect reality. The trade-off is maturity: this is a pre-1.0 package that changes documented behaviour in patch releases (v0.28.1 alters retry-time memory persistence with no opt-out), so the recommendation is to adopt with pinned versions, a named owner for upgrades, and an explicit upgrade budget — not to treat it as a drop-in commodity library.

For engineering. Three things landed and one thing to watch:

• Correctness fixes that change reported outcomes. Declined Remember writes (empty key, reserved swarm: prefix, unknown/unaddressable scope) and capture-policy Skiped writes now surface as failed in nativeResult->tools and as unsuccessful SwarmToolResult events, with the decline text in error. Nothing more or less is stored than before, but any metrics, alerting, or retry logic keyed on tool success shifts. The policy's reason is deliberately not shown to the model.
• Retry semantics change (no switch). Under the default replay mode, Run-scope memory mutations made through the frozen_view replay view used to be silently discarded yet read as stored. They are now persisted after the retried step's invocation, guardrails, and step recording succeed, before the durable checkpoint; later steps can read them; a retry failing earlier saves nothing. The save is not atomic, ordinary memory events now fire on a successful retry, and a write the capture policy skips at save time fails the step. Read UPGRADING.md#upgrading-to-v0281 before bumping.
• Opt-in agent memory scope. forAgent() on Recall/Remember, plus swarm.memory.tools.agent_scope (SWARM_MEMORY_TOOLS_AGENT_SCOPE, default false) and swarmMemoryTools(agentScope: true). Both are needed for any binding to take effect; a subclass overriding agent() bypasses the config key, and an agent() override beats a forAgent() binding. make:memory-tool --scope=agent no longer generates the agent() placeholder and now warns about the required binding — remove the null-returning placeholder from any previously generated tool before binding.
• Planner schema contract tightened. RoutePlanSchema::worker() now declares with_outputs as required (may be empty) and next as required-but-nullable; rollup()/node() output validates, and with_outputs accepts a list of node ids as well as the alias map. Existing PHP-authored plans keep validating, and the planner still tolerates a worker node omitting with_outputs, so scripted coordinators need no change — only schema snapshot tests need updating.
• Test-only additions. Runner-level coverage drives the recovery paths (durable-checkpoint failure after the save; save-time capture-policy Skip on sequential and branch paths) and structural tests pin replay boundaries and streamed tool-result handler ordering. No src/ behaviour change from these.

Ask: approve adoption behind a pinned version, with a small spike on the frozen_view retry change against our own memory writes and a one-off audit of every metric derived from tool-call outcomes before we upgrade.