Skip to content

feat(session): report crash recovery and discarded inputs in GetSession #3397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
adalundhe wants to merge 2 commits into from
Closed

feat(session): report crash recovery and discarded inputs in GetSession #3397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d7e91f2
feat(session): record inputs a crash recovery discards
adalundhe Nov 4, 2026
85e17ea
feat(session): report crash recovery in GetSession
adalundhe Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/architecture/runtime-and-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,23 @@ changes after the retained snapshot are lost; the discarded turn receives no
checkpoint at that older snapshot. Another revert against the now-healthy Actor
returns `FAILED_PRECONDITION` with `KAGENT_SESSION_RUNTIME_NOT_CRASHED`.

`GetSession` reports a read-only recovery observation for the recorded Actor.
It is the only Session read that calls Substrate; MCP and the other Session
responses read the stored record and omit `recovery`. An unavailable or
replaced Actor leaves the observation unknown and does not prevent history
reads. The observation and `RevertSession` share one crash check, so chat offers
a revert exactly when the revert would be admitted. Chat offers that revert and
the existing fork action for a saved READY checkpoint.

Recovery records exact task and message identities for user inputs after the
retained snapshot boundary, including accepted inputs not yet published. Chat
marks those inputs "Not remembered after recovery" and retains the public
transcript; completed A2A tasks and their history are not rewound, so a reply
to a marked input can still appear. The annotations remain on the recovered
Session. A revert to a snapshot that no history event records leaves the
boundary unknown and adds no annotations. Forks copy checkpoint-bounded history
into a fresh Session and do not inherit its delivery annotations.

```mermaid
sequenceDiagram
participant Client
Expand Down
8 changes: 7 additions & 1 deletion docs/lifecycle-retries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,18 @@ should likewise retain the `request_id` passed to `create_sandbox`.

## Recovering a crashed Session

Call `SessionService.RevertSession` with the Session ID to restore its recorded runtime to the last durable snapshot.
Chat offers a revert or a fork from an existing READY checkpoint after a confirmed
runtime crash. Call `SessionService.RevertSession` with the Session ID to restore
its recorded runtime to the last durable snapshot.
The caller needs Session update access. The operation verifies Substrate's CRASHED state and the recorded Actor identity.
Recovery fails interrupted turns and waiting tasks absent from the retained snapshot.
It preserves durable terminal results and returns the Session to READY with its Actor suspended.
It discards runtime changes since that snapshot and does not replay input.
A runtime without a snapshot restarts from its initial state.
`GetSession.recovery.failed_messages` identifies user inputs absent from the
restored runtime by both task and message ID. Their public history remains
available, and chat marks them "Not remembered after recovery". Only
`GetSession` returns `recovery`.

Retry an interrupted revert against the same Session ID. Pending recovery retains its operation across API restarts.
The lifecycle worker retries already admitted recoveries; it does not initiate recovery for other crashed Sessions.
Expand Down
Loading