@opencode/codemode 2.2.5 → 2.2.7

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 (142) hide show
  1. package/README.md +164 -7
  2. package/dist/codemode.d.ts +60 -4
  3. package/dist/codemode.js +63 -8
  4. package/dist/extension.d.ts +27 -9
  5. package/dist/extension.js +7 -3
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/interpreter/callback.d.ts +12 -1
  9. package/dist/interpreter/callback.js +13 -1
  10. package/dist/interpreter/execute.d.ts +1 -1
  11. package/dist/interpreter/execute.js +16 -4
  12. package/dist/interpreter/extensions.d.ts +3 -3
  13. package/dist/interpreter/extensions.js +17 -11
  14. package/dist/interpreter/globals.js +10 -0
  15. package/dist/interpreter/interpreter.d.ts +11 -1
  16. package/dist/interpreter/interpreter.js +88 -4
  17. package/dist/interpreter/modules.d.ts +4 -0
  18. package/dist/interpreter/modules.js +33 -0
  19. package/dist/interpreter/promises.js +2 -2
  20. package/dist/interpreter/runner.d.ts +1 -11
  21. package/dist/interpreter/runner.js +1 -13
  22. package/dist/stdlib/iterator.js +1 -2
  23. package/dist/suspend-error.d.ts +24 -0
  24. package/dist/suspend-error.js +25 -0
  25. package/dist/tool-runtime.d.ts +31 -7
  26. package/dist/tool-runtime.js +116 -26
  27. package/dist/tool.d.ts +45 -2
  28. package/dist/tool.js +30 -7
  29. package/dist/vm/async.d.ts +78 -0
  30. package/dist/vm/async.js +335 -0
  31. package/dist/vm/code.d.ts +122 -0
  32. package/dist/vm/code.js +407 -0
  33. package/dist/vm/compiler/compile.d.ts +13 -0
  34. package/dist/vm/compiler/compile.js +1477 -0
  35. package/dist/vm/compiler/scope.d.ts +74 -0
  36. package/dist/vm/compiler/scope.js +515 -0
  37. package/dist/vm/data.d.ts +7 -0
  38. package/dist/vm/data.js +13 -0
  39. package/dist/vm/generators.d.ts +42 -0
  40. package/dist/vm/generators.js +413 -0
  41. package/dist/vm/host.d.ts +106 -0
  42. package/dist/vm/host.js +231 -0
  43. package/dist/vm/index.d.ts +6 -0
  44. package/dist/vm/index.js +6 -0
  45. package/dist/vm/internal-prelude.d.ts +45 -0
  46. package/dist/vm/internal-prelude.js +534 -0
  47. package/dist/vm/opcodes.d.ts +222 -0
  48. package/dist/vm/opcodes.js +235 -0
  49. package/dist/vm/prelude/bytecode.d.ts +18 -0
  50. package/dist/vm/prelude/bytecode.js +31 -0
  51. package/dist/vm/prelude/bytecode.json +1 -0
  52. package/dist/vm/prelude/helpers.d.ts +8 -0
  53. package/dist/vm/prelude/helpers.js +258 -0
  54. package/dist/vm/prelude/prelude.d.ts +21 -0
  55. package/dist/vm/prelude/prelude.js +53 -0
  56. package/dist/vm/prelude/source.d.ts +1 -0
  57. package/dist/vm/prelude/source.js +652 -0
  58. package/dist/vm/runtime/callback.d.ts +25 -0
  59. package/dist/vm/runtime/callback.js +51 -0
  60. package/dist/vm/runtime/driver.d.ts +68 -0
  61. package/dist/vm/runtime/driver.js +254 -0
  62. package/dist/vm/runtime/errors.d.ts +23 -0
  63. package/dist/vm/runtime/errors.js +169 -0
  64. package/dist/vm/runtime/execute.d.ts +80 -0
  65. package/dist/vm/runtime/execute.js +442 -0
  66. package/dist/vm/runtime/extensions.d.ts +16 -0
  67. package/dist/vm/runtime/extensions.js +337 -0
  68. package/dist/vm/runtime/generators.d.ts +6 -0
  69. package/dist/vm/runtime/generators.js +44 -0
  70. package/dist/vm/runtime/globals.d.ts +6 -0
  71. package/dist/vm/runtime/globals.js +137 -0
  72. package/dist/vm/runtime/interpreter.d.ts +53 -0
  73. package/dist/vm/runtime/interpreter.js +96 -0
  74. package/dist/vm/runtime/intrinsic-names.d.ts +56 -0
  75. package/dist/vm/runtime/intrinsic-names.js +166 -0
  76. package/dist/vm/runtime/intrinsics.d.ts +15 -0
  77. package/dist/vm/runtime/intrinsics.js +111 -0
  78. package/dist/vm/runtime/limits.d.ts +10 -0
  79. package/dist/vm/runtime/limits.js +19 -0
  80. package/dist/vm/runtime/model.d.ts +58 -0
  81. package/dist/vm/runtime/model.js +57 -0
  82. package/dist/vm/runtime/modules.d.ts +4 -0
  83. package/dist/vm/runtime/modules.js +33 -0
  84. package/dist/vm/runtime/native.d.ts +19 -0
  85. package/dist/vm/runtime/native.js +41 -0
  86. package/dist/vm/runtime/objects.d.ts +403 -0
  87. package/dist/vm/runtime/objects.js +784 -0
  88. package/dist/vm/runtime/operations.d.ts +49 -0
  89. package/dist/vm/runtime/operations.js +288 -0
  90. package/dist/vm/runtime/promises.d.ts +55 -0
  91. package/dist/vm/runtime/promises.js +232 -0
  92. package/dist/vm/runtime/references.d.ts +8 -0
  93. package/dist/vm/runtime/references.js +51 -0
  94. package/dist/vm/runtime/signals.d.ts +69 -0
  95. package/dist/vm/runtime/signals.js +68 -0
  96. package/dist/vm/runtime/source.d.ts +29 -0
  97. package/dist/vm/runtime/source.js +63 -0
  98. package/dist/vm/runtime/table.d.ts +43 -0
  99. package/dist/vm/runtime/table.js +132 -0
  100. package/dist/vm/scheduler.d.ts +190 -0
  101. package/dist/vm/scheduler.js +74 -0
  102. package/dist/vm/snapshot/codec.d.ts +117 -0
  103. package/dist/vm/snapshot/codec.js +848 -0
  104. package/dist/vm/snapshot/snapshot.d.ts +53 -0
  105. package/dist/vm/snapshot/snapshot.js +74 -0
  106. package/dist/vm/snapshot.d.ts +32 -0
  107. package/dist/vm/snapshot.js +309 -0
  108. package/dist/vm/stdlib/array.d.ts +16 -0
  109. package/dist/vm/stdlib/array.js +311 -0
  110. package/dist/vm/stdlib/bytes.d.ts +11 -0
  111. package/dist/vm/stdlib/bytes.js +222 -0
  112. package/dist/vm/stdlib/collections.d.ts +7 -0
  113. package/dist/vm/stdlib/collections.js +188 -0
  114. package/dist/vm/stdlib/console.d.ts +6 -0
  115. package/dist/vm/stdlib/console.js +93 -0
  116. package/dist/vm/stdlib/date.d.ts +2 -0
  117. package/dist/vm/stdlib/date.js +123 -0
  118. package/dist/vm/stdlib/headers.d.ts +2 -0
  119. package/dist/vm/stdlib/headers.js +92 -0
  120. package/dist/vm/stdlib/iterator.d.ts +2 -0
  121. package/dist/vm/stdlib/iterator.js +30 -0
  122. package/dist/vm/stdlib/json.d.ts +3 -0
  123. package/dist/vm/stdlib/json.js +42 -0
  124. package/dist/vm/stdlib/math.d.ts +3 -0
  125. package/dist/vm/stdlib/math.js +73 -0
  126. package/dist/vm/stdlib/number.d.ts +3 -0
  127. package/dist/vm/stdlib/number.js +72 -0
  128. package/dist/vm/stdlib/object.d.ts +6 -0
  129. package/dist/vm/stdlib/object.js +201 -0
  130. package/dist/vm/stdlib/regexp.d.ts +8 -0
  131. package/dist/vm/stdlib/regexp.js +119 -0
  132. package/dist/vm/stdlib/string.d.ts +2 -0
  133. package/dist/vm/stdlib/string.js +272 -0
  134. package/dist/vm/stdlib/url.d.ts +25 -0
  135. package/dist/vm/stdlib/url.js +255 -0
  136. package/dist/vm/stdlib/value.d.ts +6 -0
  137. package/dist/vm/stdlib/value.js +32 -0
  138. package/dist/vm/stdlib/web.d.ts +5 -0
  139. package/dist/vm/stdlib/web.js +97 -0
  140. package/dist/vm/vm.d.ts +226 -0
  141. package/dist/vm/vm.js +2931 -0
  142. package/package.json +8 -5
