@opencode/codemode 2.2.4 → 2.2.6

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 (133) hide show
  1. package/README.md +70 -1
  2. package/dist/codemode.d.ts +55 -4
  3. package/dist/codemode.js +63 -8
  4. package/dist/extension.d.ts +14 -9
  5. package/dist/extension.js +2 -2
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/interpreter/execute.d.ts +1 -1
  9. package/dist/interpreter/execute.js +16 -4
  10. package/dist/interpreter/extensions.d.ts +3 -3
  11. package/dist/interpreter/extensions.js +17 -11
  12. package/dist/interpreter/globals.js +10 -0
  13. package/dist/interpreter/interpreter.d.ts +11 -1
  14. package/dist/interpreter/interpreter.js +86 -2
  15. package/dist/interpreter/modules.d.ts +4 -0
  16. package/dist/interpreter/modules.js +33 -0
  17. package/dist/suspend-error.d.ts +23 -0
  18. package/dist/suspend-error.js +25 -0
  19. package/dist/tool-runtime.d.ts +4 -1
  20. package/dist/vm/async.d.ts +78 -0
  21. package/dist/vm/async.js +335 -0
  22. package/dist/vm/code.d.ts +122 -0
  23. package/dist/vm/code.js +407 -0
  24. package/dist/vm/compiler/compile.d.ts +13 -0
  25. package/dist/vm/compiler/compile.js +1477 -0
  26. package/dist/vm/compiler/scope.d.ts +74 -0
  27. package/dist/vm/compiler/scope.js +515 -0
  28. package/dist/vm/data.d.ts +7 -0
  29. package/dist/vm/data.js +13 -0
  30. package/dist/vm/generators.d.ts +42 -0
  31. package/dist/vm/generators.js +413 -0
  32. package/dist/vm/host.d.ts +103 -0
  33. package/dist/vm/host.js +226 -0
  34. package/dist/vm/index.d.ts +6 -0
  35. package/dist/vm/index.js +6 -0
  36. package/dist/vm/internal-prelude.d.ts +45 -0
  37. package/dist/vm/internal-prelude.js +534 -0
  38. package/dist/vm/opcodes.d.ts +222 -0
  39. package/dist/vm/opcodes.js +235 -0
  40. package/dist/vm/prelude/bytecode.d.ts +18 -0
  41. package/dist/vm/prelude/bytecode.js +31 -0
  42. package/dist/vm/prelude/bytecode.json +1 -0
  43. package/dist/vm/prelude/helpers.d.ts +8 -0
  44. package/dist/vm/prelude/helpers.js +258 -0
  45. package/dist/vm/prelude/prelude.d.ts +21 -0
  46. package/dist/vm/prelude/prelude.js +53 -0
  47. package/dist/vm/prelude/source.d.ts +1 -0
  48. package/dist/vm/prelude/source.js +652 -0
  49. package/dist/vm/runtime/callback.d.ts +25 -0
  50. package/dist/vm/runtime/callback.js +51 -0
  51. package/dist/vm/runtime/driver.d.ts +58 -0
  52. package/dist/vm/runtime/driver.js +184 -0
  53. package/dist/vm/runtime/errors.d.ts +23 -0
  54. package/dist/vm/runtime/errors.js +169 -0
  55. package/dist/vm/runtime/execute.d.ts +80 -0
  56. package/dist/vm/runtime/execute.js +414 -0
  57. package/dist/vm/runtime/extensions.d.ts +16 -0
  58. package/dist/vm/runtime/extensions.js +270 -0
  59. package/dist/vm/runtime/generators.d.ts +6 -0
  60. package/dist/vm/runtime/generators.js +44 -0
  61. package/dist/vm/runtime/globals.d.ts +6 -0
  62. package/dist/vm/runtime/globals.js +137 -0
  63. package/dist/vm/runtime/interpreter.d.ts +50 -0
  64. package/dist/vm/runtime/interpreter.js +94 -0
  65. package/dist/vm/runtime/intrinsic-names.d.ts +56 -0
  66. package/dist/vm/runtime/intrinsic-names.js +166 -0
  67. package/dist/vm/runtime/intrinsics.d.ts +15 -0
  68. package/dist/vm/runtime/intrinsics.js +111 -0
  69. package/dist/vm/runtime/limits.d.ts +10 -0
  70. package/dist/vm/runtime/limits.js +19 -0
  71. package/dist/vm/runtime/model.d.ts +58 -0
  72. package/dist/vm/runtime/model.js +57 -0
  73. package/dist/vm/runtime/modules.d.ts +4 -0
  74. package/dist/vm/runtime/modules.js +33 -0
  75. package/dist/vm/runtime/native.d.ts +19 -0
  76. package/dist/vm/runtime/native.js +41 -0
  77. package/dist/vm/runtime/objects.d.ts +403 -0
  78. package/dist/vm/runtime/objects.js +784 -0
  79. package/dist/vm/runtime/operations.d.ts +49 -0
  80. package/dist/vm/runtime/operations.js +288 -0
  81. package/dist/vm/runtime/promises.d.ts +55 -0
  82. package/dist/vm/runtime/promises.js +232 -0
  83. package/dist/vm/runtime/references.d.ts +8 -0
  84. package/dist/vm/runtime/references.js +51 -0
  85. package/dist/vm/runtime/signals.d.ts +69 -0
  86. package/dist/vm/runtime/signals.js +68 -0
  87. package/dist/vm/runtime/source.d.ts +29 -0
  88. package/dist/vm/runtime/source.js +63 -0
  89. package/dist/vm/runtime/table.d.ts +43 -0
  90. package/dist/vm/runtime/table.js +132 -0
  91. package/dist/vm/scheduler.d.ts +178 -0
  92. package/dist/vm/scheduler.js +63 -0
  93. package/dist/vm/snapshot/codec.d.ts +87 -0
  94. package/dist/vm/snapshot/codec.js +751 -0
  95. package/dist/vm/snapshot/snapshot.d.ts +49 -0
  96. package/dist/vm/snapshot/snapshot.js +70 -0
  97. package/dist/vm/snapshot.d.ts +32 -0
  98. package/dist/vm/snapshot.js +306 -0
  99. package/dist/vm/stdlib/array.d.ts +16 -0
  100. package/dist/vm/stdlib/array.js +311 -0
  101. package/dist/vm/stdlib/bytes.d.ts +11 -0
  102. package/dist/vm/stdlib/bytes.js +222 -0
  103. package/dist/vm/stdlib/collections.d.ts +7 -0
  104. package/dist/vm/stdlib/collections.js +188 -0
  105. package/dist/vm/stdlib/console.d.ts +6 -0
  106. package/dist/vm/stdlib/console.js +93 -0
  107. package/dist/vm/stdlib/date.d.ts +2 -0
  108. package/dist/vm/stdlib/date.js +123 -0
  109. package/dist/vm/stdlib/headers.d.ts +2 -0
  110. package/dist/vm/stdlib/headers.js +92 -0
  111. package/dist/vm/stdlib/iterator.d.ts +2 -0
  112. package/dist/vm/stdlib/iterator.js +30 -0
  113. package/dist/vm/stdlib/json.d.ts +3 -0
  114. package/dist/vm/stdlib/json.js +42 -0
  115. package/dist/vm/stdlib/math.d.ts +3 -0
  116. package/dist/vm/stdlib/math.js +73 -0
  117. package/dist/vm/stdlib/number.d.ts +3 -0
  118. package/dist/vm/stdlib/number.js +72 -0
  119. package/dist/vm/stdlib/object.d.ts +6 -0
  120. package/dist/vm/stdlib/object.js +201 -0
  121. package/dist/vm/stdlib/regexp.d.ts +8 -0
  122. package/dist/vm/stdlib/regexp.js +119 -0
  123. package/dist/vm/stdlib/string.d.ts +2 -0
  124. package/dist/vm/stdlib/string.js +272 -0
  125. package/dist/vm/stdlib/url.d.ts +25 -0
  126. package/dist/vm/stdlib/url.js +255 -0
  127. package/dist/vm/stdlib/value.d.ts +6 -0
  128. package/dist/vm/stdlib/value.js +32 -0
  129. package/dist/vm/stdlib/web.d.ts +5 -0
  130. package/dist/vm/stdlib/web.js +97 -0
  131. package/dist/vm/vm.d.ts +225 -0
  132. package/dist/vm/vm.js +2931 -0
  133. package/package.json +6 -3
