From 5ad0d06ab227cc7ca0e7b8420ea8641caeabefb4 Mon Sep 17 00:00:00 2001 From: James Long Date: Wed, 4 Nov 2026 22:40:52 +0000 Subject: [PATCH] feat(codemode): save and restore a run's state as a snapshot, with a round-trip test mode --- packages/codemode/package.json | 3 +- packages/codemode/src/codemode.ts | 79 +- packages/codemode/src/data.ts | 2 +- packages/codemode/src/interpreter/driver.ts | 208 +++- packages/codemode/src/interpreter/execute.ts | 339 ++++++- .../codemode/src/interpreter/extensions.ts | 3 +- .../codemode/src/interpreter/interpreter.ts | 13 +- .../src/interpreter/intrinsic-names.ts | 13 +- packages/codemode/src/interpreter/model.ts | 16 + packages/codemode/src/interpreter/table.ts | 3 +- packages/codemode/src/machine/machine.ts | 34 +- packages/codemode/src/machine/scheduler.ts | 11 +- packages/codemode/src/machine/task.ts | 9 +- packages/codemode/src/snapshot/codec.ts | 887 ++++++++++++++++++ packages/codemode/src/snapshot/snapshot.ts | 344 +++++++ packages/codemode/src/stdlib/array.ts | 2 +- packages/codemode/src/tool-runtime.ts | 112 ++- packages/codemode/src/tool.ts | 60 +- packages/codemode/test/machine.test.ts | 5 +- 19 files changed, 2006 insertions(+), 137 deletions(-) create mode 100644 packages/codemode/src/snapshot/codec.ts create mode 100644 packages/codemode/src/snapshot/snapshot.ts diff --git a/packages/codemode/package.json b/packages/codemode/package.json index 34a41d3b3b3..1e2f59231e6 100644 --- a/packages/codemode/package.json +++ b/packages/codemode/package.json @@ -24,7 +24,8 @@ "pack": "bun run script/pack.ts", "typecheck": "bun check --no-script", "typecheck:tsc": "tsc --noEmit", - "test": "bun test" + "test": "bun test", + "test:roundtrip": "CODEMODE_ROUNDTRIP=1 bun test" }, "dependencies": { "acorn": "8.15.0", diff --git a/packages/codemode/src/codemode.ts b/packages/codemode/src/codemode.ts index f9d7a877029..20330cfd9e3 100644 --- a/packages/codemode/src/codemode.ts +++ b/packages/codemode/src/codemode.ts @@ -1,7 +1,10 @@ import { Effect, Schema } from "effect" import { fromJson } from "./data.js" import type { Extension } from "./extension.js" -import { executeProgram } from "./interpreter/execute.js" +import type { Json } from "./data.js" +import type { Outcome } from "./interpreter/driver.js" +import { executeSetup, resumeProgram, type Run, type Setup, startProgram } from "./interpreter/execute.js" +import type { Snapshot } from "./snapshot/snapshot.js" import { extensionGlobals } from "./interpreter/extensions.js" import { globalNames } from "./interpreter/globals.js" import { scanTools } from "./scan.js" @@ -9,6 +12,9 @@ import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime import type { Tools } from "./tools.js" export { scanTools } +export { fromBytes, SnapshotError, toBytes } from "./snapshot/snapshot.js" +export type { Header as SnapshotHeader, Snapshot } from "./snapshot/snapshot.js" +export type { Outcome, Run } /** A tool call admitted during an execution. */ export type { @@ -52,8 +58,18 @@ export type Options = {}, Extensions ex hooks?: ToolRuntime.Hooks> /** Host functions and objects exposed as globals, also importable by Node module name; see `Extension.make`. */ extensions?: Extensions - /** Resource limits enforced on each execution. */ + /** Resource limits enforced on each execution. Time counts active time only, across every resume of a run. */ limits?: ExecutionLimits + /** How `run.suspend` saves a run; see `Runtime.start`. */ + suspend?: SuspendOptions +} + +/** How suspending a run settles its host calls and saves its state. */ +export type SuspendOptions = { + /** Milliseconds to wait for running host calls to finish before detaching or abandoning them. Default 50. */ + readonly graceMs?: number + /** The most bytes a saved state may take; a larger one fails the run instead of suspending it. */ + readonly maxBytes?: number } /** The Effect environment an execution needs: what the tools and the extensions' Effect globals require. */ @@ -131,10 +147,47 @@ export const Result = Schema.Union([Success, Failure]) /** Result of executing a CodeMode program. Program failures are data, not Effect failures. */ export type Result = typeof Result.Type +/** A host call a suspended run was waiting on. */ +export type Pending = { + readonly id: number + /** The tool path, `search`, or an extension function's name. */ + readonly path: string + readonly args: ReadonlyArray + /** The idempotency key, `:`; a durable tool names its work by it. */ + readonly key: string + /** + * `queued`: it never started. `starting`: it may have started, and its outcome is unknown. `started`: a durable + * tool's work, still running, reattached by its handle on resume. + */ + readonly status: "queued" | "starting" | "started" +} + +/** A run stopped by `run.suspend`: its whole state, to resume with `Runtime.resume`, and the calls it waits on. */ +export type Suspended = { + readonly ok: "suspended" + readonly state: Snapshot + readonly pending: ReadonlyArray +} + /** Reusable confined runtime over explicit tools. */ export type Runtime = { readonly catalog: ReadonlyArray readonly execute: (code: string, bindings?: Readonly>) => Effect.Effect + /** + * Starts a program as a run that can be suspended: `run.result` runs it, and `run.suspend` stops it at the next step + * boundary and saves its state. `runId` names its host calls' idempotency keys; a random one by default. + */ + readonly start: ( + code: string, + bindings?: Readonly>, + options?: { readonly runId?: string }, + ) => Run + /** + * Continues a suspended run (its `state`, or that state as bytes) in this runtime, which must be the same build with + * the same extensions. `outcomes` settles pending calls whose outcome the host knows, by key. Throws a + * `SnapshotError` when the state can't be resumed here. + */ + readonly resume: (state: Snapshot | Uint8Array, outcomes?: Readonly>) => Run } const validateLimit = (name: keyof ExecutionLimits, value: number | undefined, minimum: number): number | undefined => { @@ -178,14 +231,26 @@ export const make = < bound.add(name) } } + if (options.suspend?.graceMs !== undefined) validateLimit("graceMs" as keyof ExecutionLimits, options.suspend.graceMs, 0) + const setup: Setup> = { + prepared, + limits, + hooks: options.hooks ?? {}, + globals: extensions.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, extensions), + lossy: extensions.length > 0, + suspend: options.suspend, + } + const data = (bindings: Readonly> | undefined) => + bindings === undefined + ? undefined + : (ctx: Parameters[0]) => + Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)] as const) return { get catalog() { return prepared.catalog }, - execute: (code, bindings) => - executeProgram(code, prepared, limits, options.hooks ?? {}, (ctx) => [ - ...Object.entries(bindings ?? {}).map(([name, value]) => [name, fromJson(ctx, value)] as const), - ...extensionGlobals(ctx, extensions), - ]), + execute: (code, bindings) => executeSetup(setup, code, data(bindings)), + start: (code, bindings, runOptions) => startProgram(setup, code, data(bindings), runOptions?.runId), + resume: (state, outcomes) => resumeProgram(setup, state, outcomes), } } diff --git a/packages/codemode/src/data.ts b/packages/codemode/src/data.ts index 91fa8dcd1ba..cca62947560 100644 --- a/packages/codemode/src/data.ts +++ b/packages/codemode/src/data.ts @@ -129,7 +129,7 @@ function walkStep(task: MachineTask, frame: Frame, input: unknown): Out { } } -const DESCEND: unique symbol = Symbol("descend") +export const DESCEND: unique symbol = Symbol("descend") // Advances one level: its JSON once it is done, DESCEND after pushing a child level, or PENDING. function visit( diff --git a/packages/codemode/src/interpreter/driver.ts b/packages/codemode/src/interpreter/driver.ts index 9a1b273f2bd..bd141da73cf 100644 --- a/packages/codemode/src/interpreter/driver.ts +++ b/packages/codemode/src/interpreter/driver.ts @@ -1,41 +1,63 @@ import { Cause, type Context, Effect, Exit, Fiber } from "effect" +import type { Json } from "../data.js" import type { Machine } from "../machine/machine.js" import type { HostCall } from "../machine/scheduler.js" import type { ToolRuntime } from "../tool-runtime.js" +import { toolError } from "../tool-error.js" import { locate } from "./errors.js" -import { PendingThrow } from "./model.js" +import { lostError, PendingThrow } from "./model.js" import { abrupt, type Completion, Interruption, normal } from "./signals.js" +/** What `Driver.run` returns when a suspend was asked for: the machine stopped at a step boundary. */ +export const SUSPENDED: unique symbol = Symbol("codemode.suspended") + +/** An outcome the host already knows for a pending call, by its key, handed to a resumed run. */ +export type Outcome = { readonly ok: true; readonly value: Json } | { readonly ok: false; readonly error: string } + /** * Runs a machine in Effect: the only place program execution meets the host. It calls `machine.run` until the program * ends, and does what each stop asks: yields to the Effect scheduler for a slice, and starts the host calls the machine * queued, as fibers with the caller's services, reporting each outcome back with `machine.complete`. Fibers live only * here, by host call id, and never become part of the machine's state. + * + * A durable tool's call runs as two fibers, `start` then `attach`, so suspending can detach the second and keep the + * handle `start` gave. The machine and tool bridge can be swapped for restored ones between stops (the round-trip test + * mode does); a fiber's outcome goes to whichever machine is current, by host call id. */ export class Driver { private readonly fibers = new Map>() + // Calls whose fibers were interrupted to suspend or end the run: their outcomes are not reported. + private readonly detached = new Set() private wake: (() => void) | undefined private stopping = false + private suspending = false + // Blocking host work interrupted on its own, which interrupts the execution. + private interrupted: Cause.Cause | undefined + /** Called at every slice and host stop, before queued calls start: the round-trip test mode swaps the machine. */ + checkpoint: Effect.Effect | undefined constructor( - private readonly machine: Machine, - private readonly tools: ToolRuntime, + public machine: Machine, + public tools: ToolRuntime, /** The services host work runs with: the caller's, so tools see its context, tracing, and clock. */ private readonly services: Context.Context, ) {} /** - * Runs the machine until the program's body completes, then returns how it ended. Host work it started may still be - * running; `interrupt` stops it. Host work interrupted on its own that reaches the program's body, or blocking host - * work that is interrupted, interrupts the execution. + * Runs the machine until the program's body completes, then returns how it ended, or `SUSPENDED` once a suspend + * was asked for. Host work it started may still be running; `interrupt` stops it, `detach` settles it to suspend. + * Host work interrupted on its own that reaches the program's body, or blocking host work that is interrupted, + * interrupts the execution. */ - run(): Effect.Effect { + run(): Effect.Effect { const self = this - const machine = this.machine return Effect.gen(function* () { while (true) { - const stop = machine.run() + if (self.interrupted !== undefined) return yield* Effect.failCause(self.interrupted) + if (self.suspending) return SUSPENDED + const stop = self.machine.run() if (stop.kind === "slice") { + if (self.checkpoint !== undefined) yield* self.checkpoint yield* Effect.yieldNow continue } @@ -44,15 +66,10 @@ export class Driver { yield* self.settled continue } - for (const call of stop.calls) { - if (!call.blocking) { - self.start(call) - continue - } - const exit = yield* Effect.exit(self.work(call)) - if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause) - machine.complete(call.id, Exit.isSuccess(exit) ? normal(exit.value) : abrupt(Cause.squash(exit.cause))) - } + if (self.checkpoint !== undefined) yield* self.checkpoint + // Suspending now leaves the calls queued: none of them has started. + if (self.suspending) continue + for (const handed of stop.calls) self.launch(self.machine.call(handed.id) ?? handed) continue } if (stop.kind === "stuck") { @@ -71,34 +88,149 @@ export class Driver { }) } - /** Stops host work still running, waiting for its cleanup. */ + /** Asks `run` to stop at the next step boundary, waking it if it waits on host work. */ + suspend(): void { + this.suspending = true + this.wake?.() + } + + /** + * Settles running host work to suspend: waits up to `graceMs` for calls that are not detachable yet (a durable + * tool's `start`, any other call) to finish, so their outcomes are saved, then interrupts the rest. A durable tool's + * `attach` is interrupted at once; its work keeps running and its call stays `started` with its handle. Any other + * call still running stays `starting`: its outcome is unknown. + */ + detach(graceMs: number): Effect.Effect { + const self = this + return Effect.gen(function* () { + const waiting = [...self.fibers].filter(([id]) => self.machine.call(id)?.status !== "started") + if (waiting.length > 0 && graceMs > 0) { + yield* Effect.raceFirst( + Fiber.awaitAll(waiting.map(([, fiber]) => fiber)), + Effect.sleep(graceMs), + ) + } + while (self.fibers.size > 0) { + for (const id of self.fibers.keys()) self.detached.add(id) + yield* Fiber.interruptAll([...self.fibers.values()]) + } + }) + } + + /** Stops host work still running, waiting for its cleanup; a durable tool's work is cancelled. */ interrupt(): Effect.Effect { const self = this return Effect.gen(function* () { self.stopping = true while (self.fibers.size > 0) yield* Fiber.interruptAll([...self.fibers.values()]) + // A suspended run's durable work keeps running, to be reattached on resume. + if (self.suspending) return + for (const call of self.machine.calls()) { + const request = call.request + if (call.status !== "started" || request.kind !== "tool" || call.handle === undefined) continue + yield* Effect.ignore(self.tools.cancel(request.path, call.handle)).pipe(Effect.provideContext(self.services)) + } }) } - private work(call: HostCall): Effect.Effect { - const request = call.request - if (request.kind === "tool") return this.tools.execute(request.path, request.args) - if (request.kind === "search") return this.tools.search(request.args) - // An extension's work, made by the extension bridge with the program's services in its requirements. - return this.machine.ctx.extensionWork!(request.call) as Effect.Effect + /** + * Picks up the host calls a restored machine was waiting on: an outcome the host already knows completes its call; + * a durable call reattaches by handle, or finds its handle by key, or starts; a call that never started starts; any + * other call that was running re-runs when its tool is safe to retry, and otherwise fails with an error the program + * can catch, since it may have partially run. + */ + resume(outcomes: Readonly>): void { + for (const call of this.machine.calls()) { + const known = outcomes[call.key] + if (known !== undefined) { + this.machine.complete(call.id, known.ok ? normal(known.value) : abrupt(toolError(known.error))) + continue + } + const request = call.request + if (request.kind === "extension") { + const failure = + call.status === "queued" ? lostError(`The call to ${call.label}`) : interruptedError(call.label) + this.machine.complete(call.id, abrupt(failure)) + continue + } + if (request.kind === "tool" && this.tools.tool(request.path)?.durable !== undefined) { + if (call.status === "started" && call.handle !== undefined) this.attach(call) + else if (call.status === "starting") this.lookup(call) + else this.launch(call) + continue + } + const retry = request.kind === "search" || this.retries(call) + if (call.status === "queued" || retry) this.launch(call) + else this.machine.complete(call.id, abrupt(interruptedError(call.label))) + } } - // Starts concurrent host work now; its outcome goes back to the machine's inbox, in completion order. - private start(call: HostCall): void { - // Starts synchronously, so admission and hooks happen before the machine runs another job. - const fiber = Effect.runForkWith(this.services)(this.work(call)) - this.fibers.set(call.id, fiber) + private retries(call: HostCall): boolean { + const request = call.request + return request.kind === "tool" && this.tools.tool(request.path)?.retry === "safe" + } + + // Starts host work now; its outcome goes back to the machine: a blocking call's continues the job that made it, a + // concurrent call's waits in the inbox and settles its promise in a later job, in completion order. + private launch(call: HostCall): void { + call.status = "starting" + const request = call.request + if (request.kind === "tool" && this.tools.tool(request.path)?.durable !== undefined) { + return this.fork(call.id, this.tools.start(request.path, request.args, call.key), (handle) => { + const current = this.machine.call(call.id) + if (current === undefined) return + current.status = "started" + current.handle = handle as Json + this.attach(current) + }) + } + if (request.kind === "tool") return this.fork(call.id, this.tools.execute(request.path, request.args)) + if (request.kind === "search") return this.fork(call.id, this.tools.search(request.args)) + // An extension's work, made by the extension bridge with the program's services in its requirements. + return this.fork(call.id, this.machine.ctx.extensionWork!(request.call) as Effect.Effect) + } + + private attach(call: HostCall): void { + const request = call.request + if (request.kind !== "tool") return + this.fork(call.id, this.tools.attach(request.path, request.args, call.handle!)) + } + + // A durable call that may have started before the run was saved: reattach to its work if it did, else start it. + private lookup(call: HostCall): void { + const request = call.request + if (request.kind !== "tool") return + this.fork(call.id, this.tools.lookup(request.path, call.key), (handle) => { + const current = this.machine.call(call.id) + if (current === undefined) return + if (handle === undefined) return this.launch(current) + current.status = "started" + current.handle = handle as Json + this.attach(current) + }) + } + + // Forks `work` with the caller's services; it starts synchronously, so admission and hooks happen before the machine + // runs another job. A success goes to `next` when given, otherwise to the machine. + private fork(id: number, work: Effect.Effect, next?: (value: unknown) => void): void { + const fiber = Effect.runForkWith(this.services)(work) + this.fibers.set(id, fiber) fiber.addObserver((exit) => { - this.fibers.delete(call.id) - // Interrupted by the program ending: nothing is left to settle. - if (this.stopping) return + if (this.fibers.get(id) === fiber) this.fibers.delete(id) + // Interrupted to end or suspend the run: nothing is left to settle. + if (this.stopping || this.detached.has(id)) return + const call = this.machine.call(id) + if (call === undefined) return + if (next !== undefined && Exit.isSuccess(exit)) return next(exit.value) + if (call.blocking) { + // Blocking work interrupted on its own interrupts the execution. + if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) this.interrupted = exit.cause + else this.machine.complete(id, Exit.isSuccess(exit) ? normal(exit.value) : abrupt(Cause.squash(exit.cause))) + this.wake?.() + return + } this.machine.complete( - call.id, + id, Exit.isSuccess(exit) ? normal(exit.value) : abrupt( @@ -115,7 +247,7 @@ export class Driver { private get settled(): Effect.Effect { return Effect.callback((resume) => { - if (this.machine.ready) return resume(Effect.void) + if (this.machine.ready || this.suspending || this.interrupted !== undefined) return resume(Effect.void) this.wake = () => { this.wake = undefined resume(Effect.void) @@ -126,3 +258,9 @@ export class Driver { }) } } + +/** What a call that was running when its run was suspended fails with, when it can't safely run again. */ +const interruptedError = (label: string) => + toolError( + `The call to ${label} was interrupted when the run was suspended and may have partially run; check its effects before calling it again.`, + ) diff --git a/packages/codemode/src/interpreter/execute.ts b/packages/codemode/src/interpreter/execute.ts index becfb04c56b..410bf7c9a6d 100644 --- a/packages/codemode/src/interpreter/execute.ts +++ b/packages/codemode/src/interpreter/execute.ts @@ -1,15 +1,51 @@ import { parse, type Program } from "acorn" -import { Cause, Effect, Option, Schema } from "effect" -import type { DataValue, Diagnostic, ResolvedExecutionLimits, Result } from "../codemode.js" +import { Cause, Deferred, Effect, Option, Schema } from "effect" +import type { + DataValue, + Diagnostic, + Pending, + ResolvedExecutionLimits, + Result, + Suspended, +} from "../codemode.js" +import type { Json } from "../data.js" +import { capture, fromBytes, restore, type Snapshot, SnapshotError, toBytes } from "../snapshot/snapshot.js" import { ToolRuntime } from "../tool-runtime.js" import { normalizeError } from "./errors.js" import { createBuiltins } from "./intrinsics.js" import { Interpreter } from "./interpreter.js" import type { Value } from "./objects.js" import { formatLocation, sourceLocation } from "./model.js" -import { Driver } from "./driver.js" -import type { Machine } from "../machine/machine.js" +import { Driver, type Outcome, SUSPENDED } from "./driver.js" +import { Interruption } from "./signals.js" import { Source } from "./source.js" +import { stats } from "../machine/task.js" + +/** How a runtime runs programs: its tools, limits, hooks, and host globals, shared by every run it starts. */ +export type Setup = { + readonly prepared: ToolRuntime.Prepared + readonly limits: ResolvedExecutionLimits + readonly hooks: ToolRuntime.Hooks + /** The host's globals, made again for a restored run; see `Interpreter`. */ + readonly globals?: ((ctx: Interpreter) => ReadonlyArray) | undefined + /** Whether the host globals can hand the program values with no data form (extensions can). */ + readonly lossy?: boolean + /** How long suspending waits for running host calls to finish, and the most bytes a saved state may take. */ + readonly suspend?: { readonly graceMs?: number | undefined; readonly maxBytes?: number | undefined } +} + +/** A running execution: its outcome, and a way to suspend it. */ +export type Run = { + /** Runs the program: its result, or its saved state once suspended. Run it once. */ + readonly result: Effect.Effect + /** + * Stops the run at the next step boundary, settles its host calls, and saves its state; what `result` gives. A run + * that already ended gives its result. + */ + readonly suspend: Effect.Effect +} + +const DEFAULT_GRACE_MS = 50 export const executeProgram = ( code: string, @@ -17,56 +53,213 @@ export const executeProgram = ( limits: ResolvedExecutionLimits, hooks: ToolRuntime.Hooks, globals?: (ctx: Interpreter) => ReadonlyArray, -): Effect.Effect => { + bindings?: (ctx: Interpreter) => ReadonlyArray, +): Effect.Effect => + executeSetup({ prepared, limits, hooks, globals }, code, bindings) + +/** Runs one program to its end; nothing can suspend it. */ +export const executeSetup = ( + setup: Setup, + code: string, + bindings?: (ctx: Interpreter) => ReadonlyArray, +): Effect.Effect => + // Allocate execution state inside suspension so reused Effects never share it. + Effect.suspend(() => startProgram(setup, code, bindings).result as Effect.Effect) + +/** Starts a program: a handle whose `result` runs it, and whose `suspend` saves its state. */ +export const startProgram = ( + setup: Setup, + code: string, + bindings?: (ctx: Interpreter) => ReadonlyArray, + runId: string = crypto.randomUUID(), +): Run => { if (code.trim().length === 0) { - return Effect.succeed({ - ok: false, - error: { kind: "ParseError", message: "Code cannot be empty." }, - toolCalls: [], - }) + return ended({ ok: false, error: { kind: "ParseError", message: "Code cannot be empty." }, toolCalls: [] }) + } + return new Execution(setup, runId, 0, () => { + const parsed = parseProgram(code) + if (!parsed.ok) return { ok: false, error: parsed.error, toolCalls: [] } + const ctx = instantiate(setup, bindings) + ctx.machine.runId = runId + ctx.start(parsed.source) + return ctx + }).run +} + +/** + * Resumes a saved run in this runtime: a handle like `startProgram`'s. `outcomes` completes pending host calls by + * key. Throws a `SnapshotError` when the state can't be read or belongs to another build, other host globals, or + * other sources. + */ +export const resumeProgram = ( + setup: Setup, + saved: Snapshot | Uint8Array | unknown, + outcomes: Readonly> = {}, +): Run => { + const fresh = instantiate(setup) + const snapshot = restoreInto(setup, saved instanceof Uint8Array ? fromBytes(saved) : saved, fresh) + return new Execution(setup, snapshot.header.runId, snapshot.header.budget.activeMs, () => fresh, outcomes).run +} + +const ended = (result: Result): Run => ({ result: Effect.succeed(result), suspend: Effect.succeed(result) }) + +// Sources restored recently, by text: the AST is never changed, so runs restored from the same program share it. +const restoredSources = new Map() + +const restoreInto = (setup: Setup, saved: unknown, fresh: Interpreter): Snapshot => + restore(saved, fresh as Interpreter, { + bare: bare(), + parse: (code) => { + const known = restoredSources.get(code) + if (known !== undefined) return known + const parsed = parseProgram(code) + if (!parsed.ok) throw new SnapshotError(`A saved source no longer parses: ${parsed.error.message}`) + if (restoredSources.size >= 16) restoredSources.delete(restoredSources.keys().next().value!) + restoredSources.set(code, parsed.source) + return parsed.source + }, + interruption: () => new Interruption(Cause.interrupt()), + }) + +// A new runtime: intrinsics, the host globals, the program's bindings, and a fresh tool bridge. +const instantiate = ( + setup: Setup, + bindings?: (ctx: Interpreter) => ReadonlyArray, +): Interpreter => { + const ctx = new Interpreter({ + tools: ToolRuntime.make(setup.prepared, setup.limits.maxToolCalls, setup.hooks), + builtins: createBuiltins(), + logs: [], + globals: setup.globals, + bindings, + }) + if (roundTrip) driven.add(ctx.machine) + return ctx +} + +let bareRuntime: Interpreter | undefined +// The intrinsics alone, which the build id is taken from. +const bare = () => (bareRuntime ??= instantiate({ prepared: ToolRuntime.prepare({}), limits: noLimits, hooks: {} })) +const noLimits: ResolvedExecutionLimits = { timeoutMs: undefined, maxToolCalls: undefined, maxOutputBytes: undefined } + +const pristines = new WeakMap>() +// A runtime as fresh as a run's, never run, to tell which built-ins and host globals a run changed. +const pristine = (setup: Setup): Interpreter => { + if (setup.globals === undefined) return bare() + const known = pristines.get(setup) + if (known !== undefined) return known + const made = instantiate(setup) as Interpreter + pristines.set(setup, made) + return made +} + +/** + * The round-trip test mode (`CODEMODE_ROUNDTRIP=1`): at every host stop and every slice, which come every few steps, + * a run's state is saved to bytes and restored into a brand-new runtime, which continues the run. + */ +const roundTrip = typeof process !== "undefined" && process.env.CODEMODE_ROUNDTRIP === "1" +const ROUND_TRIP_STEPS = 5 +const ROUND_TRIP_MAX = 200 +// The machines runs drive, so tests that step a machine themselves see no extra slices. +const driven = new WeakSet() +if (roundTrip) { + // A slice every few steps, so the run stops (and round-trips) all through its body, not only at host calls. + let countdown = ROUND_TRIP_STEPS + stats.inspect = (_stack, task) => { + if (!driven.has(task.machine) || --countdown > 0) return + countdown = ROUND_TRIP_STEPS + task.slice = true + } +} + +/** One run's state: the runtime it is in now (restoring swaps it), its driver, and how much active time it used. */ +class Execution { + private ctx: Interpreter | undefined + private driver: Driver | undefined + private suspendAsked = false + private started = false + private trips = 0 + // Checkpoints to let pass before the next round trip, so a large state is not saved at every one. + private skip = 0 + private readonly done = Deferred.makeUnsafe() + + constructor( + private readonly setup: Setup, + private readonly runId: string, + /** Active milliseconds used before this run, by earlier ones of the same execution. */ + private readonly activeBefore: number, + private readonly prepare: () => Interpreter | Result, + private readonly outcomes?: Readonly>, + ) {} + + get run(): Run { + return { + result: Effect.suspend(() => { + if (this.started) return Deferred.await(this.done) + this.started = true + return this.execute().pipe(Effect.onExit((exit) => Deferred.done(this.done, exit))) + }), + suspend: Effect.suspend(() => { + this.suspendAsked = true + this.driver?.suspend() + return Deferred.await(this.done) + }), + } } - // Allocate execution state inside suspension so reused Effects never share it. - return Effect.suspend(() => { - const builtins = createBuiltins() - const tools = ToolRuntime.make(prepared, limits.maxToolCalls, hooks) - const logs: Array = [] - const logged = () => (logs.length > 0 ? { logs: [...logs] } : {}) + private execute(): Effect.Effect { + const self = this + const setup = this.setup + const limits = setup.limits + const startedAt = Date.now() + const logged = () => { + const logs = self.ctx?.logs ?? [] + return logs.length > 0 ? { logs: [...logs] } : {} + } + const toolCalls = () => self.ctx?.tools.calls ?? [] // Set only after copy-out so timeouts cannot report invalid values as completed. - let returned: { value: DataValue; machine: Machine } | undefined - let driver: Driver | undefined + let returned: { value: DataValue; warnings: () => Array } | undefined const base = Effect.gen(function* () { - const parsed = parseProgram(code) - if (!parsed.ok) return { ok: false, error: parsed.error, toolCalls: [] } satisfies Result + const prepared = self.prepare() + if (!(prepared instanceof Interpreter)) return prepared + self.ctx = prepared const services = yield* Effect.context() - const ctx = new Interpreter({ tools, builtins, logs, globals }) - ctx.start(parsed.source) - driver = new Driver(ctx.machine, tools, services) + const driver = new Driver(prepared.machine, prepared.tools, services) + self.driver = driver + if (self.suspendAsked) driver.suspend() + if (roundTrip) driver.checkpoint = Effect.sync(() => self.trip()) + if (self.outcomes !== undefined) driver.resume(self.outcomes) const outcome = yield* driver.run() + if (outcome === SUSPENDED) { + yield* driver.detach(setup.suspend?.graceMs ?? DEFAULT_GRACE_MS) + return self.save(Date.now() - startedAt) + } + const ctx = self.ctx if (!outcome.ok) { - return { ok: false, error: normalizeError(outcome.error), ...logged(), toolCalls: tools.calls } satisfies Result + return { ok: false, error: normalizeError(outcome.error), ...logged(), toolCalls: toolCalls() } satisfies Result } const result = (outcome.value as DataValue | undefined) ?? null - returned = { value: result, machine: ctx.machine } + const machine = ctx.machine + returned = { value: result, warnings: () => machine.diagnostics() } // Host work the program left running is interrupted, not awaited. yield* driver.interrupt() - const warnings = ctx.machine.diagnostics() + const warnings = machine.diagnostics() return { ok: true, value: result, ...(warnings.length > 0 ? { warnings } : {}), ...logged(), - toolCalls: tools.calls, + toolCalls: toolCalls(), } satisfies Result - }).pipe(Effect.ensuring(Effect.suspend(() => driver?.interrupt() ?? Effect.void))) + }).pipe(Effect.ensuring(Effect.suspend(() => self.driver?.interrupt() ?? Effect.void))) const timeoutMs = limits.timeoutMs const operation = timeoutMs === undefined ? base : base.pipe( Effect.timeoutOrElse({ - duration: timeoutMs, + duration: Math.max(0, timeoutMs - this.activeBefore), orElse: () => Effect.sync(() => { if (returned === undefined) { @@ -74,7 +267,7 @@ export const executeProgram = ( ok: false, error: { kind: "TimeoutExceeded", message: `Execution timed out after ${timeoutMs}ms.` }, ...logged(), - toolCalls: tools.calls, + toolCalls: toolCalls(), } satisfies Result } // Keep the timeout warning first so truncation preserves it. @@ -86,10 +279,10 @@ export const executeProgram = ( kind: "TimeoutExceeded", message: `The program returned, but background work was still running at the ${timeoutMs}ms timeout and was interrupted. Await all started promises.`, }, - ...returned.machine.diagnostics(), + ...returned.warnings(), ], ...logged(), - toolCalls: tools.calls, + toolCalls: toolCalls(), } satisfies Result }), }), @@ -103,14 +296,90 @@ export const executeProgram = ( ok: false, error: normalizeError(Cause.squash(cause)), ...logged(), - toolCalls: tools.calls, + toolCalls: toolCalls(), } satisfies Result), ), Effect.map((result) => - limits.maxOutputBytes === undefined ? result : boundOutput(result, limits.maxOutputBytes), + result.ok === "suspended" || limits.maxOutputBytes === undefined + ? result + : boundOutput(result, limits.maxOutputBytes), ), ) - }) + } + + // Saves the run's state once its host calls are settled. + private save(activeMs: number): Result | Suspended { + const ctx = this.ctx! + const limits = this.setup.limits + const saved = capture(ctx as Interpreter, { + bare: bare(), + pristine: pristine(this.setup), + runId: this.runId, + limits: { + timeoutMs: limits.timeoutMs ?? null, + maxToolCalls: limits.maxToolCalls ?? null, + maxOutputBytes: limits.maxOutputBytes ?? null, + }, + activeMs: this.activeBefore + activeMs, + strict: false, + }) + const maxBytes = this.setup.suspend?.maxBytes + if (maxBytes !== undefined) { + const size = toBytes(saved.snapshot).byteLength + if (size > maxBytes) { + const message = `The run's state takes ${size} bytes, more than the ${maxBytes}-byte limit, so it couldn't be suspended.` + return { ok: false, error: { kind: "ExecutionFailure", message }, toolCalls: ctx.tools.calls } + } + } + const pending = ctx.machine.calls().flatMap((call): Array => { + if (call.status === "completed") return [] + const request = call.request + return [ + { + id: call.id, + path: request.kind === "tool" ? request.path.join(".") : request.kind === "search" ? "search" : call.label, + args: request.kind === "extension" ? [] : request.args.map((arg): Json => arg ?? null), + key: call.key, + status: call.status, + }, + ] + }) + return { ok: "suspended", state: saved.snapshot, pending } + } + + // The round-trip test mode's checkpoint: saves the state to bytes and continues in a brand-new runtime. States that + // hold live host values (an extension call in flight, a function an extension returned) can't round-trip, so they + // are skipped; a lost value anywhere else is a codec gap and fails the run. + private trip(): void { + const ctx = this.ctx! + const driver = this.driver! + if (this.trips >= ROUND_TRIP_MAX) { + driven.delete(ctx.machine) + return + } + if (this.skip > 0) { + this.skip-- + return + } + if (ctx.machine.calls().some((call) => call.request.kind === "extension")) return + this.trips++ + const saved = capture(ctx as Interpreter, { + bare: bare(), + pristine: pristine(this.setup), + runId: this.runId, + limits: { timeoutMs: null, maxToolCalls: null, maxOutputBytes: null }, + activeMs: 0, + strict: this.setup.lossy !== true, + }) + const bytes = toBytes(saved.snapshot) + this.skip = Math.floor(saved.snapshot.records.length / 200 + bytes.byteLength / 100_000) + if (saved.lost.length > 0) return + const fresh = instantiate(this.setup) + restoreInto(this.setup, fromBytes(bytes), fresh) + this.ctx = fresh + driver.machine = fresh.machine + driver.tools = fresh.tools + } } export const parseProgram = ( diff --git a/packages/codemode/src/interpreter/extensions.ts b/packages/codemode/src/interpreter/extensions.ts index 853a777c0ba..a94ecfc7821 100644 --- a/packages/codemode/src/interpreter/extensions.ts +++ b/packages/codemode/src/interpreter/extensions.ts @@ -5,7 +5,7 @@ import { errorMessage, errorType } from "./errors.js" import type { Interpreter } from "./interpreter.js" import { createErrorValue } from "./intrinsics.js" import { MAX_ARRAY_LENGTH, MAX_VALUE_DEPTH } from "./limits.js" -import { type AstNode, PendingThrow, rangeError, Throw, typeError } from "./model.js" +import { type AstNode, Lost, lostError, PendingThrow, rangeError, Throw, typeError } from "./model.js" import { native } from "./native.js" import { define, @@ -223,6 +223,7 @@ const ExtensionCall = nativeKind("extension call", (task, frame, input) => { const invocation = slots[3] as ExtensionInvocation | undefined const args = slots[1] as ReadonlyArray if (frame.phase === 2) return input as Value + if (slots[0] instanceof Lost) throw lostError(`The function ${label}`) if (frame.phase === 0 && invocation !== undefined && task.ctx.tools.hooks["extension.before"] !== undefined) { frame.phase = 1 const call = { stage: "before", label, invocation, host: undefined, args, threw: false } as const diff --git a/packages/codemode/src/interpreter/interpreter.ts b/packages/codemode/src/interpreter/interpreter.ts index 9fddc2d275f..e8ecbd3f2b3 100644 --- a/packages/codemode/src/interpreter/interpreter.ts +++ b/packages/codemode/src/interpreter/interpreter.ts @@ -25,12 +25,13 @@ export class Interpreter { /** Names for this runtime's intrinsics, taken before any program code can change a built-in. */ readonly intrinsics: IntrinsicNames /** Template objects by site: a tag sees the same `strings` array every time its literal is evaluated, as in JS. */ - readonly templates = new WeakMap() + readonly templates = new Map() /** Makes the Effect an extension function's host work runs as; set by the extension bridge. */ extensionWork: ((request: ExtensionRequest) => unknown) | undefined /** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */ readonly sources = new Map() - private readonly globalScope: Map + /** The global bindings: the intrinsics, the host's globals, and the program's bindings. */ + readonly globalScope: Map private readonly modules = new Map() private readonly namespaces = new Map() @@ -38,7 +39,10 @@ export class Interpreter { readonly tools: ToolRuntime readonly builtins: Builtins readonly logs?: Array + /** The host's globals (extensions, a test harness): made again, the same way, when a saved run is restored. */ readonly globals?: (ctx: Interpreter) => ReadonlyArray + /** Data bound for this program, part of its saved state; host globals of the same name win. */ + readonly bindings?: (ctx: Interpreter) => ReadonlyArray }) { this.tools = options.tools this.builtins = options.builtins @@ -48,8 +52,9 @@ export class Interpreter { // Program code has no receiver: top-level `this` is undefined, as in a module. this.globalScope = new Map([["this", { mutable: false, value: undefined }]]) const intrinsics = globals(this) - this.intrinsics = new IntrinsicNames(intrinsics, this.builtins) - for (const [name, value] of [...intrinsics, ...(options.globals?.(this) ?? [])]) { + const hosts = options.globals?.(this) ?? [] + this.intrinsics = new IntrinsicNames(intrinsics, this.builtins, hosts) + for (const [name, value] of [...intrinsics, ...(options.bindings?.(this) ?? []), ...hosts]) { this.globalScope.set(name, { mutable: false, value }) } nativeRule.sealed.add(this.builtins.Function) diff --git a/packages/codemode/src/interpreter/intrinsic-names.ts b/packages/codemode/src/interpreter/intrinsic-names.ts index 840a55f878b..e28a9c3c5b6 100644 --- a/packages/codemode/src/interpreter/intrinsic-names.ts +++ b/packages/codemode/src/interpreter/intrinsic-names.ts @@ -5,7 +5,8 @@ import { Obj, type Value } from "./objects.js" /** * Deterministic names for one runtime's intrinsic objects, so saved state can refer to a built-in by name instead of * copying it: a breadth-first walk from the global names (`Array.prototype.map`), then `%Name%` for built-in - * prototypes the walk cannot reach (`%Generator%`) and what is reachable from them. The first path found names a value. + * prototypes the walk cannot reach (`%Generator%`) and what is reachable from them, then `@name` for the host's globals + * (extensions, a test harness) and what only they reach. The first path found names a value. * * The walk runs when the runtime is created, before any program can change a built-in; the names themselves are * spelled out only when asked for. @@ -19,7 +20,11 @@ export class IntrinsicNames { private names: Array | undefined private lookup: Map | undefined - constructor(globals: ReadonlyArray, builtins: Builtins) { + constructor( + globals: ReadonlyArray, + builtins: Builtins, + hosts: ReadonlyArray = [], + ) { let next = 0 const visit = (value: Value, path: string | readonly [number, string | symbol]) => { if (!(value instanceof Obj) || this.index.has(value)) return @@ -40,6 +45,10 @@ export class IntrinsicNames { visit(value, `%${name}%`) drain() } + for (const [name, value] of hosts) { + visit(value, `@${name}`) + drain() + } } /** The name of an intrinsic, or undefined for any other object. */ diff --git a/packages/codemode/src/interpreter/model.ts b/packages/codemode/src/interpreter/model.ts index 56243864912..f9913d9b2e8 100644 --- a/packages/codemode/src/interpreter/model.ts +++ b/packages/codemode/src/interpreter/model.ts @@ -54,6 +54,22 @@ export class PendingThrow { } } +/** + * A host value a restored run cannot have back: a function an extension returned, or what a host function returned, + * which have no data form. Using it fails with `lostError`. + */ +export class Lost { + constructor(readonly description: string) {} +} + +/** What using a value lost to a suspend throws. */ +export const lostError = (description: string, node?: AstNode): PendingThrow => + new PendingThrow( + "TypeError", + `${description} came from the host and was lost when the run was suspended; get it again after resuming.`, + node, + ) + const failure = (type: ErrorType, kind?: DiagnosticKind) => (message: string, node?: AstNode) => new PendingThrow(type, message, node, kind) diff --git a/packages/codemode/src/interpreter/table.ts b/packages/codemode/src/interpreter/table.ts index 2e1c5aa4124..b6b21ac455e 100644 --- a/packages/codemode/src/interpreter/table.ts +++ b/packages/codemode/src/interpreter/table.ts @@ -1,6 +1,7 @@ import type { Value } from "./objects.js" -const deleted: unique symbol = Symbol("codemode.deleted") +/** The key of a deleted entry. */ +export const deleted: unique symbol = Symbol("codemode.deleted") /** A position in a table's entries, kept by the table so compaction can move it. */ export type TableCursor = { index: number; done: boolean } diff --git a/packages/codemode/src/machine/machine.ts b/packages/codemode/src/machine/machine.ts index f6af584040b..77918bdf65b 100644 --- a/packages/codemode/src/machine/machine.ts +++ b/packages/codemode/src/machine/machine.ts @@ -47,6 +47,8 @@ export class Machine { outcome: Completion | undefined /** Frames suspended at an `await`, by the slice cut off the stack, so a stall can point at the one that is stuck. */ readonly parked = new Map, Parked>() + /** Names this run's host calls, so each has an idempotency key (`HostCall.key`). */ + runId = "" private readonly queue: Array = [] private head = 0 @@ -84,10 +86,7 @@ export class Machine { if (this.queued.length > 0) { const calls = this.queued this.queued = [] - for (const call of calls) { - call.status = "inFlight" - this.running.set(call.id, call) - } + for (const call of calls) this.running.set(call.id, call) return { kind: "host", calls } } if (this.sliced) { @@ -135,9 +134,25 @@ export class Machine { this.inbox.push({ call, completion }) } - /** Whether a host call's outcome is waiting to be delivered. */ + /** Whether `run` has something to do: a blocking call's outcome, or one waiting in the inbox while no job runs. */ get ready(): boolean { - return this.inbox.length > 0 || this.input !== undefined + return this.input !== undefined || (this.root.stack.length === 0 && this.inbox.length > 0) + } + + /** A host call handed to the driver and not yet completed, by id. */ + call(id: number): HostCall | undefined { + return this.running.get(id) + } + + /** The host calls handed to the driver and not yet completed, in the order they were made. */ + calls(): Array { + return [...this.running.values()] + } + + /** Drops jobs already run from the queue, so saved state holds only the ones still to run. */ + compact(): void { + this.queue.splice(0, this.head) + this.head = 0 } /** @@ -174,7 +189,8 @@ export class Machine { readonly site: AstNode | undefined }, ): HostCall { - const record = new HostCall(this.nextHostID++, request, call.label, false, call.result, call.resolving, call.site) + const id = this.nextHostID++ + const record = new HostCall(id, `${this.runId}:${id}`, request, call.label, false, call.result, call.resolving, call.site) this.queued.push(record) return record } @@ -305,8 +321,10 @@ export class Machine { return } if (signal instanceof Host) { + const id = this.nextHostID++ const call = new HostCall( - this.nextHostID++, + id, + `${this.runId}:${id}`, signal.request, signal.request.kind, true, diff --git a/packages/codemode/src/machine/scheduler.ts b/packages/codemode/src/machine/scheduler.ts index 45eb6102dd0..7ba543d7a36 100644 --- a/packages/codemode/src/machine/scheduler.ts +++ b/packages/codemode/src/machine/scheduler.ts @@ -97,9 +97,18 @@ export type ExtensionRequest = { * promise in a later job; a blocking call stops the machine, and no other job runs until it ends. */ export class HostCall { - status: "queued" | "inFlight" | "completed" = "queued" + /** + * Where the call is: `queued` (written ahead, not started), `starting` (the host may have started it; a durable + * tool's handle is not known yet), `started` (a durable tool returned `handle`, so its work can be reattached), or + * `completed`. + */ + status: "queued" | "starting" | "started" | "completed" = "queued" + /** A durable tool's handle on its running work, once started. */ + handle: Json | undefined = undefined constructor( readonly id: number, + /** The idempotency key, `:`, which a durable tool also names its work by. */ + readonly key: string, readonly request: HostRequest, /** What runs: a tool path, or an extension function's label. */ readonly label: string, diff --git a/packages/codemode/src/machine/task.ts b/packages/codemode/src/machine/task.ts index c88239b9159..c67e890a224 100644 --- a/packages/codemode/src/machine/task.ts +++ b/packages/codemode/src/machine/task.ts @@ -21,9 +21,12 @@ import type { Machine } from "./machine.js" /** * Steps run by every machine task in this process, so tests can see that a program ran on the machine; `inspect`, when - * a test sets it, sees the stack before every step. + * a test sets it, sees the stack (and the task) before every step. */ -export const stats: { steps: number; inspect: ((stack: ReadonlyArray) => void) | undefined } = { +export const stats: { + steps: number + inspect: ((stack: ReadonlyArray, task: MachineTask) => void) | undefined +} = { steps: 0, inspect: undefined, } @@ -128,7 +131,7 @@ export class MachineTask { let value = input while (true) { stats.steps++ - if (stats.inspect !== undefined) stats.inspect(stack) + if (stats.inspect !== undefined) stats.inspect(stack, this) if (!ok) { let error = value while (true) { diff --git a/packages/codemode/src/snapshot/codec.ts b/packages/codemode/src/snapshot/codec.ts new file mode 100644 index 00000000000..0bdeffc28fb --- /dev/null +++ b/packages/codemode/src/snapshot/codec.ts @@ -0,0 +1,887 @@ +import { DESCEND } from "../data.js" +import { Interpreter } from "../interpreter/interpreter.js" +import { + type AstNode, + AsyncIteratorSymbol, + GeneratorReturn, + IteratorSymbol, + Lost, + lostError, + OptionalShortCircuit, + PendingThrow, + Throw, +} from "../interpreter/model.js" +import { + Arguments, + Arr, + BoundFn, + Bytes, + DateObj, + ErrorObj, + Fn, + GeneratorObj, + HeadersObj, + Helper, + IteratorObj, + MapObj, + Native, + Obj, + Position, + PromiseObj, + RegExpObj, + Resolver, + SetObj, + type Slot, + URLObj, + type Value, + URLSearchParamsObj, + WeakMapObj, + WeakSetObj, +} from "../interpreter/objects.js" +import { ScopeStack } from "../interpreter/scope.js" +import { Await, Convert, Enter, Host, Interruption, Invoke, Push, Slice, Yield } from "../interpreter/signals.js" +import { deleted, OrderedTable } from "../interpreter/table.js" +import { Frame, kinds, PENDING } from "../machine/frame.js" +import { AsyncFromSyncIterator } from "../machine/generators.js" +import { Machine } from "../machine/machine.js" +import { consumers, EXIT } from "../machine/native-kind.js" +import { HostCall, Resolving } from "../machine/scheduler.js" +import { MachineTask } from "../machine/task.js" +import { NEXT } from "../stdlib/array.js" +import { TextDecoderObj } from "../stdlib/bytes.js" +import { ToolError, toolError } from "../tool-error.js" +import { ToolReference, ToolRuntimeError } from "../tool-runtime.js" + +// A graph codec for a run's state: every object reachable from the roots becomes one record, so identity, sharing, +// and cycles survive, and every value inside a record is tagged JSON. Built-ins, frame kinds, consumers, AST nodes, +// and the machine's own objects are named rather than copied; a value with no data form (a live host function, say) +// becomes a `Lost` placeholder. Nothing here evaluates anything: decoding only allocates and assigns. + +/** A plain JSON value, as a snapshot holds it. */ +export type Json = null | boolean | number | string | ReadonlyArray | { readonly [key: string]: Json } + +/** + * A value inside a record: a JSON primitive, or a tag (an array whose first item says what it is): + * - `["u"]` undefined, `["n", "NaN" | "Infinity" | "-Infinity" | "-0"]` a number JSON cannot spell, `["-"]` an absent + * field, `["h"]` an array hole; + * - `["s", name]` an interpreter symbol, `["k", name]` a frame kind, `["c", name]` a consumer; + * - `["i", name]` a built-in or host global, unchanged since the runtime was made; + * - `["a", source, index]` an AST node, `["A", source, index, key]` an array the AST owns; + * - `["r", id]` another record. + */ +export type Encoded = string | number | boolean | null | ReadonlyArray + +/** One object of the graph. `t` says how to read the rest. */ +export type Record = { readonly t: string; readonly [field: string]: Json } + +/** A saved state can't be read, or doesn't fit this runtime. */ +export class SnapshotError extends Error { + override readonly name = "SnapshotError" +} + +/** What the encoder asks of the runtime whose state it saves. */ +export type EncodeEnv = { + /** The name of a built-in or host global object. */ + readonly nameOf: (value: Obj) => string | undefined + /** Whether a named object is still as the runtime made it, so its name alone restores it. */ + readonly unchanged: (value: Obj, name: string) => boolean + /** The anchors: objects the restored runtime already has, filled in place (`Machine`, its root task, ...). */ + readonly anchorOf: (value: object) => string | undefined + readonly nodeId: (node: AstNode) => readonly [source: string, index: number] | undefined + readonly astArray: (array: ReadonlyArray) => readonly [source: string, index: number, key: string] | undefined + /** Values with no data form are reported here; strict encoding throws on the first instead. */ + readonly lost: Array + readonly strict: boolean +} + +/** What the decoder asks of the fresh runtime it restores into. */ +export type DecodeEnv = { + readonly named: (name: string) => Obj | undefined + readonly anchor: (name: string) => object | undefined + readonly node: (source: string, index: number) => AstNode | undefined + readonly astArray: (source: string, index: number, key: string) => Array | undefined + /** An `Interruption` (it holds an Effect cause, which this module does not make). */ + readonly interruption: () => Interruption +} + +// --- Registries --- + +const symbols = new Map([ + ["iterator", IteratorSymbol], + ["asyncIterator", AsyncIteratorSymbol], + ["pending", PENDING], + ["exit", EXIT], + ["optionalShortCircuit", OptionalShortCircuit], + ["slice", Slice], + ["deleted", deleted], + ["next", NEXT], + ["descend", DESCEND], +]) +const symbolNames = new Map([...symbols].map(([name, symbol]) => [symbol, name])) + +/** How one class saves: its own fields in order, and how a restored instance is made whole. */ +type ClassSpec = { + readonly name: string + readonly ctor: Function + /** Saved fields, in the order a constructor makes them. */ + readonly fields: ReadonlyArray + /** Own fields that are not saved: caches and runtime configuration, set to `reset`'s values. */ + readonly skip?: ReadonlyArray + /** Own fields with the same value on every instance. */ + readonly constants?: Readonly<{ [field: string]: unknown }> + /** An `Obj`: its prototype, extensibility, and properties are saved too. */ + readonly obj?: boolean + /** The restored runtime already has this object; it is filled in place. */ + readonly anchor?: string + /** Sets fields that are not saved, once the saved ones are in. */ + readonly reset?: (value: never) => void +} + +const objFields = ["props", "extensible", "proto"] +const callable = { tag: "Function" } + +const specs: ReadonlyArray = [ + { name: "Obj", ctor: Obj, fields: [], obj: true, constants: { tag: "Object" } }, + { name: "Arr", ctor: Arr, fields: ["items", "elements"], obj: true, constants: { tag: "Array" } }, + { name: "ErrorObj", ctor: ErrorObj, fields: ["failure"], obj: true, constants: { tag: "Error" } }, + { + name: "Fn", + ctor: Fn, + fields: ["length", "parameters", "body", "capturedScopes", "async", "generator", "arrow"], + obj: true, + constants: callable, + }, + { name: "Arguments", ctor: Arguments, fields: [], obj: true, constants: { tag: "Arguments" } }, + // Only named natives are saved (by name); an unnamed one is a host function, saved as `LostNative`. + { name: "Native", ctor: Native, fields: [], skip: ["length", "call", "construct", "callback"], obj: true }, + { + name: "BoundFn", + ctor: BoundFn, + fields: ["length", "target", "boundThis", "boundArgs"], + obj: true, + constants: { ...callable, construct: undefined, callback: true }, + }, + { + name: "Resolver", + ctor: Resolver, + fields: ["length", "resolving", "kind"], + obj: true, + constants: { ...callable, construct: undefined, callback: true }, + }, + { + name: "PromiseObj", + ctor: PromiseObj, + fields: ["state", "result", "reactions", "handled", "id"], + obj: true, + constants: { tag: "Promise" }, + }, + { + name: "GeneratorObj", + ctor: GeneratorObj, + fields: ["state", "frames", "queue", "asynchronous"], + obj: true, + constants: { tag: "Generator" }, + }, + { name: "IteratorObj", ctor: IteratorObj, fields: ["cursor"], obj: true, constants: { tag: "Iterator" } }, + { name: "DateObj", ctor: DateObj, fields: ["time"], obj: true, constants: { tag: "Date" } }, + { + name: "RegExpObj", + ctor: RegExpObj, + fields: ["source", "flags", "lastIndex"], + skip: ["compiled"], + obj: true, + constants: { tag: "RegExp" }, + reset: (value: { compiled: unknown }) => { + value.compiled = undefined + }, + }, + { name: "MapObj", ctor: MapObj, fields: ["map"], obj: true, constants: { tag: "Map" } }, + { name: "SetObj", ctor: SetObj, fields: ["set"], obj: true, constants: { tag: "Set" } }, + { name: "WeakMapObj", ctor: WeakMapObj, fields: ["map"], obj: true, constants: { tag: "WeakMap" } }, + { name: "WeakSetObj", ctor: WeakSetObj, fields: ["set"], obj: true, constants: { tag: "WeakSet" } }, + { + name: "URLSearchParamsObj", + ctor: URLSearchParamsObj, + fields: ["params"], + obj: true, + constants: { tag: "URLSearchParams" }, + }, + { name: "HeadersObj", ctor: HeadersObj, fields: ["headers"], obj: true, constants: { tag: "Headers" } }, + { name: "URLObj", ctor: URLObj, fields: ["searchParams", "url"], obj: true, constants: { tag: "URL" } }, + { name: "Bytes", ctor: Bytes, fields: ["bytes"], obj: true, constants: { tag: "Uint8Array" } }, + { name: "TextDecoderObj", ctor: TextDecoderObj, fields: ["decoder"], obj: true, constants: { tag: "Object" } }, + { + name: "AsyncFromSyncIterator", + ctor: AsyncFromSyncIterator, + fields: ["sync", "site"], + obj: true, + constants: { tag: "AsyncFromSyncIterator" }, + }, + { name: "Helper", ctor: Helper, fields: ["done", "running", "inner", "op", "source", "callback", "count"] }, + { name: "Position", ctor: Position, fields: ["index", "done", "source", "kind", "arrays"] }, + { + name: "OrderedTable", + ctor: OrderedTable, + fields: ["keys", "values", "cursors", "tombstones", "pruneAt"], + skip: ["index"], + // The index is derived from the keys. + reset: (table: { keys: Array; index: Map }) => { + table.index = new Map() + table.keys.forEach((key, at) => { + if (key !== deleted) table.index.set(key, at) + }) + }, + }, + { name: "ScopeStack", ctor: ScopeStack, fields: ["scopes", "fn"] }, + { name: "Frame", ctor: Frame, fields: ["kind", "node", "phase", "scope", "slots"] }, + { + name: "HostCall", + ctor: HostCall, + fields: ["status", "handle", "id", "key", "request", "label", "blocking", "result", "resolving", "site"], + }, + { name: "Resolving", ctor: Resolving, fields: ["done", "scheduler", "promise", "site"] }, + { name: "Throw", ctor: Throw, fields: ["value"] }, + { name: "GeneratorReturn", ctor: GeneratorReturn, fields: ["value"] }, + { name: "PendingThrow", ctor: PendingThrow, fields: ["type", "message", "kind", "suggestions", "node", "value"] }, + { name: "Enter", ctor: Enter, fields: ["frames", "input"] }, + { name: "Push", ctor: Push, fields: ["kind", "slots"] }, + { name: "Convert", ctor: Convert, fields: ["hints", "values", "ordinal", "coerce"] }, + { name: "Await", ctor: Await, fields: ["value", "node"] }, + { name: "Yield", ctor: Yield, fields: ["value"] }, + { name: "Host", ctor: Host, fields: ["request"] }, + { name: "Invoke", ctor: Invoke, fields: ["callable", "thisValue", "args", "site"] }, + { name: "ToolReference", ctor: ToolReference, fields: ["path"] }, + { name: "Lost", ctor: Lost, fields: ["description"] }, + { + name: "Machine", + ctor: Machine, + anchor: "machine", + fields: [ + "depth", + "intrinsicThen", + "outcome", + "parked", + "runId", + "queue", + "head", + "pending", + "nextID", + "nextHostID", + "unhandled", + "queued", + "running", + "inbox", + "input", + "sliced", + ], + skip: ["ctx", "root", "fuel", "sliceStart"], + }, + { + name: "MachineTask", + ctor: MachineTask, + anchor: "task", + fields: ["stack", "scopes", "signal", "slice"], + skip: ["machine", "ctx"], + }, + { + name: "Interpreter", + ctor: Interpreter, + anchor: "ctx", + fields: ["logs", "templates", "globalScope", "modules", "namespaces"], + skip: ["tools", "builtins", "machine", "intrinsics", "extensionWork", "sources"], + }, +] + +const byCtor = new Map(specs.map((spec) => [spec.ctor, spec])) +const byName = new Map(specs.map((spec) => [spec.name, spec])) + +/** Host error classes that can travel as a failure, by name. */ +const errorClasses = new Map([ + ["Error", Error], + ["TypeError", TypeError], + ["RangeError", RangeError], + ["SyntaxError", SyntaxError], + ["ReferenceError", ReferenceError], + ["EvalError", EvalError], + ["URIError", URIError], + ["ToolRuntimeError", ToolRuntimeError], + ["ToolError", ToolError], +]) +const errorNames = new Map([...errorClasses].map(([name, ctor]) => [ctor, name])) + +let kindNames: Map | undefined +let consumerNames: Map | undefined + +/** + * The names of every frame kind and consumer, and of every class with a codec: a build that saves a different set + * cannot read this one's snapshots. + */ +export const codecShape = (): string => + JSON.stringify([ + [...kinds.keys()].sort(), + [...consumers.keys()].sort(), + specs.map((spec) => [spec.name, spec.fields]), + [...symbols.keys()], + ]) + +// --- Encoding --- + +/** Encodes everything reachable from `roots`: the roots' values and the records they refer to. */ +export const encode = ( + roots: ReadonlyArray, + env: EncodeEnv, +): { readonly roots: Array; readonly records: Array } => { + const encoder = new Encoder(env) + const encoded = roots.map((root) => encoder.value(root)) + encoder.drain() + return { roots: encoded, records: encoder.records as Array } +} + +class Encoder { + readonly records: Array = [] + private readonly ids = new Map() + private readonly work: Array = [] + // A URL's `searchParams` is the same host object its URLSearchParams wraps; it is encoded once every URL is known. + private readonly owners = new Map() + private readonly params: Array = [] + + constructor(private readonly env: EncodeEnv) { + kindNames ??= new Map([...kinds].map(([name, kind]) => [kind, name])) + consumerNames ??= new Map([...consumers].map(([name, consumer]) => [consumer, name])) + } + + value(value: unknown): Encoded { + switch (typeof value) { + case "string": + case "boolean": + return value + case "undefined": + return ["u"] + case "number": + if (Number.isFinite(value) && !Object.is(value, -0)) return value + return ["n", Object.is(value, -0) ? "-0" : String(value)] + case "symbol": { + const name = symbolNames.get(value) + if (name === undefined) throw new SnapshotError(`Codec gap: the symbol ${String(value)} has no name.`) + return ["s", name] + } + case "bigint": + throw new SnapshotError("Codec gap: a bigint has no data form.") + } + if (value === null) return null + const object = value as object + const kind = kindNames!.get(object) + if (kind !== undefined) return ["k", kind] + const consumer = consumerNames!.get(object) + if (consumer !== undefined) return ["c", consumer] + if (object instanceof Obj) { + const name = this.env.nameOf(object) + if (name !== undefined && this.env.unchanged(object, name)) return ["i", name] + } else if (Array.isArray(object)) { + const owned = this.env.astArray(object) + if (owned !== undefined) return ["A", owned[0], owned[1], owned[2]] + } else { + const node = this.env.nodeId(object as AstNode) + if (node !== undefined) return ["a", node[0], node[1]] + } + return this.ref(object) + } + + drain(): void { + for (let object = this.work.shift(); object !== undefined; object = this.work.shift()) { + const id = this.ids.get(object)! + this.records[id] = this.record(object, id) + } + for (const [id, params] of this.params) { + const owner = this.owners.get(params) + this.records[id] = + owner === undefined ? { t: "URLSearchParams", s: params.toString() } : { t: "URLSearchParams", o: this.ref(owner) } + } + } + + private ref(object: object): Encoded { + const known = this.ids.get(object) + if (known !== undefined) return ["r", known] + const id = this.records.length + this.ids.set(object, id) + this.records.push(undefined) + this.work.push(object) + return ["r", id] + } + + private record(object: object, id: number): Record | undefined { + if (object instanceof Obj) { + const name = this.env.nameOf(object) + if (name !== undefined) { + const spec = this.spec(object) + return { t: "@", n: name, c: spec.name, ...this.fields(object, spec) } + } + } + if (Array.isArray(object)) { + // A sparse array (`length` can be ten million with nothing in it) saves only the indexes it has. + if (object.length > 1024) { + const present = Object.keys(object) + if (present.length * 2 < object.length) { + const entries: Array = [] + for (const key of present) entries.push(Number(key), this.value(object[Number(key)])) + return { t: "Array", l: object.length, s: entries } + } + } + const items: Array = [] + for (let at = 0; at < object.length; at++) items.push(at in object ? this.value(object[at]) : ["h"]) + return { t: "Array", v: items } + } + if (object instanceof Map) { + const entries: Array = [] + for (const [key, item] of object) entries.push(this.value(key), this.value(item)) + const anchor = this.env.anchorOf(object) + return anchor === undefined ? { t: "Map", e: entries } : { t: "Map", e: entries, a: anchor } + } + if (object instanceof Set) return { t: "Set", e: [...object].map((item) => this.value(item)) } + const spec = byCtor.get(object.constructor) + if (spec !== undefined && spec.name !== "Native") { + if (spec.anchor !== undefined && this.env.anchorOf(object) !== spec.anchor) { + throw new SnapshotError(`Codec gap: a second ${spec.name} is reachable from the state.`) + } + return { t: spec.name, ...this.fields(object, spec) } + } + if (object instanceof Native) { + // A host function made while the program ran: an extension's result. Its name says what was lost. + this.lose(`the function ${String(object.props.get("name") && "value" in object.props.get("name")! ? (object.props.get("name") as { value: unknown }).value : "")}`) + return { t: "LostNative", ...this.fields(object, byName.get("Fn")!, ["length"]) } + } + const proto = Object.getPrototypeOf(object) + if (proto === Object.prototype || proto === null) { + const entries: Array = [] + for (const key of Object.keys(object)) entries.push(key, this.value((object as { [key: string]: unknown })[key])) + return proto === null ? { t: "Object", e: entries, n: 1 } : { t: "Object", e: entries } + } + if (object instanceof Error) return this.error(object) + if (object instanceof Interruption) return { t: "Interruption" } + if (object instanceof URL) { + this.owners.set(object.searchParams, object) + return { t: "URL", h: object.href } + } + if (object instanceof URLSearchParams) { + this.params.push([id, object]) + return undefined + } + if (object instanceof Headers) return { t: "Headers", e: [...object].map(([key, item]) => [key, item]) } + if (object instanceof Uint8Array) { + return { t: "Uint8Array", b: this.ref(object.buffer), o: object.byteOffset, l: object.length } + } + if (object instanceof ArrayBuffer) return { t: "ArrayBuffer", d: base64(new Uint8Array(object)) } + if (object instanceof TextDecoder) return { t: "TextDecoder", f: object.fatal, i: object.ignoreBOM } + const what = typeof object === "function" ? "a host function" : `a host ${object.constructor?.name ?? "object"}` + this.lose(what) + return { t: "Lost", d: what } + } + + private lose(what: string): void { + if (this.env.strict) throw new SnapshotError(`Codec gap: ${what} has no data form.`) + this.env.lost.push(what) + } + + private spec(object: object): ClassSpec { + const spec = byCtor.get(object.constructor) + if (spec === undefined) throw new SnapshotError(`Codec gap: ${object.constructor.name} has no codec.`) + return spec + } + + // A class instance's saved fields, positional, with its `Obj` header when it is one. Fields the spec does not know + // are a codec gap: they would be silently dropped. + private fields(object: object, spec: ClassSpec, only?: ReadonlyArray): { [field: string]: Json } { + const record = object as { [field: string]: unknown } + const fields = only ?? spec.fields + if (only === undefined) { + for (const key of Object.keys(object)) { + if (fields.includes(key) || spec.skip?.includes(key) || (spec.constants !== undefined && key in spec.constants)) continue + if (spec.obj && (objFields.includes(key) || key === "tag")) continue + throw new SnapshotError(`Codec gap: ${spec.name}.${key} is not saved.`) + } + } + const values = fields.map((field) => (Object.hasOwn(object, field) ? this.value(record[field]) : ["-"])) + if (!(object instanceof Obj)) return { f: values } + const props: Array = [] + for (const [key, slot] of object.props) { + props.push(typeof key === "symbol" ? this.value(key) : key) + if ("value" in slot) { + props.push(this.value(slot.value), (slot.writable ? 1 : 0) | (slot.enumerable ? 2 : 0) | (slot.configurable ? 4 : 0)) + } else props.push(null, 8 | (slot.enumerable ? 2 : 0) | (slot.configurable ? 4 : 0)) + } + return { f: values, p: object.proto === null ? null : this.value(object.proto), x: object.extensible, o: props } + } + + private error(error: Error): Record { + const name = errorNames.get(error.constructor) + if (name === undefined) { + this.lose(`a host ${error.constructor.name}`) + return { t: "Lost", d: `a host ${error.constructor.name}` } + } + const fields: Array = [] + for (const key of Object.keys(error)) { + if (key === "message" || key === "stack") continue + fields.push(key, this.value((error as unknown as { [key: string]: unknown })[key])) + } + return { t: "Error", c: name, m: error.message, e: fields } + } +} + +// --- Decoding --- + +/** Rebuilds the graph `encode` saved, filling anchors in place: the decoded roots. */ +export const decode = ( + saved: { readonly roots: ReadonlyArray; readonly records: ReadonlyArray }, + env: DecodeEnv, +): Array => { + const decoder = new Decoder(saved.records, env) + for (let id = 0; id < saved.records.length; id++) decoder.shell(id) + for (let id = 0; id < saved.records.length; id++) decoder.fill(id) + decoder.finish() + return saved.roots.map((root) => decoder.value(root)) +} + +const invalid = (message: string): never => { + throw new SnapshotError(`Invalid snapshot: ${message}`) +} + +const isRecord = (value: unknown): value is { readonly t: string; readonly [field: string]: unknown } => + typeof value === "object" && value !== null && !Array.isArray(value) && typeof (value as { t?: unknown }).t === "string" + +const list = (value: unknown, what: string): ReadonlyArray => + Array.isArray(value) ? value : invalid(`${what} is not a list.`) + +const text = (value: unknown, what: string): string => (typeof value === "string" ? value : invalid(`${what} is not text.`)) + +const count = (value: unknown, what: string): number => + Number.isSafeInteger(value) && (value as number) >= 0 ? (value as number) : invalid(`${what} is not a count.`) + +const forbidden = new Set(["__proto__", "constructor", "prototype"]) + +class Decoder { + private readonly shells: Array + private readonly filled: Array + // Derived state is rebuilt once every record is filled in, since it reads other records. + private readonly resets: Array<() => void> = [] + + constructor( + private readonly records: ReadonlyArray, + private readonly env: DecodeEnv, + ) { + this.shells = new Array(records.length) + this.filled = new Array(records.length).fill(false) + } + + private at(id: number): { readonly t: string; readonly [field: string]: unknown } { + const record = this.records[id] + return isRecord(record) ? record : invalid(`record ${id} is malformed.`) + } + + // Allocates the object a record restores, before anything is filled in, so references and cycles resolve. + shell(id: number): object { + const known = this.shells[id] + if (known !== undefined) return known + const record = this.at(id) + const made = this.make(record, id) + this.shells[id] = made + return made + } + + private make(record: { readonly t: string; readonly [field: string]: unknown }, id: number): object { + switch (record.t) { + case "Array": + return [] + case "Object": + return record.n === 1 ? Object.create(null) : {} + case "Map": + return record.a === undefined ? new Map() : this.anchor(text(record.a, "an anchor"), Map) + case "Set": + return new Set() + case "@": { + const name = text(record.n, "a built-in name") + const named = this.env.named(name) + if (named === undefined) return invalid(`this runtime has no built-in or host global named ${name}.`) + const spec = this.classSpec(record.c) + if (named.constructor !== spec.ctor) return invalid(`${name} is not a ${spec.name} in this runtime.`) + return named + } + case "LostNative": + return Object.create(Native.prototype) + case "Interruption": + return this.env.interruption() + case "Error": { + const name = text(record.c, "an error class") + const ctor = errorClasses.get(name) ?? invalid(`unknown error class ${name}.`) + const message = text(record.m, "an error message") + if (ctor === ToolError) return toolError(message) + const made = Object.create(ctor.prototype) as Error + Object.defineProperty(made, "message", { value: message, writable: true, configurable: true, enumerable: false }) + return made + } + case "URL": + return new URL(text(record.h, "a URL")) + case "URLSearchParams": { + if (record.o === undefined) return new URLSearchParams(text(record.s, "search params")) + const owner = this.value(record.o) + return owner instanceof URL ? owner.searchParams : invalid(`record ${id} names no URL.`) + } + case "Headers": { + const entries = list(record.e, "headers").map((entry) => { + const pair = list(entry, "a header") + return [text(pair[0], "a header name"), text(pair[1], "a header value")] as [string, string] + }) + return new Headers(entries) + } + case "ArrayBuffer": + return fromBase64(text(record.d, "bytes")).buffer + case "Uint8Array": { + const buffer = this.value(record.b) + if (!(buffer instanceof ArrayBuffer)) return invalid(`record ${id} names no buffer.`) + const offset = count(record.o, "a byte offset") + const length = count(record.l, "a byte length") + if (offset + length > buffer.byteLength) return invalid(`record ${id} reaches past its buffer.`) + return new Uint8Array(buffer, offset, length) + } + case "TextDecoder": + return new TextDecoder("utf-8", { fatal: record.f === true, ignoreBOM: record.i === true }) + } + const spec = this.classSpec(record.t) + if (spec.name === "Native") return invalid("a native is saved only by name.") + if (spec.anchor !== undefined) return this.anchor(spec.anchor, spec.ctor) + return Object.create(spec.ctor.prototype) + } + + private anchor(name: string, ctor: Function): object { + const anchor = this.env.anchor(name) + if (anchor === undefined || anchor.constructor !== ctor) return invalid(`unknown anchor ${name}.`) + return anchor + } + + private classSpec(name: unknown): ClassSpec { + return byName.get(text(name, "a class")) ?? invalid(`unknown record kind ${String(name)}.`) + } + + fill(id: number): void { + if (this.filled[id]) return + this.filled[id] = true + const record = this.at(id) + const target = this.shell(id) as { [field: string]: unknown } + switch (record.t) { + case "Array": { + const array = target as unknown as Array + if (record.v === undefined) { + const length = count(record.l, "an array length") + if (length > 4_294_967_295) invalid("an array is too long.") + array.length = length + const entries = list(record.s, "a sparse array") + for (let at = 0; at < entries.length; at += 2) { + const index = count(entries[at], "an array index") + if (index >= length) invalid("an array index is past its length.") + array[index] = this.value(entries[at + 1]) + } + return + } + const items = list(record.v, "an array") + items.forEach((item, at) => { + if (Array.isArray(item) && item[0] === "h") return + array[at] = this.value(item) + }) + array.length = items.length + return + } + case "Object": { + const entries = list(record.e, "an object") + for (let at = 0; at < entries.length; at += 2) { + const key = text(entries[at], "a key") + Object.defineProperty(target, key, { + value: this.value(entries[at + 1]), + writable: true, + enumerable: true, + configurable: true, + }) + } + return + } + case "Map": { + const map = target as unknown as Map + if (record.a !== undefined) map.clear() + const entries = list(record.e, "a map") + for (let at = 0; at < entries.length; at += 2) map.set(this.value(entries[at]), this.value(entries[at + 1])) + return + } + case "Set": { + const set = target as unknown as Set + for (const item of list(record.e, "a set")) set.add(this.value(item)) + return + } + case "Error": { + const entries = list(record.e, "an error") + for (let at = 0; at < entries.length; at += 2) { + const key = text(entries[at], "a key") + if (forbidden.has(key)) invalid(`an error field is named ${key}.`) + Object.defineProperty(target, key, { + value: this.value(entries[at + 1]), + writable: true, + enumerable: true, + configurable: true, + }) + } + return + } + case "@": + return this.fillClass(target, record, this.classSpec(record.c), true) + case "LostNative": { + this.fillClass(target, record, byName.get("Fn")!, false, ["length"]) + const native = target as unknown as { tag: string; call: unknown; construct: unknown; callback: boolean } + const slot = (target as unknown as Obj).props.get("name") + const name = slot !== undefined && "value" in slot && typeof slot.value === "string" ? slot.value : "" + native.tag = "Function" + native.call = (_: unknown, __: unknown, site: AstNode | undefined) => { + throw lostError(`The function ${name || "(anonymous)"}`, site) + } + native.construct = undefined + native.callback = true + return + } + case "Interruption": + case "URL": + case "URLSearchParams": + case "Headers": + case "ArrayBuffer": + case "Uint8Array": + case "TextDecoder": + return + } + const spec = this.classSpec(record.t) + this.fillClass(target, record, spec, false) + } + + private fillClass( + target: { [field: string]: unknown }, + record: { readonly [field: string]: unknown }, + spec: ClassSpec, + named: boolean, + only?: ReadonlyArray, + ): void { + const fields = only ?? spec.fields + const values = list(record.f, `the fields of a ${spec.name}`) + if (values.length !== fields.length) invalid(`a ${spec.name} has ${values.length} fields, not ${fields.length}.`) + if (spec.obj || named) this.fillObj(target as unknown as Obj, record) + if (spec.constants !== undefined) Object.assign(target, spec.constants) + fields.forEach((field, at) => { + const value = values[at] + if (Array.isArray(value) && value[0] === "-") { + delete target[field] + return + } + target[field] = this.value(value) + }) + const reset = spec.reset + if (reset !== undefined) this.resets.push(() => reset(target as never)) + } + + finish(): void { + for (const reset of this.resets) reset() + } + + // An object's prototype, extensibility, and properties. A named object's accessors stay the ones it was made with. + private fillObj(target: Obj, record: { readonly [field: string]: unknown }): void { + const proto = record.p === null ? null : this.value(record.p) + if (proto !== null && !(proto instanceof Obj)) invalid("a prototype is not an object.") + if (typeof record.x !== "boolean") invalid("an object's extensibility is not a boolean.") + const entries = list(record.o, "an object's properties") + const props = new Map() + for (let at = 0; at < entries.length; at += 3) { + const raw = entries[at] + const key = typeof raw === "string" ? raw : this.value(raw) + if (typeof key !== "string" && typeof key !== "symbol") invalid("a property key is not a string or symbol.") + const flags = count(entries[at + 2], "property flags") + const enumerable = (flags & 2) !== 0 + const configurable = (flags & 4) !== 0 + if ((flags & 8) !== 0) { + const original = target.props?.get(key as string | symbol) + if (original === undefined || "value" in original) invalid(`the accessor ${String(key)} has no original.`) + const accessor = original as Extract + props.set(key as string | symbol, { get: accessor.get, set: accessor.set, enumerable, configurable }) + continue + } + props.set(key as string | symbol, { + value: this.value(entries[at + 1]) as Value, + writable: (flags & 1) !== 0, + enumerable, + configurable, + }) + } + const writable = target as unknown as { props: Map; proto: Obj | null; extensible: boolean } + writable.props = props + writable.extensible = record.x as boolean + writable.proto = proto as Obj | null + } + + value(value: unknown): unknown { + switch (typeof value) { + case "string": + case "boolean": + return value + case "number": + return Number.isFinite(value) ? value : invalid("a number is not finite.") + } + if (value === null) return null + if (!Array.isArray(value)) return invalid("a value is neither JSON data nor a tag.") + switch (value[0]) { + case "u": + return undefined + case "n": + switch (value[1]) { + case "NaN": + return Number.NaN + case "Infinity": + return Number.POSITIVE_INFINITY + case "-Infinity": + return Number.NEGATIVE_INFINITY + case "-0": + return -0 + } + return invalid(`unknown number ${String(value[1])}.`) + case "s": + return symbols.get(text(value[1], "a symbol")) ?? invalid(`unknown symbol ${String(value[1])}.`) + case "k": + return kinds.get(text(value[1], "a kind")) ?? invalid(`unknown frame kind ${String(value[1])}.`) + case "c": + return consumers.get(text(value[1], "a consumer")) ?? invalid(`unknown consumer ${String(value[1])}.`) + case "i": { + const name = text(value[1], "a built-in name") + return this.env.named(name) ?? invalid(`this runtime has no built-in or host global named ${name}.`) + } + case "a": + return ( + this.env.node(text(value[1], "a source"), count(value[2], "a node index")) ?? + invalid(`no node ${String(value[2])} in source ${String(value[1])}.`) + ) + case "A": + return ( + this.env.astArray(text(value[1], "a source"), count(value[2], "a node index"), text(value[3], "a key")) ?? + invalid(`no list ${String(value[3])} on node ${String(value[2])}.`) + ) + case "r": { + const id = count(value[1], "a record id") + if (id >= this.records.length) invalid(`record ${id} does not exist.`) + return this.shell(id) + } + } + return invalid(`unknown tag ${String(value[0])}.`) + } +} + +const base64 = (bytes: Uint8Array): string => { + let binary = "" + for (let at = 0; at < bytes.length; at += 0x8000) binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000)) + return btoa(binary) +} + +const fromBase64 = (encoded: string): Uint8Array => { + const binary = atob(encoded) + const bytes = new Uint8Array(binary.length) + for (let at = 0; at < binary.length; at++) bytes[at] = binary.charCodeAt(at) + return bytes +} diff --git a/packages/codemode/src/snapshot/snapshot.ts b/packages/codemode/src/snapshot/snapshot.ts new file mode 100644 index 00000000000..97eefe106a4 --- /dev/null +++ b/packages/codemode/src/snapshot/snapshot.ts @@ -0,0 +1,344 @@ +import packageJson from "../../package.json" with { type: "json" } +import type { Interpreter } from "../interpreter/interpreter.js" +import type { AstNode } from "../interpreter/model.js" +import { Arr, Native, Obj, type Slot, type Value } from "../interpreter/objects.js" +import type { Interruption } from "../interpreter/signals.js" +import { nodeId, type Source } from "../interpreter/source.js" +import { ToolReference, type ToolCall } from "../tool-runtime.js" +import { codecShape, decode, type Encoded, encode, type Record, SnapshotError } from "./codec.js" + +export { SnapshotError } + +/** The snapshot format this build writes and reads. */ +export const FORMAT = 1 + +/** + * A suspended run's whole state as JSON: a header that says which build and sources it belongs to and what budget it + * has used, and the graph of records (see codec.ts) rooted at the machine, the interpreter, and the root task, then + * every built-in or host global the run changed. + */ +export type Snapshot = { + readonly format: typeof FORMAT + readonly header: Header + readonly roots: ReadonlyArray + readonly records: ReadonlyArray +} + +export type Header = { + /** The build that wrote it: the package version, and a hash of the frame kinds, consumers, codecs, and built-ins. */ + readonly build: string + /** A hash of the host's globals (extensions, a test harness), which the resuming runtime must have too. */ + readonly hosts: string + readonly runId: string + /** The program texts, re-parsed on restore and checked against their hashes. */ + readonly sources: ReadonlyArray<{ readonly id: string; readonly code: string; readonly hash: string }> + readonly limits: { + readonly timeoutMs: number | null + readonly maxToolCalls: number | null + readonly maxOutputBytes: number | null + } + /** What the run has used so far, across every resume: active milliseconds, and tool calls admitted. */ + readonly budget: { readonly activeMs: number; readonly toolCalls: number } + readonly toolCalls: ReadonlyArray +} + +/** A runtime with the intrinsics and nothing else, which the build id is taken from. */ +export type Bare = Interpreter + +let build: string | undefined + +/** This build's id; a snapshot resumes only on the build that wrote it. */ +export const buildId = (bare: Bare): string => + (build ??= `${packageJson.version}+${hash(`${FORMAT}\n${codecShape()}\n${bare.intrinsics.all().join("\n")}`)}`) + +const hostsId = (ctx: Interpreter): string => + hash( + ctx.intrinsics + .all() + .filter((name) => name.startsWith("@")) + .join("\n"), + ) + +/** Saves a run's state. `pristine` is a fresh runtime with the same host globals, to tell which built-ins changed. */ +export const capture = ( + ctx: Interpreter, + options: { + readonly bare: Bare + readonly pristine: Interpreter + readonly runId: string + readonly limits: Header["limits"] + readonly activeMs: number + readonly strict: boolean + }, +): { readonly snapshot: Snapshot; readonly lost: ReadonlyArray } => { + const machine = ctx.machine + machine.compact() + const lost: Array = [] + const current = ctx.intrinsics + const pristine = options.pristine.intrinsics + const sources = [...ctx.sources.values()] + const anchors = new Map([ + [machine, "machine"], + [machine.root, "task"], + [ctx, "ctx"], + [ctx.globalScope, "globals"], + ]) + // A change to a built-in is saved even where no saved value refers to it (`Boolean.prototype.toString = ...`). + const unchanged = new Map() + const isUnchanged = (value: Obj, name: string) => { + let same = unchanged.get(value) + if (same === undefined) { + const original = pristine.valueOf(name) + same = original !== undefined && sameObject(value, original, current, pristine) + unchanged.set(value, same) + } + return same + } + const names = current.all() + const changed = current.values.filter((value, at) => !isUnchanged(value, names[at]!)) + const encoded = encode([machine, ctx, machine.root, ...changed], { + nameOf: (value) => current.nameOf(value), + unchanged: isUnchanged, + anchorOf: (value) => anchors.get(value), + nodeId: (node) => { + const id = nodeId(node) + return id !== undefined && ctx.sources.has(id.source) ? [id.source, id.index] : undefined + }, + astArray: (array) => { + for (const source of sources) { + const owner = astArrays(source).get(array) + if (owner !== undefined) return [source.id, owner[0], owner[1]] + } + return undefined + }, + lost, + strict: options.strict, + }) + const snapshot: Snapshot = { + format: FORMAT, + header: { + build: buildId(options.bare), + hosts: hostsId(ctx), + runId: options.runId, + sources: sources.map((source) => ({ id: source.id, code: source.code, hash: hash(source.code) })), + limits: options.limits, + budget: { activeMs: options.activeMs, toolCalls: ctx.tools.calls.length }, + toolCalls: ctx.tools.calls.map((call) => ({ name: call.name })), + }, + roots: encoded.roots, + records: encoded.records, + } + return { snapshot, lost } +} + +/** + * Restores a saved state into `fresh`, a new runtime made with the same host globals and no bindings, after checking + * that the snapshot is well formed and belongs to this build, these host globals, and its own sources. + */ +export const restore = ( + saved: unknown, + fresh: Interpreter, + options: { + readonly bare: Bare + readonly parse: (code: string) => Source + readonly interruption: () => Interruption + }, +): Snapshot => { + const snapshot = validate(saved) + const header = snapshot.header + const expected = buildId(options.bare) + if (header.build !== expected) { + throw new SnapshotError( + `This state was saved by another Code Mode build (${header.build}); this runtime is ${expected}, so it can't resume it.`, + ) + } + if (header.hosts !== hostsId(fresh)) { + throw new SnapshotError( + "This state was saved by a runtime with other host globals (extensions); resume it with the same ones.", + ) + } + for (const source of header.sources) { + if (hash(source.code) !== source.hash) throw new SnapshotError(`Source ${source.id} does not match its hash.`) + const parsed = options.parse(source.code) + if (parsed.id !== source.id) throw new SnapshotError(`Source ${source.id} is not a program source.`) + fresh.sources.set(source.id, parsed) + } + const anchors = new Map([ + ["machine", fresh.machine], + ["task", fresh.machine.root], + ["ctx", fresh], + ["globals", fresh.globalScope], + ]) + decode(snapshot, { + named: (name) => fresh.intrinsics.valueOf(name), + anchor: (name) => anchors.get(name), + node: (source, index) => fresh.sources.get(source)?.nodes[index], + astArray: (source, index, key) => { + const node = fresh.sources.get(source)?.nodes[index] as { readonly [key: string]: unknown } | undefined + const owned = node?.[key] + return key !== "loc" && Array.isArray(owned) ? owned : undefined + }, + interruption: options.interruption, + }) + fresh.tools.calls.push(...header.toolCalls.map((call) => ({ name: call.name }))) + return snapshot +} + +/** A snapshot as bytes: UTF-8 JSON. */ +export const toBytes = (snapshot: Snapshot): Uint8Array => new TextEncoder().encode(JSON.stringify(snapshot)) + +/** Reads bytes `toBytes` wrote; `restore` checks what they hold. */ +export const fromBytes = (bytes: Uint8Array): unknown => { + try { + return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) + } catch (error) { + throw new SnapshotError(`Invalid snapshot: the bytes are not UTF-8 JSON (${String(error)}).`) + } +} + +/** A snapshot's size in bytes. */ +export const byteLength = (snapshot: Snapshot): number => toBytes(snapshot).byteLength + +// --- Validation --- + +const fail = (message: string): never => { + throw new SnapshotError(`Invalid snapshot: ${message}`) +} + +const object = (value: unknown, what: string): { readonly [key: string]: unknown } => + typeof value === "object" && value !== null && !Array.isArray(value) + ? (value as { readonly [key: string]: unknown }) + : fail(`${what} is not an object.`) + +const array = (value: unknown, what: string): ReadonlyArray => + Array.isArray(value) ? value : fail(`${what} is not a list.`) + +const string = (value: unknown, what: string): string => (typeof value === "string" ? value : fail(`${what} is not text.`)) + +const number = (value: unknown, what: string): number => + typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fail(`${what} is not a number.`) + +const limit = (value: unknown, what: string): number | null => (value === null ? null : number(value, what)) + +// The header is checked in full; records are checked as they are decoded. +const validate = (saved: unknown): Snapshot => { + const root = object(saved, "the snapshot") + if (root.format !== FORMAT) fail(`format ${String(root.format)} is not ${FORMAT}.`) + const header = object(root.header, "the header") + const limits = object(header.limits, "the limits") + const budget = object(header.budget, "the budget") + const checked: Header = { + build: string(header.build, "the build"), + hosts: string(header.hosts, "the host globals"), + runId: string(header.runId, "the run id"), + sources: array(header.sources, "the sources").map((item) => { + const source = object(item, "a source") + return { + id: string(source.id, "a source id"), + code: string(source.code, "a source"), + hash: string(source.hash, "a source hash"), + } + }), + limits: { + timeoutMs: limit(limits.timeoutMs, "timeoutMs"), + maxToolCalls: limit(limits.maxToolCalls, "maxToolCalls"), + maxOutputBytes: limit(limits.maxOutputBytes, "maxOutputBytes"), + }, + budget: { activeMs: number(budget.activeMs, "the active time"), toolCalls: number(budget.toolCalls, "tool calls") }, + toolCalls: array(header.toolCalls, "the tool calls").map((item) => ({ + name: string(object(item, "a tool call").name, "a tool name"), + })), + } + const roots = array(root.roots, "the roots") + if (roots.length < 3) fail("there are fewer than three roots.") + return { + format: FORMAT, + header: checked, + roots: roots as ReadonlyArray, + records: array(root.records, "the records") as ReadonlyArray, + } +} + +// --- Helpers --- + +const arrays = new WeakMap, readonly [number, string]>>() + +// The lists AST nodes own (a function's parameters, a block's body), by node and key, so state that holds one keeps +// pointing into the tree, where caches are keyed by them. +const astArrays = (source: Source): Map, readonly [number, string]> => { + const known = arrays.get(source) + if (known !== undefined) return known + const owned = new Map, readonly [number, string]>() + source.nodes.forEach((node: AstNode, index) => { + for (const [key, child] of Object.entries(node)) if (key !== "loc" && Array.isArray(child)) owned.set(child, [index, key]) + }) + arrays.set(source, owned) + return owned +} + +type Names = Interpreter["intrinsics"] + +// Whether a named object is as the runtime made it: same class, prototype, extensibility, and properties, with object +// values that are the same-named built-ins. Objects of other classes (an extension's Map, say) always count as changed. +const sameObject = (value: Obj, original: Obj, names: Names, pristine: Names): boolean => { + const ctor = value.constructor + if (ctor !== original.constructor || (ctor !== Obj && ctor !== Arr && ctor !== Native)) return false + if (value.extensible !== original.extensible) return false + if (!sameValue(value.proto, original.proto, names, pristine)) return false + if (value.props.size !== original.props.size) return false + const left = value.props.entries() + const right = original.props.entries() + for (let a = left.next(), b = right.next(); !a.done && !b.done; a = left.next(), b = right.next()) { + if (a.value[0] !== b.value[0] || !sameSlot(a.value[1], b.value[1], names, pristine)) return false + } + if (value instanceof Arr && original instanceof Arr) { + const elements = value.elements + if ( + elements.writable !== original.elements.writable || + elements.enumerable !== original.elements.enumerable || + elements.configurable !== original.elements.configurable || + value.items.length !== original.items.length + ) { + return false + } + for (let at = 0; at < value.items.length; at++) { + if (at in value.items !== at in original.items) return false + if (!sameValue(value.items[at], original.items[at], names, pristine)) return false + } + } + return true +} + +const sameSlot = (slot: Slot, original: Slot, names: Names, pristine: Names): boolean => { + if (slot.enumerable !== original.enumerable || slot.configurable !== original.configurable) return false + if (!("value" in slot)) return !("value" in original) + return "value" in original && slot.writable === original.writable && sameValue(slot.value, original.value, names, pristine) +} + +const sameValue = (value: Value | null, original: Value | null, names: Names, pristine: Names): boolean => { + if (value instanceof Obj) { + if (!(original instanceof Obj)) return false + const name = names.nameOf(value) + return name !== undefined && name === pristine.nameOf(original) + } + if (value instanceof ToolReference) { + return ( + original instanceof ToolReference && + value.path.length === original.path.length && + value.path.every((segment, at) => segment === original.path[at]) + ) + } + return Object.is(value, original) +} + +// FNV-1a over UTF-16 code units, twice with different offsets: a fingerprint, not a security check. +const hash = (text: string): string => { + let a = 0x811c9dc5 + let b = 0x01000193 ^ 0x9e3779b9 + for (let at = 0; at < text.length; at++) { + const code = text.charCodeAt(at) + a = Math.imul(a ^ code, 0x01000193) + b = Math.imul(b ^ code, 0x01000193) ^ (b >>> 13) + } + return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0") +} diff --git a/packages/codemode/src/stdlib/array.ts b/packages/codemode/src/stdlib/array.ts index 18ac944f649..7f72799a8c4 100644 --- a/packages/codemode/src/stdlib/array.ts +++ b/packages/codemode/src/stdlib/array.ts @@ -524,7 +524,7 @@ const elements = (target: Arr | Bytes): ArrayLike => (target instanceof A // Whether a callback method visits holes: only the find methods do, as undefined. const visitsHoles = (op: CallbackOp) => op.startsWith("find") const backwards = (op: CallbackOp) => op === "findLast" || op === "findLastIndex" || op === "reduceRight" -const NEXT: unique symbol = Symbol("next") +export const NEXT: unique symbol = Symbol("next") // Slots: what the method does, the receiver, the callback, its `this`, the fixed length, the next index, what it has // built so far (the values, or the accumulator), and the element the callback is looking at. diff --git a/packages/codemode/src/tool-runtime.ts b/packages/codemode/src/tool-runtime.ts index 8660d4fd630..ced33035338 100644 --- a/packages/codemode/src/tool-runtime.ts +++ b/packages/codemode/src/tool-runtime.ts @@ -12,7 +12,7 @@ import { outputTypeScript, } from "./tool-schema.js" import { isNamespace, type Namespace } from "./namespace.js" -import { isTool, type Tool } from "./tool.js" +import { type Handle, isTool, type Tool } from "./tool.js" import type { Tools } from "./tools.js" export const compareText = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0) @@ -381,6 +381,20 @@ export type ToolRuntime = { ) => Effect.Effect readonly search: (args: Array) => Effect.Effect readonly keys: (path: ReadonlyArray) => ReadonlyArray + /** The tool at `path`, if there is one, so a caller can see whether it is durable or safe to retry. */ + readonly tool: (path: ReadonlyArray) => Tool | undefined + /** Admits a call to a durable tool, as `execute` does, and starts its work under `key`: its handle. */ + readonly start: (path: ReadonlyArray, args: Array, key: string) => Effect.Effect + /** Waits for a durable tool's work: its output, as `execute` gives it. Interrupting it detaches. */ + readonly attach: ( + path: ReadonlyArray, + args: Array, + handle: Handle, + ) => Effect.Effect + /** The handle of a durable tool's work started under `key`, if it was. */ + readonly lookup: (path: ReadonlyArray, key: string) => Effect.Effect + /** Stops a durable tool's work. */ + readonly cancel: (path: ReadonlyArray, handle: Handle) => Effect.Effect } /** Per-execution call state over tools prepared once for the runtime. */ @@ -388,8 +402,8 @@ export const make = ( prepared: Prepared, maxToolCalls: number | undefined, hooks: Hooks = {}, + calls: Array = [], ): ToolRuntime => { - const calls: Array = [] const root = prepared.root const recordCall = (call: ToolCall): void => { @@ -399,12 +413,12 @@ export const make = ( calls.push(call) } - const executeTool = (name: string, tool: Tool, args: Array) => + const decode = (name: string, tool: Tool, args: Array) => Effect.gen(function* () { const normalized = args.length === 0 ? [{}] : args if (normalized.length !== 1) throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`) - const input = yield* Effect.try({ + return yield* Effect.try({ try: () => decodeToolInput(tool, normalized[0]), catch: (cause) => new ToolRuntimeError( @@ -413,36 +427,54 @@ export const make = ( name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."], ), }) + }) + + // A tool's own failure becomes a ToolError; interruption passes through. + const failure = (effect: Effect.Effect) => + effect.pipe( + Effect.catchCause((cause) => { + if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt + return Effect.fail( + toolError( + Cause.prettyErrors(cause) + .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name)) + .join("\n"), + ), + ) + }), + ) + + // The same round trip a tool result would take through text: exact JSON.stringify semantics. + const output = (name: string, tool: Tool, raw: unknown) => + Effect.try({ + try: (): Json | undefined => { + const text = JSON.stringify(decodeToolOutput(tool, raw)) + return text === undefined ? undefined : JSON.parse(text) + }, + catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`), + }) + + const executeTool = (name: string, tool: Tool, args: Array) => + Effect.gen(function* () { + const input = yield* decode(name, tool, args) yield* Effect.sync(() => recordCall({ name })) return yield* hooked( { name, input }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () { - const raw = yield* Effect.suspend(() => tool.execute(input)).pipe( - Effect.catchCause((cause) => { - if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt - return Effect.fail( - toolError( - Cause.prettyErrors(cause) - .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name)) - .join("\n"), - ), - ) - }), - ) - // The same round trip a tool result would take through text: exact JSON.stringify semantics. - return yield* Effect.try({ - try: (): Json | undefined => { - const text = JSON.stringify(decodeToolOutput(tool, raw)) - return text === undefined ? undefined : JSON.parse(text) - }, - catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`), - }) + const raw = yield* failure(Effect.suspend(() => tool.execute(input))) + return yield* output(name, tool, raw) }), ) }) + const durableTool = (path: ReadonlyArray) => { + const tool = lookup(root, canonicalSegments(path))?.tool + if (tool?.durable === undefined) throw new TypeError(`Tool '${canonicalSegments(path).join(".")}' is not durable.`) + return { name: canonicalSegments(path).join("."), tool, durable: tool.durable } + } + return { calls, hooks, @@ -456,6 +488,38 @@ export const make = ( return executeTool("search", makeSearchTool(prepared.searchIndex), args) return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args) }), + tool: (path) => lookup(root, canonicalSegments(path))?.tool, + start: (path, args, key) => + Effect.suspend(() => { + const found = durableTool(path) + return Effect.gen(function* () { + const input = yield* decode(found.name, found.tool, args) + yield* Effect.sync(() => recordCall({ name: found.name })) + const before = hooks["tool.before"] + if (before !== undefined) yield* before({ name: found.name, input }) + return yield* failure(Effect.suspend(() => found.durable.start(input, { key }))) + }) + }), + attach: (path, args, handle) => + Effect.suspend(() => { + const found = durableTool(path) + const after = hooks["tool.after"] + const run = Effect.gen(function* () { + const raw = yield* failure(Effect.suspend(() => found.durable.attach(handle))) + return yield* output(found.name, found.tool, raw) + }) + if (after === undefined) return run + // Detaching is not an outcome: `after` sees how the work ended, once it has. + return Effect.flatMap(decode(found.name, found.tool, args), (input) => + Effect.onExit(run, (exit) => { + if (Exit.isSuccess(exit)) return after({ name: found.name, input }, { status: "success", value: exit.value }) + if (Cause.hasInterruptsOnly(exit.cause)) return Effect.void + return after({ name: found.name, input }, { status: "failure", error: Cause.squash(exit.cause) }) + }), + ) + }), + lookup: (path, key) => Effect.suspend(() => failure(durableTool(path).durable.lookup(key))), + cancel: (path, handle) => Effect.suspend(() => failure(durableTool(path).durable.cancel(handle))), } } diff --git a/packages/codemode/src/tool.ts b/packages/codemode/src/tool.ts index e39138fd595..64b3c109377 100644 --- a/packages/codemode/src/tool.ts +++ b/packages/codemode/src/tool.ts @@ -41,6 +41,27 @@ export type JsonSchema = { /** Either a validating Effect Schema or a render-only JSON Schema document. */ export type SchemaType = Schema.Decoder | JsonSchema +/** A JSON handle a durable tool gives for work that outlives the fiber waiting on it. */ +export type Handle = Schema.Json + +/** + * How a durable tool runs work that can outlive a suspended run: `start` launches it under the idempotency `key` and + * returns a handle quickly; `attach` waits for its result (interrupting it detaches, never cancels); `lookup` finds the + * handle of work started under `key` when the run was saved before `start` returned; `cancel` stops the work. + */ +export type Durable = { + readonly start: (input: Input, context: { readonly key: string }) => Effect.Effect + readonly attach: (handle: Handle) => Effect.Effect + readonly lookup: (key: string) => Effect.Effect + readonly cancel: (handle: Handle) => Effect.Effect +} + +/** + * Whether a call that was running when its run was suspended may run again on resume: `safe` re-runs it; `unsafe` + * (the default) rejects the program's promise instead, since the call may have partially run. + */ +export type Retry = "safe" | "unsafe" + /** Executable tool exposed through CodeMode's `tools` object. */ export type Tool = { readonly _tag: "CodeModeTool" @@ -48,19 +69,27 @@ export type Tool = { readonly input: SchemaType readonly output: SchemaType | undefined readonly execute: (input: unknown) => Effect.Effect + readonly durable?: Durable | undefined + readonly retry?: Retry | undefined } type InputType = S extends Schema.Decoder ? S["Type"] : unknown type ResultType = S extends undefined ? void : S extends Schema.Decoder ? S["Encoded"] : unknown -/** Options for declaring one CodeMode tool. */ +/** Options for declaring one CodeMode tool: `execute`, `durable`, or both (`execute` then runs outside a run). */ export type Options = { readonly description: string readonly input: I readonly output?: O - readonly execute: (input: InputType) => Effect.Effect, unknown, R> -} + readonly retry?: Retry +} & ( + | { + readonly execute: (input: InputType) => Effect.Effect, unknown, R> + readonly durable?: Durable, ResultType, R> + } + | { readonly execute?: undefined; readonly durable: Durable, ResultType, R> } +) export const isTool = (value: Tool | Namespace | Tools | undefined): value is Tool => value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool" @@ -70,14 +99,23 @@ export const isTool = (value: Tool | Namespace | Tools | und * * Effect Schemas validate values; JSON Schemas only shape the model-visible signature. * Without `output`, results are exposed as `void`. Hosts remain responsible for authorization - * and durable side effects. + * and durable side effects; a `durable` tool keeps its work running across a suspended run (see `Durable`). */ export const make = ( options: Options, -): Tool => ({ - _tag: "CodeModeTool", - description: options.description, - input: options.input, - output: options.output, - execute: (input) => options.execute(input as InputType), -}) +): Tool => { + const durable = options.durable as Durable | undefined + const execute = options.execute as ((input: unknown) => Effect.Effect) | undefined + if (execute === undefined && durable === undefined) throw new TypeError("A tool needs `execute` or `durable`.") + return { + _tag: "CodeModeTool", + description: options.description, + input: options.input, + output: options.output, + execute: + execute ?? + ((input) => Effect.flatMap(durable!.start(input, { key: crypto.randomUUID() }), (handle) => durable!.attach(handle))), + ...(durable === undefined ? {} : { durable }), + ...(options.retry === undefined ? {} : { retry: options.retry }), + } +} diff --git a/packages/codemode/test/machine.test.ts b/packages/codemode/test/machine.test.ts index c6d6973d159..0e59e716fb9 100644 --- a/packages/codemode/test/machine.test.ts +++ b/packages/codemode/test/machine.test.ts @@ -216,7 +216,7 @@ describe("machine", () => { [1, 2, 3].map((value) => ({ request: { kind: "tool", path: ["echo"], args: [{ value }] }, blocking: false, - status: "inFlight", + status: "queued", })), ) // Nothing else can run until host work completes. @@ -349,6 +349,7 @@ describe("machine", () => { describe("built-ins as data", () => { test("every frame on every stack is data at every step", async () => { const seenKinds = new Set() + const previous = stats.inspect stats.inspect = (stack) => { const seen = new Set() for (const frame of stack) { @@ -402,7 +403,7 @@ describe("built-ins as data", () => { `) expect(result).toMatchObject({ all: [2, 4, 3], raced: "first", any: 8, tried: 12, thenned: 3, tool: 20 }) } finally { - stats.inspect = undefined + stats.inspect = previous } for (const name of [ "Array callback",