[Platform] Introduce asynchronous jobs and move MiniMax polling out of the result converter

[wachterjohannes]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	-
License	MIT

Asynchronous work already exists in this component — hand-rolled, and in the wrong layer:

• Bridge\MiniMax\MiniMaxResultConverter::handleAsyncTask() polls a task with clock->sleep() up to 600 times, holding an HttpClientInterface, an API key and a ClockInterface to do so — inside a class whose contract is a pure RawResult → Result mapping.
• Bridge\Replicate\Client::request() does the same in the model client.
• Capability::TEXT_TO_SPEECH_ASYNC is already in the enum, used by exactly one bridge.

So the question is not whether the component should support async work, but that it already does, twice, inconsistently. Today one invoke() call blocks for minutes, the caller cannot observe the job or stop waiting, the operation does not survive the process that started it, and the state machine is not testable in isolation.

This PR introduces the job as a platform primitive and moves MiniMax onto it. Replicate and batch endpoints are deliberately left for follow-ups.

Why "job" and not "batch"

Video generation, asynchronous speech, OpenAI/Anthropic message batches, Gemini long-running operations and Replicate predictions all share one mechanic: submit → identifier → poll → fetch. And the body you eventually get back is the same one a synchronous call would have returned, which is why ResultConverterInterface is untouched here — an asynchronous result is not a new result type, only a different delivery.

Batch is then "a job with N items" rather than a second abstraction: JobHandle::$data carries the per-item keys when that lands.

What it looks like

$handle = $platform->invoke('MiniMax-Hailuo-02', new Text('A cat playing the piano'), [
    'duration' => 6,
])->asJob();

The handle holds no client and no connection, only what is needed to ask the provider about the job again — so it can be stored and picked up elsewhere:

// process one
$repository->save($id, json_encode($handle));

// a worker, possibly much later
$handle = JobHandle::fromArray(json_decode($repository->load($id), true));
$jobClient = $platform->getJobClient($handle);

if ($jobClient->getStatus($handle)->is(JobStateCase::SUCCEEDED)) {
    $jobClient->getResult($handle)->asFile('video.mp4');
}

To simply block, hand it to a runner — which owns the one polling loop left in the component and takes its budget from the caller, seconds for speech and minutes for video, instead of a constant inside a bridge:

$result = (new JobRunner(pollInterval: 1.0, maxPolls: 600))->wait($platform->getJobClient($handle), $handle);

Pieces

Class	Role
Job\JobHandle	Serializable reference: id, provider, provider-specific data. No client, no closure
Job\JobStateCase / Job\JobStatus	Normalized state plus the provider's own wording, mirroring FinishReason/FinishReasonCase. An unknown state maps to UNKNOWN and counts as non-terminal, so a state a provider adds later does not abort a running job
Job\JobClientInterface	getStatus() / getResult(), exactly one request per call, never sleeps
Job\JobRunner	The blocking loop, with ClockInterface, poll interval and budget
Result\JobResult	ResultInterface whose content is the handle; DeferredResult::asJob() reads it
Job\JobProviderInterface	Optional capability, so ProviderInterface stays untouched

Provider takes an optional JobClientInterface as its last constructor argument, and stamps the provider name onto the handle after conversion — a converter cannot know the name its provider was registered under, since that is a Provider argument and Factory::createProvider() lets it be overridden.

Exception\JobFailedException carries the status; Exception\JobTimeoutException carries the handle, so a job that outlived its budget can be handed on rather than lost.

Verified against the live API

Not only against mocks — every path was run against api.minimax.io:

	Result
Async speech	submit 1.0s, finished after 8.5s, mp3 written
Video	finished after 79.5s, 668 KB, ISO Media, MP4 Base Media v1
Resume	started in one process, Processing in a second, Success + download in a third — resolved purely from the serialized handle

Running it also turned up two things mocks could not have shown, both fixed here:

MiniMax reports rejections with HTTP 200. The reason sits in base_resp and the payload keys are simply absent — an unknown voice on t2a_v2 gives 2054 "voice id not exist", an unsupported model on image_generation gives 2013 "invalid params, ...", an empty account gives 1008 "insufficient balance", all with HTTP 200, while every success carries status_code: 0. Previously this surfaced as an error about a missing array key — or, for an asynchronous task, as polling a task that never existed (task_id: 0 is handed out as a placeholder) until the budget ran out. The converter now checks base_resp for every endpoint. Chat is the exception: a bad model there does return a real HTTP 400, already covered by HttpStatusErrorHandlingTrait.

The asynchronous speech endpoint does not return audio. It returns a tar bundling the mp3 with a .titles and an .extra file, which the bridge previously labelled audio/mpeg — so asFile('out.mp3') wrote an archive. The job client now unpacks the audio, making async and sync speech produce the same thing. TarArchive is a small ustar reader: the archive uses the header's prefix field because the paths exceed the 100-byte name field, and the mp3 is not the first member, so both had to be handled. PharData would have meant a temp file plus ext-phar as a new bridge dependency.

The test fixture is a real archive produced by tar --format ustar rather than hand-written, so the reader is not being tested against its own writer.

Not in this PR

• Replicate (Client.php:60) — same shape, follow-up now that the primitive exists.
• Batch (N items, custom_id correlation).
• No Capability::ASYNC_JOB — the JobResult type is already the signal, a capability would be a second truth.
• No scheduler or webhook handling in the component. Polling belongs in ai-bundle via Messenger/Scheduler/symfony/webhook; Platform only provides submit/status/fetch.
• No MiniMax status-code → exception mapping. Every non-zero base_resp code throws a RuntimeException carrying the code and the provider's message. Mapping 1004 to AuthenticationException and 1002 to RateLimitExceededException would be plausible, but only 1008, 2013 and 2054 were actually observed and a half-map is worse than none. Happy to add it if wanted.

BC break

Video generation and asynchronous speech return a JobResult instead of binary data, so reading them through asBinary()/asFile() throws. Waiting became explicit. MiniMaxResultConverter also lost its HTTP client, API key, endpoint and clock arguments. Both are documented in UPGRADE.md; code building the bridge through Bridge\MiniMax\Factory is unaffected.

[wachterjohannes]

the API delivery a tar file - to avoid the dependency to a tar lib i have implemented this little class

[chr-hertel]

We have an isolation problem here that we should resolve still.

Symptoms:

• $result instanceof JobResult in TypedResultTrait::as()
• $result instanceof JobResult in Provider::invoke()

I think this should be handled already down below in the ModelClient/ResultConverter layer while constructing the JobResult. We don't have the provider name there, but strictly speaking that is irrelevant. from a logic point of view that layer "knows" where it is and how to move on 🤔