Time-travel API

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

import { timeTravel, revertToAttempt } from "smthrs";
import type {
  TimeTravelOptions,
  TimeTravelResult,
  RevertOptions,
  RevertResult,
} from "smthrs";

Both take the run’s SmithersDb adapter as their first argument. A missing attempt or pointer returns success: false. Crossing an unresolved external effect throws TIME_TRAVEL_SIDE_EFFECT_BLOCKED with the boundary report in the error details.

timeTravel

Restores VCS to a previous attempt, then resets the target node (and optionally its dependents) to pending so the engine re-runs from there. Use this to resume a run: it cancels later attempts, deletes their output rows, discards frames recorded after the attempt started, and flips the run back to running.

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

SmithersDb

required

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

TimeTravelOptions

required

Show TimeTravelOptions

string

required

The run to roll back.

string

required

The node whose attempt is the rollback target.

number

default:"0"

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

number

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

boolean

default:"true"

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

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.

boolean

default:"false"

Cross unresolved external effects, record the crossing, and mark the run for attention.

boolean

default:"false"

Skip registered compensation handlers. Skipped effects require force.

(event: SmithersEvent) => void

Callback for TimeTravelStarted / TimeTravelFinished events. See SmithersEvent.

Promise<object>

Show TimeTravelResult

boolean

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

string

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

boolean

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

string[]

The node ids flipped back to pending, deduplicated.

EffectBoundaryReport

Unconditional report with blocking, revertible, and warnings arrays.

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

Restores the working copy to an attempt’s JJ pointer and discards DB frames recorded after the attempt started. Files-only: it doesn’t reset nodes, cancel attempts, or change run status, leaving the graph untouched. Use it when you need only the filesystem state of a past attempt. Unlike timeTravel, both iteration and attempt are required.

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

SmithersDb

required

The database adapter for the run. See SmithersDb.

RevertOptions

required

Show RevertOptions

string

required

The run to revert.

string

required

The node whose attempt is the revert target.

number

required

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

number

required

Attempt number to restore.

boolean

default:"false"

Cross unresolved external effects and mark the run for attention.

boolean

default:"false"

Skip registered compensation handlers. Skipped effects require force.

(event: SmithersEvent) => void

Callback for RevertStarted / RevertFinished events. See SmithersEvent.

Promise<object>

Show RevertResult

boolean

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

string

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

string

Failure reason. Present only when success is false.

EffectBoundaryReport

Unconditional report with blocking, revertible, and warnings arrays.

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

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

Both revertToAttempt and timeTravel need JJ on PATH and a JJ-initialized workspace; 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.

External-effect boundary

Marked tool calls and Tasks are checked before history moves. Discard operations compensate entries with a registered handler before changing VCS or database history. Replays and running forks never compensate the parent run. Every result carries:

type EffectBoundaryReport = {
  blocking: CrossedEffect[];
  revertible: CrossedEffect[];
  warnings: CrossedEffect[];
};

The guard treats unknown like succeeded. A process may stop after an external API accepted a request but before Smithers recorded the response. Pass force: true only when double execution or external drift is acceptable. Git commits, ref changes, worktree writes, and git push are exempt. GitHub API mutations are not. 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 facade exports. Use those instead of importing non-exported functions from the package.

CLI overview for fork, replay, rewind, snapshots, and timeline. See Time-travel commands compared to disambiguate rewind, replay, timetravel, and revert.
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 smthrs timeline RUN_ID
bunx smthrs 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

External-effect boundary

CLI surface

​timeTravel

​revertToAttempt

​External-effect boundary

​CLI surface

timeTravel

revertToAttempt

External-effect boundary

CLI surface