@opencode/codemode 2.2.6 → 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.
- package/README.md +109 -21
- package/dist/codemode.d.ts +6 -1
- package/dist/codemode.js +2 -2
- package/dist/extension.d.ts +13 -0
- package/dist/extension.js +5 -1
- package/dist/index.d.ts +1 -1
- package/dist/interpreter/callback.d.ts +12 -1
- package/dist/interpreter/callback.js +13 -1
- package/dist/interpreter/interpreter.js +2 -2
- package/dist/interpreter/promises.js +2 -2
- package/dist/interpreter/runner.d.ts +1 -11
- package/dist/interpreter/runner.js +1 -13
- package/dist/stdlib/iterator.js +1 -2
- package/dist/suspend-error.d.ts +3 -2
- package/dist/suspend-error.js +3 -3
- package/dist/tool-runtime.d.ts +27 -6
- package/dist/tool-runtime.js +116 -26
- package/dist/tool.d.ts +45 -2
- package/dist/tool.js +30 -7
- package/dist/vm/host.d.ts +4 -1
- package/dist/vm/host.js +9 -4
- package/dist/vm/runtime/driver.d.ts +17 -7
- package/dist/vm/runtime/driver.js +89 -19
- package/dist/vm/runtime/execute.d.ts +1 -1
- package/dist/vm/runtime/execute.js +35 -7
- package/dist/vm/runtime/extensions.d.ts +1 -1
- package/dist/vm/runtime/extensions.js +82 -15
- package/dist/vm/runtime/interpreter.d.ts +3 -0
- package/dist/vm/runtime/interpreter.js +2 -0
- package/dist/vm/scheduler.d.ts +15 -3
- package/dist/vm/scheduler.js +13 -2
- package/dist/vm/snapshot/codec.d.ts +31 -1
- package/dist/vm/snapshot/codec.js +100 -3
- package/dist/vm/snapshot/snapshot.d.ts +5 -1
- package/dist/vm/snapshot/snapshot.js +5 -1
- package/dist/vm/snapshot.js +4 -1
- package/dist/vm/vm.d.ts +1 -0
- package/package.json +3 -3
|
@@ -9,7 +9,7 @@ import { extensionGlobals } from "./extensions.js";
|
|
|
9
9
|
import { createBuiltins } from "./intrinsics.js";
|
|
10
10
|
import { Interpreter } from "./interpreter.js";
|
|
11
11
|
import { formatLocation, sourceLocation } from "./model.js";
|
|
12
|
-
import { Driver, SUSPENDED } from "./driver.js";
|
|
12
|
+
import { callPath, Driver, SUSPENDED } from "./driver.js";
|
|
13
13
|
import { Interruption } from "./signals.js";
|
|
14
14
|
import { Source } from "./source.js";
|
|
15
15
|
/** Turns a suspended outcome into a failure, for callers that only run programs to their end. */
|
|
@@ -25,10 +25,10 @@ export const finishExecution = (outcome) => Effect.map(outcome, (outcome) => {
|
|
|
25
25
|
/** Runs a program on the VM with `CodeMode.make`'s extensions and JSON bindings. */
|
|
26
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
27
|
? undefined
|
|
28
|
-
: (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]), extensions.
|
|
28
|
+
: (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]), extensions.some((extension) => extension.snapshot === undefined));
|
|
29
29
|
export const executeProgram = (code, prepared, limits, hooks, globals, bindings, lossy = false) => finishExecution(startProgram({ prepared, limits, hooks, globals, lossy }, code, bindings).run());
|
|
30
30
|
/** A program ready to run on the VM: nothing runs until `run`. */
|
|
31
|
-
export const startProgram = (setup, code, bindings) => new Running(setup, 0, () => {
|
|
31
|
+
export const startProgram = (setup, code, bindings, runId = crypto.randomUUID()) => new Running(setup, 0, () => {
|
|
32
32
|
if (code.trim().length === 0) {
|
|
33
33
|
return { ok: false, error: { kind: "ParseError", message: "Code cannot be empty." }, toolCalls: [] };
|
|
34
34
|
}
|
|
@@ -36,6 +36,7 @@ export const startProgram = (setup, code, bindings) => new Running(setup, 0, ()
|
|
|
36
36
|
if (!parsed.ok)
|
|
37
37
|
return { ok: false, error: parsed.error, toolCalls: [] };
|
|
38
38
|
const runtime = instantiate(setup, bindings);
|
|
39
|
+
runtime.vm.hosts.runId = runId;
|
|
39
40
|
runtime.vm.start(parsed.source);
|
|
40
41
|
return runtime;
|
|
41
42
|
});
|
|
@@ -58,6 +59,13 @@ export const resumeProgram = (setup, saved) => Effect.try({
|
|
|
58
59
|
};
|
|
59
60
|
const fresh = instantiate(resumed);
|
|
60
61
|
const snapshot = restoreInto(state, fresh.vm);
|
|
62
|
+
for (const call of fresh.vm.calls()) {
|
|
63
|
+
if (call.status !== "started")
|
|
64
|
+
continue;
|
|
65
|
+
if (call.request.kind !== "tool" || fresh.tools.mode(call.request.path)?._tag !== "CodeModeDurable") {
|
|
66
|
+
throw new SnapshotError(`The pending durable call ${call.key} (${callPath(call)}) cannot resume because that tool is no longer a durable tool in this runtime.`);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
61
69
|
return new Running(resumed, snapshot.header.budget.activeMs, () => fresh, true);
|
|
62
70
|
},
|
|
63
71
|
catch: (error) => (error instanceof SnapshotError ? error : new SnapshotError(String(error))),
|
|
@@ -142,7 +150,6 @@ export class Running {
|
|
|
142
150
|
if (roundTrip)
|
|
143
151
|
self.driver.checkpoint = Effect.sync(() => self.trip());
|
|
144
152
|
self.startedAt = Date.now();
|
|
145
|
-
yield* Deferred.succeed(self.started, undefined);
|
|
146
153
|
return yield* self.execute();
|
|
147
154
|
}).pipe(Effect.onExit((exit) => Effect.andThen(Deferred.succeed(self.started, undefined), Deferred.done(self.done, exit))));
|
|
148
155
|
}
|
|
@@ -177,6 +184,7 @@ export class Running {
|
|
|
177
184
|
const driver = self.driver;
|
|
178
185
|
if (self.resuming)
|
|
179
186
|
driver.resume();
|
|
187
|
+
yield* Deferred.succeed(self.started, undefined);
|
|
180
188
|
const outcome = yield* driver.run();
|
|
181
189
|
if (outcome === SUSPENDED)
|
|
182
190
|
return self.suspended;
|
|
@@ -248,6 +256,14 @@ export class Running {
|
|
|
248
256
|
running,
|
|
249
257
|
});
|
|
250
258
|
}
|
|
259
|
+
// Idempotent calls in flight are saved as queued so they run again on resume under the same key.
|
|
260
|
+
const idempotent = vm.calls().filter((call) => call.status === "running");
|
|
261
|
+
for (const call of idempotent)
|
|
262
|
+
call.status = "queued";
|
|
263
|
+
const restoreRunning = () => {
|
|
264
|
+
for (const call of idempotent)
|
|
265
|
+
call.status = "running";
|
|
266
|
+
};
|
|
251
267
|
const limits = this.setup.limits;
|
|
252
268
|
const saved = attempt(() => vm.capture({
|
|
253
269
|
limits: {
|
|
@@ -259,6 +275,7 @@ export class Running {
|
|
|
259
275
|
strict: false,
|
|
260
276
|
}));
|
|
261
277
|
if (!saved.ok) {
|
|
278
|
+
restoreRunning();
|
|
262
279
|
const error = saved.error;
|
|
263
280
|
return new SuspendError({
|
|
264
281
|
message: `The run's state couldn't be saved: ${error instanceof Error ? error.message : String(error)}`,
|
|
@@ -269,6 +286,7 @@ export class Running {
|
|
|
269
286
|
if (maxBytes !== undefined) {
|
|
270
287
|
const size = toBytes(snapshot).byteLength;
|
|
271
288
|
if (size > maxBytes) {
|
|
289
|
+
restoreRunning();
|
|
272
290
|
return new SuspendError({
|
|
273
291
|
message: `The run's state takes ${size} bytes, more than the ${maxBytes}-byte limit, so it couldn't be suspended.`,
|
|
274
292
|
running: [],
|
|
@@ -278,8 +296,8 @@ export class Running {
|
|
|
278
296
|
return { ok: "suspended", state: snapshot };
|
|
279
297
|
}
|
|
280
298
|
// The round-trip test mode's checkpoint: saves the state to bytes and continues in a brand-new runtime. States that
|
|
281
|
-
// hold live host values (an extension call in flight, a function an extension
|
|
282
|
-
// are skipped; a lost value anywhere else is a codec gap and fails the run.
|
|
299
|
+
// hold live host values (an extension call in flight, a function an extension without `snapshot` hooks returned)
|
|
300
|
+
// can't round-trip, so they are skipped; a lost value anywhere else is a codec gap and fails the run.
|
|
283
301
|
trip() {
|
|
284
302
|
const driver = this.driver;
|
|
285
303
|
if (this.trips >= ROUND_TRIP_MAX) {
|
|
@@ -293,13 +311,23 @@ export class Running {
|
|
|
293
311
|
if (driver.holdsHostValues)
|
|
294
312
|
return;
|
|
295
313
|
this.trips++;
|
|
296
|
-
const
|
|
314
|
+
const attempted = attempt(() => this.ctx.vm.capture({ strict: !this.setup.lossy }));
|
|
315
|
+
// An extension's `snapshot` hooks may refuse to save a value, which fails a suspend, not the run.
|
|
316
|
+
if (!attempted.ok) {
|
|
317
|
+
const error = attempted.error;
|
|
318
|
+
if (error instanceof SnapshotError && error.message.startsWith("The extension "))
|
|
319
|
+
return;
|
|
320
|
+
throw error;
|
|
321
|
+
}
|
|
322
|
+
const saved = attempted.value;
|
|
297
323
|
const bytes = toBytes(saved.snapshot);
|
|
298
324
|
this.skip = Math.floor(saved.snapshot.records.length / 200 + bytes.byteLength / 100_000);
|
|
299
325
|
if (saved.lost.length > 0)
|
|
300
326
|
return;
|
|
301
327
|
const fresh = instantiate(this.setup);
|
|
302
328
|
restoreInto(fromBytes(bytes), fresh.vm);
|
|
329
|
+
for (const [key, invocation] of this.ctx.tools.invocations)
|
|
330
|
+
fresh.tools.invocations.set(key, invocation);
|
|
303
331
|
this.ctx = fresh;
|
|
304
332
|
driver.vm = fresh.vm;
|
|
305
333
|
driver.tools = fresh.tools;
|
|
@@ -13,4 +13,4 @@ export declare const extensionGlobals: <R>(ctx: Interpreter<R>, extensions: Read
|
|
|
13
13
|
* Calls a synchronous extension function's host function, once its `extension.before` hook allowed it: a promise for
|
|
14
14
|
* a result that settles later (an Effect or a Promise), or the request that settles what it returned or threw now.
|
|
15
15
|
*/
|
|
16
|
-
export declare const startExtensionCall: <R>(ctx: Interpreter<R>, host: Function, args: ReadonlyArray<unknown>, call: Pick<ExtensionRequest, "label" | "invocation">, site: AstNode | undefined) => PromiseObj | ExtensionRequest;
|
|
16
|
+
export declare const startExtensionCall: <R>(ctx: Interpreter<R>, host: Function, args: ReadonlyArray<unknown>, call: Pick<ExtensionRequest, "label" | "extension" | "invocation">, site: AstNode | undefined) => PromiseObj | ExtensionRequest;
|
|
@@ -9,6 +9,7 @@ import { native } from "./native.js";
|
|
|
9
9
|
import { define, get, has, hidden, keys, Arr, Bytes, DateObj, ErrorObj, HeadersObj, PromiseObj, MapObj, Obj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, coerceToString, } from "./objects.js";
|
|
10
10
|
import { describeValue, isOpaque } from "./references.js";
|
|
11
11
|
import { Push } from "./signals.js";
|
|
12
|
+
import { SnapshotError } from "../snapshot/codec.js";
|
|
12
13
|
/**
|
|
13
14
|
* The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in
|
|
14
15
|
* wrappers are copied, a host function becomes a program function whose calls cross the same way, and a host Promise
|
|
@@ -16,6 +17,9 @@ import { Push } from "./signals.js";
|
|
|
16
17
|
*/
|
|
17
18
|
export const extensionGlobals = (ctx, extensions) => {
|
|
18
19
|
const builtins = ctx.builtins;
|
|
20
|
+
const byName = new Map(extensions.map((extension) => [extension.name, extension]));
|
|
21
|
+
// The program functions wrapping functions inside values a hooked extension returned, by where they came from.
|
|
22
|
+
const origins = new WeakMap();
|
|
19
23
|
const toHost = (value, label, depth = 0, seen = new Set()) => {
|
|
20
24
|
if (depth > MAX_VALUE_DEPTH)
|
|
21
25
|
throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
|
|
@@ -53,16 +57,19 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
53
57
|
seen.delete(value);
|
|
54
58
|
return copied;
|
|
55
59
|
};
|
|
56
|
-
// `
|
|
57
|
-
const fromHost = (value, label, depth = 0, seen = new Set(),
|
|
60
|
+
// `within` says where the value is, so a function inside it fires the hooks, or can be saved; see `Within`.
|
|
61
|
+
const fromHost = (value, label, depth = 0, seen = new Set(), within) => {
|
|
58
62
|
if (depth > MAX_VALUE_DEPTH)
|
|
59
63
|
throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
|
|
60
64
|
if (isPrimitive(value))
|
|
61
65
|
return value;
|
|
62
66
|
if (typeof value === "function")
|
|
63
|
-
return wrap(value, label,
|
|
67
|
+
return wrap(value, label, within);
|
|
64
68
|
if (value !== null && typeof value === "object") {
|
|
65
|
-
const next = (item, path) => fromHost(item, path, depth + 1, seen,
|
|
69
|
+
const next = (item, path, key) => fromHost(item, path, depth + 1, seen, within && {
|
|
70
|
+
...within,
|
|
71
|
+
path: key === undefined || within.path === undefined ? undefined : [...within.path, key],
|
|
72
|
+
});
|
|
66
73
|
// Nothing a host value hands back is kept: results are read as primitives or copied. Where the value's own
|
|
67
74
|
// method could hand back host storage or an object (`getTime`, `slice`, `map`), its internal data is read.
|
|
68
75
|
if (value instanceof Date)
|
|
@@ -91,7 +98,7 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
91
98
|
const field = fields[key];
|
|
92
99
|
if (typeof field === "function")
|
|
93
100
|
continue;
|
|
94
|
-
const item = crossing(() => next(field, `${label}.${key}
|
|
101
|
+
const item = crossing(() => next(field, `${label}.${key}`, key));
|
|
95
102
|
if (item === left)
|
|
96
103
|
continue;
|
|
97
104
|
define(copied, key, item, key === "cause" ? hidden : undefined);
|
|
@@ -130,7 +137,7 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
130
137
|
const items = [];
|
|
131
138
|
for (let index = 0; index < length; index += 1) {
|
|
132
139
|
if (index in value)
|
|
133
|
-
items[index] = next(value[index], `${label}[${index}]
|
|
140
|
+
items[index] = next(value[index], `${label}[${index}]`, index);
|
|
134
141
|
}
|
|
135
142
|
items.length = length;
|
|
136
143
|
seen.delete(value);
|
|
@@ -140,7 +147,7 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
140
147
|
if (prototype === Object.prototype || prototype === null) {
|
|
141
148
|
const copied = new Obj(builtins.Object);
|
|
142
149
|
for (const [key, item] of Object.entries(value))
|
|
143
|
-
define(copied, key, next(item, `${label}.${key}
|
|
150
|
+
define(copied, key, next(item, `${label}.${key}`, key));
|
|
144
151
|
seen.delete(value);
|
|
145
152
|
return copied;
|
|
146
153
|
}
|
|
@@ -150,26 +157,67 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
150
157
|
// A host function as a program function. Arguments cross in; for a global or a global object's function, the
|
|
151
158
|
// `extension.before` hook runs before the host function is called, so a call it denies never reaches the host. The
|
|
152
159
|
// host's result, or what it threw, crosses out so the program catches a copy, and `extension.after` sees how the
|
|
153
|
-
// call ended. Functions inside results are part of a value's API and skip the hooks
|
|
154
|
-
|
|
160
|
+
// call ended. Functions inside results are part of a value's API and skip the hooks; one inside a value an extension
|
|
161
|
+
// with `snapshot` hooks returned is known by where it came from, so a suspended run can save it.
|
|
162
|
+
const wrap = (value, label, within) => {
|
|
155
163
|
// The host function's own `name` and `length` can be anything, even getters: each is read once, and only text
|
|
156
164
|
// and a count cross.
|
|
157
165
|
const name = value.name;
|
|
158
166
|
const length = value.length;
|
|
159
|
-
|
|
167
|
+
const extension = within?.extension.name;
|
|
168
|
+
const root = within?.root;
|
|
169
|
+
const wrapped = native(builtins, {
|
|
160
170
|
runtime: "extension",
|
|
161
171
|
name: typeof name === "string" ? name : "",
|
|
162
172
|
length: typeof length === "number" && Number.isSafeInteger(length) && length >= 0 ? length : 0,
|
|
163
173
|
call: (_, values, site) => {
|
|
164
174
|
const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`));
|
|
165
|
-
const invocation =
|
|
175
|
+
const invocation = within !== undefined && root === undefined ? { extension: extension, name: label, args } : undefined;
|
|
166
176
|
// A denied call fails the way the global would: an async global rejects its promise, a sync one throws.
|
|
167
177
|
if (isAsync(value)) {
|
|
168
|
-
return pending(ctx, { stage: "run", label, invocation, host: value, args, threw: false }, site);
|
|
178
|
+
return pending(ctx, { stage: "run", label, extension, invocation, host: value, args, threw: false }, site);
|
|
169
179
|
}
|
|
170
|
-
return new Push("extension call", [value, args, label, invocation]);
|
|
180
|
+
return new Push("extension call", [value, args, label, invocation, extension]);
|
|
171
181
|
},
|
|
172
182
|
});
|
|
183
|
+
if (root !== undefined && within.path !== undefined) {
|
|
184
|
+
origins.set(wrapped, { extension: extension, root, path: within.path, label });
|
|
185
|
+
}
|
|
186
|
+
return wrapped;
|
|
187
|
+
};
|
|
188
|
+
ctx.hosts = {
|
|
189
|
+
extensions: extensions.map((extension) => ({ name: extension.name, hooked: extension.snapshot !== undefined })),
|
|
190
|
+
origin: (value) => origins.get(value),
|
|
191
|
+
encode: (name, root) => hostStep(name, "save", () => hooks(name).encode(root)),
|
|
192
|
+
decode: (name, data) => {
|
|
193
|
+
const root = hostStep(name, "restore", () => hooks(name).decode(data));
|
|
194
|
+
if ((typeof root !== "object" && typeof root !== "function") || root === null) {
|
|
195
|
+
throw new SnapshotError(`The extension "${name}" restored a value it returned as ${typeof root}, not an object.`);
|
|
196
|
+
}
|
|
197
|
+
return root;
|
|
198
|
+
},
|
|
199
|
+
rewrap: (target, origin) => {
|
|
200
|
+
const host = origin.path.reduce((at, key) => (typeof at === "object" && at !== null) || typeof at === "function"
|
|
201
|
+
? at[key]
|
|
202
|
+
: undefined, origin.root);
|
|
203
|
+
if (typeof host !== "function") {
|
|
204
|
+
throw new SnapshotError(`The extension "${origin.extension}" restored a value with no function at ${origin.label}, so this state can't resume.`);
|
|
205
|
+
}
|
|
206
|
+
const made = wrap(host, origin.label, {
|
|
207
|
+
extension: byName.get(origin.extension),
|
|
208
|
+
root: origin.root,
|
|
209
|
+
path: origin.path,
|
|
210
|
+
});
|
|
211
|
+
// The restored function keeps its own properties; only what calling it does comes from the new one.
|
|
212
|
+
Object.assign(target, { tag: made.tag, call: made.call, construct: made.construct, callback: made.callback });
|
|
213
|
+
origins.set(target, origin);
|
|
214
|
+
},
|
|
215
|
+
};
|
|
216
|
+
const hooks = (name) => {
|
|
217
|
+
const snapshot = byName.get(name)?.snapshot;
|
|
218
|
+
if (snapshot === undefined)
|
|
219
|
+
throw new SnapshotError(`The extension "${name}" has no snapshot hooks.`);
|
|
220
|
+
return snapshot;
|
|
173
221
|
};
|
|
174
222
|
// The Effect each step of an extension call runs as, with the program's services in its requirements.
|
|
175
223
|
ctx.extensionWork = (request) => {
|
|
@@ -181,12 +229,20 @@ export const extensionGlobals = (ctx, extensions) => {
|
|
|
181
229
|
if (request.stage === "before")
|
|
182
230
|
return before ?? Effect.void;
|
|
183
231
|
const after = call && hooks["extension.after"];
|
|
184
|
-
const
|
|
232
|
+
const extension = request.extension === undefined ? undefined : byName.get(request.extension);
|
|
233
|
+
// What a function returns is a value of its extension's, which its `snapshot` hooks save, when it has them.
|
|
234
|
+
const settle = (effect) => (after ? hooked(call, undefined, after, effect) : effect).pipe(Effect.mapBoth({
|
|
235
|
+
onFailure: cross,
|
|
236
|
+
onSuccess: (result) => fromHost(result, label, 0, new Set(), extension?.snapshot !== undefined &&
|
|
237
|
+
((typeof result === "object" && result !== null) || typeof result === "function")
|
|
238
|
+
? { extension, root: result, path: [] }
|
|
239
|
+
: undefined),
|
|
240
|
+
}));
|
|
185
241
|
if (request.stage === "settle")
|
|
186
242
|
return settle(outcome(request.host, request.threw));
|
|
187
243
|
return Effect.andThen(before ?? Effect.void, settle(Effect.suspend(() => outcome(...callHost(request.host, request.args)))));
|
|
188
244
|
};
|
|
189
|
-
return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, fromHost(value, name, 0, new Set(), extension
|
|
245
|
+
return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, fromHost(value, name, 0, new Set(), { extension, root: undefined, path: undefined })]));
|
|
190
246
|
};
|
|
191
247
|
// An asynchronous host call: the program holds a promise that settles when the host's work does.
|
|
192
248
|
const pending = (ctx, call, site) => {
|
|
@@ -205,6 +261,17 @@ export const startExtensionCall = (ctx, host, args, call, site) => {
|
|
|
205
261
|
return pending(ctx, request, site);
|
|
206
262
|
return request;
|
|
207
263
|
};
|
|
264
|
+
// Runs an extension's `snapshot` hook; what goes wrong is the state's problem, said as such.
|
|
265
|
+
const hostStep = (extension, what, step) => {
|
|
266
|
+
try {
|
|
267
|
+
return step();
|
|
268
|
+
}
|
|
269
|
+
catch (error) {
|
|
270
|
+
if (error instanceof SnapshotError)
|
|
271
|
+
throw error;
|
|
272
|
+
throw new SnapshotError(`The extension "${extension}" couldn't ${what} a value it returned: ${error instanceof Error ? error.message : String(error)}`);
|
|
273
|
+
}
|
|
274
|
+
};
|
|
208
275
|
/** Calls a host function: what it returned, or what it threw. */
|
|
209
276
|
const callHost = (value, args) => {
|
|
210
277
|
try {
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ToolRuntime } from "../../tool-runtime.js";
|
|
2
2
|
import type { ExtensionRequest } from "../scheduler.js";
|
|
3
|
+
import type { HostBridge } from "../snapshot/codec.js";
|
|
3
4
|
import { Vm } from "../vm.js";
|
|
4
5
|
import type { Builtins } from "./intrinsics.js";
|
|
5
6
|
import { IntrinsicNames } from "./intrinsic-names.js";
|
|
@@ -21,6 +22,8 @@ export declare class Interpreter<R> {
|
|
|
21
22
|
readonly prelude: Prelude;
|
|
22
23
|
/** Makes the Effect an extension function's host work runs as; set by the extension bridge. */
|
|
23
24
|
extensionWork: ((request: ExtensionRequest) => unknown) | undefined;
|
|
25
|
+
/** Saves and restores values returned by extensions with `snapshot` hooks; set by the extension bridge. */
|
|
26
|
+
hosts: HostBridge | undefined;
|
|
24
27
|
/** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */
|
|
25
28
|
readonly sources: Map<string, Source>;
|
|
26
29
|
/** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
|
|
@@ -19,6 +19,8 @@ export class Interpreter {
|
|
|
19
19
|
prelude;
|
|
20
20
|
/** Makes the Effect an extension function's host work runs as; set by the extension bridge. */
|
|
21
21
|
extensionWork;
|
|
22
|
+
/** Saves and restores values returned by extensions with `snapshot` hooks; set by the extension bridge. */
|
|
23
|
+
hosts;
|
|
22
24
|
/** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */
|
|
23
25
|
sources = new Map();
|
|
24
26
|
/** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
|
package/dist/vm/scheduler.d.ts
CHANGED
|
@@ -101,6 +101,7 @@ export type HostRequest = {
|
|
|
101
101
|
export type ExtensionRequest = {
|
|
102
102
|
readonly stage: "before" | "settle" | "run";
|
|
103
103
|
readonly label: string;
|
|
104
|
+
readonly extension?: string | undefined;
|
|
104
105
|
invocation: ExtensionInvocation | undefined;
|
|
105
106
|
host: unknown;
|
|
106
107
|
args: ReadonlyArray<unknown>;
|
|
@@ -113,6 +114,8 @@ export type ExtensionRequest = {
|
|
|
113
114
|
*/
|
|
114
115
|
export declare class HostCall {
|
|
115
116
|
readonly id: number;
|
|
117
|
+
/** The call's stable idempotency key, `<runId>:<callId>`. */
|
|
118
|
+
readonly key: string;
|
|
116
119
|
readonly request: HostRequest;
|
|
117
120
|
/** What runs: a tool path, or an extension function's label. */
|
|
118
121
|
readonly label: string;
|
|
@@ -124,9 +127,18 @@ export declare class HostCall {
|
|
|
124
127
|
readonly resolving: Resolving | undefined;
|
|
125
128
|
/** The call that started the work, where a defect it raises is located. */
|
|
126
129
|
readonly site: AstNode | undefined;
|
|
127
|
-
/**
|
|
128
|
-
|
|
129
|
-
|
|
130
|
+
/**
|
|
131
|
+
* Where the call is: `queued` (written ahead, not started), `running` (or in `start` for a durable tool),
|
|
132
|
+
* `started` (a durable tool whose `start` returned its `data`, now in `wait`), or `completed`.
|
|
133
|
+
*/
|
|
134
|
+
status: "queued" | "running" | "started" | "completed";
|
|
135
|
+
/** The JSON data a durable tool's `start` returned, saved so a resumed run can call `wait(data)`. */
|
|
136
|
+
data: Json | undefined;
|
|
137
|
+
/** Whether a tool call has already been counted against `maxToolCalls` and recorded in `toolCalls`. */
|
|
138
|
+
admitted: boolean;
|
|
139
|
+
constructor(id: number,
|
|
140
|
+
/** The call's stable idempotency key, `<runId>:<callId>`. */
|
|
141
|
+
key: string, request: HostRequest,
|
|
130
142
|
/** What runs: a tool path, or an extension function's label. */
|
|
131
143
|
label: string,
|
|
132
144
|
/** The running job waits for it: its outcome continues the frame that asked, before any other job. */
|
package/dist/vm/scheduler.js
CHANGED
|
@@ -6,15 +6,25 @@ import { locate } from "./runtime/errors.js";
|
|
|
6
6
|
*/
|
|
7
7
|
export class HostCall {
|
|
8
8
|
id;
|
|
9
|
+
key;
|
|
9
10
|
request;
|
|
10
11
|
label;
|
|
11
12
|
blocking;
|
|
12
13
|
result;
|
|
13
14
|
resolving;
|
|
14
15
|
site;
|
|
15
|
-
/**
|
|
16
|
+
/**
|
|
17
|
+
* Where the call is: `queued` (written ahead, not started), `running` (or in `start` for a durable tool),
|
|
18
|
+
* `started` (a durable tool whose `start` returned its `data`, now in `wait`), or `completed`.
|
|
19
|
+
*/
|
|
16
20
|
status = "queued";
|
|
17
|
-
|
|
21
|
+
/** The JSON data a durable tool's `start` returned, saved so a resumed run can call `wait(data)`. */
|
|
22
|
+
data = undefined;
|
|
23
|
+
/** Whether a tool call has already been counted against `maxToolCalls` and recorded in `toolCalls`. */
|
|
24
|
+
admitted = false;
|
|
25
|
+
constructor(id,
|
|
26
|
+
/** The call's stable idempotency key, `<runId>:<callId>`. */
|
|
27
|
+
key, request,
|
|
18
28
|
/** What runs: a tool path, or an extension function's label. */
|
|
19
29
|
label,
|
|
20
30
|
/** The running job waits for it: its outcome continues the frame that asked, before any other job. */
|
|
@@ -26,6 +36,7 @@ export class HostCall {
|
|
|
26
36
|
/** The call that started the work, where a defect it raises is located. */
|
|
27
37
|
site) {
|
|
28
38
|
this.id = id;
|
|
39
|
+
this.key = key;
|
|
29
40
|
this.request = request;
|
|
30
41
|
this.label = label;
|
|
31
42
|
this.blocking = blocking;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type AstNode } from "../runtime/model.js";
|
|
2
|
-
import { Obj } from "../runtime/objects.js";
|
|
2
|
+
import { Native, Obj } from "../runtime/objects.js";
|
|
3
3
|
import { Interruption } from "../runtime/signals.js";
|
|
4
4
|
/** A plain JSON value, as a snapshot holds it. */
|
|
5
5
|
export type Json = null | boolean | number | string | ReadonlyArray<Json> | {
|
|
@@ -24,6 +24,34 @@ export type Record = {
|
|
|
24
24
|
/** A saved state can't be read, or doesn't fit this runtime. */
|
|
25
25
|
import { SnapshotError } from "../../suspend-error.js";
|
|
26
26
|
export { SnapshotError };
|
|
27
|
+
/**
|
|
28
|
+
* Where a function inside a value an extension returned came from, so a saved state can name it instead of losing it:
|
|
29
|
+
* the extension, the value its function returned (`root`), which the extension's `snapshot` hooks save, and the path
|
|
30
|
+
* from there to the function.
|
|
31
|
+
*/
|
|
32
|
+
export type HostOrigin = {
|
|
33
|
+
readonly extension: string;
|
|
34
|
+
readonly root: object;
|
|
35
|
+
readonly path: ReadonlyArray<string | number>;
|
|
36
|
+
/** What the program calls it, for its errors (`fetch.text`). */
|
|
37
|
+
readonly label: string;
|
|
38
|
+
};
|
|
39
|
+
/** The extension bridge's side of saving and restoring those functions; see `extensionGlobals`. */
|
|
40
|
+
export type HostBridge = {
|
|
41
|
+
/** Each extension's name, and whether it has `snapshot` hooks: a state resumes only where both match. */
|
|
42
|
+
readonly extensions: ReadonlyArray<{
|
|
43
|
+
readonly name: string;
|
|
44
|
+
readonly hooked: boolean;
|
|
45
|
+
}>;
|
|
46
|
+
/** Where a program function wrapping a host function came from, when its extension can save it. */
|
|
47
|
+
readonly origin: (value: object) => HostOrigin | undefined;
|
|
48
|
+
/** A returned value as its extension saves it. */
|
|
49
|
+
readonly encode: (extension: string, root: object) => unknown;
|
|
50
|
+
/** A returned value back from what `encode` gave. */
|
|
51
|
+
readonly decode: (extension: string, data: unknown) => object;
|
|
52
|
+
/** Makes `target`, a restored program function, call the host function `origin` leads to. */
|
|
53
|
+
readonly rewrap: (target: Native, origin: HostOrigin) => void;
|
|
54
|
+
};
|
|
27
55
|
/** What the encoder asks of the runtime whose state it saves. */
|
|
28
56
|
export type EncodeEnv = {
|
|
29
57
|
/** The name of a built-in or host global object. */
|
|
@@ -36,6 +64,7 @@ export type EncodeEnv = {
|
|
|
36
64
|
/** Values with no data form are reported here; strict encoding throws on the first instead. */
|
|
37
65
|
readonly lost: Array<string>;
|
|
38
66
|
readonly strict: boolean;
|
|
67
|
+
readonly hosts?: HostBridge | undefined;
|
|
39
68
|
/** More classes to save, an engine's own (the VM's frames and closures), after the built-in ones. */
|
|
40
69
|
readonly specs?: ReadonlyArray<ClassSpec> | undefined;
|
|
41
70
|
/** The data an engine names an object or symbol by, saved as `["x", data]`, instead of copying it. */
|
|
@@ -48,6 +77,7 @@ export type DecodeEnv = {
|
|
|
48
77
|
readonly node: (source: string, index: number) => AstNode | undefined;
|
|
49
78
|
/** An `Interruption` (it holds an Effect cause, which this module does not make). */
|
|
50
79
|
readonly interruption: () => Interruption;
|
|
80
|
+
readonly hosts?: HostBridge | undefined;
|
|
51
81
|
readonly specs?: ReadonlyArray<ClassSpec> | undefined;
|
|
52
82
|
/** What `EncodeEnv.external` named. */
|
|
53
83
|
readonly external?: ((data: Json) => unknown) | undefined;
|
|
@@ -110,7 +110,7 @@ const builtinSpecs = () => [
|
|
|
110
110
|
{
|
|
111
111
|
name: "HostCall",
|
|
112
112
|
ctor: HostCall,
|
|
113
|
-
fields: ["status", "id", "request", "label", "blocking", "result", "resolving", "site"],
|
|
113
|
+
fields: ["status", "data", "admitted", "id", "key", "request", "label", "blocking", "result", "resolving", "site"],
|
|
114
114
|
},
|
|
115
115
|
{ name: "Resolving", ctor: Resolving, fields: ["done", "scheduler", "promise", "site"] },
|
|
116
116
|
{ name: "Throw", ctor: Throw, fields: ["value"] },
|
|
@@ -124,7 +124,7 @@ const builtinSpecs = () => [
|
|
|
124
124
|
ctor: Interpreter,
|
|
125
125
|
anchor: "ctx",
|
|
126
126
|
fields: ["logs", "globalScope", "modules", "namespaces"],
|
|
127
|
-
skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "sources", "prelude"],
|
|
127
|
+
skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "hosts", "sources", "prelude"],
|
|
128
128
|
},
|
|
129
129
|
];
|
|
130
130
|
let builtins;
|
|
@@ -186,6 +186,8 @@ class Encoder {
|
|
|
186
186
|
// A URL's `searchParams` is the same host object its URLSearchParams wraps; it is encoded once every URL is known.
|
|
187
187
|
owners = new Map();
|
|
188
188
|
params = [];
|
|
189
|
+
// One `HostValue` record per value an extension returned, however many of its functions the state holds.
|
|
190
|
+
roots = new Map();
|
|
189
191
|
specs;
|
|
190
192
|
constructor(env) {
|
|
191
193
|
this.env = env;
|
|
@@ -296,7 +298,14 @@ class Encoder {
|
|
|
296
298
|
return { t: spec.name, ...this.fields(object, spec) };
|
|
297
299
|
}
|
|
298
300
|
if (object instanceof Native) {
|
|
299
|
-
// A host function made while the program ran
|
|
301
|
+
// A host function made while the program ran: inside a value an extension returned. Its extension saves that
|
|
302
|
+
// value when it has `snapshot` hooks; otherwise its name says what was lost.
|
|
303
|
+
const origin = this.env.hosts?.origin(object);
|
|
304
|
+
if (origin !== undefined) {
|
|
305
|
+
const root = this.hostValue(origin.extension, origin.root);
|
|
306
|
+
const fields = this.fields(object, hostFunction, hostFunction.fields);
|
|
307
|
+
return { t: "HostFunction", e: origin.extension, h: root, k: [...origin.path], l: origin.label, ...fields };
|
|
308
|
+
}
|
|
300
309
|
this.lose(`the function ${functionName(object)}`);
|
|
301
310
|
return { t: "LostNative", ...this.fields(object, hostFunction, hostFunction.fields) };
|
|
302
311
|
}
|
|
@@ -332,6 +341,19 @@ class Encoder {
|
|
|
332
341
|
this.lose(what);
|
|
333
342
|
return { t: "Lost", f: [what] };
|
|
334
343
|
}
|
|
344
|
+
// A value an extension returned, as its `snapshot.encode` saves it: plain data, checked before it is copied.
|
|
345
|
+
hostValue(extension, root) {
|
|
346
|
+
const known = this.roots.get(root);
|
|
347
|
+
if (known !== undefined)
|
|
348
|
+
return known;
|
|
349
|
+
const data = plainData(this.env.hosts.encode(extension, root), extension, new Set());
|
|
350
|
+
const id = this.records.length;
|
|
351
|
+
const ref = ["r", id];
|
|
352
|
+
this.roots.set(root, ref);
|
|
353
|
+
this.records.push(undefined);
|
|
354
|
+
this.records[id] = { t: "HostValue", e: extension, d: this.value(data) };
|
|
355
|
+
return ref;
|
|
356
|
+
}
|
|
335
357
|
lose(what) {
|
|
336
358
|
if (this.env.strict)
|
|
337
359
|
throw new SnapshotError(`Codec gap: ${what} has no data form.`);
|
|
@@ -421,6 +443,10 @@ class Decoder {
|
|
|
421
443
|
filled;
|
|
422
444
|
// Derived state is rebuilt once every record is filled in, since it reads other records.
|
|
423
445
|
resets = [];
|
|
446
|
+
// Functions inside values extensions returned, wrapped again once every record is filled in.
|
|
447
|
+
hostFunctions = [];
|
|
448
|
+
// Those values, given back once each by their extension's `snapshot.decode`, by `HostValue` record.
|
|
449
|
+
hostValues = new Map();
|
|
424
450
|
specs;
|
|
425
451
|
constructor(records, env) {
|
|
426
452
|
this.records = records;
|
|
@@ -464,7 +490,10 @@ class Decoder {
|
|
|
464
490
|
return named;
|
|
465
491
|
}
|
|
466
492
|
case "LostNative":
|
|
493
|
+
case "HostFunction":
|
|
467
494
|
return Object.create(Native.prototype);
|
|
495
|
+
case "HostValue":
|
|
496
|
+
return {};
|
|
468
497
|
case "Interruption":
|
|
469
498
|
return this.env.interruption();
|
|
470
499
|
case "Error": {
|
|
@@ -607,6 +636,11 @@ class Decoder {
|
|
|
607
636
|
native.callback = true;
|
|
608
637
|
return;
|
|
609
638
|
}
|
|
639
|
+
case "HostFunction":
|
|
640
|
+
this.fillClass(target, record, hostFunction, false);
|
|
641
|
+
this.hostFunctions.push([target, record]);
|
|
642
|
+
return;
|
|
643
|
+
case "HostValue":
|
|
610
644
|
case "Interruption":
|
|
611
645
|
case "URL":
|
|
612
646
|
case "URLSearchParams":
|
|
@@ -643,6 +677,32 @@ class Decoder {
|
|
|
643
677
|
finish() {
|
|
644
678
|
for (const reset of this.resets)
|
|
645
679
|
reset();
|
|
680
|
+
if (this.hostFunctions.length === 0)
|
|
681
|
+
return;
|
|
682
|
+
const hosts = this.env.hosts ?? invalid("a function from an extension is saved, and this runtime has no extensions.");
|
|
683
|
+
for (const [target, record] of this.hostFunctions) {
|
|
684
|
+
const extension = text(record.e, "an extension");
|
|
685
|
+
const path = list(record.k, "a path").map((key) => typeof key === "number" ? count(key, "a path index") : text(key, "a path key"));
|
|
686
|
+
hosts.rewrap(target, {
|
|
687
|
+
extension,
|
|
688
|
+
root: this.hostValue(hosts, record.h, extension),
|
|
689
|
+
path,
|
|
690
|
+
label: text(record.l, "a label"),
|
|
691
|
+
});
|
|
692
|
+
}
|
|
693
|
+
}
|
|
694
|
+
// A value an extension returned, given back once by its `snapshot.decode` from the data it saved.
|
|
695
|
+
hostValue(hosts, ref, extension) {
|
|
696
|
+
const id = Array.isArray(ref) && ref[0] === "r" ? count(ref[1], "a record id") : invalid("a host value is not a record.");
|
|
697
|
+
const known = this.hostValues.get(id);
|
|
698
|
+
if (known !== undefined)
|
|
699
|
+
return known;
|
|
700
|
+
const record = id < this.records.length ? this.at(id) : invalid(`record ${id} does not exist.`);
|
|
701
|
+
if (record.t !== "HostValue" || record.e !== extension)
|
|
702
|
+
invalid(`record ${id} is not a value of ${extension}.`);
|
|
703
|
+
const root = hosts.decode(extension, this.value(record.d));
|
|
704
|
+
this.hostValues.set(id, root);
|
|
705
|
+
return root;
|
|
646
706
|
}
|
|
647
707
|
// An object's prototype, extensibility, and properties. A named object's accessors stay the ones it was made with.
|
|
648
708
|
fillObj(target, record) {
|
|
@@ -730,6 +790,43 @@ class Decoder {
|
|
|
730
790
|
return invalid(`unknown tag ${String(value[0])}.`);
|
|
731
791
|
}
|
|
732
792
|
}
|
|
793
|
+
// What an extension's `snapshot.encode` gives must be plain data the codec copies and hands back to `decode`: JSON
|
|
794
|
+
// values and Uint8Arrays. Views (such as a `Buffer` slice on a shared slab) are copied into standalone `Uint8Array`s.
|
|
795
|
+
const plainData = (data, extension, seen) => {
|
|
796
|
+
if (data === null || typeof data === "string" || typeof data === "boolean")
|
|
797
|
+
return data;
|
|
798
|
+
if (typeof data === "number" && Number.isFinite(data))
|
|
799
|
+
return data;
|
|
800
|
+
if (data instanceof Uint8Array) {
|
|
801
|
+
return data.constructor === Uint8Array && data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
|
|
802
|
+
? data
|
|
803
|
+
: new Uint8Array(data);
|
|
804
|
+
}
|
|
805
|
+
const fail = (what) => {
|
|
806
|
+
throw new SnapshotError(`The extension "${extension}" saved a value it returned as data holding ${what}; snapshot.encode must give plain data (JSON values and Uint8Arrays).`);
|
|
807
|
+
};
|
|
808
|
+
if (typeof data !== "object") {
|
|
809
|
+
return fail(data === undefined ? "undefined" : typeof data === "number" ? String(data) : `a ${typeof data}`);
|
|
810
|
+
}
|
|
811
|
+
if (seen.has(data))
|
|
812
|
+
return fail("a circular reference");
|
|
813
|
+
const proto = Object.getPrototypeOf(data);
|
|
814
|
+
if (!Array.isArray(data) && proto !== Object.prototype && proto !== null) {
|
|
815
|
+
const name = data.constructor?.name ?? "object";
|
|
816
|
+
return fail(`${/^[AEIOU]/.test(name) ? "an" : "a"} ${name}`);
|
|
817
|
+
}
|
|
818
|
+
seen.add(data);
|
|
819
|
+
if (Array.isArray(data)) {
|
|
820
|
+
const out = data.map((item) => plainData(item, extension, seen));
|
|
821
|
+
seen.delete(data);
|
|
822
|
+
return out;
|
|
823
|
+
}
|
|
824
|
+
const out = proto === null ? Object.create(null) : {};
|
|
825
|
+
for (const [key, item] of Object.entries(data))
|
|
826
|
+
out[key] = plainData(item, extension, seen);
|
|
827
|
+
seen.delete(data);
|
|
828
|
+
return out;
|
|
829
|
+
};
|
|
733
830
|
const functionName = (fn) => {
|
|
734
831
|
const slot = fn.props.get("name");
|
|
735
832
|
return slot !== undefined && "value" in slot && typeof slot.value === "string" && slot.value !== ""
|