package/README.md CHANGED
@@ -14,7 +14,8 @@ The idea of code mode was originally introduced by Cloudflare. See
14
14
  ## How it differs from JavaScript
15
15
 
16
16
  - **Only supported APIs are available.** Programs can use the provided tools, supported JavaScript built-ins, and the
17
- globals the host adds through extensions. Timers, `process`, filesystem access, imports, and modules are unavailable.
17
+ globals the host adds through extensions. Timers, `process`, filesystem access, packages, and `export` are
18
+ unavailable.
18
19
  - **Unfinished work is interrupted.** Tool calls and async functions start when called. When the program finishes,
19
20
  anything still running is interrupted. Unhandled rejections from un-awaited promises are returned as warnings.
20
21
  - **REPL-style results.** Without an explicit `return`, the final top-level expression becomes the result. `undefined`
@@ -96,6 +97,60 @@ denies it: the host function is never called, and the program catches the failur
96
97
  fails the way the call itself would: a tool call or asynchronous global rejects its promise, and a synchronous global
97
98
  throws.
98
99
 
100
+ ### Bytecode VM and suspending/resuming a run (experimental, `engine: "vm"`)
101
+
102
+ Pass `engine: "vm"` to `CodeMode.make` or `CodeMode.execute` to run programs on the bytecode VM instead of the default
103
+ `"legacy"` AST interpreter. `runtime.execute(code, bindings?)` keeps the same `Effect<CodeMode.Result>` signature on
104
+ both engines.
105
+
106
+ On `engine: "vm"`, `CodeMode.make` returns a `CodeMode.VmRuntime`, which can also run a program step by step:
107
+ `runtime.program(code, bindings?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`. `run()` runs it in
108
+ the current fiber until it ends or is suspended, and gives a `CodeMode.Outcome`: a `Result`, or:
109
+
110
+ ```ts
111
+ type Suspended = {
112
+ ok: "suspended"
113
+ state: CodeMode.Snapshot // JSON; CodeMode.toBytes / CodeMode.fromBytes convert it
114
+ }
115
+
116
+ const runtime = CodeMode.make({ tools, engine: "vm" })
117
+
118
+ // inline
119
+ const outcome = yield* runtime.program(code).run()
120
+
121
+ // in the background, suspended from another fiber
122
+ const program = runtime.program(code)
123
+ const fiber = yield* Effect.forkChild(program.run())
124
+ const suspended = yield* program.suspend() // the same Suspended that run() returns
125
+ const outcome = yield* Fiber.join(fiber)
126
+
127
+ // later, in this process or another one built from the same version
128
+ yield* runtime.resume(CodeMode.toBytes(suspended.state)).run()
129
+ ```
130
+
131
+ The default runtime has no `program` or `resume`. A program runs once: running it again is a defect, so make another
132
+ with `runtime.program` or `runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and
133
+ every call in progress.
134
+
135
+ `program.suspend(options?)` saves the run's state and stops it at once, and `run()` returns the same `Suspended`. It
136
+ can be suspended only while no host call (tool, `search`, `fetch`, or extension call) is running. When one is in
137
+ progress, `suspend` fails with a `CodeMode.SuspendError` naming each blocking call by its path (`tools.x.y`, `fetch`),
138
+ and the run goes on untouched. Tool calls queued but not started don't block: they start on resume. Outcomes already
139
+ waiting in the inbox are part of the state. A suspend after the run ended gives its result; one issued before `run()`
140
+ has started waits for it to start (and for ever if it never runs).
141
+
142
+ The suspend is immediate: the program shares the thread with the caller, so it is at a step boundary. Its checks, saving
143
+ the state, and checking it against `options.maxBytes` all happen before anything about the run changes, so a state that
144
+ can't be saved or is too large fails the suspend the same way.
145
+
146
+ A resumed run keeps the limits it was saved with: `timeoutMs` counts active time across every resume, and `maxToolCalls`
147
+ counts every call of the run. A state resumes only on the same build of this package and with the same extensions. The
148
+ state is checked when the resumed program runs: its `run()` fails with a `CodeMode.SnapshotError` when it can't be
149
+ resumed here or is malformed. Built-ins are saved by name and only their changes are copied.
150
+
151
+ Set `CODEMODE_ROUNDTRIP=1` (`bun run test:roundtrip`) to run the tests on the VM with every run saved to bytes and
152
+ restored into a brand-new runtime at every host call and every few steps.
153
+
99
154
  ### `Extension.make`
100
155
 
101
156
  Extensions are host functions a program calls directly as globals, such as `fetch`. Unlike tools they are not in the
@@ -136,6 +191,20 @@ Every value crossing in either direction is converted, never shared: arguments c
136
191
  copies, and a function inside a result is callable the same way. A global that shadows a built-in or another
137
192
  extension throws at `CodeMode.make`.
138
193
 
194
+ A global can also be an object of functions, such as `fs`. Every function reachable from it is an entry point like a
195
+ global, so calls fire the `extension` hooks with their path as the name (`fs.readFile`, `fs.promises.readFile`).
196
+
197
+ Programs load globals the way Node code loads modules. `import` and `require` take a global by its Node module name,
198
+ with or without `node:`; `fs/promises`, `url`, `util`, and `buffer` resolve to the globals that provide them. There are
199
+ no packages, so anything else throws.
200
+
201
+ ```js
202
+ import fs, { readFile } from "node:fs" // the `fs` global, if the host provides one
203
+ import { URL } from "url"
204
+ const crypto = require("crypto")
205
+ const { default: same } = await import("fs")
206
+ ```
207
+
139
208
  ### OpenAPI tools
140
209
 
141
210
  `OpenAPI.fromSpec` converts an OpenAPI 3.x document into one tool per supported operation. Dotted `operationId` values
@@ -1,9 +1,13 @@
1
1
  import { Effect, Schema } from "effect";
2
2
  import type { Extension } from "./extension.js";
3
3
  import { scanTools } from "./scan.js";
4
+ import { fromBytes, SnapshotError, SuspendError, toBytes } from "./suspend-error.js";
4
5
  import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js";
5
6
  import type { Tools } from "./tools.js";
6
- export { scanTools };
7
+ import type { VmEngine } from "./vm/index.js";
8
+ export { fromBytes, scanTools, SnapshotError, SuspendError, toBytes };
9
+ export type SnapshotHeader = VmEngine.SnapshotHeader;
10
+ export type Snapshot = VmEngine.Snapshot;
7
11
  /** A tool call admitted during an execution. */
8
12
  export type { CallResult, ExtensionInvocation, Hooks, ToolCall, ToolDescription, ToolInvocation, } from "./tool-runtime.js";
9
13
  /** Signature-construction helpers for host-owned catalog instructions. */
@@ -28,16 +32,28 @@ export type ResolvedExecutionLimits = {
28
32
  readonly maxToolCalls: number | undefined;
29
33
  readonly maxOutputBytes: number | undefined;
30
34
  };
35
+ /** Execution engine: the default AST generator interpreter (`"legacy"`) or the experimental bytecode VM (`"vm"`). */
36
+ export type Engine = "legacy" | "vm";
37
+ /** How `program.suspend` saves a run's state (`engine: "vm"` only). */
38
+ export type SuspendOptions = {
39
+ /** The most bytes a saved state may take; a larger one fails the suspend, and the run goes on. */
40
+ readonly maxBytes?: number;
41
+ };
31
42
  /** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
32
43
  export type Options<Provided extends Record<string, unknown> = {}, Extensions extends ReadonlyArray<Extension> = []> = {
33
44
  /** Explicit tools exposed to the program as `tools`. */
34
45
  tools?: Provided & Tools<Services<Provided>>;
35
46
  /** Hooks around every tool and extension call the program makes; see `Hooks`. */
36
47
  hooks?: ToolRuntime.Hooks<Environment<Provided, Extensions>>;
37
- /** Host functions exposed as globals; see `Extension.make`. */
48
+ /** Host functions and objects exposed as globals, also importable by Node module name; see `Extension.make`. */
38
49
  extensions?: Extensions;
39
- /** Resource limits enforced on each execution. */
50
+ /** Resource limits enforced on each execution. Time counts active time only, across every resume of a run. */
40
51
  limits?: ExecutionLimits;
52
+ /**
53
+ * Interpreter that runs programs. `"vm"` is the experimental bytecode VM, whose runtime (`VmRuntime`) can also
54
+ * suspend and resume runs; the default is `"legacy"`.
55
+ */
56
+ engine?: Engine;
41
57
  };
42
58
  /** The Effect environment an execution needs: what the tools and the extensions' Effect globals require. */
43
59
  export type Environment<Provided extends Record<string, unknown>, Extensions extends ReadonlyArray<Extension>> = Services<Provided> | Extension.Services<Extensions[number]>;
@@ -145,12 +161,47 @@ export declare const Result: Schema.Union<readonly [Schema.Struct<{
145
161
  }>]>;
146
162
  /** Result of executing a CodeMode program. Program failures are data, not Effect failures. */
147
163
  export type Result = typeof Result.Type;
164
+ /** A run stopped by `program.suspend`: its whole state, to resume with `VmRuntime.resume`. */
165
+ export type Suspended = {
166
+ readonly ok: "suspended";
167
+ readonly state: Snapshot;
168
+ };
169
+ /** How a run of a program ended: its result, or its saved state once suspended. */
170
+ export type Outcome = Result | Suspended;
148
171
  /** Reusable confined runtime over explicit tools. */
149
172
  export type Runtime<R = never> = {
150
173
  readonly catalog: ReadonlyArray<ToolDescription>;
151
174
  readonly execute: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Effect.Effect<Result, never, R>;
152
175
  };
176
+ /** A runtime on the bytecode VM (`engine: "vm"`, experimental): it can also suspend runs and resume them. */
177
+ export type VmRuntime<R = never> = Runtime<R> & {
178
+ /** A program ready to run once; nothing runs until `program.run()`. */
179
+ readonly program: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Program<R>;
180
+ /**
181
+ * A suspended run (its `state`, or that state as bytes) as a program to continue in this runtime, which must be the
182
+ * same build with the same extensions. The state is checked when it runs: `run()` fails with a `SnapshotError` when
183
+ * it can't be resumed here.
184
+ */
185
+ readonly resume: (state: Snapshot | Uint8Array) => Program<R, SnapshotError>;
186
+ };
187
+ /**
188
+ * One run of a program on the VM. `run()` runs it in the current fiber until it ends or is suspended, and owns its host
189
+ * calls: interrupting `run()` interrupts them. A program runs once: running it again is a defect.
190
+ */
191
+ export type Program<R = never, E = never> = {
192
+ readonly run: () => Effect.Effect<Outcome, E, R>;
193
+ /**
194
+ * Saves the run's state and stops it, at once, from another fiber: `run()` then returns the same `Suspended`, and so
195
+ * does this. It fails with a `SuspendError`, leaving the run running, while a host call (tool, `search`, `fetch`, or
196
+ * extension call) is in progress, or when the state can't be saved or is over `options.maxBytes`. A run that already
197
+ * ended gives its result. Before `run()` starts, this waits for it to start.
198
+ */
199
+ readonly suspend: (options?: SuspendOptions) => Effect.Effect<Outcome, SuspendError>;
200
+ };
153
201
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
154
202
  export declare const execute: <const Provided extends Record<string, unknown>, const Extensions extends ReadonlyArray<Extension> = []>(options: ExecuteOptions<Provided, Extensions>) => Effect.Effect<Result, never, Environment<Provided, Extensions>>;
155
203
  /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
156
- export declare const make: <const Provided extends Record<string, unknown> = {}, const Extensions extends ReadonlyArray<Extension> = []>(options?: Options<Provided, Extensions>) => Runtime<Environment<Provided, Extensions>>;
204
+ export declare function make<const Provided extends Record<string, unknown> = {}, const Extensions extends ReadonlyArray<Extension> = []>(options: Options<Provided, Extensions> & {
205
+ engine: "vm";
206
+ }): VmRuntime<Environment<Provided, Extensions>>;
207
+ export declare function make<const Provided extends Record<string, unknown> = {}, const Extensions extends ReadonlyArray<Extension> = []>(options?: Options<Provided, Extensions>): Runtime<Environment<Provided, Extensions>>;
package/dist/codemode.js CHANGED
@@ -1,11 +1,12 @@
1
- import { Effect, Schema } from "effect";
1
+ import { Deferred, Effect, Exit, Schema } from "effect";
2
2
  import { fromJson } from "./data.js";
3
3
  import { executeProgram } from "./interpreter/execute.js";
4
4
  import { extensionGlobals } from "./interpreter/extensions.js";
5
5
  import { globalNames } from "./interpreter/globals.js";
6
6
  import { scanTools } from "./scan.js";
7
+ import { fromBytes, SnapshotError, SuspendError, toBytes } from "./suspend-error.js";
7
8
  import { ToolRuntime } from "./tool-runtime.js";
8
- export { scanTools };
9
+ export { fromBytes, scanTools, SnapshotError, SuspendError, toBytes };
9
10
  /** Signature-construction helpers for host-owned catalog instructions. */
10
11
  export { searchSignature, toolExpression } from "./tool-runtime.js";
11
12
  /** Schema for a host tool input containing CodeMode source. */
@@ -60,11 +61,11 @@ const resolveExecutionLimits = (limits) => ({
60
61
  });
61
62
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
62
63
  export const execute = (options) => make(options).execute(options.code, options.bindings);
63
- /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
64
- export const make = (options = {}) => {
64
+ export function make(options = {}) {
65
65
  const prepared = ToolRuntime.prepare((options.tools ?? {}));
66
66
  const limits = resolveExecutionLimits(options.limits);
67
67
  const extensions = options.extensions ?? [];
68
+ // Both engines bind the same global names; test/engines.test.ts keeps them in step.
68
69
  const bound = new Set(globalNames);
69
70
  for (const extension of extensions) {
70
71
  for (const name of Object.keys(extension.globals)) {
@@ -73,13 +74,67 @@ export const make = (options = {}) => {
73
74
  bound.add(name);
74
75
  }
75
76
  }
77
+ if (options.engine !== "vm") {
78
+ return {
79
+ get catalog() {
80
+ return prepared.catalog;
81
+ },
82
+ execute: (code, bindings) => executeProgram(code, prepared, limits, options.hooks ?? {}, (ctx) => [
83
+ ...Object.entries(bindings ?? {}).map(([name, value]) => [name, fromJson(ctx, value)]),
84
+ ...extensionGlobals(ctx, extensions),
85
+ ]),
86
+ };
87
+ }
88
+ let setup;
89
+ const getSetup = (vm) => (setup ??= {
90
+ prepared,
91
+ limits,
92
+ hooks: options.hooks ?? {},
93
+ globals: extensions.length === 0 ? undefined : (ctx) => vm.extensionGlobals(ctx, extensions),
94
+ lossy: extensions.length > 0,
95
+ });
96
+ const data = (vm, bindings) => bindings === undefined
97
+ ? undefined
98
+ : (ctx) => Object.entries(bindings).map(([name, value]) => [name, vm.fromJson(ctx, value)]);
99
+ const program = (code, bindings) => vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings))));
76
100
  return {
77
101
  get catalog() {
78
102
  return prepared.catalog;
79
103
  },
80
- execute: (code, bindings) => executeProgram(code, prepared, limits, options.hooks ?? {}, (ctx) => [
81
- ...Object.entries(bindings ?? {}).map(([name, value]) => [name, fromJson(ctx, value)]),
82
- ...extensionGlobals(ctx, extensions),
83
- ]),
104
+ execute: (code, bindings) => Effect.flatMap(loadVm(), (vm) => vm.finishExecution(program(code, bindings).run())),
105
+ program,
106
+ resume: (state) => vmProgram((vm) => vm.resumeProgram(getSetup(vm), state)),
107
+ };
108
+ }
109
+ // A program's one run: `start` makes it once the VM is loaded, and a suspend waits for it.
110
+ const vmProgram = (start) => {
111
+ let claimed = false;
112
+ const started = Deferred.makeUnsafe();
113
+ return {
114
+ run: () => Effect.suspend(() => {
115
+ if (claimed) {
116
+ return Effect.die(new Error("A CodeMode program runs once; make another with runtime.program or runtime.resume."));
117
+ }
118
+ claimed = true;
119
+ return loadVm().pipe(Effect.flatMap(start), Effect.onExit((exit) => Exit.isSuccess(exit)
120
+ ? Deferred.succeed(started, exit.value)
121
+ : Deferred.fail(started, new SuspendError({ message: "The program didn't start.", running: [] }))), Effect.flatMap((running) => running.run()));
122
+ }),
123
+ suspend: (options) => {
124
+ const maxBytes = options?.maxBytes;
125
+ if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {
126
+ throw new RangeError("maxBytes must be a safe integer greater than or equal to 0.");
127
+ }
128
+ return Effect.flatMap(Deferred.await(started), (running) => running.suspend(maxBytes));
129
+ },
84
130
  };
85
131
  };
132
+ // The VM is loaded on first use so the default engine pulls in none of its code.
133
+ let vmLoaded;
134
+ let vmEngine;
135
+ const loadVm = () => vmLoaded !== undefined
136
+ ? Effect.succeed(vmLoaded)
137
+ : Effect.promise(() => (vmEngine ??= import("./vm/index.js").then((mod) => {
138
+ vmLoaded = mod;
139
+ return mod;
140
+ })));
@@ -1,24 +1,29 @@
1
1
  export * as Extension from "./extension.js";
2
2
  import type { Effect } from "effect";
3
3
  /**
4
- * Host functions a program calls directly as globals. Values crossing in either direction are converted, never
5
- * shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
6
- * same way. Extension calls are not tool calls. A global may return a value, a Promise, or an Effect, and an
7
- * Effect's requirements join the runtime's environment.
4
+ * Host values a program reaches directly as globals: functions, or objects of functions such as `fs`. Values crossing
5
+ * in either direction are converted, never shared: arguments come in as copies, results go out as copies, and a
6
+ * function inside a result is callable the same way. Extension calls are not tool calls. A global may return a value,
7
+ * a Promise, or an Effect, and an Effect's requirements join the runtime's environment.
8
8
  *
9
9
  * A global is synchronous unless it is an `async` function or is marked with `async`. The `extension.before` hook
10
10
  * runs before the call, so a denied call never reaches the host; it fails the way the global would, by rejecting the
11
- * promise of an asynchronous global and by throwing from a synchronous one.
11
+ * promise of an asynchronous global and by throwing from a synchronous one. Functions inside a global object are
12
+ * called the same way, named by their path (`fs.readFile`).
13
+ *
14
+ * Programs can also `import` or `require` a global by its Node module name; see `interpreter/modules.ts`.
12
15
  */
13
- export type Extension<Globals extends Readonly<Record<string, Function>> = Readonly<Record<string, Function>>> = {
16
+ export type Extension<Globals extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
14
17
  readonly name: string;
15
18
  readonly globals: Globals;
16
19
  };
17
- /** The Effect environment required by an extension's Effect-returning globals. */
20
+ /** The Effect environment required by an extension's Effect-returning functions, at the top level or one level in. */
18
21
  export type Services<E> = E extends {
19
22
  readonly globals: infer Globals;
20
- } ? Globals[keyof Globals] extends infer Global ? Global extends (...args: never) => infer Result ? Effect.Services<Result> : never : never : never;
21
- export declare const make: <const Globals extends Readonly<Record<string, Function>>>(options: Extension<Globals>) => Extension<Globals>;
23
+ } ? GlobalServices<Globals[keyof Globals]> : never;
24
+ type GlobalServices<Global> = Global extends (...args: never) => unknown ? Requirements<Global> : Global extends object ? Requirements<Global[keyof Global]> : never;
25
+ type Requirements<F> = F extends (...args: never) => infer Result ? Effect.Services<Result> : never;
26
+ export declare const make: <const Globals extends Readonly<Record<string, unknown>>>(options: Extension<Globals>) => Extension<Globals>;
22
27
  /** Marks a global that returns a Promise or an Effect, so a denied call rejects its promise instead of throwing. */
23
28
  export declare const async: <F extends Function>(global: F) => F;
24
29
  export declare const isAsync: (global: Function) => boolean;
package/dist/extension.js CHANGED
@@ -1,8 +1,8 @@
1
1
  export * as Extension from "./extension.js";
2
2
  export const make = (options) => {
3
3
  for (const [name, value] of Object.entries(options.globals)) {
4
- if (typeof value !== "function") {
5
- throw new TypeError(`Extension "${options.name}" global "${name}" must be a function.`);
4
+ if (typeof value !== "function" && (typeof value !== "object" || value === null)) {
5
+ throw new TypeError(`Extension "${options.name}" global "${name}" must be a function or an object.`);
6
6
  }
7
7
  }
8
8
  return { name: options.name, globals: { ...options.globals } };
package/dist/index.d.ts CHANGED
@@ -3,5 +3,5 @@ export * as Extension from "./extension.js";
3
3
  export * as Namespace from "./namespace.js";
4
4
  export * as Tool from "./tool.js";
5
5
  export * as OpenAPI from "./openapi/index.js";
6
- export { searchSignature, toolExpression } from "./codemode.js";
6
+ export { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, type Outcome, type Program, type Snapshot, type SnapshotHeader, type Suspended, type SuspendOptions, type VmRuntime, } from "./codemode.js";
7
7
  export { ToolError, toolError } from "./tool-error.js";
package/dist/index.js CHANGED
@@ -3,5 +3,5 @@ export * as Extension from "./extension.js";
3
3
  export * as Namespace from "./namespace.js";
4
4
  export * as Tool from "./tool.js";
5
5
  export * as OpenAPI from "./openapi/index.js";
6
- export { searchSignature, toolExpression } from "./codemode.js";
6
+ export { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, } from "./codemode.js";
7
7
  export { ToolError, toolError } from "./tool-error.js";
@@ -2,8 +2,8 @@ import { type Program } from "acorn";
2
2
  import { Effect } from "effect";
3
3
  import type { Diagnostic, ResolvedExecutionLimits, Result } from "../codemode.js";
4
4
  import { ToolRuntime } from "../tool-runtime.js";
5
- import type { Value } from "./objects.js";
6
5
  import { Interpreter } from "./interpreter.js";
6
+ import type { Value } from "./objects.js";
7
7
  export declare const executeProgram: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.Hooks<R>, globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>) => Effect.Effect<Result, never, R>;
8
8
  export declare const parseProgram: (code: string) => {
9
9
  ok: true;
@@ -4,7 +4,7 @@ import { ToolRuntime } from "../tool-runtime.js";
4
4
  import { normalizeError } from "./errors.js";
5
5
  import { createBuiltins } from "./intrinsics.js";
6
6
  import { Interpreter } from "./interpreter.js";
7
- import { formatLocation } from "./model.js";
7
+ import { formatLocation, sourceLocation } from "./model.js";
8
8
  export const executeProgram = (code, prepared, limits, hooks, globals) => {
9
9
  if (code.trim().length === 0) {
10
10
  return Effect.succeed({
@@ -93,8 +93,22 @@ export const parseProgram = (code) => {
93
93
  sourceType: "script",
94
94
  allowReturnOutsideFunction: true,
95
95
  allowAwaitOutsideFunction: true,
96
+ // Imports bind globals by module name; scripts keep sloppy-mode semantics, which module source would make strict.
97
+ allowImportExportEverywhere: true,
96
98
  locations: true,
97
99
  });
100
+ const exported = program.body.find((statement) => statement.type.startsWith("Export"));
101
+ if (exported) {
102
+ const location = sourceLocation(exported);
103
+ return {
104
+ ok: false,
105
+ error: {
106
+ kind: "ParseError",
107
+ message: `SyntaxError: Exports aren't available. Return the result instead.${formatLocation(location)}`,
108
+ location,
109
+ },
110
+ };
111
+ }
98
112
  return { ok: true, program };
