@opencode/codemode 0.0.0-dev-1179 → 0.0.0-dev-1189

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 (91) hide show
  1. package/README.md +6 -12
  2. package/dist/codemode.d.ts +7 -21
  3. package/dist/codemode.js +17 -38
  4. package/dist/extension.d.ts +1 -1
  5. package/dist/index.d.ts +1 -1
  6. package/dist/scan.js +2 -2
  7. package/dist/tool-runtime.d.ts +8 -11
  8. package/dist/tool-runtime.js +13 -11
  9. package/dist/tool.d.ts +18 -9
  10. package/dist/tool.js +15 -23
  11. package/dist/vm/data.d.ts +1 -1
  12. package/dist/vm/runtime/execute.d.ts +16 -6
  13. package/dist/vm/runtime/execute.js +10 -7
  14. package/dist/vm/snapshot/codec.d.ts +3 -2
  15. package/dist/vm/snapshot/codec.js +3 -2
  16. package/dist/vm/snapshot/snapshot.d.ts +6 -3
  17. package/dist/vm/snapshot/snapshot.js +13 -2
  18. package/dist/vm/vm.d.ts +2 -2
  19. package/package.json +3 -5
  20. package/dist/data.d.ts +0 -21
  21. package/dist/data.js +0 -93
  22. package/dist/interpreter/callback.d.ts +0 -35
  23. package/dist/interpreter/callback.js +0 -98
  24. package/dist/interpreter/errors.d.ts +0 -23
  25. package/dist/interpreter/errors.js +0 -173
  26. package/dist/interpreter/execute.d.ts +0 -14
  27. package/dist/interpreter/execute.js +0 -207
  28. package/dist/interpreter/extensions.d.ts +0 -9
  29. package/dist/interpreter/extensions.js +0 -248
  30. package/dist/interpreter/generators.d.ts +0 -3
  31. package/dist/interpreter/generators.js +0 -168
  32. package/dist/interpreter/globals.d.ts +0 -6
  33. package/dist/interpreter/globals.js +0 -144
  34. package/dist/interpreter/interpreter.d.ts +0 -48
  35. package/dist/interpreter/interpreter.js +0 -2253
  36. package/dist/interpreter/intrinsics.d.ts +0 -15
  37. package/dist/interpreter/intrinsics.js +0 -105
  38. package/dist/interpreter/limits.d.ts +0 -10
  39. package/dist/interpreter/limits.js +0 -19
  40. package/dist/interpreter/model.d.ts +0 -68
  41. package/dist/interpreter/model.js +0 -54
  42. package/dist/interpreter/modules.d.ts +0 -4
  43. package/dist/interpreter/modules.js +0 -33
  44. package/dist/interpreter/native.d.ts +0 -17
  45. package/dist/interpreter/native.js +0 -35
  46. package/dist/interpreter/objects.d.ts +0 -301
  47. package/dist/interpreter/objects.js +0 -592
  48. package/dist/interpreter/promises.d.ts +0 -18
  49. package/dist/interpreter/promises.js +0 -292
  50. package/dist/interpreter/references.d.ts +0 -8
  51. package/dist/interpreter/references.js +0 -51
  52. package/dist/interpreter/runner.d.ts +0 -178
  53. package/dist/interpreter/runner.js +0 -480
  54. package/dist/interpreter/scope.d.ts +0 -16
  55. package/dist/interpreter/scope.js +0 -79
  56. package/dist/stdlib/array.d.ts +0 -11
  57. package/dist/stdlib/array.js +0 -498
  58. package/dist/stdlib/bytes.d.ts +0 -10
  59. package/dist/stdlib/bytes.js +0 -253
  60. package/dist/stdlib/collections.d.ts +0 -7
  61. package/dist/stdlib/collections.js +0 -497
  62. package/dist/stdlib/console.d.ts +0 -6
  63. package/dist/stdlib/console.js +0 -93
  64. package/dist/stdlib/date.d.ts +0 -2
  65. package/dist/stdlib/date.js +0 -132
  66. package/dist/stdlib/headers.d.ts +0 -2
  67. package/dist/stdlib/headers.js +0 -110
  68. package/dist/stdlib/iterator.d.ts +0 -2
  69. package/dist/stdlib/iterator.js +0 -322
  70. package/dist/stdlib/json.d.ts +0 -3
  71. package/dist/stdlib/json.js +0 -58
  72. package/dist/stdlib/math.d.ts +0 -8
  73. package/dist/stdlib/math.js +0 -97
  74. package/dist/stdlib/number.d.ts +0 -3
  75. package/dist/stdlib/number.js +0 -72
  76. package/dist/stdlib/object.d.ts +0 -6
  77. package/dist/stdlib/object.js +0 -219
  78. package/dist/stdlib/regexp.d.ts +0 -7
  79. package/dist/stdlib/regexp.js +0 -114
  80. package/dist/stdlib/string.d.ts +0 -2
  81. package/dist/stdlib/string.js +0 -272
  82. package/dist/stdlib/url.d.ts +0 -13
  83. package/dist/stdlib/url.js +0 -255
  84. package/dist/stdlib/value.d.ts +0 -7
  85. package/dist/stdlib/value.js +0 -33
  86. package/dist/stdlib/web.d.ts +0 -5
  87. package/dist/stdlib/web.js +0 -97
  88. package/dist/suspend-error.d.ts +0 -24
  89. package/dist/suspend-error.js +0 -25
  90. package/dist/vm/index.d.ts +0 -6
  91. package/dist/vm/index.js +0 -6
