AI Failures and Retries

Opaque failures

callAIResult returns { ok: false, error } when the platform cannot produce the contracted result. error is an opaque, run-bound capability: creator code may test it for truthiness and pass the exact object to settleAIFailure, but cannot inspect, serialize, persist, copy, or synthesize it. Provider, billing, credential, and policy diagnostics remain platform-private.

For callAIStream, the terminal error event carries the same opaque capability. Provisional text or tool fragments do not turn a failed stream into success.

A deliberate retry

Every additional provider generation is a new call and may be billed independently. A workflow that chooses to retry must use the successful normalized completion's attemptId as lineage and state a bounded reason:

var first = yield {
  type: "callAIResult",
  params: {
    prompt: prompt,
    slot: "game",
    purpose: "conversation",
    beneficiaryUserIds: ctx.beneficiaryUserIds
  }
};

if (!first.ok) {
  yield { type: "settleAIFailure", error: first.error };
  return;
}

if (first.value.semanticStatus === "invalid_output") {
  var retry = yield {
    type: "callAIResult",
    params: {
      prompt: repairedPrompt,
      slot: "game",
      purpose: "conversation",
      beneficiaryUserIds: ctx.beneficiaryUserIds,
      retryOfAttemptId: first.value.attemptId,
      retryReason: "invalid_output"
    }
  };
  if (!retry.ok) yield { type: "settleAIFailure", error: retry.error };
}

Valid retry reasons are invalid_output, tool_validation_failed, provider_failure, user_requested, and workflow_policy. Runtime ceilings still limit concurrent and total generations.

Redelivery is not retry

The host persists an attempt identity before dispatch. Re-entering the same attempt with the same request reattaches or replays its exact terminal result; reusing that identity with a changed request fails as an integrity error. The platform does not automatically launch a second generation after an ambiguous provider dispatch. If dispatch outcome is unknown, the user is not charged and the workflow receives a terminal failure.