99
113
  }
100
114
  catch (error) {
@@ -114,9 +128,7 @@ const decodeAcornError = Schema.decodeUnknownOption(AcornError);
114
128
  const parseDiagnostic = (error) => {
115
129
  const location = { line: error.loc.line, column: error.loc.column + 1 };
116
130
  const reason = error.message.replace(/ \(\d+:\d+\)$/, "");
117
- const text = reason === "'import' and 'export' may appear only with 'sourceType: module'"
118
- ? "Imports and exports aren't available. Call tools through `tools` and use the built-in globals."
119
- : `${reason.endsWith(".") ? reason : `${reason}.`} Code must be plain JavaScript written as a program body.`;
131
+ const text = `${reason.endsWith(".") ? reason : `${reason}.`} Code must be plain JavaScript written as a program body.`;
120
132
  return { kind: "ParseError", message: `SyntaxError: ${text}${formatLocation(location)}`, location };
121
133
  };
122
134
  const utf8ByteLength = (value) => new TextEncoder().encode(value).byteLength;
@@ -2,8 +2,8 @@ import { type Extension } from "../extension.js";
2
2
  import type { Interpreter } from "./interpreter.js";
3
3
  import { type Value } from "./objects.js";
4
4
  /**
5
- * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
6
- * built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
7
- * host Promise or Effect becomes a program promise.
5
+ * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in
6
+ * wrappers are copied, a host function becomes a program function whose calls cross the same way, and a host Promise
7
+ * or Effect becomes a program promise.
8
8
  */
9
9
  export declare const extensionGlobals: <R>(ctx: Interpreter<R>, extensions: ReadonlyArray<Extension>) => ReadonlyArray<readonly [string, Value]>;
@@ -9,9 +9,9 @@ import { fn } from "./native.js";
9
9
  import { define, get, has, hidden, keys, Arr, Bytes, DateObj, ErrorObj, HeadersObj, MapObj, Obj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, coerceToString, } from "./objects.js";
10
10
  import { describeValue, isOpaque } from "./references.js";
11
11
  /**
12
- * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
13
- * built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
14
- * host Promise or Effect becomes a program promise.
12
+ * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in
13
+ * wrappers are copied, a host function becomes a program function whose calls cross the same way, and a host Promise
14
+ * or Effect becomes a program promise.
15
15
  */
16
16
  export const extensionGlobals = (ctx, extensions) => {
17
17
  const builtins = ctx.builtins;
@@ -52,15 +52,16 @@ export const extensionGlobals = (ctx, extensions) => {
52
52
  seen.delete(value);
53
53
  return copied;
54
54
  };
55
- const fromHost = (value, label, depth = 0, seen = new Set()) => {
55
+ // `extension` is set while converting a global object, whose functions are entry points like globals and fire the hooks.
56
+ const fromHost = (value, label, depth = 0, seen = new Set(), extension) => {
56
57
  if (depth > MAX_VALUE_DEPTH)
57
58
  throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
58
59
  if (isPrimitive(value))
59
60
  return value;
60
61
  if (typeof value === "function")
61
- return wrap(value, label);
62
+ return wrap(value, label, extension === undefined ? undefined : (args) => ({ extension, name: label, args }));
62
63
  if (value !== null && typeof value === "object") {
63
- const next = (item, path) => fromHost(item, path, depth + 1, seen);
64
+ const next = (item, path) => fromHost(item, path, depth + 1, seen, extension);
64
65
  // Nothing a host value hands back is kept: results are read as primitives or copied. Where the value's own
65
66
  // method could hand back host storage or an object (`getTime`, `slice`, `map`), its internal data is read.
66
67
  if (value instanceof Date)
@@ -145,10 +146,10 @@ export const extensionGlobals = (ctx, extensions) => {
145
146
  }
146
147
  throw typeError(`${label} produced ${describeHost(value)}, which the program cannot hold.`);
147
148
  };
148
- // A host function as a program function. Arguments cross in; for a global, the `extension.before` hook runs before
149
- // the host function is called, so a call it denies never reaches the host. The host's result, or what it threw,
150
- // crosses out so the program catches a copy, and `extension.after` sees how the call ended. Functions inside
151
- // results are part of a value's API and skip the hooks.
149
+ // A host function as a program function. Arguments cross in; for a global or a global object's function, the
150
+ // `extension.before` hook runs before the host function is called, so a call it denies never reaches the host. The
151
+ // host's result, or what it threw, crosses out so the program catches a copy, and `extension.after` sees how the
152
+ // call ended. Functions inside results are part of a value's API and skip the hooks.
152
153
  const wrap = (value, label, describe) => {
153
154
  // The host function's own `name` and `length` can be anything, even getters: each is read once, and only text
154
155
  // and a count cross.
@@ -180,7 +181,12 @@ export const extensionGlobals = (ctx, extensions) => {
180
181
  ctx.runner.host(work, (settled) => (settled.ok ? resolving.resolve(settled.value) : resolving.reject(settled.error)), site);
181
182
  return promise;
182
183
  };
183
- return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, wrap(value, name, (args) => ({ extension: extension.name, name, args }))]));
184
+ return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [
185
+ name,
186
+ typeof value === "function"
187
+ ? wrap(value, name, (args) => ({ extension: extension.name, name, args }))
188
+ : fromHost(value, name, 0, new Set(), extension.name),
189
+ ]));
184
190
  };