package/README.md CHANGED
@@ -101,13 +101,9 @@ runs before the call reaches the host, and a failing one denies it: the host fun
101
101
  catches the failure as a thrown error. A denied call fails the way the call itself would: a tool call or asynchronous
102
102
  global rejects its promise, and a synchronous global throws.
103
103
 
104
- ### Bytecode VM and suspending/resuming a run (experimental, `engine: "vm"`)
104
+ ### Suspending and resuming a run
105
105
 
106
- Pass `engine: "vm"` to `CodeMode.make` or `CodeMode.execute` to run programs on the bytecode VM instead of the default
107
- `"legacy"` AST interpreter. `runtime.execute(code, bindings?)` keeps the same `Effect<CodeMode.Result>` signature on
108
- both engines.
109
-
110
- On `engine: "vm"`, `CodeMode.make` returns a `CodeMode.VmRuntime`, which can also run a program step by step:
106
+ `CodeMode.make` returns a `CodeMode.Runtime`, which can also run a program step by step:
111
107
  `runtime.program(code, bindings?, { runId }?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`. Every
112
108
  host call gets a stable key `<runId>:<callId>` (using a generated UUID when `runId` is omitted), saved in the snapshot
113
109
  and passed to tools as `execute(input, { key })` and to hooks as `call.key`. `run()` runs the program in the current
@@ -119,7 +115,7 @@ type Suspended = {
119
115
  state: CodeMode.Snapshot // JSON; CodeMode.toBytes / CodeMode.fromBytes convert it
120
116
  }
121
117
 
122
- const runtime = CodeMode.make({ tools, engine: "vm" })
118
+ const runtime = CodeMode.make({ tools })
123
119
 
124
120
  // inline
125
121
  const outcome = yield* runtime.program(code).run()
@@ -134,8 +130,7 @@ const outcome = yield* Fiber.join(fiber)
134
130
  yield* runtime.resume(CodeMode.toBytes(suspended.state)).run()
135
131
  ```
136
132
 
137
- The default runtime has no `program` or `resume`, and ignores `Tool.idempotent`, `Tool.durable`, and extension
138
- `snapshot` hooks. A program runs once: running it again is a defect, so make another with `runtime.program` or
133
+ A program runs once: running it again is a defect, so make another with `runtime.program` or
139
134
  `runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and every call in progress
140
135
  (and cancels any started durable tool work).
141
136
 
