BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/durable-resume.mdx
View on GitHub---
title: "Durable Resume"
description: "When a hosted agent run is interrupted and resumes in the same turn, a tool-call journal derived from the durable ledger blocks exact repeats of write calls that already completed."
---
# Durable Resume
<Callout id="doc-block-dres1who" tone="info">
**Who is this for:** anyone who wants to understand how the framework's run
recovery avoids duplicate side effects. This is built-in behavior — there is
nothing to wire up.
</Callout>
Hosted agent runs get interrupted: a serverless function hits its hard timeout mid-stream, a gateway drops the connection at 45s, a socket hangs up, the platform cold-starts. The framework already recovers from these by saving the conversation prefix and re-running the LLM call ("continue from where you left off"). But recovery alone has a sharp edge: if the interrupted attempt **already sent an email or created a ticket**, a naive resume could do it again.
Durable resume closes that gap. On resume, the framework knows which side-effecting tool calls already completed and refuses to re-run them — at two layers.
<Diagram id="doc-block-1sldt6j" title="Two layers block duplicate side effects on resume" summary={"The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."}>
```html
<div class="diagram-durable">
<div class="diagram-box" data-rough>
Run-event ledger<br /><small class="diagram-muted"
>tool_start / tool_done</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center" data-rough>
<strong>Tool-call journal</strong
><small class="diagram-ok">completed = start+done</small
><small class="diagram-warn">interrupted = start, no done</small>
</div>
<div class="diagram-col">
<div class="diagram-pill">Layer 1 · prompt note → model</div>
<div class="diagram-pill accent">
Layer 2 · hard-block re-dispatched write
</div>
</div>
</div>
```
```css
.diagram-durable {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.diagram-durable .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.diagram-durable .diagram-arrow {
font-size: 22px;
line-height: 1;
}
.diagram-durable .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
}
```
</Diagram>
## The tool-call journal {#journal}
The journal is a **pure read over the durable run-event ledger** — there is no new recording hook in the hot path. It classifies the tool calls already recorded for the current turn:
- **Completed** — a `tool_start` with a matching `tool_done`. The call ran, its side effect happened, and its result was recorded. **Do not re-run.**
- **Interrupted** — a `tool_start` with **no** matching `tool_done`. The call began, its side effect may or may not have landed, and the interruption ate the result. Outcome unknown.
Matching mirrors how durable turns are rebuilt elsewhere: a `tool_done` pairs with the oldest still-open `tool_start` for the same tool name (FIFO per tool). A `clear` event (discarded partial output) resets the per-turn tally so abandoned partials don't leave phantom open calls.
## Layer 1: prompt-level journal note {#prompt-note}
When a run resumes (soft timeout, gateway timeout, or any resumable transport error), the framework appends a **structured journal note** to the resume prompt, right after the "continue from where you left off" nudge. The note tells the model, in plain text:
- which tool calls **already completed** (with short results) so it reuses them and does **not** re-run them, and
- which tool calls were **interrupted with unknown outcome** so it verifies state before assuming success or failure.
When the journal is empty (a turn with no tool activity, or a clean continuation), nothing extra is appended and resume behavior is byte-for-byte what it was before. The journal itself is required, though: if the ledger can't be read, even after one retry, the resumed run stops before the model runs, with `tool_call_journal_unreadable`, and asks you to send the request again. Without the ledger it can't tell which steps already finished.
## Layer 2: tool-layer hard-block {#hard-block}
The prompt note is advisory — a well-behaved model heeds it, but a model isn't a guarantee. So the loop also enforces it at the tool layer.
Before the loop runs in a resumed chunk, it snapshots the journal once (capturing only **prior** chunks of this logical turn). When the model re-dispatches a **write** tool whose tool name **and input** match a completed journal entry, the loop short-circuits: it returns the journaled result instead of executing the action, with a note that the call already completed in an earlier interrupted attempt and was not re-run to avoid a duplicate side effect.
Key properties:
- **Write tools only.** Read-only (`readOnly` / GET) actions are never blocked — re-reading is safe and idempotent.
- **Content-addressed.** The match is on tool name + input signature, so a resumed call sitting at a different position in the turn still matches; a _different_ call (different args) is treated as fresh and runs normally.
- **Consume-once.** Each completed entry is claimed when matched, so two genuinely-distinct identical fresh calls in the same turn don't both short-circuit on one journaled completion.
- **Fresh calls untouched.** A first-turn call sees an empty journal; nothing changes for normal runs.
<Callout id="doc-block-fjhhyg" tone="warning">
The hard-block stops only an **exact repeat**: the same write tool with the same input, after an earlier attempt in the same turn finished and recorded its result. It does not rule out every duplicate email, charge, or ticket:
- **A reworded retry isn't matched.** If the model changes any argument, such as the email body, the call no longer matches a completed call, so the hard-block doesn't stop it.
- **After a crash mid-send, a repeat is held back only for the rest of the turn.** If the process dies after the side effect lands but before its result is recorded, the call counts as interrupted, and the hard-block covers only completed calls. The resumed run holds back that write tool instead, as [Writes with an unknown outcome](#unknown-outcome) describes. A new message starts a new turn, where nothing holds it back.
- **A crashed run can resume in the same turn through either of two separate paths.** One is a [durable background run](/docs/durable-background-runs). The other is a later chunk of a normal foreground turn using the [foreground self-chain](/docs/durable-background-runs#foreground-self-chain). Any other crashed run ends with an error. Choosing **Continue** on it resumes the same turn, so both layers apply.
An action whose side effect must never repeat needs its own idempotency check. The hard-block never applies to read-only actions.
</Callout>
## Writes with an unknown outcome {#unknown-outcome}
A write's outcome is unknown when it started but no result was recorded, when it timed out, or when it failed after it began writing without saying whether anything was saved. Running it again could apply the change twice, so for the rest of the turn the loop holds back that tool:
- **The same call again.** If the model repeats the call with the same arguments, the loop first checks whether that call's own result was recorded after all, and returns it if so. Otherwise the call doesn't run: the run stops with `write_tool_outcome_unknown` and asks you to check what was saved, then reply "continue".
- **Any other call to that tool.** A call with different arguments, such as a reworded email, doesn't run either. The model is told that the earlier call may already have applied, and to check the current state with a read and tell you what it found. The turn goes on, unless the earlier call can't be identified because it recorded no arguments to compare or was left out of the replayed history. Then any call to that tool could be a repeat, so it stops the run the way the same call does.
An action marked `retrySafe` is exempt, because running it again can't duplicate or corrupt data: it validates before it writes, or it sets an end state, such as replacing a record by ID. The model can correct its arguments and try again. Read-only actions aren't held back unless a write ran inside one.
## Automatic continuation after a time limit {#auto-continue}
When the server stops a turn at its run time limit and nothing server-side picks it up, the chat continues it on its own, in the **same turn**. The resumed run gets the thread's tool calls and results plus the journal note above, so finished steps are reused, and an identical repeat of a write — including a cross-app `call-agent` delegation, whose idempotency key is derived from the turn — returns the recorded result instead of being sent again. The chat shows a _Resuming_ status, and Stop keeps working.
A turn continues automatically **at most three times**. The count is stored with the turn's runs, so reloading the page does not reset it, and a second tab cannot double it. After that, or after any error, stop, cancellation, or credential or rate limit, the turn ends with **Continue** available and waits for you.
Choosing **Continue** resumes the stopped run's own turn the same way, with no limit on how often, so both layers apply to it as they do to an automatic continuation. It is offered only for the conversation's newest stop. If you send a new message instead, the agent is first told what the unfinished turn already did, but neither layer blocks a repeat.
## What's next
- [**Real-Time Sync**](/docs/real-time-collaboration) — how the durable run ledger streams to the client and replays on reconnect.
- [**Actions**](/docs/actions-overview) — `readOnly` marks reads as safe to re-run; everything else is treated as side-effecting.
- [**In-Loop Processors**](/docs/processors) — another loop-internal hardening seam.
- [**Durable Background Runs**](/docs/durable-background-runs) — moving a long turn onto a separate background function.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |