Time-travel API

Every successful task attempt records the workspace’s JJ change ID into _smithers_attempts.jj_pointer. The time-travel API replays a run to one of those points: it restores the filesystem from the captured pointer and discards the graph snapshots recorded after the attempt began, so the run’s timeline rolls back to that attempt. The public, facade-exported surface is two functions. revertToAttempt is the low-level VCS restore; timeTravel is the higher-level reset that can also reset the target node and its dependents so the engine re-runs them.

import { timeTravel, revertToAttempt } from "smithers-orchestrator";
import type {
  TimeTravelOptions,
  TimeTravelResult,
  RevertOptions,
  RevertResult,
} from "smithers-orchestrator";

Both take the run’s SmithersDb adapter as their first argument. Neither throws for a missing attempt or a missing pointer; they report failure on the returned success boolean. Inspect result.success rather than wrapping the call in try/catch.

timeTravel

Restore VCS to a previous attempt, then reset the target node (and optionally its dependents) back to pending so the engine re-runs from there. This is the entry point you want when you intend to resume the run: it cancels later attempts, deletes the affected output rows, discards frames recorded after the attempt started, and flips the run back to running.

function timeTravel(adapter: SmithersDb, opts: TimeTravelOptions): Promise<TimeTravelResult>;

adapter

SmithersDb

required

The database adapter for the run, as returned by the authoring factory’s db layer. See SmithersDb.

opts

TimeTravelOptions

required

Show TimeTravelOptions

runId

string

required

The run to roll back.

nodeId

string

required

The node whose attempt is the rollback target.

iteration

number

default:"0"

Loop iteration of the node. Defaults to 0 for non-looped nodes.

attempt

number

Attempt number to restore. Omit to use the latest recorded attempt.

resetDependents

boolean

default:"true"

Also reset every node that ran after the target (later iterations, attempts started after the target’s start time, or ordered after it) back to pending. Set false to reset only the target node.

restoreVcs

boolean

default:"true"

Restore the working copy from the attempt’s JJ pointer before resetting nodes. Set false to reset DB state without touching the filesystem.

onProgress

(event: SmithersEvent) => void

Callback for TimeTravelStarted / TimeTravelFinished events. See SmithersEvent.

TimeTravelResult

Promise<object>

Show TimeTravelResult

success

boolean

true once the reset committed. false if the attempt or node was not found, or the VCS restore failed.

jjPointer

string

The JJ change ID restored from, when one was recorded for the attempt.

vcsRestored

boolean

Whether the working copy was actually restored. false when restoreVcs was off or the attempt had no pointer.

resetNodes

string[]

The node ids flipped back to pending, deduplicated.

error

string

Failure reason. Present only when success is false.

const reset = await timeTravel(adapter, {
  runId: "RUN_ID",
  nodeId: "NODE_ID",
  attempt: 2,
  iteration: 0,
  resetDependents: true,
  restoreVcs: true,
});

if (!reset.success) throw new Error(reset.error);
// reset.resetNodes are now pending; resume the run to re-execute them.

Source timetravel.js · TimeTravelOptions.ts · Tests timetravel.e2e.test.jsx · See also Revert, revertToAttempt

revertToAttempt

Restore the working copy to an attempt’s JJ pointer and discard DB frames recorded after the attempt started. This is files-only: it does not reset nodes, cancel attempts, or change the run status, so it leaves the graph untouched. Use it when you only need the filesystem state of a past attempt. Unlike timeTravel, both iteration and attempt are required.

function revertToAttempt(adapter: SmithersDb, opts: RevertOptions): Promise<RevertResult>;

adapter

SmithersDb

required

The database adapter for the run. See SmithersDb.

opts

RevertOptions

required

Show RevertOptions

runId

string

required

The run to revert.

nodeId

string

required

The node whose attempt is the revert target.

iteration

number

required

Loop iteration of the node. Pass 0 for non-looped nodes.

attempt

number

required

Attempt number to restore.

onProgress

(event: SmithersEvent) => void

Callback for RevertStarted / RevertFinished events. See SmithersEvent.

RevertResult

Promise<object>

Show RevertResult

success

boolean

true once the working copy was restored. false if the attempt was not found, had no recorded pointer, or the JJ restore failed.

jjPointer

string

The JJ change ID restored from. Present on success and on a failed restore where a pointer existed.

error

string

Failure reason. Present only when success is false.

const result = await revertToAttempt(adapter, {
  runId: "RUN_ID",
  nodeId: "NODE_ID",
  attempt: 2,
  iteration: 0,
});

if (!result.success) throw new Error(result.error);

revertToAttempt and timeTravel need JJ in PATH and a JJ-initialized workspace, and the target attempt must have completed while JJ was available (otherwise no pointer was captured). See Revert for the requirements and the equivalent CLI command.

Source revert.js · RevertOptions.ts · Tests revert.test.js · See also Revert, timeTravel

CLI surface

The richer time-travel surface (fork, replay, rewind, snapshots, and timeline) is driven through the CLI and the rewind RPC, not as facade exports. Reach for those rather than importing non-exported functions from the package.

CLI overview for fork, replay, rewind, snapshots, and timeline.
Revert for the revert command that mirrors revertToAttempt.
rewind-run RPC to rewind a run over the gateway.

# Browse the timeline, then rewind to a checkpoint and resume.
bunx smithers-orchestrator timeline RUN_ID
bunx smithers-orchestrator rewind RUN_ID FRAME_NO

Source time-travel/src · Tests time-travel/tests · See also CLI overview, Revert, rewind-run RPC

Overview

Core API

Runtime

Types & errors

Gateway RPC

timeTravel

revertToAttempt

CLI surface

​timeTravel

​revertToAttempt

​CLI surface

timeTravel

revertToAttempt

CLI surface