Interruptions

Some programs cannot finish in a single invocation. They may need a person to approve an action, an application to complete authentication, or another system to provide information later.

run supports this pattern by allowing a host function to interrupt execution and return control to the host. The host can persist the returned state, collect a decision, and continue the same logical run in a later invocation.

An interruption is a request from a host function to pause the workflow. The host function supplies an application-defined payload that describes the decision being requested.

For example, a host function responsible for sending a message might interrupt before performing the side effect:

const context = getHostFunctionContext();

if (context.resume === undefined) {
  context.interrupt({
    kind: 'approval',
    message: 'Send this message?',
  });
}

The invocation resolves with an interrupted result after pending host function work has settled. Each interruption contains an ID, the fully qualified host function name (hostFunctionName), the guest arguments, and the payload created by the host function.

An interruption is an expected result rather than an error.

Continuations

A continuation is the token returned with an interrupted result. It represents the state required to replay the source and continue the logical run.

You choose where continuations are stored. The token is an opaque string, so it can live in a database, a durable key-value store, or a job record:

if (result.status === 'interrupted') {
  await continuationStore.set(approvalId, {
    continuation: result.continuation,
    interruptions: result.interruptions,
  });
}

When the external decision is available, the host reads the same token and passes it back to the runner as continuation. The token must not be modified between these invocations.

Treat a continuation as a bearer capability: anyone holding a valid token can resume the workflow. Store it behind access controls and keep the raw token out of logs.

The default signed continuation protects integrity but does not encrypt its contents. Base64 is not encryption, so keep sensitive data out of source, host function arguments, interruption payloads, and continuation context.

A continuation codec is responsible for encoding replay state into a token and decoding that token later. The package provides a signed codec, a stored codec, and an interface for custom codecs.

Resolutions

A resolution is the host application's answer to an interruption. It contains the interruption ID and an application-defined value.

When the run continues, the host function that created the interruption is invoked again. Its host function context contains resume information with the original payload and the supplied resolution.

const context = getHostFunctionContext();

if (context.resume === undefined) {
  context.interrupt({
    kind: 'approval',
    message: 'Send this message?',
  });
}

if (context.resume.resolution !== true) {
  return { sent: false };
}

return { sent: true };

When an interrupted result contains several interruptions, the host must resolve all of them together before continuing the run.

Replay

Continuing an interrupted run starts a new invocation and executes the source again from the beginning. This process is called replay.

The continuation contains a ledger, which is an ordered record of host function outcomes from earlier attempts. During replay, previously fulfilled host functions return their recorded values and previously rejected host functions reproduce their recorded errors. Those settled host functions are not called again.

The interrupted host function is called again after the matching resolution becomes available. The host function uses its resume information to decide how execution should continue.

Replay validates that the host function names and serialized arguments occur in the same order as before. If the source takes a different path, continuation validation fails instead of applying recorded outcomes to different work.

Determinism

Guest time and pseudorandom behavior are deterministic across replay. The logical run records an initial clock value and random seed, so the source observes the same sequence in later attempts.

Determinism helps the source reach the same host function calls during replay. It does not make host functions or external systems deterministic. Host functions remain responsible for protecting side effects with idempotency keys, request identifiers, or transactional application logic.

Identity

Every invocation has an invocation ID that identifies that execution attempt. Replaying a run creates a new invocation ID.

The logical run ID remains stable across the original invocation and all replay attempts. Each host function call also receives a request ID and a one-based request index.

Together they let the host correlate logs across a workflow that spans several attempts.