StreamEvent

StreamEvent = object

The canonical Mode 2 streaming event union, discriminated by ‘type’. Every variant shares an envelope of schemaVersion, runId, sequence, timestamp, and type. ‘sequence’ is the ordering authority for events within a run (a monotonically increasing integer starting at 0 per runId) — consumers must order by ‘sequence’, not by arrival order, since a bridge hop (e.g. a future Capacitor bridge) could reorder delivery. Known event types are split into user-visible content (‘content_delta’, ‘content_snapshot’) and mechanical/diagnostic types (‘lifecycle’, ‘diagnostic’, ‘terminal’) so SDKs can distinguish what belongs in a chat UI from what is orchestration detail. Forward compatibility: this union closes with an open ‘unknown_event’ branch so a consumer built against an older revision of this schema does not hard-fail when a newer, additive minor revision introduces a new known type; per contracts/README.md’s schema evolution policy, SDKs must treat an unrecognized ‘type’ as ignore-or-pass-through-for-diagnostics, never as a hard error. All three engines implement this union (see docs/architecture/architecture.md).

Indexable

[property: string]: unknown

Properties

payload?

optional payload?: Payload

Event-specific diagnostic metadata. It must not contain prompt payloads or raw secrets, matching the same guardrail as TelemetryEvent.payload.

Structurally identical to StreamTerminalOutcome (contracts/schemas/stream-terminal-outcome.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.

Optional event-specific payload for the unrecognized type. It must not contain prompt payloads or raw secrets.

---

runId

runId: string

Opaque run identifier this event belongs to, matching StreamRunHandle.runId.

---

schemaVersion

schemaVersion: "1.0"

Contract schema version used to interpret this event payload.

---

sequence

sequence: number

Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.

Zero-based, monotonically increasing event index within this run. This is always the highest sequence number for the run: the terminal event.

---

timestamp

timestamp: number

Wall-clock event timestamp in Unix epoch milliseconds.

---

type

type: string

User-visible content: an incremental text increment since the previous content_delta or content_snapshot event. Mirrors ProviderDescriptor.streamingStyle ‘tokens’/‘chunks’ (packages/inderun-web/src/core/provider.ts) — providers reporting either style normalize to content_delta.

User-visible content: the full cumulative text produced so far. Mirrors ProviderDescriptor.streamingStyle ‘snapshots’ (packages/inderun-web/src/core/provider.ts) — providers reporting that style normalize to content_snapshot rather than content_delta. Retraction: a provider of any streamingStyle may additionally emit a content_snapshot to withdraw content it has already delivered, since a snapshot replaces the run’s cumulative text rather than appending to it; an empty one therefore resets that text to nothing. This is how a provider whose backend rejects an in-flight response after partial delivery — an on-device safety/policy check, for example — tells consumers to discard what they have, so a consumer must handle content_snapshot even when the provider’s declared style is ‘tokens’ or ‘chunks’.

Mechanical/diagnostic: a run lifecycle transition (e.g. provider selection, execution start). Not user-visible content; not part of the generated text.

Mechanical/diagnostic: free-form orchestration or provider diagnostic detail. Not user-visible content.

Progress of a prepare() run (ADR 019).

Terminal: the last event of the run, carrying the mutually-exclusive completion/error/cancellation outcome. No further StreamEvent is delivered for this runId after this event.

Forward-compatibility catch-all: any event type not among the known constants above. Exists so a consumer validating against this revision of the schema does not hard-fail when a future additive revision introduces a new known event type; SDKs must ignore or pass through such events for diagnostics rather than treating them as an error.