[ben-reitz]

A host module that holds something for a run, such as a browser session, can't tell when to let go of it. A run waiting in ctx.interrupt() gives up its isolate and later replays from the top, and a run that ends tells its modules nothing.

createScopedModule() adds a host module whose state lives for one scope of a run: from when the run's code starts in an isolate until it waits in ctx.interrupt() or ends. A run that resumes starts a new scope. The backend calls start on the scope's first call to the module and closes the instance when the scope ends:

"codemode:browser": createScopedModule({
  description: "A browser: `open(url)`.",
  exports: ["open"],
  async start(scope, host) {
    const session = await browsers.connect({ conversation: scope.metadata.conversation });
    return {
      functions: { open: ([url]) => session.open(String(url)) },
      async close(end) {
        await session.close();
        if (end.reason !== "paused") end.log("Closed the browser.\n");
      },
    };
  },
}),

The export names are listed up front because the backend needs them before any run starts, and a call fails if start returns different functions. Concurrent first calls share one start, so start gets its own signal, which aborts when the run is killed. Only a final close can log(), and that text is saved in the same transaction as the run's end, so a restart can never replay a run against output it didn't write. Plain modules and factories work as before.

Ending a run now also waits for a pause's release to finish, so killing a run as it pauses can't publish its exit while the isolate is still shutting down.

Unit and workerd tests cover each moment in the diagram, plus a shared first start, an exports mismatch, a kill during start, a close that throws, and output cut at maxStdioBytes. docs/17_isolate_javascript.md has a new section on scoped modules.

[changeset-bot]

🦋 Changeset detected

Latest commit: ccef2c5

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@293

commit: ccef2c5

[aron-cf]

@ben-reitz Spent a bit of time reviewing this with an agent. The biggest bit for me is the addition of the new createScopedModule API. This feels like a smell, and we should probably look at the different uses of modules to try and unify a single interface. I'd like a single interface ideally. I've just opened #297 for which I need to look into reworking this. So my main question is how much this blocks the browser api today? Can we ship the other 4? Or do we need this in?

This is sorta where I got to in my session:

---

The module kinds differ mainly in how long their state lives:

Kind	Lifetime	Gets host services	Cleanup
{ fn } object	the backend's	no	—
Factory	the connection's	yes	none today
createScopedModule()	one scope	yes	close(end)

1. Normalize host modules into one internal form in parseModules, for example:

   interface NormalizedHostModule {
     readonly exports: readonly string[];
     readonly lifetime: "backend" | "connection" | "scope";
     readonly description: string | (() => string);
     start(ctx: { host: WorkspaceModuleHost; scope?: WorkspaceModuleScope }):
       WorkspaceScopedModuleInstance | Promise<WorkspaceScopedModuleInstance>;
   }

   An object becomes lifetime: "backend", and its start returns { functions: obj }. A factory becomes "connection", started once per handle as it is now. A scoped module becomes "scope". The bridge would then take one (specifier, signal) => Promise<functions> lookup instead of #hostModuleOf plus #scopedModules, and #callHostModule would lose its start === undefined branch. The unsafeToRepeat check after the instance resolves would cover every kind, not just scoped modules. The public forms (object, factory, createScopedModule) stay as shorthand, so nothing changes for users.

   This doesn't need to happen in this PR. It could be a follow-up once scoped modules are no longer experimental.

2. If factories need cleanup, add close when the connection is disposed, not per-run hooks. A factory's state lives for the whole connection, but nothing tells it when the connection ends. An optional close on what the factory returns would be the same instance-plus-close pattern at a different lifetime. I'd only add it once a module needs it.

3. Put run-level observability on the backend, not on modules. If we want something like "tell me when a run ends" for metrics or auditing, an option such as onRunEnd(execution, status) on WorkerJavaScriptBackend fits better than every module subscribing to every run. That concern isn't about module state.

Smaller things in this PR

• A slow start can leak. #closeInstances awaits started inside the maxHostCallMs race. If start resolves after the deadline, nobody closes the instance. Could late arrivals be closed with started.then((i) => i.close?.(end)), or should the docs say start must honour scope.signal?
• closeOutput.write keeps the whole first chunk that goes over the limit (it checks bytes > room before pushing). Cutting at write time would cap memory at about room.
• description is read once. Spreading options in createScopedModule runs any getter, and parseModules builds the line eagerly, while factory descriptions are read lazily. Maybe push a thunk the way factories do?
• createScopedModule could check typeof options.start === "function". If start lives on a prototype, the spread drops it silently, and the first call then fails with "start is not a function".
• The description says start's signal "aborts when the run is killed". It also aborts when the isolate is released for a pause, which the JSDoc gets right.

[ben-reitz]

Replaced by #301, which now carries this commit.