[scuffi]

Summary

Stacked on #238. Lets a host module function pause a replayable run until someone answers, for approvals and the like. The code being run doesn't change: it calls postComment() and gets a result, however long the answer takes.

modules: {
  "ws:github": {
    postComment: async ([issue, body], ctx) => {
      const { approved } = await ctx.interrupt({ kind: "approval", issue, body });
      if (!approved) throw new Error("The comment was rejected.");
      return github.comment(issue, body, { idempotencyKey: ctx.callId });
    },
  },
}

// Elsewhere, for example from a request handler:
for (const call of await workspace.runtime.pending()) {
  await workspace.runtime.respond(call.id, call.callId, { approved: true });
}

It ships in the same release as #238, and #238's API doesn't change.

Changes

ctx.interrupt(payload)
  └─ journal: call → waiting, with payload
  └─ bridge: hold new calls, let calls in flight finish and journal
  └─ backend: release the isolate. The run stays "running".

runtime.respond(id, callId, answer)
  └─ journal: call → answered (throws ENOTWAITING if it isn't waiting)
  └─ none left waiting → relaunch, replay to the call
       └─ function runs again with the same callId, interrupt() returns value

• WorkspaceModuleCallContext.interrupt(), runtime.pending() and runtime.respond(). pending() and respond() are on workspace.stub().runtime too, for a Worker calling the object. Plain data both ways, so nothing to dispose.
• An onWait(call) backend option, called with the fields pending() lists once a wait is saved, so an app can message whoever answers instead of polling. It's at most once per wait, so pending() stays the source of truth.
• The journal gets waiting and answered states, with the payload and answer. Each waiting call records when it started waiting, which pending() reports. The run's resume row tracks when its first unanswered call started waiting and how long it has waited in total, so waiting doesn't count toward the timeout.
• Recovery leaves waiting runs alone, so a wait survives a deploy. Resuming after an answer doesn't count as an attempt, and starts the run's attempts again.
• interrupt() throws in a run that isn't replayable, with a message that says to use onInterrupt: "replay". That's in the JSDoc and the docs too, so switching a backend off replay is a visible break for modules that interrupt, not a silent one.
• A call can interrupt once. The journal keeps one answer per call, so a second interrupt() throws rather than getting the first one's answer.
• interrupt(), pending(), respond() and the pending call type are marked experimental in their JSDoc, like restart and replay.
• Two fixes found along the way. Output a released isolate writes on its way out is now dropped, as it isn't the run's. And unsafeToRepeat still applies to a call cut off after it got its answer.

Testing

End-to-end in workerd: answering resumes the run; a restart while a call waits; two interrupts in one Promise.all; a call in flight finishes and is journaled before release; waiting doesn't count toward the timeout; killing a waiting run; an answer that arrives before the run is released; onWait hearing about a wait once across a restart and resume; two calls in flight that both interrupt, answered together; and interrupt() throwing in an onInterrupt: "fail" run. Unit tests for the journal's waiting states, the bridge's unsafeToRepeat check and the one-interrupt limit, an answer starting the run's attempts again, plus a stub pass-through test. I disabled the quiesce wait, the timeout adjustment, the frame guard, the limit, the resume after release and the onWait call in turn, and each one failed its test.

In production, on the personal account, I redeployed while a call waited. The old instance kept serving for about five minutes, then the new version took over with the call still waiting. Answering it resumed the run there, and every comment was posted once.

Scenario	Result
Approve, reject, answer twice	Code gets each answer, second answer throws ENOTWAITING
Crash while waiting (local)	Still waiting on the new instance, attempt unchanged
Crash between calls (local)	Resumes at attempt 2, no repeats
Redeploy while waiting (production)	New version picks it up after ~5 min, completes

Caveats

• A run is released once each call in flight has finished or is waiting too, and those waits are answered together. A call made after the first interrupt is held until the run resumes, so when a call interrupts straight away, the next call in its Promise.all can be left for a later round. Batching those can come later without an API change.
• Every answer replays the run from the top, so a run that waits often replays often.
• Anything a module function does before interrupt() runs again on resume.
• This edits computer: Restart or replay interrupted isolate JavaScript runs #238's new tables in place rather than migrating them, so the two must ship in the same release.

Follow-ups

• needsApproval tools in ws:tools/ai-sdk on top of interrupt().
• A waiting status on getExec(), so a client can tell a waiting run from a working one without pending().

[changeset-bot]

🦋 Changeset detected

Latest commit: ba58d1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/dofs	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@251

commit: ba58d1e