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
messagesJsonwhen 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 roletoolfor 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
textfrom 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