From 555c5fe844311cdae1ad156f0cf8197650e52b75 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Tue, 4 Aug 2026 12:03:36 -0600 Subject: [PATCH] docs: Added documentation for the new .recover command --- REPL.md | 20 ++++++++++++++++++++ Sessions.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/REPL.md b/REPL.md index 613a9d7..eab7766 100644 --- a/REPL.md +++ b/REPL.md @@ -194,6 +194,26 @@ of the last response. ![continue](./images/repl/continue.gif) +## `.recover` - Recover from an interrupted agentic session + +When a long-running agentic session is interrupted for one reason or another, e.g. by an API error (rate limits, +network failures, token exhaustion, etc.) or a Ctrl+C during generation, Coyote checkpoints the session state +at the point of failure. `.recover` lets you resume from that checkpoint without losing the tool calls and +context accumulated before the error: + +``` +.recover [message] +``` + +If you don't provide a message, Coyote sends `"Please continue from where you left off."` The model receives the full +session history up to the interruption, including all completed tool calls and their results, followed by your +recovery message, and continues from there. + +**Requires an active session.** `.recover` is only available when a session is open. Without a session, interrupted +context is not preserved and there is nothing to recover from. + +See [Error Recovery](Sessions#error-recovery) in the sessions documentation for more detail. + ## `.regenerate` - Regenerate the last response If ever your response is interrupted, or you want to try generating it again, you can use the `.regenerate` command to do this without having to retype your query: diff --git a/Sessions.md b/Sessions.md index 1612d7d..863d643 100644 --- a/Sessions.md +++ b/Sessions.md @@ -169,3 +169,38 @@ to remove the last exchange from the session and restore your original prompt fo > **REPL only.** When running Coyote as a one-shot CLI command (`coyote `), Ctrl+C aborts as usual. Mid-stream interruption > is a REPL-only feature. + +# Error Recovery + +During long agentic sessions, errors can interrupt generation mid-chain; e.g. transient API errors (rate +limits, network failures, token exhaustion, timeouts, etc). Without recovery, all the tool calls and +context accumulated in the current session would be lost. + +When a session is active and an error occurs during generation, Coyote automatically checkpoints the full session +state, including every completed tool call and its result up to the point of failure, and marks the session as +recoverable. You can then resume with: + +``` +.recover [message] +``` + +The model receives: +- The original user prompt +- All tool calls and results that completed before the error +- An `[Response interrupted due to error]` marker as the last assistant turn +- Your recovery message (defaults to `"Please continue from where you left off."` if omitted) + +**How this differs from `.continue`:** `.continue` is for text responses that were cut off mid-generation (e.g., +the model hit its output token limit mid-sentence). `.recover` is for agentic chains that were cut off by some +error, restoring full tool call context so the model can continue the task rather than restart it. + +> **Requires an active session.** Without a session, interrupted agentic context is not preserved. If you run +> long multi-tool tasks, use a session to make them recoverable. + +> **Completed turns are preserved; the interrupted turn is not.** Tool calls that fully executed before the error +> are checkpointed. Any tool call that the model had begun streaming but not yet completed at the moment of failure +> is not included, meaning the model will need to re-issue it. + +> **Ctrl+C during generation also triggers recovery.** If you interrupt a streaming response with Ctrl+C while a +> session is active, the same checkpoint is written and `.recover` is available afterward. This is also the time +> when users can inject additional prompts or context to long-running prompts.