@@ -177,8 +172,7 @@ Tool.make({
177
172
  - **`Tool.idempotent(execute)`:** idempotent/read-only work safe to run again. If a suspend lands while the call is
178
173
  running, the VM detaches and interrupts it without firing `tool.after`, saves the call in the snapshot as queued, and
179
174
  re-runs it on resume with the same `key` without double-counting it against `maxToolCalls`.
180
- - **`Tool.durable({ start, wait, cancel })`:** work that outlives a suspended run (when run without a suspend or on the
181
- legacy engine, it runs `start` then `wait`):
175
+ - **`Tool.durable({ start, wait, cancel })`:** work that outlives a suspended run:
182
176
  - `start(input, { key }) => Effect<Data /* Json */>` begins the work and returns JSON `data` (inferred into `wait`
183
177
  and `cancel`);
184
178
  - `wait(data, { key }) => Effect<Output>` connects to the running work and waits for its result;
@@ -209,7 +203,7 @@ extensions (and the same extension `snapshot` hooks). The state is checked when
209
203
  fails with a `CodeMode.SnapshotError` when it can't be resumed here or is malformed. Built-ins are saved by name and
210
204
  only their changes are copied.
211
205
 
212
- Set `CODEMODE_ROUNDTRIP=1` (`bun run test:roundtrip`) to run the tests on the VM with every run saved to bytes and
206
+ Set `CODEMODE_ROUNDTRIP=1` (`bun run test:roundtrip`) to run the tests with every run saved to bytes and
213
207
  restored into a brand-new runtime at every host call and every few steps.
214
208
 
215
209
  ### `Extension.make`
@@ -1,13 +1,12 @@
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";
5
4
  import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js";
6
5
  import type { Tools } from "./tools.js";
7
- import type { VmEngine } from "./vm/index.js";
6
+ import { SuspendError } from "./vm/runtime/execute.js";
7
+ import { fromBytes, type Snapshot, SnapshotError, type SnapshotHeader, toBytes } from "./vm/snapshot/snapshot.js";
8
8
  export { fromBytes, scanTools, SnapshotError, SuspendError, toBytes };
9
- export type SnapshotHeader = VmEngine.SnapshotHeader;
10
- export type Snapshot = VmEngine.Snapshot;
9
+ export type { Snapshot, SnapshotHeader };
11
10
  /** A tool call admitted during an execution. */
12
11
  export type { CallResult, ExtensionInvocation, Hooks, ToolCall, ToolDescription, ToolInvocation, } from "./tool-runtime.js";
13
12
  /** Signature-construction helpers for host-owned catalog instructions. */
@@ -32,14 +31,12 @@ export type ResolvedExecutionLimits = {
32
31
  readonly maxToolCalls: number | undefined;
33
32
  readonly maxOutputBytes: number | undefined;
34
33
  };
35
- /** Execution engine: the default AST generator interpreter (`"legacy"`) or the experimental bytecode VM (`"vm"`). */
36
- export type Engine = "legacy" | "vm";
37
- /** Options for `VmRuntime.program`. */
34
+ /** Options for `Runtime.program`. */
38
35
  export type ProgramOptions = {
39
36
  /** Names this run's host calls (`<runId>:<callId>`); a random UUID by default. */
40
37
  readonly runId?: string;
41
38
  };
42
- /** How `program.suspend` saves a run's state (`engine: "vm"` only). */
39
+ /** How `program.suspend` saves a run's state. */
43
40
  export type SuspendOptions = {
44
41
  /** The most bytes a saved state may take; a larger one fails the suspend, and the run goes on. */
45
42
  readonly maxBytes?: number;
@@ -54,11 +51,6 @@ export type Options<Provided extends Record<string, unknown> = {}, Extensions ex
54
51
  extensions?: Extensions;
55
52
  /** Resource limits enforced on each execution. Time counts active time only, across every resume of a run. */
56
53
  limits?: ExecutionLimits;
57
- /**
58
- * Interpreter that runs programs. `"vm"` is the experimental bytecode VM, whose runtime (`VmRuntime`) can also
59
- * suspend and resume runs; the default is `"legacy"`.
60
- */
61
- engine?: Engine;
62
54
  };
63
55
  /** The Effect environment an execution needs: what the tools and the extensions' Effect globals require. */
64
56
  export type Environment<Provided extends Record<string, unknown>, Extensions extends ReadonlyArray<Extension>> = Services<Provided> | Extension.Services<Extensions[number]>;
@@ -166,20 +158,17 @@ export declare const Result: Schema.Union<readonly [Schema.Struct<{
166
158
  }>]>;
167
159
  /** Result of executing a CodeMode program. Program failures are data, not Effect failures. */
168
160
  export type Result = typeof Result.Type;
169
- /** A run stopped by `program.suspend`: its whole state, to resume with `VmRuntime.resume`. */
161
+ /** A run stopped by `program.suspend`: its whole state, to resume with `Runtime.resume`. */
170
162
  export type Suspended = {
171
163
  readonly ok: "suspended";
172
164
  readonly state: Snapshot;
173
165
  };
174
166
  /** How a run of a program ended: its result, or its saved state once suspended. */
175
167
  export type Outcome = Result | Suspended;
176
- /** Reusable confined runtime over explicit tools. */
168
+ /** Reusable confined runtime over explicit tools and extensions. */
177
169
  export type Runtime<R = never> = {
178
170
  readonly catalog: ReadonlyArray<ToolDescription>;
179
171
  readonly execute: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Effect.Effect<Result, never, R>;
180
- };
181
- /** A runtime on the bytecode VM (`engine: "vm"`, experimental): it can also suspend runs and resume them. */
182
- export type VmRuntime<R = never> = Runtime<R> & {
183
172
  /** A program ready to run once; nothing runs until `program.run()`. */
184
173
  readonly program: (code: string, bindings?: Readonly<Record<string, DataValue>>, options?: ProgramOptions) => Program<R>;
185
174
  /**
@@ -206,7 +195,4 @@ export type Program<R = never, E = never> = {
206
195
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
207
196
  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>>;
208
197
  /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
209
- export declare function make<const Provided extends Record<string, unknown> = {}, const Extensions extends ReadonlyArray<Extension> = []>(options: Options<Provided, Extensions> & {
210
- engine: "vm";
211
- }): VmRuntime<Environment<Provided, Extensions>>;
212
198
  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,11 @@
1
1
  import { Deferred, Effect, Exit, Schema } from "effect";
2
- import { fromJson } from "./data.js";
3
- import { executeProgram } from "./interpreter/execute.js";
4
- import { extensionGlobals } from "./interpreter/extensions.js";
5
- import { globalNames } from "./interpreter/globals.js";
6
2
  import { scanTools } from "./scan.js";
7
- import { fromBytes, SnapshotError, SuspendError, toBytes } from "./suspend-error.js";
8
3
  import { ToolRuntime } from "./tool-runtime.js";
4
+ import { fromJson } from "./vm/data.js";
5
+ import { finishExecution, resumeProgram, startProgram, SuspendError } from "./vm/runtime/execute.js";
6
+ import { extensionGlobals } from "./vm/runtime/extensions.js";
7
+ import { globalNames } from "./vm/runtime/globals.js";
8
+ import { fromBytes, SnapshotError, toBytes } from "./vm/snapshot/snapshot.js";
9
9
  export { fromBytes, scanTools, SnapshotError, SuspendError, toBytes };
10
10
  /** Signature-construction helpers for host-owned catalog instructions. */
11
11
  export { searchSignature, toolExpression } from "./tool-runtime.js";
@@ -61,11 +61,11 @@ const resolveExecutionLimits = (limits) => ({
61
61
  });
62
62
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
63
63
  export const execute = (options) => make(options).execute(options.code, options.bindings);
64
+ /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
64
65
  export function make(options = {}) {
65
66
  const prepared = ToolRuntime.prepare((options.tools ?? {}));
66
67
  const limits = resolveExecutionLimits(options.limits);
67
68
  const extensions = options.extensions ?? [];
68
- // Both engines bind the same global names; test/engines.test.ts keeps them in step.
69
69
  const bound = new Set(globalNames);
70
70
  for (const extension of extensions) {
71
71
  for (const name of Object.keys(extension.globals)) {
@@ -74,40 +74,28 @@ export function make(options = {}) {
74
74
  bound.add(name);
75
75
  }
76
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 ??= {
77
+ const setup = {
90
78
  prepared,
91
79
  limits,
92
80
  hooks: options.hooks ?? {},
93
- globals: extensions.length === 0 ? undefined : (ctx) => vm.extensionGlobals(ctx, extensions),
81
+ globals: extensions.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, extensions),
94
82
  lossy: extensions.some((extension) => extension.snapshot === undefined),
95
- });
96
- const data = (vm, bindings) => bindings === undefined
83
+ };
84
+ const data = (bindings) => bindings === undefined
97
85
  ? undefined
98
- : (ctx) => Object.entries(bindings).map(([name, value]) => [name, vm.fromJson(ctx, value)]);
99
- const program = (code, bindings, programOptions) => vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings), programOptions?.runId)));
86
+ : (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]);
87
+ const program = (code, bindings, programOptions) => makeProgram(() => Effect.succeed(startProgram(setup, code, data(bindings), programOptions?.runId)));
100
88
  return {
101
89
  get catalog() {
102
90
  return prepared.catalog;
103
91
  },
104
- execute: (code, bindings) => Effect.flatMap(loadVm(), (vm) => vm.finishExecution(program(code, bindings).run())),
92
+ execute: (code, bindings) => Effect.suspend(() => finishExecution(program(code, bindings).run())),
105
93
  program,
106
- resume: (state) => vmProgram((vm) => vm.resumeProgram(getSetup(vm), state)),
94
+ resume: (state) => makeProgram(() => resumeProgram(setup, state)),
107
95
  };