185
191
  /**
186
192
  * Calls a host function and describes what the program waits on. A returned Effect or Promise settles later; a
@@ -84,6 +84,16 @@ const symbolGlobal = (ctx) => {
84
84
  const table = {
85
85
  tools: () => new ToolReference([]),
86
86
  search: (ctx) => native(ctx.builtins, { name: "search", call: (_, args) => ctx.search(args), callback: false }),
87
+ require: (ctx) => native(ctx.builtins, {
88
+ name: "require",
89
+ length: 1,
90
+ call: (_, args, site) => {
91
+ const specifier = args[0];
92
+ if (typeof specifier !== "string")
93
+ throw typeError("require expects a module name string.");
94
+ return ctx.module(specifier, site);
95
+ },
96
+ }),
87
97
  undefined: () => undefined,
88
98
  NaN: () => NaN,
89
99
  Infinity: () => Infinity,
@@ -4,7 +4,7 @@ import { type Json } from "../data.js";
4
4
  import { type ToolRuntime } from "../tool-runtime.js";
5
5
  import { type AstNode } from "./model.js";
6
6
  import { type Builtins } from "./intrinsics.js";
7
- import { type Cursor, Arr, type Value } from "./objects.js";
7
+ import { type Cursor, Arr, Obj, type Value } from "./objects.js";
8
8
  import { type Eval, Runner } from "./runner.js";
9
9
  /** One program execution: the tool bridge, job queue, captured logs, and the global scope built once. */
