Expose typed provider failures through agent.core/run-outcome

[andreasronge]

Problem

A provider failure currently reaches Lisp with a coarse envelope, and agent.core converts its :provider-error action into fatal fail. A workflow therefore cannot inspect the failure and choose whether to retry the same LLM alias, restart on another alias, or abort.

This is the recovery-contract dependency identified by #1240. It is not a dependency of model routing itself.

Private exception diagnostics are insufficient: workflow policy needs stable, bounded, public kind and reason values. Conversely, a transport failure must not be classified as a subject/model failure.

Proposed contract

1. Classify expected transport failures into stable public reasons while retaining bounded details and private diagnostics under their existing disclosure rules.
2. Make agent.core/run-outcome return a distinct provider outcome:

{:status :provider-failure
 :error error
 :model alias}

3. Keep agent.core/run-value, run-result-value, and agent.main fail-fast. Recovery is available only to workflows that deliberately call run-outcome.
4. Do not add a runtime recovery: retry | choose-alternate | abort axis. Stable kind + reason are facts; the disposition is workflow policy.
5. Do not promise transcript-preserving failover. Restarting with another alias starts another loop unless a separate feature later exposes resumable state.

When #1240 lands, every post-resolution LLM failure must carry the resolved installation alias (and public installation revision where appropriate), including when the caller omitted model and the manifest default resolved it.

Failure distinctions required by #1240

At minimum, workflows must be able to distinguish:

• transient transport/provider failure: retrying the same alias may work;
• per-alias quota exhaustion: the same alias cannot run, but another may;
• global LLM capability quota exhaustion: no selected alias can run;
• invalid or unknown alias: correct the request; no provider attempt occurred.

A single retryable? boolean does not encode all three recovery dispositions, so callers act on the closed kind and reason vocabulary.

Compatibility

This changes run-outcome behavior for provider failures. It must not change the existing fail-fast behavior of agent.main or misclassify infrastructure failure as subject behavior.

Acceptance criteria

• Stable public transport reasons are documented and tested at the Dispatcher/LLM boundary.
• run-outcome returns :provider-failure with the complete bounded error.
• run-value, run-result-value, and agent.main remain fail-fast.
• Existing subject-failure outcomes are unchanged.
• Tests cover explicit and manifest-default model aliases once llm-request: select the model per call, so one run can use several #1240 is available.
• Documentation states that failover restarts rather than resumes the agent loop.

Related

• llm-request: select the model per call, so one run can use several #1240 — per-call model selection and deliberate alias failover.
• Use one adequately sized Finch pool for command-owned LLM concurrency #1287 — pool geometry; related incident, but not this public contract.