RecoveringConversationHandle class

The handle of a session's own native conversation — createSession's, and each openSession session's where they are native (OpenSessionBacking.native) — made to answer again after a turn is stopped or its input did not fit.

A conversation whose generation was cancelled mid-turn answers every later message with nothing — zero chunks in about a millisecond, on every turn after, measured on native 0.16.0 through 0.17.1. So the first turn after a stop first rewinds the conversation to before the stopped turn and puts that turn back, partial reply included (ConversationHandle.rewindStoppedTurn): the model keeps everything, images and audio too. Where it cannot — on the NPU, whose executor rolls back one token at most, on a model with linear attention state, which a rewind cannot restore, or on a libLiteRtLm without the rewind — it replaces the conversation with a new one seeded with the history this handle records, as a messages_json preface, including image and audio parts.

A turn native ended context_full (§23: its input did not fit what the window has left) leaves the conversation failing every later send. The next turn first rewinds it to that turn's checkpoint, without the input that did not fit, or rebuilds it where it cannot rewind. Nothing of the history is dropped (core 2.6.0 design §6.4b, as decided for a raw session): when the window has no room for any input left, every later turn ends the same way, and the app decides — InferenceChat rotates its session by its own token budget.

A cancel that arrives after a turn has finished does not count: Dart delivers a stream's done by cancelling its subscription, which cancels the native conversation on every normal turn, and that leaves it healthy.

Public, though nothing outside this library uses it, so that tests can drive the recovery over fake handles with no engine.

Implemented types

Constructors

RecoveringConversationHandle(ConversationHandle _live, {required Future<ConversationHandle> reopen(String? messagesJson), required ToolCallReader toolCallsOf, String? noRewindReason, bool freshConversationEachTurn = false, Duration windDownTimeout = _windDownTimeout, MediaOrder mediaOrder = MediaOrder.imagesAudioText})

Properties

canRewind → bool
Whether a stopped turn or a full context is rewound before falling back to a rebuild.
no setter
freshConversationEachTurn → bool
Each turn after the first runs in a fresh conversation that replays the history (liteRtLmFreshConversationEachTurn, LiteRT-LM #4256 on MediaTek): the conversation a turn was sent on is never sent a second message.
final
hashCode → int
The hash code for this object.
no setterinherited
lastTurnCode → int?
The absl status code native's last send ended with (§23's record): non-zero only for NativeLastTurnEnd.failed and NativeLastTurnEnd.contextFull; null when lastTurnEnd is.
no setteroverride
lastTurnEnd → NativeLastTurnEnd?
How native's last send on this conversation ended (§23's record, read when the send ended), or null before one has ended here.
no setteroverride
mediaOrder → MediaOrder
Where a rebuild puts each replayed message's images and audio.
final
noRewindReason → String?
Why this conversation is never rewound and is rebuilt from history instead (the NPU, a model with linear attention state), or null when a stopped turn and a full context are rewound before falling back to a rebuild.
final
reopen → Future<ConversationHandle> Function(String? messagesJson)
Opens a conversation with this session's config, seeded with messagesJson when given.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
toolCallsOf → ToolCallReader
The tool calls of a raw reply, for the assistant turn a rebuild replays.
final
windDownTimeout → Duration
How long a turn waits for a stopped one to record itself. See _turn.
final

Methods

cancelGeneration() → void
override
chat(String text, {List<Uint8List>? imageBytes, Uint8List? audioBytes, bool enableThinking = false}) → Stream<String>
override
chatRaw(String text, {List<Uint8List>? imageBytes, Uint8List? audioBytes, bool enableThinking = false}) → Stream<String>
override
chatRawMessage(String messageJson, {bool enableThinking = false, SendOptions options = SendOptions.none}) → Stream<String>
Streams raw SDK JSON for a prebuilt message. This is how tool results go back: chatRaw always sends role user, and a tool result has to be role tool for the model to read it as the answer to its call.
override
close() → void
override
getSessionMetrics() → BenchmarkInfo
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
rewindStoppedTurn(Map<String, Object?>? partialReply) → Future<StoppedTurnRewind>
Recovery after a stop is this handle's own job, done at the next turn.
override
tokenCount(String text) → Future<int?>
Token count for text from the model's own tokenizer, or null when it cannot be obtained (no engine, native call failed). Callers must handle null rather than assume a number — this feeds context budgeting, and the four-chars-per-token estimate it replaced undercounts Chinese by more than half (measured 0.44x on gemma-4-E2B-it) while looking authoritative.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited