@draht/codemode 2026.10.20 → 2026.10.23-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/dist/cloudflare.d.ts +53 -0
  2. package/dist/cloudflare.d.ts.map +1 -0
  3. package/dist/cloudflare.js +64 -0
  4. package/dist/cloudflare.js.map +1 -0
  5. package/dist/declarations.d.ts +7 -17
  6. package/dist/declarations.d.ts.map +1 -1
  7. package/dist/declarations.js +115 -125
  8. package/dist/declarations.js.map +1 -1
  9. package/dist/index.d.ts +6 -3
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +5 -2
  12. package/dist/index.js.map +1 -1
  13. package/dist/portable.d.ts +15 -0
  14. package/dist/portable.d.ts.map +1 -0
  15. package/dist/portable.js +12 -0
  16. package/dist/portable.js.map +1 -0
  17. package/dist/runtime/execution.d.ts +68 -0
  18. package/dist/runtime/execution.d.ts.map +1 -0
  19. package/dist/runtime/execution.js +513 -0
  20. package/dist/runtime/execution.js.map +1 -0
  21. package/dist/runtime/host.d.ts +8 -31
  22. package/dist/runtime/host.d.ts.map +1 -1
  23. package/dist/runtime/host.js +52 -296
  24. package/dist/runtime/host.js.map +1 -1
  25. package/dist/runtime/inline.d.ts +63 -0
  26. package/dist/runtime/inline.d.ts.map +1 -0
  27. package/dist/runtime/inline.js +80 -0
  28. package/dist/runtime/inline.js.map +1 -0
  29. package/dist/runtime/prelude-source.d.ts +18 -4
  30. package/dist/runtime/prelude-source.d.ts.map +1 -1
  31. package/dist/runtime/prelude-source.js +202 -21
  32. package/dist/runtime/prelude-source.js.map +1 -1
  33. package/dist/runtime/protocol.d.ts +49 -6
  34. package/dist/runtime/protocol.d.ts.map +1 -1
  35. package/dist/runtime/protocol.js +6 -1
  36. package/dist/runtime/protocol.js.map +1 -1
  37. package/dist/runtime/remote.d.ts +102 -0
  38. package/dist/runtime/remote.d.ts.map +1 -0
  39. package/dist/runtime/remote.js +175 -0
  40. package/dist/runtime/remote.js.map +1 -0
  41. package/dist/runtime/vm.d.ts +24 -0
  42. package/dist/runtime/vm.d.ts.map +1 -0
  43. package/dist/runtime/vm.js +297 -0
  44. package/dist/runtime/vm.js.map +1 -0
  45. package/dist/runtime/worker.js +11 -110
  46. package/dist/runtime/worker.js.map +1 -1
  47. package/dist/source.d.ts +2 -1
  48. package/dist/source.d.ts.map +1 -1
  49. package/dist/source.js +8 -2
  50. package/dist/source.js.map +1 -1
  51. package/dist/types.d.ts +129 -15
  52. package/dist/types.d.ts.map +1 -1
  53. package/dist/types.js.map +1 -1
  54. package/package.json +16 -4
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Runs the VM in another isolate, reached over an RPC boundary such as a Cloudflare Durable Object
3
+ * stub, while tools keep running in the caller.
4
+ *
5
+ * Problem: a VM on the calling thread blocks that thread while the script computes. In a Durable
6
+ * Object that serves an agent session, a CPU-heavy script would stall every other request to the
7
+ * session (including the user's abort) for seconds. Measured on Cloudflare (October 2026), a
8
+ * script that computed for 10 seconds delayed the session's other requests by 10 seconds when it
9
+ * ran in the session object or in a Dynamic Worker, but by about 50 ms when it ran in a Durable
10
+ * Object of a separately deployed Worker.
11
+ *
12
+ * Solution: the caller keeps the host role (`RemoteCodemodeSandbox`: tools, call records,
13
+ * deadline, abort) and the remote side only runs the VM (`serveCodemodeRemote`, behind
14
+ * `CodemodeSandboxDurableObject` in `@draht/codemode/cloudflare`).
15
+ *
16
+ * Protocol, one RPC call per execution:
17
+ *
18
+ * client remote
19
+ * remote.execute(request, exchange) ───────▶ starts the VM (in-thread, with interrupt budget)
20
+ * ◀─────── exchange([...outputs, call]) one call per tool call
21
+ * runs the tool, replies with result ──────▶ VM continues
22
+ * ◀─────── exchange([...outputs, done]) terminal, reply ignored
23
+ * execute() resolves ◀────────────────────── VM disposed
24
+ *
25
+ * `exchange` is a function the client passes in; over Workers RPC it becomes a stub that calls back
26
+ * into the client. Output is buffered on the remote side and sent with the next call or the
27
+ * terminal message, so a script that prints in a loop does not make one RPC per line. Each
28
+ * `exchange` carries at most one call, so concurrent tool calls are concurrent RPCs. Calls on one
29
+ * stub are delivered in order, which keeps output ordered before the call or result that follows.
30
+ *
31
+ * Termination: the client cannot interrupt a remote VM that is computing. When the client finishes
32
+ * first (deadline, abort, `close()`), it answers every pending and later `exchange` with
33
+ * `{ type: "stop" }`, and the remote stops the VM at that point. A script that computes without
34
+ * calling a tool runs until its interrupt budget is used up. The remote reports that as a
35
+ * `failure` message, which the client turns into the same `kind: "timeout"` error an in-thread
36
+ * VM produces.
37
+ *
38
+ * Failure: if the RPC call rejects (the remote isolate crashed, hit its CPU limit, or was
39
+ * redeployed) or returns without a terminal message, the execution fails with `kind: "sandbox"`.
40
+ */
41
+ import type { CodemodeError, CodemodeSandboxBaseOptions } from "../types.ts";
42
+ import type { CodemodeWasmModule } from "../wasm.ts";
43
+ import { CodemodeSandboxBase } from "./execution.ts";
44
+ import { type HostToWorkerMessage, type VmStartData, type WorkerToHostMessage } from "./protocol.ts";
45
+ export interface CodemodeRemoteRequest {
46
+ data: VmStartData;
47
+ /** Requested interrupt budget. The remote may lower it, see {@link CodemodeServeOptions}. */
48
+ interruptBudget?: number;
49
+ }
50
+ /** What the remote sends to the client: VM messages, or a failure outside the VM bridge. */
51
+ export type CodemodeRemoteMessage = WorkerToHostMessage | {
52
+ type: "failure";
53
+ error: CodemodeError;
54
+ };
55
+ /**
56
+ * The client's answer to an exchange: the result of the call the exchange carried, `null` when it
57
+ * carried no call, or `stop` once the client no longer wants the execution.
58
+ */
59
+ export type CodemodeRemoteReply = HostToWorkerMessage | {
60
+ type: "stop";
61
+ } | null;
62
+ export type CodemodeRemoteExchange = (messages: CodemodeRemoteMessage[]) => Promise<CodemodeRemoteReply>;
63
+ /**
64
+ * The remote end, usually a Durable Object stub for `CodemodeSandboxDurableObject`. Anything with
65
+ * this method works, for example an in-process object in tests.
66
+ */
67
+ export interface CodemodeRemote {
68
+ execute(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange): Promise<void>;
69
+ }
70
+ export interface RemoteCodemodeSandboxOptions extends CodemodeSandboxBaseOptions {
71
+ /**
72
+ * Returns the remote that runs one execution, called once per `execute()`. For a Durable Object,
73
+ * pick the instance here, for example `() => env.CODEMODE_SANDBOX.getByName(sessionId)`.
74
+ */
75
+ remote: () => CodemodeRemote;
76
+ /** Interrupt budget requested from the remote. Default: the remote's default. */
77
+ interruptBudget?: number;
78
+ }
79
+ export interface CodemodeServeOptions {
80
+ wasm: CodemodeWasmModule | Promise<CodemodeWasmModule>;
81
+ /** Upper bound for a request's interrupt budget, and the budget when a request names none. */
82
+ maxInterruptBudget?: number;
83
+ /** Upper bound for a request's VM memory, and the limit when a request names none. */
84
+ maxMemoryLimitBytes?: number;
85
+ }
86
+ /**
87
+ * Remote side of {@link RemoteCodemodeSandbox}: runs one execution's VM on this thread and
88
+ * forwards everything it reports through `exchange`. Resolves once the VM has stopped and the
89
+ * terminal message has been delivered, or the client asked to stop. Never rejects.
90
+ */
91
+ export declare function serveCodemodeRemote(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange, options: CodemodeServeOptions): Promise<void>;
92
+ /**
93
+ * Runs each execution's VM on a remote, usually a Cloudflare Durable Object deployed with
94
+ * `CodemodeSandboxDurableObject`, while tools run here. Same API and results as
95
+ * `CodemodeSandbox`, so it can replace it. Differences: a script that computes without calling a
96
+ * tool is limited by the remote's interrupt budget rather than `timeoutMs`, and after a deadline or
97
+ * abort the remote VM keeps computing until it next calls a tool or uses up that budget.
98
+ */
99
+ export declare class RemoteCodemodeSandbox extends CodemodeSandboxBase {
100
+ constructor(options: RemoteCodemodeSandboxOptions);
101
+ }
102
+ //# sourceMappingURL=remote.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/runtime/remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAiD,MAAM,gBAAgB,CAAC;AAEpG,OAAO,EACN,KAAK,mBAAmB,EAExB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAEpG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAEhF,MAAM,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAEzG;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,4BAA6B,SAAQ,0BAA0B;IAC/E;;;OAGG;IACH,MAAM,EAAE,MAAM,cAAc,CAAC;IAC7B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvD,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAyFf;AAqED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC7D,YAAY,OAAO,EAAE,4BAA4B,EAEhD;CACD"}
@@ -0,0 +1,175 @@
1
+ import { CodemodeSandboxBase, errorMessage } from "./execution.js";
2
+ import { DEFAULT_INTERRUPT_BUDGET, inlineLauncher } from "./inline.js";
3
+ import { isWorkerToHostMessage, } from "./protocol.js";
4
+ /** Output buffered on the remote before it is flushed without waiting for a call. */
5
+ const FLUSH_ITEMS = 1_000;
6
+ const FLUSH_CHARS = 1 << 20;
7
+ /**
8
+ * Remote side of {@link RemoteCodemodeSandbox}: runs one execution's VM on this thread and
9
+ * forwards everything it reports through `exchange`. Resolves once the VM has stopped and the
10
+ * terminal message has been delivered, or the client asked to stop. Never rejects.
11
+ */
12
+ export function serveCodemodeRemote(request, exchange, options) {
13
+ const maxBudget = options.maxInterruptBudget ?? DEFAULT_INTERRUPT_BUDGET;
14
+ const budget = Math.min(request.interruptBudget ?? maxBudget, maxBudget);
15
+ const requestedMemory = request.data.memoryLimitBytes;
16
+ const maxMemory = options.maxMemoryLimitBytes;
17
+ const memoryLimitBytes = requestedMemory === undefined
18
+ ? maxMemory
19
+ : maxMemory === undefined
20
+ ? requestedMemory
21
+ : Math.min(requestedMemory, maxMemory);
22
+ const data = { ...request.data, memoryLimitBytes };
23
+ return new Promise((resolve) => {
24
+ let channel;
25
+ let ended = false;
26
+ let buffered = [];
27
+ let bufferedChars = 0;
28
+ /** Replies that arrived before the launcher returned the channel. */
29
+ const unsent = [];
30
+ const takeBuffer = () => {
31
+ const batch = buffered;
32
+ buffered = [];
33
+ bufferedChars = 0;
34
+ return batch;
35
+ };
36
+ const end = (terminal) => {
37
+ if (ended)
38
+ return;
39
+ ended = true;
40
+ const batch = takeBuffer();
41
+ const delivered = terminal ? exchange([...batch, terminal]).catch(() => null) : Promise.resolve();
42
+ void delivered
43
+ .then(() => channel?.stop())
44
+ .catch(() => undefined)
45
+ .then(() => resolve());
46
+ };
47
+ const reply = (message) => {
48
+ if (ended || message === null)
49
+ return;
50
+ if (message.type === "stop") {
51
+ end(undefined);
52
+ return;
53
+ }
54
+ if (channel)
55
+ channel.post(message);
56
+ else
57
+ unsent.push(message);
58
+ };
59
+ const onMessage = (message) => {
60
+ if (ended)
61
+ return;
62
+ const typed = message;
63
+ switch (typed.type) {
64
+ case "output": {
65
+ buffered.push(typed);
66
+ bufferedChars += typed.item.type === "text" ? typed.item.text.length : typed.item.data.length;
67
+ if (buffered.length >= FLUSH_ITEMS || bufferedChars >= FLUSH_CHARS) {
68
+ exchange(takeBuffer()).then(reply, () => end(undefined));
69
+ }
70
+ break;
71
+ }
72
+ case "started":
73
+ buffered.push(typed);
74
+ break;
75
+ // Sent at once: a host replaying a script waits for it to see that the script issued no further call.
76
+ case "call":
77
+ case "idle":
78
+ exchange([...takeBuffer(), typed]).then(reply, () => end(undefined));
79
+ break;
80
+ default:
81
+ end(typed);
82
+ }
83
+ };
84
+ const launch = inlineLauncher(options.wasm, budget);
85
+ Promise.resolve(launch(data, {
86
+ message: onMessage,
87
+ failure: (error) => end({ type: "failure", error }),
88
+ })).then((started) => {
89
+ channel = started;
90
+ if (ended) {
91
+ void started.stop().catch(() => undefined);
92
+ return;
93
+ }
94
+ for (const message of unsent.splice(0))
95
+ started.post(message);
96
+ }, (error) => end({ type: "failure", error: { kind: "sandbox", message: errorMessage(error) } }));
97
+ });
98
+ }
99
+ function remoteLauncher(remote, interruptBudget) {
100
+ return (data, events) => {
101
+ let stopped = false;
102
+ let settled = false;
103
+ const waiting = new Map();
104
+ const exchange = (messages) => new Promise((resolve) => {
105
+ if (stopped || !Array.isArray(messages)) {
106
+ resolve({ type: "stop" });
107
+ return;
108
+ }
109
+ // Register the waiter first: the host may answer a call synchronously, for example when the
110
+ // tool throws before returning a promise.
111
+ const call = messages.find((message) => isWorkerToHostMessage(message) && message.type === "call");
112
+ if (call?.type === "call")
113
+ waiting.set(call.id, resolve);
114
+ else
115
+ resolve(null);
116
+ for (const message of messages) {
117
+ if (typeof message === "object" && message !== null && message.type === "failure") {
118
+ settled = true;
119
+ events.failure(message.error);
120
+ continue;
121
+ }
122
+ // Malformed messages still go to the host, which fails the execution as a broken bridge.
123
+ events.message(message);
124
+ if (isWorkerToHostMessage(message) && (message.type === "done" || message.type === "crash"))
125
+ settled = true;
126
+ }
127
+ });
128
+ let target;
129
+ try {
130
+ target = remote();
131
+ }
132
+ catch (error) {
133
+ throw new Error(`Failed to reach the remote sandbox: ${errorMessage(error)}`);
134
+ }
135
+ const request = interruptBudget === undefined ? { data } : { data, interruptBudget };
136
+ Promise.resolve()
137
+ .then(() => target.execute(request, exchange))
138
+ .then(() => {
139
+ if (!settled && !stopped) {
140
+ events.failure({ kind: "sandbox", message: "Remote sandbox returned before the script settled" });
141
+ }
142
+ }, (error) => {
143
+ if (!stopped)
144
+ events.failure({ kind: "sandbox", message: `Remote sandbox failed: ${errorMessage(error)}` });
145
+ });
146
+ return {
147
+ post: (message) => {
148
+ const resolve = waiting.get(message.id);
149
+ if (!resolve)
150
+ return;
151
+ waiting.delete(message.id);
152
+ resolve(message);
153
+ },
154
+ stop: async () => {
155
+ stopped = true;
156
+ for (const resolve of waiting.values())
157
+ resolve({ type: "stop" });
158
+ waiting.clear();
159
+ },
160
+ };
161
+ };
162
+ }
163
+ /**
164
+ * Runs each execution's VM on a remote, usually a Cloudflare Durable Object deployed with
165
+ * `CodemodeSandboxDurableObject`, while tools run here. Same API and results as
166
+ * `CodemodeSandbox`, so it can replace it. Differences: a script that computes without calling a
167
+ * tool is limited by the remote's interrupt budget rather than `timeoutMs`, and after a deadline or
168
+ * abort the remote VM keeps computing until it next calls a tool or uses up that budget.
169
+ */
170
+ export class RemoteCodemodeSandbox extends CodemodeSandboxBase {
171
+ constructor(options) {
172
+ super(options, remoteLauncher(options.remote, options.interruptBudget));
173
+ }
174
+ }
175
+ //# sourceMappingURL=remote.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/runtime/remote.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runs the VM in another isolate, reached over an RPC boundary such as a Cloudflare Durable Object\n * stub, while tools keep running in the caller.\n *\n * Problem: a VM on the calling thread blocks that thread while the script computes. In a Durable\n * Object that serves an agent session, a CPU-heavy script would stall every other request to the\n * session (including the user's abort) for seconds. Measured on Cloudflare (October 2026), a\n * script that computed for 10 seconds delayed the session's other requests by 10 seconds when it\n * ran in the session object or in a Dynamic Worker, but by about 50 ms when it ran in a Durable\n * Object of a separately deployed Worker.\n *\n * Solution: the caller keeps the host role (`RemoteCodemodeSandbox`: tools, call records,\n * deadline, abort) and the remote side only runs the VM (`serveCodemodeRemote`, behind\n * `CodemodeSandboxDurableObject` in `@draht/codemode/cloudflare`).\n *\n * Protocol, one RPC call per execution:\n *\n * client remote\n * remote.execute(request, exchange) ───────▶ starts the VM (in-thread, with interrupt budget)\n * ◀─────── exchange([...outputs, call]) one call per tool call\n * runs the tool, replies with result ──────▶ VM continues\n * ◀─────── exchange([...outputs, done]) terminal, reply ignored\n * execute() resolves ◀────────────────────── VM disposed\n *\n * `exchange` is a function the client passes in; over Workers RPC it becomes a stub that calls back\n * into the client. Output is buffered on the remote side and sent with the next call or the\n * terminal message, so a script that prints in a loop does not make one RPC per line. Each\n * `exchange` carries at most one call, so concurrent tool calls are concurrent RPCs. Calls on one\n * stub are delivered in order, which keeps output ordered before the call or result that follows.\n *\n * Termination: the client cannot interrupt a remote VM that is computing. When the client finishes\n * first (deadline, abort, `close()`), it answers every pending and later `exchange` with\n * `{ type: \"stop\" }`, and the remote stops the VM at that point. A script that computes without\n * calling a tool runs until its interrupt budget is used up. The remote reports that as a\n * `failure` message, which the client turns into the same `kind: \"timeout\"` error an in-thread\n * VM produces.\n *\n * Failure: if the RPC call rejects (the remote isolate crashed, hit its CPU limit, or was\n * redeployed) or returns without a terminal message, the execution fails with `kind: \"sandbox\"`.\n */\nimport type { CodemodeError, CodemodeSandboxBaseOptions } from \"../types.ts\";\nimport type { CodemodeWasmModule } from \"../wasm.ts\";\nimport { CodemodeSandboxBase, errorMessage, type VmChannel, type VmLauncher } from \"./execution.ts\";\nimport { DEFAULT_INTERRUPT_BUDGET, inlineLauncher } from \"./inline.ts\";\nimport {\n\ttype HostToWorkerMessage,\n\tisWorkerToHostMessage,\n\ttype VmStartData,\n\ttype WorkerToHostMessage,\n} from \"./protocol.ts\";\n\nexport interface CodemodeRemoteRequest {\n\tdata: VmStartData;\n\t/** Requested interrupt budget. The remote may lower it, see {@link CodemodeServeOptions}. */\n\tinterruptBudget?: number;\n}\n\n/** What the remote sends to the client: VM messages, or a failure outside the VM bridge. */\nexport type CodemodeRemoteMessage = WorkerToHostMessage | { type: \"failure\"; error: CodemodeError };\n\n/**\n * The client's answer to an exchange: the result of the call the exchange carried, `null` when it\n * carried no call, or `stop` once the client no longer wants the execution.\n */\nexport type CodemodeRemoteReply = HostToWorkerMessage | { type: \"stop\" } | null;\n\nexport type CodemodeRemoteExchange = (messages: CodemodeRemoteMessage[]) => Promise<CodemodeRemoteReply>;\n\n/**\n * The remote end, usually a Durable Object stub for `CodemodeSandboxDurableObject`. Anything with\n * this method works, for example an in-process object in tests.\n */\nexport interface CodemodeRemote {\n\texecute(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange): Promise<void>;\n}\n\nexport interface RemoteCodemodeSandboxOptions extends CodemodeSandboxBaseOptions {\n\t/**\n\t * Returns the remote that runs one execution, called once per `execute()`. For a Durable Object,\n\t * pick the instance here, for example `() => env.CODEMODE_SANDBOX.getByName(sessionId)`.\n\t */\n\tremote: () => CodemodeRemote;\n\t/** Interrupt budget requested from the remote. Default: the remote's default. */\n\tinterruptBudget?: number;\n}\n\n/** Output buffered on the remote before it is flushed without waiting for a call. */\nconst FLUSH_ITEMS = 1_000;\nconst FLUSH_CHARS = 1 << 20;\n\nexport interface CodemodeServeOptions {\n\twasm: CodemodeWasmModule | Promise<CodemodeWasmModule>;\n\t/** Upper bound for a request's interrupt budget, and the budget when a request names none. */\n\tmaxInterruptBudget?: number;\n\t/** Upper bound for a request's VM memory, and the limit when a request names none. */\n\tmaxMemoryLimitBytes?: number;\n}\n\n/**\n * Remote side of {@link RemoteCodemodeSandbox}: runs one execution's VM on this thread and\n * forwards everything it reports through `exchange`. Resolves once the VM has stopped and the\n * terminal message has been delivered, or the client asked to stop. Never rejects.\n */\nexport function serveCodemodeRemote(\n\trequest: CodemodeRemoteRequest,\n\texchange: CodemodeRemoteExchange,\n\toptions: CodemodeServeOptions,\n): Promise<void> {\n\tconst maxBudget = options.maxInterruptBudget ?? DEFAULT_INTERRUPT_BUDGET;\n\tconst budget = Math.min(request.interruptBudget ?? maxBudget, maxBudget);\n\tconst requestedMemory = request.data.memoryLimitBytes;\n\tconst maxMemory = options.maxMemoryLimitBytes;\n\tconst memoryLimitBytes =\n\t\trequestedMemory === undefined\n\t\t\t? maxMemory\n\t\t\t: maxMemory === undefined\n\t\t\t\t? requestedMemory\n\t\t\t\t: Math.min(requestedMemory, maxMemory);\n\tconst data: VmStartData = { ...request.data, memoryLimitBytes };\n\n\treturn new Promise<void>((resolve) => {\n\t\tlet channel: VmChannel | undefined;\n\t\tlet ended = false;\n\t\tlet buffered: CodemodeRemoteMessage[] = [];\n\t\tlet bufferedChars = 0;\n\t\t/** Replies that arrived before the launcher returned the channel. */\n\t\tconst unsent: HostToWorkerMessage[] = [];\n\n\t\tconst takeBuffer = (): CodemodeRemoteMessage[] => {\n\t\t\tconst batch = buffered;\n\t\t\tbuffered = [];\n\t\t\tbufferedChars = 0;\n\t\t\treturn batch;\n\t\t};\n\t\tconst end = (terminal: CodemodeRemoteMessage | undefined): void => {\n\t\t\tif (ended) return;\n\t\t\tended = true;\n\t\t\tconst batch = takeBuffer();\n\t\t\tconst delivered = terminal ? exchange([...batch, terminal]).catch(() => null) : Promise.resolve();\n\t\t\tvoid delivered\n\t\t\t\t.then(() => channel?.stop())\n\t\t\t\t.catch(() => undefined)\n\t\t\t\t.then(() => resolve());\n\t\t};\n\t\tconst reply = (message: CodemodeRemoteReply): void => {\n\t\t\tif (ended || message === null) return;\n\t\t\tif (message.type === \"stop\") {\n\t\t\t\tend(undefined);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (channel) channel.post(message);\n\t\t\telse unsent.push(message);\n\t\t};\n\t\tconst onMessage = (message: unknown): void => {\n\t\t\tif (ended) return;\n\t\t\tconst typed = message as WorkerToHostMessage;\n\t\t\tswitch (typed.type) {\n\t\t\t\tcase \"output\": {\n\t\t\t\t\tbuffered.push(typed);\n\t\t\t\t\tbufferedChars += typed.item.type === \"text\" ? typed.item.text.length : typed.item.data.length;\n\t\t\t\t\tif (buffered.length >= FLUSH_ITEMS || bufferedChars >= FLUSH_CHARS) {\n\t\t\t\t\t\texchange(takeBuffer()).then(reply, () => end(undefined));\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase \"started\":\n\t\t\t\t\tbuffered.push(typed);\n\t\t\t\t\tbreak;\n\t\t\t\t// Sent at once: a host replaying a script waits for it to see that the script issued no further call.\n\t\t\t\tcase \"call\":\n\t\t\t\tcase \"idle\":\n\t\t\t\t\texchange([...takeBuffer(), typed]).then(reply, () => end(undefined));\n\t\t\t\t\tbreak;\n\t\t\t\tdefault:\n\t\t\t\t\tend(typed);\n\t\t\t}\n\t\t};\n\n\t\tconst launch = inlineLauncher(options.wasm, budget);\n\t\tPromise.resolve(\n\t\t\tlaunch(data, {\n\t\t\t\tmessage: onMessage,\n\t\t\t\tfailure: (error) => end({ type: \"failure\", error }),\n\t\t\t}),\n\t\t).then(\n\t\t\t(started) => {\n\t\t\t\tchannel = started;\n\t\t\t\tif (ended) {\n\t\t\t\t\tvoid started.stop().catch(() => undefined);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tfor (const message of unsent.splice(0)) started.post(message);\n\t\t\t},\n\t\t\t(error: unknown) => end({ type: \"failure\", error: { kind: \"sandbox\", message: errorMessage(error) } }),\n\t\t);\n\t});\n}\n\nfunction remoteLauncher(remote: () => CodemodeRemote, interruptBudget: number | undefined): VmLauncher {\n\treturn (data, events) => {\n\t\tlet stopped = false;\n\t\tlet settled = false;\n\t\tconst waiting = new Map<number, (reply: CodemodeRemoteReply) => void>();\n\n\t\tconst exchange: CodemodeRemoteExchange = (messages) =>\n\t\t\tnew Promise<CodemodeRemoteReply>((resolve) => {\n\t\t\t\tif (stopped || !Array.isArray(messages)) {\n\t\t\t\t\tresolve({ type: \"stop\" });\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// Register the waiter first: the host may answer a call synchronously, for example when the\n\t\t\t\t// tool throws before returning a promise.\n\t\t\t\tconst call = messages.find((message) => isWorkerToHostMessage(message) && message.type === \"call\");\n\t\t\t\tif (call?.type === \"call\") waiting.set(call.id, resolve);\n\t\t\t\telse resolve(null);\n\t\t\t\tfor (const message of messages) {\n\t\t\t\t\tif (typeof message === \"object\" && message !== null && message.type === \"failure\") {\n\t\t\t\t\t\tsettled = true;\n\t\t\t\t\t\tevents.failure(message.error);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\t// Malformed messages still go to the host, which fails the execution as a broken bridge.\n\t\t\t\t\tevents.message(message);\n\t\t\t\t\tif (isWorkerToHostMessage(message) && (message.type === \"done\" || message.type === \"crash\"))\n\t\t\t\t\t\tsettled = true;\n\t\t\t\t}\n\t\t\t});\n\n\t\tlet target: CodemodeRemote;\n\t\ttry {\n\t\t\ttarget = remote();\n\t\t} catch (error) {\n\t\t\tthrow new Error(`Failed to reach the remote sandbox: ${errorMessage(error)}`);\n\t\t}\n\t\tconst request: CodemodeRemoteRequest = interruptBudget === undefined ? { data } : { data, interruptBudget };\n\t\tPromise.resolve()\n\t\t\t.then(() => target.execute(request, exchange))\n\t\t\t.then(\n\t\t\t\t() => {\n\t\t\t\t\tif (!settled && !stopped) {\n\t\t\t\t\t\tevents.failure({ kind: \"sandbox\", message: \"Remote sandbox returned before the script settled\" });\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t(error: unknown) => {\n\t\t\t\t\tif (!stopped)\n\t\t\t\t\t\tevents.failure({ kind: \"sandbox\", message: `Remote sandbox failed: ${errorMessage(error)}` });\n\t\t\t\t},\n\t\t\t);\n\n\t\treturn {\n\t\t\tpost: (message) => {\n\t\t\t\tconst resolve = waiting.get(message.id);\n\t\t\t\tif (!resolve) return;\n\t\t\t\twaiting.delete(message.id);\n\t\t\t\tresolve(message);\n\t\t\t},\n\t\t\tstop: async () => {\n\t\t\t\tstopped = true;\n\t\t\t\tfor (const resolve of waiting.values()) resolve({ type: \"stop\" });\n\t\t\t\twaiting.clear();\n\t\t\t},\n\t\t};\n\t};\n}\n\n/**\n * Runs each execution's VM on a remote, usually a Cloudflare Durable Object deployed with\n * `CodemodeSandboxDurableObject`, while tools run here. Same API and results as\n * `CodemodeSandbox`, so it can replace it. Differences: a script that computes without calling a\n * tool is limited by the remote's interrupt budget rather than `timeoutMs`, and after a deadline or\n * abort the remote VM keeps computing until it next calls a tool or uses up that budget.\n */\nexport class RemoteCodemodeSandbox extends CodemodeSandboxBase {\n\tconstructor(options: RemoteCodemodeSandboxOptions) {\n\t\tsuper(options, remoteLauncher(options.remote, options.interruptBudget));\n\t}\n}\n"]}
@@ -0,0 +1,24 @@
1
+ import type { CodemodeWasmModule } from "../wasm.ts";
2
+ import type { HostToWorkerMessage, VmStartData, WorkerToHostMessage } from "./protocol.ts";
3
+ export interface VmSession {
4
+ deliver(message: HostToWorkerMessage): void;
5
+ /** Releases the VM's wasm instance. The session must not be used afterwards. */
6
+ dispose(): void;
7
+ }
8
+ export interface StartVmOptions {
9
+ data: VmStartData;
10
+ wasm: CodemodeWasmModule;
11
+ /**
12
+ * QuickJS's guard on its own stack, which turns deep recursion into a catchable `RangeError`.
13
+ * The wasm frames also use the host thread's native stack, so the guard must trip before that
14
+ * stack runs out: a host overflow fails the whole execution instead. Default: `MAX_STACK_SIZE`
15
+ * (512 KiB), which fits the 4 MB stack of a Node worker thread but not a 1 MB main thread.
16
+ */
17
+ maxStackSize?: number;
18
+ /** Interrupt polls this VM may use, if the launcher counts them; part of the fingerprint. */
19
+ interruptBudget?: number;
20
+ post(message: WorkerToHostMessage): void;
21
+ shouldInterrupt(): boolean;
22
+ }
23
+ export declare function startVm(options: StartVmOptions): Promise<VmSession>;
24
+ //# sourceMappingURL=vm.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vm.d.ts","sourceRoot":"","sources":["../../src/runtime/vm.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE3F,MAAM,WAAW,SAAS;IACzB,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC5C,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,eAAe,IAAI,OAAO,CAAC;CAC3B;AAiGD,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CA0LzE"}
@@ -0,0 +1,297 @@
1
+ /**
2
+ * Drives one QuickJS VM through one script, independent of the transport that connects it to the
3
+ * host. The worker thread, the in-thread launcher, and the remote server all run the VM through
4
+ * this module, so the bridge between prelude and host exists once.
5
+ *
6
+ * Contract with the caller:
7
+ * - `post` receives every message for the host, synchronously from inside VM callbacks. The
8
+ * caller must not re-enter the VM from `post` (no `deliver`, no `dispose`); a worker posts to
9
+ * another thread, and the in-thread launcher defers delivery to a microtask.
10
+ * - `deliver` hands the VM a tool result and runs the script until it waits again. It must only be
11
+ * called while the VM is idle, which holds for any caller that never re-enters from `post`.
12
+ * - `shouldInterrupt` is polled by QuickJS while the script runs, and here between batches of
13
+ * promise jobs. Returning true throws an uncatchable error in the script; the VM then reports
14
+ * `crash` or a failed `done`. The job batches matter for a script such as `while (true) await
15
+ * null`: every iteration is a separate job that executes only a few opcodes, so QuickJS's own
16
+ * polling, which counts opcodes, would let it run for a long time between polls.
17
+ * - The VM never decides on its own when it is finished: after `done` or `crash` it stays alive
18
+ * until the caller disposes it (or terminates the worker that hosts it).
19
+ *
20
+ * Failures after the VM exists are reported as a `crash` message; `startVm` only rejects when the
21
+ * VM cannot be created at all.
22
+ *
23
+ * Deterministic mode (`data.deterministic`, used by `CodemodeSandboxBase.start()`): a script must make the same
24
+ * calls with the same arguments every time it runs with the same results, so a host can replay it after a restart.
25
+ * The VM is otherwise deterministic, because it only runs when the host delivers something and has no timers.
26
+ * What remains is fixed here:
27
+ * - Time: every WASI clock reads virtual time, `startedAt` and then the `now` of the result being processed, never going backwards.
28
+ * While the context is created, the realtime clock reads a value derived from the seed instead, because QuickJS
29
+ * seeds `Math.random()` from the first clock read, and which read comes first is the engine's business.
30
+ * - Randomness: `random_get` draws from a PRNG over the seed.
31
+ * - Timezone: UTC, not the host's.
32
+ * - Garbage collection: `WeakRef` and `FinalizationRegistry` are not available; collection timing is not.
33
+ * - Delivery order: results carry a `seq` and are applied strictly in that order, buffering early ones, because a
34
+ * transport (RPC replies) may deliver them in another order than the host sent them.
35
+ * The VM reports `started` with its fingerprint before the script runs, and `idle` with the number of calls issued
36
+ * after each drain, so the host can check a replay step by step.
37
+ */
38
+ import { Intrinsics, JSException, MAX_STACK_SIZE, QuickJS } from "quickjs-wasi";
39
+ import { PRELUDE_SOURCE } from "./prelude-source.js";
40
+ /**
41
+ * Bumped whenever this module or the prelude changes what a deterministic script observes, beyond what the
42
+ * fingerprint's other parts (engine versions, prelude hash, limits) already capture.
43
+ */
44
+ const DETERMINISTIC_VERSION = 1;
45
+ /** FNV-1a over UTF-16 code units, as 8 hex digits: identifies the prelude in the fingerprint. */
46
+ function fnv1a(text) {
47
+ let hash = 0x811c9dc5;
48
+ for (let index = 0; index < text.length; index++) {
49
+ hash ^= text.charCodeAt(index);
50
+ hash = Math.imul(hash, 0x01000193);
51
+ }
52
+ return (hash >>> 0).toString(16).padStart(8, "0");
53
+ }
54
+ const PRELUDE_HASH = fnv1a(PRELUDE_SOURCE);
55
+ /** mulberry32: a small, fast PRNG; one 32-bit draw per call. */
56
+ function prng(seed) {
57
+ let state = seed >>> 0;
58
+ return () => {
59
+ state = (state + 0x6d2b79f5) >>> 0;
60
+ let value = Math.imul(state ^ (state >>> 15), 1 | state);
61
+ value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
62
+ return (value ^ (value >>> 14)) >>> 0;
63
+ };
64
+ }
65
+ /** WASI clock and random functions for deterministic mode, on top of {@link discardOutput}. */
66
+ function deterministicWasi(clock) {
67
+ const random = prng(clock.seed ^ 0x9e3779b9);
68
+ return (memory) => ({
69
+ ...discardOutput(memory),
70
+ clock_time_get(clockId, _precision, resultPtr) {
71
+ let nanoseconds;
72
+ // QuickJS seeds Math.random() from this reading in microseconds and turns 0 into 1, so seed s reads s + 1.
73
+ if (clock.creating)
74
+ nanoseconds = clockId === 0 ? BigInt(clock.seed + 1) * 1000n : 0n;
75
+ else if (clockId === 0)
76
+ nanoseconds = BigInt(Math.round(clock.now)) * 1000000n;
77
+ else
78
+ nanoseconds = BigInt(Math.round(clock.now - clock.startedAt)) * 1000000n;
79
+ new DataView(memory.buffer).setBigUint64(resultPtr, nanoseconds, true);
80
+ return 0;
81
+ },
82
+ random_get(bufPtr, bufLen) {
83
+ const bytes = new Uint8Array(memory.buffer, bufPtr, bufLen);
84
+ for (let index = 0; index < bufLen; index += 4) {
85
+ const value = random();
86
+ for (let byte = 0; byte < 4 && index + byte < bufLen; byte++)
87
+ bytes[index + byte] = value >>> (byte * 8);
88
+ }
89
+ return 0;
90
+ },
91
+ });
92
+ }
93
+ /**
94
+ * QuickJS writes engine diagnostics to fd 1 and 2, which the default shim
95
+ * forwards to the host's stdout and stderr. That output belongs to the host
96
+ * application (for example a TUI), so it is discarded. Reporting every byte as
97
+ * written keeps libc from retrying.
98
+ */
99
+ function discardOutput(memory) {
100
+ return {
101
+ fd_write(_fd, iovsPtr, iovsLen, nwrittenPtr) {
102
+ const view = new DataView(memory.buffer);
103
+ let written = 0;
104
+ for (let i = 0; i < iovsLen; i++) {
105
+ written += view.getUint32(iovsPtr + i * 8 + 4, true);
106
+ }
107
+ view.setUint32(nwrittenPtr, written, true);
108
+ return 0;
109
+ },
110
+ };
111
+ }
112
+ function describeException(error) {
113
+ const head = error.message ? `${error.name}: ${error.message}` : error.name;
114
+ const stack = error.stack?.trimEnd();
115
+ return JSON.stringify({ name: error.name, message: error.message, stack: stack ? `${head}\n${stack}` : head });
116
+ }
117
+ /** Promise jobs run between two `shouldInterrupt` polls while draining the job queue. */
118
+ const JOBS_PER_POLL = 50;
119
+ function crashMessage(error) {
120
+ return { type: "crash", message: error instanceof Error ? `${error.name}: ${error.message}` : String(error) };
121
+ }
122
+ export async function startVm(options) {
123
+ const { data, post } = options;
124
+ const maxStackSize = options.maxStackSize ?? MAX_STACK_SIZE;
125
+ const deterministic = data.deterministic;
126
+ const clock = deterministic && {
127
+ creating: true,
128
+ startedAt: deterministic.startedAt,
129
+ now: deterministic.startedAt,
130
+ seed: deterministic.seed >>> 0,
131
+ };
132
+ const vm = await QuickJS.create({
133
+ wasm: options.wasm,
134
+ memoryLimit: data.memoryLimitBytes,
135
+ // Without a guard, deep recursion overflows the wasm stack and traps instead of throwing a
136
+ // catchable RangeError.
137
+ maxStackSize,
138
+ interruptHandler: options.shouldInterrupt,
139
+ wasi: clock ? deterministicWasi(clock) : discardOutput,
140
+ ...(clock ? { timezoneOffset: 0, intrinsics: Intrinsics.ALL & ~Intrinsics.WEAK_REF } : {}),
141
+ });
142
+ if (clock)
143
+ clock.creating = false;
144
+ let disposed = false;
145
+ /** Calls the script has issued, tools and globals; reported with every `idle`. */
146
+ let issued = 0;
147
+ /** Deterministic mode: the next result to apply, and results that arrived before it. */
148
+ let nextSeq = 1;
149
+ /** The result being processed, 0 during the script's first run; reported with `done`. */
150
+ let current = 0;
151
+ const early = new Map();
152
+ const apply = (message) => {
153
+ vm.withScope(() => {
154
+ vm.callFunction(settle, api, vm.newNumber(message.id), message.ok ? vm.true : vm.false, message.payload === undefined ? vm.undefined : vm.newString(message.payload), message.properties === undefined ? vm.undefined : vm.newString(message.properties));
155
+ });
156
+ drain();
157
+ };
158
+ const session = {
159
+ deliver(message) {
160
+ if (disposed)
161
+ return;
162
+ try {
163
+ if (!clock) {
164
+ apply(message);
165
+ return;
166
+ }
167
+ const { seq } = message;
168
+ if (seq === undefined || !Number.isInteger(seq) || seq < nextSeq || early.has(seq)) {
169
+ throw new Error(`Result ${message.id} has sequence number ${seq}, expected ${nextSeq} or later, once`);
170
+ }
171
+ early.set(seq, message);
172
+ for (let next = early.get(nextSeq); next !== undefined; next = early.get(nextSeq)) {
173
+ early.delete(nextSeq);
174
+ // Never backwards: a resumed host's clock may be behind the one that started the run.
175
+ if (next.now !== undefined && Number.isFinite(next.now))
176
+ clock.now = Math.max(clock.now, next.now);
177
+ current = nextSeq;
178
+ apply(next);
179
+ post({ type: "idle", seq: nextSeq, issued });
180
+ nextSeq++;
181
+ }
182
+ }
183
+ catch (error) {
184
+ post(crashMessage(error));
185
+ }
186
+ },
187
+ dispose() {
188
+ if (disposed)
189
+ return;
190
+ disposed = true;
191
+ vm.dispose();
192
+ },
193
+ };
194
+ let api;
195
+ let settle;
196
+ let stalled;
197
+ // `executePendingJobs()` runs the queue to empty without a chance to interrupt, so jobs run one at a
198
+ // time through the (internal, but public) exports; quickjs-wasi is pinned to an exact version.
199
+ const exports = vm._getExports();
200
+ /** Run queued jobs, then fail a script that waits on nothing that can ever resume it. */
201
+ const drain = () => {
202
+ let jobs = 0;
203
+ while (exports.qjs_is_job_pending()) {
204
+ // A job only fails for uncatchable errors, such as an interrupt.
205
+ if (exports.qjs_execute_pending_job() < 0)
206
+ throw new Error("Promise job failed");
207
+ if (++jobs % JOBS_PER_POLL === 0 && options.shouldInterrupt())
208
+ throw new Error("Execution interrupted");
209
+ }
210
+ vm.callFunction(stalled, api).dispose();
211
+ };
212
+ try {
213
+ // Called from the prelude with primitives only.
214
+ const bridge = vm.newFunction("bridge", (kind, a, b, c) => {
215
+ switch (kind.toString()) {
216
+ case "call":
217
+ case "global":
218
+ issued++;
219
+ post({
220
+ type: "call",
221
+ id: a.toNumber(),
222
+ target: kind.toString() === "call" ? "tool" : "global",
223
+ name: b.toString(),
224
+ args: c === undefined || c.isUndefined ? undefined : c.toString(),
225
+ });
226
+ break;
227
+ case "output":
228
+ post({
229
+ type: "output",
230
+ item: a.toString() === "image"
231
+ ? { type: "image", data: b.toString(), mimeType: c.toString() }
232
+ : a.toString() === "console"
233
+ ? { type: "text", text: b.toString(), console: true }
234
+ : { type: "text", text: b.toString() },
235
+ });
236
+ break;
237
+ case "done": {
238
+ // The host stops the VM on `done`, so the `idle` of this drain never arrives: report its numbers here.
239
+ const during = clock ? { during: { seq: current, issued } } : {};
240
+ if (a.toBoolean()) {
241
+ post({
242
+ type: "done",
243
+ ok: true,
244
+ value: b === undefined || b.isUndefined ? undefined : b.toString(),
245
+ writes: c.toString(),
246
+ ...during,
247
+ });
248
+ }
249
+ else {
250
+ post({ type: "done", ok: false, error: b.toString(), ...during });
251
+ }
252
+ break;
253
+ }
254
+ }
255
+ return vm.undefined;
256
+ });
257
+ // These handles live as long as the VM, which the caller disposes as a whole.
258
+ api = vm.withScope((scope) => scope.escape(vm.callFunction(vm.evalCode(PRELUDE_SOURCE, "codemode-prelude.js"), vm.undefined, bridge, vm.newString(JSON.stringify(data.tools)), vm.newString(JSON.stringify(data.globals)), vm.newString(JSON.stringify(data.store)), vm.newString(data.preLockdownSource ?? ""))));
259
+ settle = api.getProp("settle");
260
+ const run = api.getProp("run");
261
+ stalled = api.getProp("stalled");
262
+ if (clock) {
263
+ const versions = vm.versions;
264
+ const budget = options.interruptBudget ?? "none";
265
+ // Trusted host replacements change script behavior and must invalidate a replay too.
266
+ const preludeHash = data.preLockdownSource
267
+ ? fnv1a(`${PRELUDE_SOURCE}\n${data.preLockdownSource}`)
268
+ : PRELUDE_HASH;
269
+ post({
270
+ type: "started",
271
+ fingerprint: `quickjs-wasi ${versions["quickjs-wasi"]}, quickjs ${versions.quickjs}, prelude ${preludeHash}, deterministic ${DETERMINISTIC_VERSION}, stack ${maxStackSize}, heap ${data.memoryLimitBytes ?? "none"}, budget ${budget}`,
272
+ });
273
+ }
274
+ // The prefix shares the first line with the script so reported line numbers
275
+ // match the script as written.
276
+ let fn;
277
+ try {
278
+ fn = vm.evalCode(`(async (tools, console) => {${data.code}\n})`, "codemode.js");
279
+ }
280
+ catch (error) {
281
+ if (!(error instanceof JSException))
282
+ throw error;
283
+ post({ type: "done", ok: false, error: describeException(error) });
284
+ return session;
285
+ }
286
+ vm.callFunction(run, api, fn).dispose();
287
+ fn.dispose();
288
+ drain();
289
+ if (clock)
290
+ post({ type: "idle", seq: 0, issued });
291
+ }
292
+ catch (error) {
293
+ post(crashMessage(error));
294
+ }
295
+ return session;
296
+ }
297
+ //# sourceMappingURL=vm.js.map