Interface: StreamTextResult
Defined in: packages/agentos/src/api/streamText.ts:229
The object returned immediately by streamText.
Consumers iterate textStream for raw token deltas or fullStream for
all event types; the promise properties settle once that iteration has
drained the stream, and awaiting one of them alone starts no request.
Properties
cacheDiagnostics
cacheDiagnostics:
Promise<CacheDiagnostics|null>
Defined in: packages/agentos/src/api/streamText.ts:355
Cache-diagnostics verdict of the FINAL step (Anthropic beta; see
GenerateTextOptions.cacheDiagnostics). Resolves when the stream
completes: null when the run did not opt in, when the provider sent no
verdict, or when the compared requests did not diverge; a populated
cacheMissReason names the earliest divergence. Settled in the
generator's cleanup too, so awaiting after early abandonment never hangs.
fallback?
optionalfallback:Promise<FallbackSignal|undefined>
Defined in: packages/agentos/src/api/streamText.ts:281
The failover trail, resolved when the stream ends: fired is true when a
fallback leg served or was tried; finalProvider / finalModel name the
run that answered; undefined only when the stream ended before routing.
Optional in the type, so an object typed as StreamTextResult without it
still compiles; streamText always sets it.
finishReason
finishReason:
Promise<StreamFinishReason>
Defined in: packages/agentos/src/api/streamText.ts:335
Resolves to the reason the FINAL model step stopped emitting, on the same cadence as usage (when the stream completes):
'stop'— natural end of turn (or an unknown provider vocabulary).'length'— the provider's output token cap cut the text off; the assembled reply is TRUNCATED mid-thought. Hosts that persist or cache streamed prose as canonical should branch on this before doing so (wilds-ai narrator truncation guard, 2026-07-08).'tool-calls'— the run ended with outstanding tool calls and no final text (maxSteps exhaustion).'error'— the stream emitted anerrorpart.
An answer the model refused keeps the reason it reports here ('stop',
or 'length' when the output cap cut the refusal message off);
refusal resolves to the message, and the text stream carried
none of it.
Historically the streaming surface discarded the provider's reason
and fabricated 'stop'; the provider layer always had it (final
chunk choices[0].finishReason; Anthropic maps max_tokens →
length in its adapter). Settled via the generator's cleanup on
early abandonment too, so awaiting it after a partial consume does
not hang. On a stream the consumer abandoned it does not say why the
stream ended: it reports the latest step that finished. The
prompt-shim tool-emulation path reports 'length' when the output cap
cut off the reply that ended it, and 'stop' otherwise (its internal
calls do not thread any other per-step reason).
fullStream
fullStream:
AsyncIterable<StreamPart>
Defined in: packages/agentos/src/api/streamText.ts:235
Async iterable that yields all StreamPart events in order.
grounding?
optionalgrounding:Promise<VerifiedResponse|undefined>
Defined in: packages/agentos/src/api/streamText.ts:231
Citation verdicts after text completes, when enabled on a default-runtime session.
guardReport?
optionalguardReport:Promise<TextGuardrailReport|undefined>
Defined in: packages/agentos/src/api/streamText.ts:286
With guards: resolves when the stream ends to what each stage's guards answered. After a stop it is the report
the error part carries. Unset on a call without guards.
historyOmitted?
optionalhistoryOmitted:Promise<PromptHistoryOmission|undefined>
Defined in: packages/agentos/src/api/streamText.ts:305
On a gmi() or agent({ runtime: 'gmi' }) session's stream(): the
conversation history the turn's requests left out to fit the prompt
engine's history budget, as GenerateTextResult.historyOmitted reports it
on send(). Resolves when the stream ends, to undefined when every
request carried the whole history or the turn ended before the GMI
returned its output. Unset on streamText() and on the default runtime.
memoryRecall?
optionalmemoryRecall:Promise<MemoryRecallCapture|undefined>
Defined in: packages/agentos/src/api/streamText.ts:296
On a gmi() or agent({ runtime: 'gmi' }) session's stream() with
cognitive memory: the recall capture of the turn's memory assembly, as
GenerateTextResult.memoryRecall carries it on send(). Resolves when the
stream ends, also when the turn fails after its memory assembly (the
record is that assembly's), to undefined when the turn assembled no
memory block or memory.recall.capture is 'off'. Unset on
streamText() and on the default runtime.
model
model:
Promise<string>
Defined in: packages/agentos/src/api/streamText.ts:273
Resolves to the resolved model id once the stream has started.
provider
provider:
Promise<string>
Defined in: packages/agentos/src/api/streamText.ts:271
Resolves to the resolved provider id (e.g. openrouter, anthropic)
once the stream has started. Available eagerly because routing happens
before the first chunk; exposed as a Promise so the type lines up with
the rest of this contract and so callers don't see undefined while the
stream is still spinning up. Used by wilds-ai's [llm-call] telemetry
line for per-step latency attribution (production fix 2026-05-05:
narrator-stream rows were logging provider=unknown model=unknown,
which made model-routing audits significantly harder).
providerMessageId
providerMessageId:
Promise<string|null>
Defined in: packages/agentos/src/api/streamText.ts:363
Provider message id (msg_...) of the FINAL step; null when the run
did not opt into cache diagnostics or the provider sent no id. Persist it
and pass it back as the next request's
cacheDiagnostics.previousMessageId to thread the comparison across
turns (the wilds-ai narrator threads it per session).
refusal?
optionalrefusal:Promise<string|undefined>
Defined in: packages/agentos/src/api/streamText.ts:346
The model's refusal message when the final step declined the request
with one (OpenAI's refusal): resolves with finishReason, to the
whole message (possibly the empty string) when that is 'stop', to the
piece that came when the output cap cut the message off ('length'),
and to undefined when the model did not refuse or the stream ended on
an error. The message never goes out as a text part. Read this promise
to tell a refusal from an empty answer. Set by streamText(); other
surfaces that return this shape may leave it unset.
responseModel
responseModel:
Promise<string|undefined>
Defined in: packages/agentos/src/api/streamText.ts:252
Provider-reported model id of the final step (may differ from the
requested/resolved id across aliases and fallback hops; spec batch-1
C1). Settles on every terminal path — normal completion, fallback,
error, early abandonment — and is undefined when no chunk reported a
model id. The existing model-related fields keep their meaning.
serviceTier
serviceTier:
Promise<string|undefined>
Defined in: packages/agentos/src/api/streamText.ts:258
Provider-reported service tier the final step actually ran at (OpenAI;
spec batch-1 C2). Settles on every terminal path; undefined when no
chunk reported a tier.
text
text:
Promise<string>
Defined in: packages/agentos/src/api/streamText.ts:242
Resolves to the assembled assistant reply when the stream completes: the text of the latest step that produced any. A stream that ends mid-step, on an error after output or because the consumer stopped reading, resolves to the text that step delivered.
textStream
textStream:
AsyncIterable<string>
Defined in: packages/agentos/src/api/streamText.ts:233
Async iterable that yields only raw text-delta strings (filters out non-text parts).
toolCalls
toolCalls:
Promise<ToolCallRecord[]>
Defined in: packages/agentos/src/api/streamText.ts:260
Resolves to the ordered list of ToolCallRecords when the stream completes.
usage
usage:
Promise<TokenUsage>
Defined in: packages/agentos/src/api/streamText.ts:244
Resolves to aggregated TokenUsage when the stream completes.