108
96
  }
109
- // A program's one run: `start` makes it once the VM is loaded, and a suspend waits for it.
110
- const vmProgram = (start) => {
97
+ // A program's one run: `start` makes it when `run()` is called, and a suspend waits for it.
98
+ const makeProgram = (start) => {
111
99
  let claimed = false;
112
100
  const started = Deferred.makeUnsafe();
113
101
  return {
@@ -116,7 +104,7 @@ const vmProgram = (start) => {
116
104
  return Effect.die(new Error("A CodeMode program runs once; make another with runtime.program or runtime.resume."));
117
105
  }
118
106
  claimed = true;
119
- return loadVm().pipe(Effect.flatMap(start), Effect.onExit((exit) => Exit.isSuccess(exit)
107
+ return start().pipe(Effect.onExit((exit) => Exit.isSuccess(exit)
120
108
  ? Deferred.succeed(started, exit.value)
121
109
  : Deferred.fail(started, new SuspendError({ message: "The program didn't start.", running: [] }))), Effect.flatMap((running) => running.run()));
122
110
  }),
@@ -129,12 +117,3 @@ const vmProgram = (start) => {
129
117
  },
130
118
  };
131
119
  };
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
- })));
@@ -16,7 +16,7 @@ import type { Effect } from "effect";
16
16
  export type Extension<Globals extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
17
17
  readonly name: string;
18
18
  readonly globals: Globals;
19
- /** How a suspended run saves the values this extension's functions returned (`engine: "vm"` only); see `Snapshot`. */
19
+ /** How a suspended run saves the values this extension's functions returned; see `Snapshot`. */
20
20
  readonly snapshot?: Snapshot | undefined;
21
21
  };
22
22
  /**
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 { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, type Outcome, type Program, type ProgramOptions, type Snapshot, type SnapshotHeader, type Suspended, type SuspendOptions, type VmRuntime, } from "./codemode.js";
6
+ export { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, type Outcome, type Program, type ProgramOptions, type Runtime, type Snapshot, type SnapshotHeader, type Suspended, type SuspendOptions, } from "./codemode.js";
7
7
  export { ToolError, toolError } from "./tool-error.js";
package/dist/scan.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { Result } from "effect";
2
- import { parseProgram } from "./interpreter/execute.js";
3
- import { formatLocation } from "./interpreter/model.js";
2
+ import { parseProgram } from "./vm/runtime/execute.js";
3
+ import { formatLocation } from "./vm/runtime/model.js";
4
4
  /**
5
5
  * Extracts every `tools.<path>` referenced by a Code Mode program, in first-seen order. Fails on syntax errors,
6
6
  * dynamic bracket access (`tools[name]`), or aliasing/passing `tools` rather than calling `tools.<path>(...)` directly.
@@ -1,15 +1,12 @@
1
1
  import { Effect } from "effect";
2
- import type { Json } from "./data.js";
2
+ import type { Json } from "./vm/data.js";
3
3
  import type { DiagnosticKind } from "./codemode.js";
4
4
  import { type Namespace } from "./namespace.js";
5
- import { type Durable, type Idempotent, type Tool, type ToolContext } from "./tool.js";
5
+ import { type Durable, type Idempotent, type Tool } 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
- type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends {
10
- readonly _tag: "CodeModeTool";
11
- readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, infer R>;
12
- } ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
9
+ type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends Tool<infer R> ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
13
10
  export type ToolCall = {
14
11
  readonly name: string;
15
12
  };
@@ -88,8 +85,8 @@ export declare class ToolRuntimeError extends Error {
88
85
  constructor(kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "ToolCallLimitExceeded">, message: string, suggestions?: ReadonlyArray<string>);
89
86
  }
90
87
  export type ExecuteCallOptions = {
91
- readonly key?: string | undefined;
92
- readonly admit?: ((name: string) => void) | undefined;
88
+ readonly key: string;
89
+ readonly admit: (name: string) => void;
93
90
  readonly detaching?: (() => boolean) | undefined;
94
91
  };
95
92
  /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */
