v0.2.0 — the durable Agent API lifecycle

Long-running research now has an explicit lifecycle instead of a queued response pretending to be text.

What is new

$agent = app(PrismManager::class)->resolve("perplexity")->agent();

$queued   = $agent->create("Research the Prism ecosystem", ["preset" => "deep-research"]);
$snapshot = $agent->retrieve($queued->id);
$finished = $agent->wait($queued->id, maxAttempts: 60, intervalMilliseconds: 1000);
$cancelled = $agent->cancel($queued->id);

Every snapshot carries a typed AgentStatus, an AgentProtocol discriminator, the resolved model, structured output, flattened annotations, the full provider usage and cost ledger, a typed error when present, and the unmodified response body in raw.

Failed, incomplete and cancelled runs are lifecycle results, not transport exceptions. Malformed and non-successful HTTP responses still throw.

wait() is deliberately bounded, and it validates its own bounds. Queue workers should normally persist the response id and retrieve it in a later job; the helper exists for short bounded waits, not indefinite polling.

What is deliberately absent

No list endpoint. Perplexity documents create, retrieve and cancel for Agent responses, and does not document one that lists them — so this package does not guess. The older async Sonar API does have one, but it is a separate legacy protocol and is not silently mixed with Agent response ids or statuses.

Upgrading

Additive. No dependency changes, no breaking changes — composer require particle-academy/prism-perplexity:^0.2.0.

Closes #1.