StreamTerminalOutcome

StreamTerminalOutcome = object

How a Mode 2 stream run ended. Completion, error, and cancellation are mutually exclusive terminal outcomes, enforced here as a closed set of three oneOf branches discriminated by ‘outcome’ (unlike StreamEvent.type, this set is not open-ended: the three-way terminal outcome is a fixed architectural guarantee, not something new outcome kinds get added to; the payload of each branch may grow additively). Exactly one StreamTerminalOutcome is produced per run, and no further StreamEvent is delivered after it (see docs/architecture/architecture.md, ‘Cancellation And Fallback’). This shape is also embedded by value as the payload of the terminal StreamEvent (stream-event.schema.json) so it can additionally be exposed standalone, e.g. as a completion future/promise a stream handle resolves independently of consuming the full event sequence; the two copies must stay structurally identical. Note on additionalProperties: per this repo’s forward-compatible convention every branch permits unknown extra fields, so mutual exclusivity is enforced via the required ‘outcome’ discriminator plus each branch’s own required peer field being present (finalText or output / error), and for ‘cancelled’ by the discriminator alone, not by forbidding a payload from also carrying an unrelated stray field from another branch’s vocabulary.

Indexable

[property: string]: unknown

Properties

error?

optional error?: Error

The normalized error for this failure. Structurally identical to IndeRunError (contracts/schemas/inderun-error.schema.json), duplicated by value here rather than by $ref, matching this repo’s schema convention of no cross-file references. Keep both shapes in sync; a cross-check test asserts a shared fixture validates against both schemas.

---

finalText?

optional finalText?: string

The full, cumulative text produced by a text run. Equivalent in role to TaskResult.output.text for Mode 1. A text run sets it; a non-text run carries output instead.

---

finishReason?

optional finishReason?: FinishReason

How generation ended, mirroring TaskResult.finishReason for Mode 1: ‘stop’ (natural end), ‘length’ (hit maxOutputTokens), ‘error’ (provider reported a non-fatal issue on an otherwise completed run). ‘cancelled’ is included so this enum stays identical to TaskResult.finishReason, but it is unreachable here: cancellation is its own terminal outcome branch. Optional: providers that do not report a finish reason omit it.

---

outcome

outcome: Outcome

The stream completed normally: every provider-generated event was delivered before this outcome was produced.

The stream ended in failure: validation, routing (no eligible provider), or every attempted provider failing.

The stream was cancelled. No further StreamEvent is delivered after this outcome, and no further fallback attempt is made, per the engine’s cancellation guarantee.

---

output?

optional output?: TaskOutput

The normalized output of the run, the same shape run() returns in TaskResult.output. Set for every non-text run; a text run may set it alongside finalText. See task-output.schema.json.

What a cancelled non-text run had already produced: a playback run that committed (audio may have been heard) carries a playback output, and an artifact run cancelled while the engine was writing its artifact to an application destination carries that application-owned artifact, whose bytes the write left at the destination. Absent when nothing was produced, e.g. an artifact run cancelled before its artifact was handed over, whose partial media the engine discards. See task-output.schema.json.

---

partialText?

optional partialText?: string

Whatever cumulative text a text run had already delivered before it failed after committing to its provider. Absent when nothing was delivered.

Whatever cumulative text a text run had already delivered via content_delta/content_snapshot StreamEvents before the cancellation point. Always set for a text run, and empty if cancellation occurred before any content was produced. A non-text run never sets it.

---

provenance?

optional provenance?: ExecutionProvenance

Normalized execution provenance: which target ran, its declared locality, the configured and reported model, and how fallback and routing played out. See execution-provenance.schema.json.

---

reason?

optional reason?: string

Optional human-readable reason the run was cancelled (e.g. caller-initiated abort). Not a machine-taxonomy field; use errorClass on the ‘error’ outcome branch for failure classification.

---

runId

runId: string

The stream run this outcome terminates, matching StreamRunHandle.runId and every StreamEvent.runId for the run.

---

schemaVersion

schemaVersion: "1.0"

Contract schema version used to interpret this outcome payload.

---

telemetry?

optional telemetry?: Telemetry

Required metadata providing an overview of the execution result and performance metrics. Same shape as TaskResult.telemetry.

---

usage?

optional usage?: Usage

Optional metadata regarding the quantity of tokens processed by the provider. Same shape as TaskResult.usage.