@@ -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. */
@@ -1,13 +1,14 @@
1
1
  import { fromJson, toBoundary } from "../data.js";
2
2
  import { ToolReference } from "../tool-runtime.js";
3
- import { AsyncIteratorSymbol, GeneratorReturn, IteratorSymbol, OptionalShortCircuit, invalidData, Throw, rangeError, typeError, unsupportedSyntax, } from "./model.js";
3
+ import { AsyncIteratorSymbol, GeneratorReturn, IteratorSymbol, OptionalShortCircuit, invalidData, PendingThrow, syntaxError, Throw, rangeError, typeError, unsupportedSyntax, } from "./model.js";
4
4
  import { checkStringLength } from "./limits.js";
5
5
  import { locate, materialize } from "./errors.js";
6
6
  import { primitivePrototype } from "./intrinsics.js";
7
7
  import { globals } from "./globals.js";
8
- import { assign, Callable, define, frozen, get, hostCursor, IteratorObj, has, hasOwn, hidden, hasPrototype, keys, Native, parseArrayIndex, Arguments, Arr, Fn, GeneratorObj, Obj, PromiseObj, iteratorResult, remove, set, coerceToNumber, coerceToString, } from "./objects.js";
9
- import { preserveConsumerError, toPrimitive } from "./callback.js";
10
- import { AsyncBoundary, Await, Call, Interruption, isEval, MAX_CALL_DEPTH, Runner, Slice, Task, Yield, normal, } from "./runner.js";
8
+ import { assign, Callable, define, frozen, get, hostCursor, IteratorObj, has, hasOwn, hidden, hasPrototype, keys, Native, parseArrayIndex, Arguments, Arr, Fn, GeneratorObj, Obj, PromiseObj, iteratorResult, remove, set, coerceToNumber, coerceToString, entries, getOwn, } from "./objects.js";
9
+ import { Interruption, isEval, preserveConsumerError, toPrimitive } from "./callback.js";
10
+ import { AsyncBoundary, Await, Call, MAX_CALL_DEPTH, Runner, Slice, Task, Yield, normal, } from "./runner.js";
11
+ import { moduleName, resolveModule } from "./modules.js";
11
12
  import { describeValue, isOpaque, rejectCircularInsertion, typeofValue } from "./references.js";