@@ -98,13 +95,13 @@ export type ToolRuntime<R = never> = {
98
95
  readonly hooks: Hooks<R>;
99
96
  readonly invocations: Map<string, ToolInvocation>;
100
97
  readonly record: (name: string) => void;
101
- readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
102
- readonly search: (args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
98
+ readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>, options: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
99
+ readonly search: (args: Array<Json | undefined>, options: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
103
100
  readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
104
101
  /** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */
105
102
  readonly mode: (path: ReadonlyArray<string>) => Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
106
103
  /** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */
107
- readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, admit?: (name: string) => void) => Effect.Effect<Json, unknown, R>;
104
+ readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, admit: (name: string) => void) => Effect.Effect<Json, unknown, R>;
108
105
  /**
109
106
  * Waits for a durable tool's running work: its output, as `execute` gives it. `detaching` says whether an
110
107
  * interruption detaches to suspend the run, which `tool.after` doesn't see, or ends the call, which it sees as
@@ -416,8 +416,6 @@ export const make = (prepared, maxToolCalls, hooks = {}) => {
416
416
  const calls = [];
417
417
  const invocations = new Map();
418
418
  const root = prepared.root;
419
- const runId = crypto.randomUUID();
420
- let nextCallId = 0;
421
419
  const recordCall = (call) => {
422
420
  if (maxToolCalls !== undefined && calls.length >= maxToolCalls) {
423
421
  throw new ToolRuntimeError("ToolCallLimitExceeded", `Execution exceeded its tool-call limit of ${maxToolCalls}.`);
@@ -452,23 +450,26 @@ export const make = (prepared, maxToolCalls, hooks = {}) => {
452
450
  catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
453
451
  });
454
452
  const executeTool = (name, tool, args, options) => Effect.gen(function* () {
455
- const key = options?.key ?? `${runId}:${nextCallId++}`;
453
+ if ("_tag" in tool.execute && tool.execute._tag === "CodeModeDurable") {
454
+ throw new TypeError(`Tool '${name}' is a durable tool; start it with ToolRuntime.start.`);
455
+ }
456
+ const run = "_tag" in tool.execute ? tool.execute.execute : tool.execute;
457
+ const key = options.key;
456
458
  const input = yield* decode(name, tool, args);
457
- const admit = options?.admit;
458
- yield* Effect.sync(() => (admit !== undefined ? admit(name) : recordCall({ name })));
459
+ yield* Effect.sync(() => options.admit(name));
459
460
  return yield* hooked({ name, input, key }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
460
- const raw = yield* failure(Effect.suspend(() => tool.execute(input, { key })));
461
+ const raw = yield* failure(Effect.suspend(() => run(input, { key })));
461
462
  return yield* output(name, tool, raw);
462
- }), options?.detaching);
463
+ }), options.detaching);
463
464
  });
464
465
  const durableTool = (path) => {
465
466
  const segments = canonicalSegments(path);
466
467
  const name = segments.join(".");
467
468
  const tool = lookup(root, segments)?.tool;
468
- if (tool?.mode?._tag !== "CodeModeDurable") {
469
+ if (tool === undefined || !("_tag" in tool.execute) || tool.execute._tag !== "CodeModeDurable") {
469
470
  throw new TypeError(`Tool '${name}' is not a durable tool.`);
470
471
  }
471
- return { name, tool, durable: tool.mode };
472
+ return { name, tool, durable: tool.execute };
472
473
  };
473
474
  return {
474
475
  calls,
@@ -488,13 +489,14 @@ export const make = (prepared, maxToolCalls, hooks = {}) => {
488
489
  const segments = canonicalSegments(path);
489
490
  if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
490
491
  return undefined;
491
- return lookup(root, segments)?.tool?.mode;
492
+ const execute = lookup(root, segments)?.tool?.execute;
493
+ return execute !== undefined && "_tag" in execute ? execute : undefined;
492
494
  },
493
495
  start: (path, args, key, admit) => Effect.suspend(() => {
494
496
  const found = durableTool(path);
495
497
  return Effect.gen(function* () {
496
498
  const input = yield* decode(found.name, found.tool, args);
497
- yield* Effect.sync(() => (admit !== undefined ? admit(found.name) : recordCall({ name: found.name })));
499
+ yield* Effect.sync(() => admit(found.name));
498
500
  const invocation = { name: found.name, input, key };
499
501
  invocations.set(key, invocation);
500
502
  const before = hooks["tool.before"];
package/dist/tool.d.ts CHANGED
@@ -44,12 +44,11 @@ export type ToolContext = {
44
44
  };
45
45
  export type ExecuteFn<Input = unknown, Output = unknown, R = never> = (input: Input, context: ToolContext) => Effect.Effect<Output, unknown, R>;
46
46
  /**
47
- * A tool execution wrapper for idempotent work that is safe to run again. If a suspend lands while the call is running
48
- * (`engine: "vm"`), the VM interrupts it without firing `tool.after`, keeps the call queued in the snapshot, and
49
- * re-runs it on resume with the same `key` without double-counting against `maxToolCalls`.
47
+ * A tool execution wrapper for idempotent work that is safe to run again. If a suspend lands while the call is running,
48
+ * the VM interrupts it without firing `tool.after`, keeps the call queued in the snapshot, and re-runs it on resume
49
+ * with the same `key` without double-counting against `maxToolCalls`.
50
50
  */
51
51
  export type Idempotent<Input = unknown, Output = unknown, R = never> = {
52
- (input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>;
53
52
  readonly _tag: "CodeModeIdempotent";
54
53
  readonly execute: ExecuteFn<Input, Output, R>;
55
54
  };
@@ -67,6 +66,17 @@ export type DurableOptions<Data extends Schema.Json, Input = unknown, Output = u
67
66
  };
68
67
  /** A tool execution wrapper for work that keeps running across a suspend and reconnects through its JSON data. */
69
68
  export type Durable<Input = unknown, Output = unknown, R = never> = {
69
+ readonly _tag: "CodeModeDurable";
70
+ readonly start: (input: Input, context: ToolContext) => Effect.Effect<Schema.Json, unknown, R>;
71
+ readonly wait: (data: never, context: ToolContext) => Effect.Effect<Output, unknown, R>;
72
+ readonly cancel: (data: never) => Effect.Effect<void, unknown, R>;
73
+ };
74
+ type IdempotentOption<Input = unknown, Output = unknown, R = never> = {
75
+ (input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>;
76
+ readonly _tag: "CodeModeIdempotent";
77
+ readonly execute: ExecuteFn<Input, Output, R>;
78
+ };
79
+ type DurableOption<Input = unknown, Output = unknown, R = never> = {
70
80
  (input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>;
71
81
  readonly _tag: "CodeModeDurable";
72
82
  readonly start: (input: Input, context: ToolContext) => Effect.Effect<Schema.Json, unknown, R>;
@@ -80,8 +90,7 @@ export type Tool<R = never> = {
80
90
  readonly input: SchemaType;
81
91
  readonly freeform?: boolean;
82
92
  readonly output: SchemaType | undefined;
83
- readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, R>;
84
- readonly mode?: Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
93
+ readonly execute: ExecuteFn<unknown, unknown, R> | Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R>;
85
94
  };
86
95
  type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown;
87
96
  type ResultType<S> = S extends undefined ? void : S extends Schema.Decoder<unknown> ? S["Encoded"] : unknown;
@@ -95,16 +104,16 @@ export type Options<I extends SchemaType, O extends SchemaType | undefined, R =
95
104
  */
96
105
  readonly freeform?: boolean;
97
106
  readonly output?: O;
98
- readonly execute: ExecuteFn<InputType<I>, ResultType<O>, R> | Idempotent<InputType<I>, ResultType<O>, R> | Durable<InputType<I>, ResultType<O>, R>;
107
+ readonly execute: ExecuteFn<InputType<I>, ResultType<O>, R> | IdempotentOption<InputType<I>, ResultType<O>, R> | DurableOption<InputType<I>, ResultType<O>, R>;
99
108
  };
100
109
  export declare const isTool: <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined) => value is Tool<R>;
101
110
  /** Marks a tool's `execute` function as safe to interrupt on suspend and re-run on resume with the same key. */
102
- export declare const idempotent: <Input, Output, R = never>(execute: ExecuteFn<Input, Output, R>) => Idempotent<Input, Output, R>;
111
+ export declare const idempotent: <Input, Output, R = never>(execute: ExecuteFn<Input, Output, R>) => IdempotentOption<Input, Output, R>;
103
112
  /**
104
113
  * Wraps a tool's execution as `start`, `wait`, and `cancel` so work started before a suspend keeps running and
105
114
  * reconnects through its JSON data on resume.
106
115
  */
107
- export declare const durable: <Data extends Schema.Json, Input = unknown, Output = unknown, RStart = never, RWait = never, RCancel = never>(options: DurableOptions<Data, Input, Output, RStart, RWait, RCancel>) => Durable<Input, Output, RStart | RWait | RCancel>;
116
+ export declare const durable: <Data extends Schema.Json, Input = unknown, Output = unknown, RStart = never, RWait = never, RCancel = never>(options: DurableOptions<Data, Input, Output, RStart, RWait, RCancel>) => DurableOption<Input, Output, RStart | RWait | RCancel>;
108
117
  /**
109
118
  * Declares one schema-described tool available to a CodeMode program through `tools.*`.
110
119
  *
package/dist/tool.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { Effect, Schema } from "effect";
2
2
  export const isTool = (value) => value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool";
3
3
  /** Marks a tool's `execute` function as safe to interrupt on suspend and re-run on resume with the same key. */
4
- export const idempotent = (execute) => Object.assign((input, context) => execute(input, context), {
4
+ export const idempotent = (execute) => ({
5
5
  _tag: "CodeModeIdempotent",
6
6
  execute,
7
7
  });
@@ -9,15 +9,12 @@ export const idempotent = (execute) => Object.assign((input, context) => execute
9
9
  * Wraps a tool's execution as `start`, `wait`, and `cancel` so work started before a suspend keeps running and
10
10
  * reconnects through its JSON data on resume.
11
11
  */
12
- export const durable = (options) => {
13
- const wait = options.wait;
14
- return Object.assign((input, context) => Effect.flatMap(options.start(input, context), (data) => wait(data, context)), {
15
- _tag: "CodeModeDurable",
16
- start: options.start,
17
- wait: options.wait,
18
- cancel: options.cancel,
19
- });
20
- };
12
+ export const durable = (options) => ({
13
+ _tag: "CodeModeDurable",
14
+ start: options.start,
15
+ wait: options.wait,
16
+ cancel: options.cancel,
17
+ });
21
18
  /**
22
19
  * Declares one schema-described tool available to a CodeMode program through `tools.*`.
23
20
  *
@@ -25,16 +22,11 @@ export const durable = (options) => {
25
22
  * Without `output`, results are exposed as `void`. Hosts remain responsible for authorization
26
23
  * and durable side effects.
27
24
  */
28
- export const make = (options) => {
29
- const spec = options.execute;
30
- const mode = "_tag" in spec ? spec : undefined;
31
- return {
32
- _tag: "CodeModeTool",
33
- description: options.description,
34
- input: options.input,
35
- ...(options.freeform && { freeform: true }),
36
- output: options.output,
37
- ...(mode === undefined ? {} : { mode }),
38
- execute: (input, context = { key: crypto.randomUUID() }) => spec(input, context),
39
- };
40
- };
25
+ export const make = (options) => ({
26
+ _tag: "CodeModeTool",
27
+ description: options.description,
28
+ input: options.input,
29
+ ...(options.freeform && { freeform: true }),
30
+ output: options.output,
31
+ execute: options.execute,
32
+ });
package/dist/vm/data.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export * as Data from "./data.js";
2
- import type { Json } from "../data.js";
2
+ import type { Json } from "./snapshot/codec.js";
3
3
  import type { Interpreter } from "./runtime/interpreter.js";
4
4
  import { type Value } from "./runtime/objects.js";
5
5
  export type { Json };
@@ -1,13 +1,25 @@
1
1
  import { type Program } from "acorn";
2
- import { Effect } from "effect";
3
- import type { DataValue, Diagnostic, Outcome, ResolvedExecutionLimits, Result } from "../../codemode.js";
4
- import type { Extension } from "../../extension.js";
2
+ import { Cause, Effect, Schema } from "effect";
3
+ import type { Diagnostic, Outcome, ResolvedExecutionLimits, Result } from "../../codemode.js";
5
4
  import { type Snapshot, SnapshotError } from "../snapshot/snapshot.js";
6
5
  import { ToolRuntime } from "../../tool-runtime.js";
7
- import { SuspendError } from "../../suspend-error.js";
8
6
  import { Interpreter } from "./interpreter.js";
9
7
  import type { Value } from "./objects.js";
10
8
  import { Source } from "./source.js";
9
+ declare const SuspendError_base: Schema.Class<SuspendError, Schema.TaggedStruct<"SuspendError", {
10
+ readonly message: Schema.String;
11
+ readonly running: Schema.$Array<Schema.Struct<{
12
+ readonly key: Schema.String;
13
+ readonly path: Schema.String;
14
+ }>>;
15
+ }>, Cause.YieldableError>;
16
+ /**
17
+ * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
18
+ * path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
19
+ * saved or was too large.
20
+ */
21
+ export declare class SuspendError extends SuspendError_base {
22
+ }
11
23
  type Globals<R> = (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>;
12
24
  /** How a runtime runs programs: its tools, limits, hooks, and host globals, shared by every run it starts. */
13
25
  export type Setup<R> = {
@@ -21,8 +33,6 @@ export type Setup<R> = {
21
33
  };
22
34
  /** Turns a suspended outcome into a failure, for callers that only run programs to their end. */
23
35
  export declare const finishExecution: <E, R>(outcome: Effect.Effect<Outcome, E, R>) => Effect.Effect<Result, E, R>;
24
- /** Runs a program on the VM with `CodeMode.make`'s extensions and JSON bindings. */
25
- export declare const execute: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.Hooks<R>, extensions: ReadonlyArray<Extension>, bindings: Readonly<Record<string, DataValue>> | undefined) => Effect.Effect<Result, never, R>;
26
36
  export declare const executeProgram: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.Hooks<R>, globals?: Globals<R>, bindings?: Globals<R>, lossy?: boolean) => Effect.Effect<Result, never, R>;
27
37
  /** A program ready to run on the VM: nothing runs until `run`. */
28
38
  export declare const startProgram: <R>(setup: Setup<R>, code: string, bindings?: Globals<R>, runId?: string) => Running<R>;
@@ -1,17 +1,24 @@
1
1
  import { parse } from "acorn";
2
2
  import { Cause, Deferred, Effect, Option, Schema } from "effect";
3
- import { fromJson } from "../data.js";
4
3
  import { fromBytes, header, SnapshotError, toBytes } from "../snapshot/snapshot.js";
5
4
  import { ToolRuntime } from "../../tool-runtime.js";
6
- import { SuspendError } from "../../suspend-error.js";
7
5
  import { normalizeError } from "./errors.js";
8
- import { extensionGlobals } from "./extensions.js";
9
6
  import { createBuiltins } from "./intrinsics.js";
10
7
  import { Interpreter } from "./interpreter.js";
11
8
  import { formatLocation, sourceLocation } from "./model.js";
12
9
  import { callPath, Driver, SUSPENDED } from "./driver.js";
13
10
  import { Interruption } from "./signals.js";
14
11
  import { Source } from "./source.js";
12
+ /**
13
+ * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
14
+ * path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
15
+ * saved or was too large.
16
+ */
17
+ export class SuspendError extends Schema.TaggedError()("SuspendError", {
18
+ message: Schema.String,
19
+ running: Schema.Array(Schema.Struct({ key: Schema.String, path: Schema.String })),
20
+ }) {
21
+ }
15
22
  /** Turns a suspended outcome into a failure, for callers that only run programs to their end. */
16
23
  export const finishExecution = (outcome) => Effect.map(outcome, (outcome) => {
17
24
  if (outcome.ok !== "suspended")
@@ -22,10 +29,6 @@ export const finishExecution = (outcome) => Effect.map(outcome, (outcome) => {
22
29
  toolCalls: outcome.state.header.toolCalls,
23
30
  };
24
31
  });
25
- /** Runs a program on the VM with `CodeMode.make`'s extensions and JSON bindings. */
26
- export const execute = (code, prepared, limits, hooks, extensions, bindings) => executeProgram(code, prepared, limits, hooks, extensions.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, extensions), bindings === undefined
27
- ? undefined
28
- : (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]), extensions.some((extension) => extension.snapshot === undefined));
29
32
  export const executeProgram = (code, prepared, limits, hooks, globals, bindings, lossy = false) => finishExecution(startProgram({ prepared, limits, hooks, globals, lossy }, code, bindings).run());
30
33
  /** A program ready to run on the VM: nothing runs until `run`. */
31
34
  export const startProgram = (setup, code, bindings, runId = crypto.randomUUID()) => new Running(setup, 0, () => {
@@ -22,8 +22,9 @@ export type Record = {
22
22
  readonly [field: string]: Json;
23
23
  };
24
24
  /** A saved state can't be read, or doesn't fit this runtime. */
25
- import { SnapshotError } from "../../suspend-error.js";
26
- export { SnapshotError };
25
+ export declare class SnapshotError extends Error {
26
+ readonly name = "SnapshotError";
27
+ }
27
28
  /**
28
29
  * Where a function inside a value an extension returned came from, so a saved state can name it instead of losing it:
29
30
  * the extension, the value its function returned (`root`), which the extension's `snapshot` hooks save, and the path
@@ -9,8 +9,9 @@ import { TextDecoderObj } from "../stdlib/bytes.js";
9
9
  import { ToolError, toolError } from "../../tool-error.js";
10
10
  import { ToolReference, ToolRuntimeError } from "../../tool-runtime.js";
11
11
  /** A saved state can't be read, or doesn't fit this runtime. */
12
- import { SnapshotError } from "../../suspend-error.js";
13
- export { SnapshotError };
12
+ export class SnapshotError extends Error {
13
+ name = "SnapshotError";
14
+ }
14
15
  // --- Registries ---
15
16
  const symbols = new Map([
16
17
  ["iterator", IteratorSymbol],
@@ -1,8 +1,11 @@
1
1
  import type { Interpreter } from "../runtime/interpreter.js";
2
2
  import type { ToolCall } from "../../tool-runtime.js";
3
- import { fromBytes, SnapshotError, toBytes } from "../../suspend-error.js";
4
- import type { Encoded, Record } from "./codec.js";
5
- export { fromBytes, SnapshotError, toBytes };
3
+ import { type Encoded, type Record, SnapshotError } from "./codec.js";
4
+ export { SnapshotError };
5
+ /** A snapshot as bytes: UTF-8 JSON. */
6
+ export declare const toBytes: (snapshot: Snapshot) => Uint8Array;
7
+ /** Reads bytes `toBytes` wrote; `restore` checks what they hold. */
8
+ export declare const fromBytes: (bytes: Uint8Array) => unknown;
6
9
  /** The snapshot format this build writes and reads: the bytecode VM's (see `src/vm/snapshot.ts`). */
7
10
  export declare const FORMAT = 2;
8
11
  /**