10
10
  export declare class Interpreter<R> {
@@ -15,6 +15,9 @@ export declare class Interpreter<R> {
15
15
  /** Template objects by site: a tag sees the same `strings` array every time its literal is evaluated, as in JS. */
16
16
  readonly templates: WeakMap<TaggedTemplateExpression, Arr>;
17
17
  private readonly root;
18
+ private readonly globalScope;
19
+ private readonly modules;
20
+ private readonly namespaces;
18
21
  constructor(options: {
19
22
  readonly tools: ToolRuntime<R>;
20
23
  /** The caller's services, which host work runs with. */
@@ -23,6 +26,13 @@ export declare class Interpreter<R> {
23
26
  readonly logs?: Array<string>;
24
27
  readonly globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>;
25
28
  });
29
+ /** A module, as `require` returns it and a default import binds it: a global, by its Node module name. */
30
+ module(specifier: string, site?: AstNode): Value;
31
+ /**
32
+ * What `import * as` and `import()` see: the module's own properties, and the module itself as `default`, the way
33
+ * Node presents a CommonJS module.
34
+ */
35
+ namespace(specifier: string, site?: AstNode): Obj;
26
36
  /** The program's body, as the first job: its completion value, copied out for the host. */
27
37
  main(program: Program): Eval<Json | undefined>;
28
38
  /** Calls into the program; a built-in passes its own call site so failures inside are located there. */