12
13
  import { fn } from "./native.js";
13
14
  import { capability, promiseLike } from "./promises.js";
@@ -252,6 +253,9 @@ export class Interpreter {
252
253
  /** Template objects by site: a tag sees the same `strings` array every time its literal is evaluated, as in JS. */
253
254
  templates = new WeakMap();
254
255
  root;
256
+ globalScope;
257
+ modules = new Map();
258
+ namespaces = new Map();
255
259
  constructor(options) {
256
260
  this.tools = options.tools;
257
261
  this.builtins = options.builtins;
@@ -261,10 +265,44 @@ export class Interpreter {
261
265
  const globalScope = new Map([["this", { mutable: false, value: undefined }]]);
262
266
  // Calling back into the program never reads frame state, so any frame serves; the root is always alive.
263
267
  this.root = new Frame(this, new ScopeStack([globalScope]));
268
+ this.globalScope = globalScope;
264
269
  for (const [name, value] of [...globals(this), ...(options.globals?.(this) ?? [])]) {
265
270
  globalScope.set(name, { mutable: false, value });
266
271
  }
267
272
  }
273
+ /** A module, as `require` returns it and a default import binds it: a global, by its Node module name. */
274
+ module(specifier, site) {
275
+ const name = moduleName(specifier);
276
+ const cached = this.modules.get(name);
277
+ if (cached !== undefined)
278
+ return cached;
279
+ const module = resolveModule(name, (global) => {
280
+ const binding = this.globalScope.get(global);
281
+ return binding && "value" in binding ? binding.value : undefined;
282
+ });
283
+ if (module === undefined)
284
+ throw new PendingThrow("Error", `Cannot import "${specifier}": it isn't available in Code Mode, which can't load packages or files. Use the provided globals, or call tools through \`tools\`.`, site);
285
+ this.modules.set(name, module);
286
+ return module;
287
+ }
288
+ /**
289
+ * What `import * as` and `import()` see: the module's own properties, and the module itself as `default`, the way
290
+ * Node presents a CommonJS module.
291
+ */
292
+ namespace(specifier, site) {
293
+ const module = this.module(specifier, site);
294
+ const name = moduleName(specifier);
295
+ const cached = this.namespaces.get(name);
296
+ if (cached)
297
+ return cached;
298
+ const namespace = new Obj(null);
299
+ if (module instanceof Obj)
300
+ for (const [key, value] of entries(module))
301
+ define(namespace, key, value);
302
+ define(namespace, "default", module);
303
+ this.namespaces.set(name, namespace);
304
+ return namespace;
305
+ }
268
306
  /** The program's body, as the first job: its completion value, copied out for the host. */
269
307
  *main(program) {
270
308
  return yield* toBoundary(this, yield* this.root.run(program));
@@ -310,11 +348,17 @@ class Frame {
310
348
  // Keep top-level declarations separate so they can shadow builtins.
311
349
  this.scopes.push();
312
350
  try {
351
+ // Imports load before any code runs, as in a module.
352
+ for (const statement of program.body)
353
+ if (statement.type === "ImportDeclaration")
354
+ this.bindImport(statement);
313
355
  this.predeclareLexical(program.body);
314
356
  this.hoistFunctions(program.body);
315
357
  this.hoistVars(program.body);
316
358
  let value = undefined;
317
359
  for (const [index, statement] of program.body.entries()) {
360
+ if (statement.type === "ImportDeclaration")
361
+ continue;
318
362
  if (index === program.body.length - 1 && statement.type === "ExpressionStatement") {
319
363
  value = yield* this.evaluateExpression(statement.expression);
320
364
  break;
@@ -335,6 +379,26 @@ class Frame {
335
379
  this.scopes.pop();
336
380
  }
337
381
  }
382
+ bindImport(node) {
383
+ const specifier = String(node.source.value);
384
+ if (node.specifiers.length === 0)
385
+ this.ctx.module(specifier, node);
386
+ for (const binding of node.specifiers) {
387
+ this.scopes.declare(binding.local.name, this.imported(binding, specifier), false, binding);
388
+ }
389
+ }
390
+ // A default import binds the module itself and a named import one of its properties, as Node imports CommonJS.
391
+ imported(binding, specifier) {
392
+ if (binding.type === "ImportDefaultSpecifier")
393
+ return this.ctx.module(specifier, binding);
394
+ const namespace = this.ctx.namespace(specifier, binding);
395
+ if (binding.type === "ImportNamespaceSpecifier")
396
+ return namespace;
397
+ const name = binding.imported.type === "Identifier" ? binding.imported.name : String(binding.imported.value);
398
+ if (!hasOwn(namespace, name))
399
+ throw syntaxError(`"${specifier}" has no export named "${name}".`, binding);
400
+ return getOwn(namespace, name);
401
+ }
338
402
  // The call returns its promise at once. Arguments cross on the caller's stack, since `toJSON` is program code, and a
339
403
  // promise argument is awaited first; the host call starts once they have crossed, so admission and hooks happen at
340
404
  // the call site, and runs concurrently with the program.
@@ -404,6 +468,8 @@ class Frame {
404
468
  return none;
405
469
  case "FunctionDeclaration":
406
470
  return none;
471
+ case "ImportDeclaration":
472
+ throw syntaxError("An import declaration may only appear at the top level of the program.", node);
407
473
  default:
408
474
  throw unsupportedSyntax(node.type, node);
409
475
  }
@@ -1311,6 +1377,8 @@ class Frame {
1311
1377
  return this.evaluateYieldExpression(node);
1312
1378
  case "NewExpression":
1313
1379
  return this.evaluateNewExpression(node);
1380
+ case "ImportExpression":
1381
+ return this.evaluateImportExpression(node);
1314
1382
  default:
1315
1383
  throw unsupportedSyntax(node.type, node);
1316
1384
  }
@@ -1625,6 +1693,22 @@ class Frame {
1625
1693
  }
1626
1694
  throw typeError("Update target must be an Identifier or MemberExpression.", argument);
1627
1695
  }
1696
+ // A module that fails to load rejects the promise, as a failed dynamic import does.
1697
+ *evaluateImportExpression(node) {
1698
+ const specifier = coerceToString(yield* this.evaluateExpression(node.source));
1699
+ if (node.options)
1700
+ yield* this.evaluateExpression(node.options);
1701
+ const promise = capability(this.ctx, node);
1702
+ try {
1703
+ promise.resolve(this.ctx.namespace(specifier, node));
1704
+ }
1705
+ catch (error) {
1706
+ if (!(error instanceof PendingThrow))
1707
+ throw error;
1708
+ promise.reject(error);
1709
+ }
1710
+ return promise.promise;
1711
+ }
1628
1712
  // EvaluateCall: a member callee supplies its base object as `this`; anything else calls with undefined.
1629
1713
  *evaluateCallExpression(node) {
1630
1714
  const callee = node.callee;
@@ -0,0 +1,4 @@
1
+ import { type Value } from "./objects.js";
2
+ /** `node:fs` names the same module as `fs`. */
3
+ export declare const moduleName: (specifier: string) => string;
4
+ export declare const resolveModule: (specifier: string, global: (name: string) => Value) => Value;
@@ -0,0 +1,33 @@
1
+ import { define, get, Obj } from "./objects.js";
2
+ /**
3
+ * What `import` and `require` load: a global, by the Node module name that provides it. `fs` loads the `fs` global
4
+ * and `crypto` the `crypto` global; the names below come from globals with different names. A module that would be
5
+ * empty isn't available.
6
+ */
7
+ const aliases = {
8
+ "fs/promises": (global) => {
9
+ const fs = global("fs");
10
+ return fs instanceof Obj ? get(fs, "promises") : undefined;
11
+ },
12
+ url: (global) => pick(global, ["URL", "URLSearchParams"]),
13
+ util: (global) => pick(global, ["TextEncoder", "TextDecoder"]),
14
+ buffer: (global) => pick(global, ["Buffer", "atob", "btoa"]),
15
+ };
16
+ /** `node:fs` names the same module as `fs`. */
17
+ export const moduleName = (specifier) => (specifier.startsWith("node:") ? specifier.slice(5) : specifier);
18
+ export const resolveModule = (specifier, global) => {
19
+ const name = moduleName(specifier);
20
+ return global(name) ?? aliases[name]?.(global);
21
+ };
22
+ function pick(global, names) {
23
+ const found = names.flatMap((name) => {
24
+ const value = global(name);
25
+ return value === undefined ? [] : [[name, value]];
26
+ });
27
+ if (found.length === 0)
28
+ return undefined;
29
+ const module = new Obj(null);
30
+ for (const [name, value] of found)
31
+ define(module, name, value);
32
+ return module;
33
+ }
@@ -3,8 +3,8 @@ import { Callable, define, get, hidden, Arr, Fn, Obj, PromiseObj, record } from
3
3
  import { constructor, fn, methods, native, receiver, requiresNew } from "./native.js";
4
4
  import { createAggregateErrorValue, materialize } from "./errors.js";
5
5
  import { describeValue, typeofValue } from "./references.js";
6
- import { isSupportedCallback } from "./callback.js";
7
- import { Interruption, normal, Task } from "./runner.js";
6
+ import { Interruption, isSupportedCallback } from "./callback.js";
7
+ import { normal, Task } from "./runner.js";
8
8
  // A `resolve`/`reject` handed to an executor or thenable: calling it settles the capability.
9
9
  const resolvingFunctions = (ctx, resolving) => ({
10
10
  resolve: fn(ctx.builtins, "resolve", 1, (_, args) => {
@@ -1,4 +1,4 @@
1
- import { Cause, type Context, Effect } from "effect";
1
+ import { type Context, Effect } from "effect";
2
2
  import type { Diagnostic } from "../codemode.js";
3
3
  import type { Interpreter } from "./interpreter.js";
4
4
  import { type AstNode, type GeneratorRequestKind } from "./model.js";
@@ -46,15 +46,6 @@ export declare class Host {
46
46
  readonly effect: Effect.Effect<unknown, unknown>;
47
47
  constructor(effect: Effect.Effect<unknown, unknown>);
48
48
  }
49
- /**
50
- * Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
51
- * it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
52
- * program's body interrupts the execution.
53
- */
54
- export declare class Interruption {
55
- readonly cause: Cause.Cause<unknown>;
56
- constructor(cause: Cause.Cause<unknown>);
57
- }
58
49
  /** Let the host run; the current job continues before any other job. */
59
50
  export declare const Slice: unique symbol;
60
51
  export type Signal = Call | Enter | Await | Yield | Host | typeof Slice;
@@ -110,7 +101,6 @@ export type Resolving = {
110
101
  type Job = () => Start | void;
111
102
  /** Most activations one task may hold, as the call-stack limit. */
112
103
  export declare const MAX_CALL_DEPTH = 10000;
113
- export declare const isEval: <A>(value: A | Eval<A>) => value is Eval<A>;
114
104
  /**
115
105
  * One execution's job queue. Program code runs only inside a job, one job at a time and each to completion, as in a
116
106
  * JavaScript engine: promise reactions and resumed awaits queue in order, host work runs concurrently and settles its
@@ -1,4 +1,5 @@
1
1
  import { Cause, Effect, Exit, Fiber } from "effect";
2
+ import { Interruption } from "./callback.js";
2
3
  import { locate, normalizeError } from "./errors.js";
3
4
  import { MAX_PENDING_PROMISES } from "./limits.js";
4
5
  import { PendingThrow, rangeError, Throw, typeError } from "./model.js";
@@ -48,17 +49,6 @@ export class Host {
48
49
  this.effect = effect;
49
50
  }
50
51
  }
51
- /**
52
- * Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
53
- * it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
54
- * program's body interrupts the execution.
55
- */
56
- export class Interruption {
57
- cause;
58
- constructor(cause) {
59
- this.cause = cause;
60
- }
61
- }
62
52
  /** Let the host run; the current job continues before any other job. */
63
53
  export const Slice = Symbol("codemode.slice");
64
54
  /** The boundary of an async body: the body's completion settles it, and the caller receives `result` at once. */
@@ -94,8 +84,6 @@ export const MAX_CALL_DEPTH = 10_000;
94
84
  /** Interpreter steps between clock checks, and how long one slice may run before the host gets a turn. */
95
85
  const FUEL = 64;
96
86
  const SLICE_MS = 1;
97
- // Program values never have a `next` method of their own: an object's properties live in its property map.
98
- export const isEval = (value) => typeof value === "object" && value !== null && typeof value.next === "function";
99
87
  /**
100
88
  * One execution's job queue. Program code runs only inside a job, one job at a time and each to completion, as in a
101
89
  * JavaScript engine: promise reactions and resumed awaits queue in order, host work runs concurrently and settles its
@@ -1,9 +1,8 @@
1
- import { applyCollectionCallback } from "../interpreter/callback.js";
1
+ import { applyCollectionCallback, Interruption } from "../interpreter/callback.js";
2
2
  import { rangeError, typeError } from "../interpreter/model.js";
3
3
  import { constructor, fn, methods, receiver, requiresNew } from "../interpreter/native.js";
4
4
  import { Arr, coerceToNumber, define, hasPrototype, hidden, iteratorResult, IteratorObj, Obj, } from "../interpreter/objects.js";
5
5
  import { describeValue } from "../interpreter/references.js";
6
- import { Interruption } from "../interpreter/runner.js";
7
6
  const finished = { done: true, value: undefined };
8
7
  // Every built-in iterator and helper shares the Iterator prototype; JS gives each collection its own, which is only
9
8
  // observable through getPrototypeOf.
@@ -0,0 +1,24 @@
1
+ import { Schema } from "effect";
2
+ import type { Snapshot } from "./vm/snapshot/snapshot.js";
3
+ declare const SuspendError_base: Schema.Class<SuspendError, Schema.TaggedStruct<"SuspendError", {
4
+ readonly message: Schema.String;
5
+ readonly running: Schema.$Array<Schema.Struct<{
6
+ readonly key: Schema.String;
7
+ readonly path: Schema.String;
8
+ }>>;
9
+ }>, import("effect/Cause").YieldableError>;
10
+ /**
11
+ * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
12
+ * path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
13
+ * saved or was too large.
14
+ */
15
+ export declare class SuspendError extends SuspendError_base {
16
+ }
17
+ export declare class SnapshotError extends Error {
18
+ readonly name = "SnapshotError";
19
+ }
20
+ /** A snapshot as bytes: UTF-8 JSON. */
21
+ export declare const toBytes: (snapshot: Snapshot) => Uint8Array;
22
+ /** Reads bytes `toBytes` wrote; `restore` checks what they hold. */
23
+ export declare const fromBytes: (bytes: Uint8Array) => unknown;
24
+ export {};
@@ -0,0 +1,25 @@
1
+ import { Schema } from "effect";
2
+ /**
3
+ * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
4
+ * path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
5
+ * saved or was too large.
6
+ */
7
+ export class SuspendError extends Schema.TaggedError()("SuspendError", {
8
+ message: Schema.String,
9
+ running: Schema.Array(Schema.Struct({ key: Schema.String, path: Schema.String })),
10
+ }) {
11
+ }
12
+ export class SnapshotError extends Error {
13
+ name = "SnapshotError";
14
+ }
15
+ /** A snapshot as bytes: UTF-8 JSON. */
16
+ export const toBytes = (snapshot) => new TextEncoder().encode(JSON.stringify(snapshot));
17
+ /** Reads bytes `toBytes` wrote; `restore` checks what they hold. */
18
+ export const fromBytes = (bytes) => {
19
+ try {
20
+ return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
21
+ }
22
+ catch (error) {
23
+ throw new SnapshotError(`Invalid snapshot: the bytes are not UTF-8 JSON (${String(error)}).`);
24
+ }
25
+ };
@@ -2,13 +2,13 @@ import { Effect } from "effect";
2
2
  import type { Json } from "./data.js";
3
3
  import type { DiagnosticKind } from "./codemode.js";
4
4
  import { type Namespace } from "./namespace.js";
5
- import { type Tool } from "./tool.js";
5
+ import { type Durable, type Idempotent, type Tool, type ToolContext } from "./tool.js";
6
6
  import type { Tools } from "./tools.js";
7
7
  export declare const compareText: (left: string, right: string) => -1 | 0 | 1;
8
8
  export type Services<T> = ServicesOf<T, []>;
9
9
  type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends {
10
10
  readonly _tag: "CodeModeTool";
11
- readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, infer R>;
11
+ readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, infer R>;
12
12
  } ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
13
13
  export type ToolCall = {
14
14
  readonly name: string;
@@ -17,8 +17,13 @@ export type ToolCall = {
17
17
  export type ToolInvocation = {
18
18
  readonly name: string;
19
19
  readonly input: unknown;
20
+ /** The call's idempotency key, `<runId>:<callId>`: the same at every hook, and across a suspended run's resumes. */
21
+ readonly key: string;
20
22
  };
21
- /** A call the program is making to an extension global, with its arguments. */
23
+ /**
24
+ * A call the program is making to an extension global or module function, with its arguments. A module function is
25
+ * named by its path from the module, such as `fs.readFile`.
26
+ */
22
27
  export type ExtensionInvocation = {
23
28
  readonly extension: string;
24
29
  readonly name: string;
@@ -41,8 +46,8 @@ export type Hooks<R = never> = {
41
46
  readonly "extension.before"?: ((call: ExtensionInvocation) => Effect.Effect<void, unknown, R>) | undefined;
42
47
  readonly "extension.after"?: ((call: ExtensionInvocation, result: CallResult) => Effect.Effect<void, never, R>) | undefined;
43
48
  };
44
- /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
45
- export declare const hooked: <Call, A, R>(call: Call, before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined, run: Effect.Effect<A, unknown, R>) => Effect.Effect<A, unknown, R>;
49
+ /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */
50
+ export declare const hooked: <Call, A, R>(call: Call, before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined, run: Effect.Effect<A, unknown, R>, detaching?: () => boolean) => Effect.Effect<A, unknown, R>;
46
51
  export type ToolDescription = {
47
52
  readonly path: string;
48
53
  readonly description: string;
@@ -78,13 +83,32 @@ export declare class ToolRuntimeError extends Error {
78
83
  readonly suggestions: ReadonlyArray<string>;
79
84
  constructor(kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "ToolCallLimitExceeded">, message: string, suggestions?: ReadonlyArray<string>);
80
85
  }
86
+ export type ExecuteCallOptions = {
87
+ readonly key?: string | undefined;
88
+ readonly admit?: ((name: string) => void) | undefined;
89
+ readonly detaching?: (() => boolean) | undefined;
90
+ };
81
91
  /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */
82
92
  export type ToolRuntime<R = never> = {
83
93
  readonly calls: Array<ToolCall>;
84
94
  readonly hooks: Hooks<R>;
85
- readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
86
- readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
95
+ readonly invocations: Map<string, ToolInvocation>;
96
+ readonly record: (name: string) => void;
97
+ readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
98
+ readonly search: (args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
87
99
  readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
100
+ /** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */
101
+ readonly mode: (path: ReadonlyArray<string>) => Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
102
+ /** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */
103
+ readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, admit?: (name: string) => void) => Effect.Effect<Json, unknown, R>;
104
+ /**
105
+ * Waits for a durable tool's running work: its output, as `execute` gives it. `detaching` says whether an
106
+ * interruption detaches to suspend the run, which `tool.after` doesn't see, or ends the call, which it sees as
107
+ * interrupted.
108
+ */
109
+ readonly wait: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, data: Json, detaching: () => boolean) => Effect.Effect<Json | undefined, unknown, R>;
110
+ /** Cancels a durable tool's started work when the run is interrupted or ends. */
111
+ readonly cancel: (path: ReadonlyArray<string>, data: Json) => Effect.Effect<void, unknown, R>;
88
112
  };
89
113
  /** Per-execution call state over tools prepared once for the runtime. */
90
114
  export declare const make: <R>(prepared: Prepared<R>, maxToolCalls: number | undefined, hooks?: Hooks<R>) => ToolRuntime<R>;