Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

When a workflow fails — a validation error, a timeout, an agent that wandered off — recovery lets the next run resume from the exact frame just before the failure, with prior state attached. No re-doing the first 18 steps.

​
How it works

Every session is indexed into a memory graph keyed by workflow shape. When a session ends in error (tagged or detected), its frames before the error are eligible recovery points. To recover:
  1. Find the failed session.
  2. Pick a recovery frame (the SDK does this for you by default).
  3. Spawn a partial replay from that frame.
// Find recent failures for this workflow
const failures = await nusomi.sessions.list({
  workflow: "process_invoice",
  status: "sealed",
  outcome: "error",
  since: "1h",
});

const failed = failures[0];

// Recover — picks the frame just before the error tag
const recovery = await nusomi.recovery.from(failed.id, {
  mode: "guided",
});

await recovery.run();

​
Choosing the recovery frame

By default, recovery picks the frame immediately before the first event whose type is error or validation_error. You can override: 
const recovery = await nusomi.recovery.from(failed.id, {
  from_frame: someFrameId, // explicit
  mode: "guided",
});
Or use a tag as the anchor: 
// You called session.tag("submitted_for_approval") earlier
const recovery = await nusomi.recovery.from(failed.id, {
  from_tag: "submitted_for_approval",
  mode: "guided",
});

​
What gets carried over

A recovery starts from the recovery frame with this state restored:
  • Browser surfaces: cookies, localStorage, sessionStorage, open tabs, scroll position.
  • Native desktop: open windows + foreground app are restored when the workflow specifies (most apps don’t expose deterministic state restoration; Nusomi will warn rather than silently lose state).
  • Server-side state: Nusomi does not rewind anything outside the captured surface. If your workflow created a half-submitted invoice in your ERP, that record still exists. Recovery resumes from the UI state — server state is whatever it currently is.
This is by design. Recovery is a UI-level primitive. Cleaning up server-side artifacts is the workflow author’s responsibility.

​
Failure budgets

A recovery itself can fail. Set a retry budget: 
const recovery = await nusomi.recovery.from(failed.id, {
  mode: "guided",
  max_attempts: 3,
  on_attempt: (n, status) => console.log(`attempt ${n}: ${status}`),
});
Each attempt is a separate session. Use max_attempts: 1 for “try once, escalate to human.”

​
Escalation

If you want a human in the loop on every failure: 
nusomi.events.on("error", async (ev) => {
  // Notify your queue
  await myQueue.push({
    session: ev.session_id,
    frame: ev.frame_id,
    replay_link: `https://app.nusomi.com/sessions/${ev.session_id}#${ev.frame_id}`,
  });
});
The replay link drops the operator at the exact frame so they can scrub the recording, see what went wrong, and resume from there.