feat(codemode): save and restore a run's state as a snapshot, with a round-trip test mode

This commit is contained in:
James Long
2026-11-04 22:40:52 +00:00
Unverified
parent fce860cf9c
commit 5ad0d06ab2
19 changed files with 2006 additions and 137 deletions
+2 -1
View File
@@ -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",
+72 -7
View File
@@ -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<Provided extends Record<string, unknown> = {}, Extensions ex
hooks?: ToolRuntime.Hooks<Environment<Provided, Extensions>>
/** 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<Json>
/** The idempotency key, `<run id>:<id>`; 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<Pending>
}
/** Reusable confined runtime over explicit tools. */
export type Runtime<R = never> = {
readonly catalog: ReadonlyArray<ToolDescription>
readonly execute: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Effect.Effect<Result, never, R>
/**
* 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<Record<string, DataValue>>,
options?: { readonly runId?: string },
) => Run<R>
/**
* 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<Record<string, Outcome>>) => Run<R>
}
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<Environment<Provided, Extensions>> = {
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<Record<string, DataValue>> | undefined) =>
bindings === undefined
? undefined
: (ctx: Parameters<typeof fromJson>[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),
}
}
+1 -1
View File
@@ -129,7 +129,7 @@ function walkStep(task: MachineTask, frame: Frame, input: unknown): Out<Value> {
}
}
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(
+173 -35
View File
@@ -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<R> {
private readonly fibers = new Map<number, Fiber.Fiber<unknown, unknown>>()
// Calls whose fibers were interrupted to suspend or end the run: their outcomes are not reported.
private readonly detached = new Set<number>()
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<unknown> | undefined
/** Called at every slice and host stop, before queued calls start: the round-trip test mode swaps the machine. */
checkpoint: Effect.Effect<void, unknown, R> | undefined
constructor(
private readonly machine: Machine,
private readonly tools: ToolRuntime<R>,
public machine: Machine,
public tools: ToolRuntime<R>,
/** The services host work runs with: the caller's, so tools see its context, tracing, and clock. */
private readonly services: Context.Context<R>,
) {}
/**
* 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<Completion, unknown, R> {
run(): Effect.Effect<Completion | typeof SUSPENDED, unknown, R> {
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<R> {
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<R> {
})
}
/** 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<void> {
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<void> {
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<unknown, unknown, R> {
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<unknown, unknown, R>
/**
* 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<Record<string, Outcome>>): 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<unknown, unknown, R>)
}
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<unknown, unknown, R>, 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<R> {
private get settled(): Effect.Effect<void> {
return Effect.callback<void>((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<R> {
})
}
}
/** 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.`,
)
+304 -35
View File
@@ -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<R> = {
readonly prepared: ToolRuntime.Prepared<R>
readonly limits: ResolvedExecutionLimits
readonly hooks: ToolRuntime.Hooks<R>
/** The host's globals, made again for a restored run; see `Interpreter`. */
readonly globals?: ((ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>) | 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<R> = {
/** Runs the program: its result, or its saved state once suspended. Run it once. */
readonly result: Effect.Effect<Result | Suspended, never, R>
/**
* 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<Result | Suspended>
}
const DEFAULT_GRACE_MS = 50
export const executeProgram = <R>(
code: string,
@@ -17,56 +53,213 @@ export const executeProgram = <R>(
limits: ResolvedExecutionLimits,
hooks: ToolRuntime.Hooks<R>,
globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
): Effect.Effect<Result, never, R> => {
bindings?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
): Effect.Effect<Result, never, R> =>
executeSetup({ prepared, limits, hooks, globals }, code, bindings)
/** Runs one program to its end; nothing can suspend it. */
export const executeSetup = <R>(
setup: Setup<R>,
code: string,
bindings?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
): Effect.Effect<Result, never, R> =>
// Allocate execution state inside suspension so reused Effects never share it.
Effect.suspend(() => startProgram(setup, code, bindings).result as Effect.Effect<Result, never, R>)
/** Starts a program: a handle whose `result` runs it, and whose `suspend` saves its state. */
export const startProgram = <R>(
setup: Setup<R>,
code: string,
bindings?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
runId: string = crypto.randomUUID(),
): Run<R> => {
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 = <R>(
setup: Setup<R>,
saved: Snapshot | Uint8Array | unknown,
outcomes: Readonly<Record<string, Outcome>> = {},
): Run<R> => {
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<never> => ({ 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<string, Source>()
const restoreInto = <R>(setup: Setup<R>, saved: unknown, fresh: Interpreter<R>): Snapshot =>
restore(saved, fresh as Interpreter<unknown>, {
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 = <R>(
setup: Setup<R>,
bindings?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
): Interpreter<R> => {
const ctx = new Interpreter<R>({
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<unknown> | undefined
// The intrinsics alone, which the build id is taken from.
const bare = () => (bareRuntime ??= instantiate<unknown>({ prepared: ToolRuntime.prepare({}), limits: noLimits, hooks: {} }))
const noLimits: ResolvedExecutionLimits = { timeoutMs: undefined, maxToolCalls: undefined, maxOutputBytes: undefined }
const pristines = new WeakMap<object, Interpreter<unknown>>()
// A runtime as fresh as a run's, never run, to tell which built-ins and host globals a run changed.
const pristine = <R>(setup: Setup<R>): Interpreter<unknown> => {
if (setup.globals === undefined) return bare()
const known = pristines.get(setup)
if (known !== undefined) return known
const made = instantiate(setup) as Interpreter<unknown>
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<object>()
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<R> {
private ctx: Interpreter<R> | undefined
private driver: Driver<R> | 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<Result | Suspended>()
constructor(
private readonly setup: Setup<R>,
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<R> | Result,
private readonly outcomes?: Readonly<Record<string, Outcome>>,
) {}
get run(): Run<R> {
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<string> = []
const logged = () => (logs.length > 0 ? { logs: [...logs] } : {})
private execute(): Effect.Effect<Result | Suspended, never, R> {
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<R> | undefined
let returned: { value: DataValue; warnings: () => Array<Diagnostic> } | 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<R>()
const ctx = new Interpreter<R>({ 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 = <R>(
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 = <R>(
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 = <R>(
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<unknown>, {
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<Pending> => {
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<unknown>, {
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 = (
@@ -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<unknown>
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
@@ -25,12 +25,13 @@ export class Interpreter<R> {
/** 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<TaggedTemplateExpression, Arr>()
readonly templates = new Map<TaggedTemplateExpression, Arr>()
/** 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<string, Source>()
private readonly globalScope: Map<string, Binding>
/** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
readonly globalScope: Map<string, Binding>
private readonly modules = new Map<string, Value>()
private readonly namespaces = new Map<string, Obj>()
@@ -38,7 +39,10 @@ export class Interpreter<R> {
readonly tools: ToolRuntime<R>
readonly builtins: Builtins
readonly logs?: Array<string>
/** The host's globals (extensions, a test harness): made again, the same way, when a saved run is restored. */
readonly globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>
/** Data bound for this program, part of its saved state; host globals of the same name win. */
readonly bindings?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>
}) {
this.tools = options.tools
this.builtins = options.builtins
@@ -48,8 +52,9 @@ export class Interpreter<R> {
// Program code has no receiver: top-level `this` is undefined, as in a module.
this.globalScope = new Map<string, Binding>([["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)
@@ -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<string> | undefined
private lookup: Map<string, Obj> | undefined
constructor(globals: ReadonlyArray<readonly [string, Value]>, builtins: Builtins) {
constructor(
globals: ReadonlyArray<readonly [string, Value]>,
builtins: Builtins,
hosts: ReadonlyArray<readonly [string, Value]> = [],
) {
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. */
@@ -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)
+2 -1
View File
@@ -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 }
+26 -8
View File
@@ -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<Array<Frame>, Parked>()
/** Names this run's host calls, so each has an idempotency key (`HostCall.key`). */
runId = ""
private readonly queue: Array<Job> = []
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<HostCall> {
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,
+10 -1
View File
@@ -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, `<run id>:<id>`, 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,
+6 -3
View File
@@ -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<Frame>) => void) | undefined } = {
export const stats: {
steps: number
inspect: ((stack: ReadonlyArray<Frame>, 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) {
+887
View File
@@ -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<Json> | { 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<Json>
/** 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<unknown>) => 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<string>
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<unknown> | undefined
/** An `Interruption` (it holds an Effect cause, which this module does not make). */
readonly interruption: () => Interruption
}
// --- Registries ---
const symbols = new Map<string, symbol>([
["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<string>
/** Own fields that are not saved: caches and runtime configuration, set to `reset`'s values. */
readonly skip?: ReadonlyArray<string>
/** 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<ClassSpec> = [
{ 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<unknown>; index: Map<unknown, number> }) => {
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<Function, ClassSpec>(specs.map((spec) => [spec.ctor, spec]))
const byName = new Map<string, ClassSpec>(specs.map((spec) => [spec.name, spec]))
/** Host error classes that can travel as a failure, by name. */
const errorClasses = new Map<string, Function>([
["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<object, string> | undefined
let consumerNames: Map<object, string> | 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<unknown>,
env: EncodeEnv,
): { readonly roots: Array<Encoded>; readonly records: Array<Record> } => {
const encoder = new Encoder(env)
const encoded = roots.map((root) => encoder.value(root))
encoder.drain()
return { roots: encoded, records: encoder.records as Array<Record> }
}
class Encoder {
readonly records: Array<Record | undefined> = []
private readonly ids = new Map<object, number>()
private readonly work: Array<object> = []
// 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<URLSearchParams, URL>()
private readonly params: Array<readonly [number, URLSearchParams]> = []
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<Encoded> = []
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<Encoded> = []
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<Encoded> = []
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<Encoded> = []
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<string>): { [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<Encoded> = []
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<Encoded> = []
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<unknown>; readonly records: ReadonlyArray<unknown> },
env: DecodeEnv,
): Array<unknown> => {
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<unknown> =>
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<object | undefined>
private readonly filled: Array<boolean>
// 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<unknown>,
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<unknown>
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<unknown, unknown>
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<unknown>
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<string>,
): 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<string | symbol, Slot>()
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<Slot, { get: unknown }>
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<string | symbol, Slot>; 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
}
+344
View File
@@ -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<Encoded>
readonly records: ReadonlyArray<Record>
}
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<ToolCall>
}
/** A runtime with the intrinsics and nothing else, which the build id is taken from. */
export type Bare = Interpreter<unknown>
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<unknown>): 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<unknown>,
options: {
readonly bare: Bare
readonly pristine: Interpreter<unknown>
readonly runId: string
readonly limits: Header["limits"]
readonly activeMs: number
readonly strict: boolean
},
): { readonly snapshot: Snapshot; readonly lost: ReadonlyArray<string> } => {
const machine = ctx.machine
machine.compact()
const lost: Array<string> = []
const current = ctx.intrinsics
const pristine = options.pristine.intrinsics
const sources = [...ctx.sources.values()]
const anchors = new Map<object, string>([
[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<Obj, boolean>()
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<unknown>,
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<string, object>([
["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<unknown> =>
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<Encoded>,
records: array(root.records, "the records") as ReadonlyArray<Record>,
}
}
// --- Helpers ---
const arrays = new WeakMap<Source, Map<ReadonlyArray<unknown>, 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<ReadonlyArray<unknown>, readonly [number, string]> => {
const known = arrays.get(source)
if (known !== undefined) return known
const owned = new Map<ReadonlyArray<unknown>, 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<unknown>["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")
}
+1 -1
View File
@@ -524,7 +524,7 @@ const elements = (target: Arr | Bytes): ArrayLike<Value> => (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.
+88 -24
View File
@@ -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<R = never> = {
) => Effect.Effect<Json | undefined, unknown, R>
readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>
readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>
/** 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<string>) => Tool<R> | undefined
/** Admits a call to a durable tool, as `execute` does, and starts its work under `key`: its handle. */
readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string) => Effect.Effect<Handle, unknown, R>
/** Waits for a durable tool's work: its output, as `execute` gives it. Interrupting it detaches. */
readonly attach: (
path: ReadonlyArray<string>,
args: Array<Json | undefined>,
handle: Handle,
) => Effect.Effect<Json | undefined, unknown, R>
/** The handle of a durable tool's work started under `key`, if it was. */
readonly lookup: (path: ReadonlyArray<string>, key: string) => Effect.Effect<Handle | undefined, unknown, R>
/** Stops a durable tool's work. */
readonly cancel: (path: ReadonlyArray<string>, handle: Handle) => Effect.Effect<void, unknown, R>
}
/** Per-execution call state over tools prepared once for the runtime. */
@@ -388,8 +402,8 @@ export const make = <R>(
prepared: Prepared<R>,
maxToolCalls: number | undefined,
hooks: Hooks<R> = {},
calls: Array<ToolCall> = [],
): ToolRuntime<R> => {
const calls: Array<ToolCall> = []
const root = prepared.root
const recordCall = (call: ToolCall): void => {
@@ -399,12 +413,12 @@ export const make = <R>(
calls.push(call)
}
const executeTool = (name: string, tool: Tool<R>, args: Array<Json | undefined>) =>
const decode = (name: string, tool: Tool<R>, args: Array<Json | undefined>) =>
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 = <R>(
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 = <A>(effect: Effect.Effect<A, unknown, R>) =>
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<R>, 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<R>, args: Array<Json | undefined>) =>
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<string>) => {
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 = <R>(
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))),
}
}
+49 -11
View File
@@ -41,6 +41,27 @@ export type JsonSchema = {
/** Either a validating Effect Schema or a render-only JSON Schema document. */
export type SchemaType = Schema.Decoder<unknown> | 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<Input = unknown, Output = unknown, R = never> = {
readonly start: (input: Input, context: { readonly key: string }) => Effect.Effect<Handle, unknown, R>
readonly attach: (handle: Handle) => Effect.Effect<Output, unknown, R>
readonly lookup: (key: string) => Effect.Effect<Handle | undefined, unknown, R>
readonly cancel: (handle: Handle) => Effect.Effect<void, unknown, R>
}
/**
* 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<R = never> = {
readonly _tag: "CodeModeTool"
@@ -48,19 +69,27 @@ export type Tool<R = never> = {
readonly input: SchemaType
readonly output: SchemaType | undefined
readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, R>
readonly durable?: Durable<unknown, unknown, R> | undefined
readonly retry?: Retry | undefined
}
type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown
type ResultType<S> = S extends undefined ? void : S extends Schema.Decoder<unknown> ? 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<I extends SchemaType, O extends SchemaType | undefined, R = never> = {
readonly description: string
readonly input: I
readonly output?: O
readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>
}
readonly retry?: Retry
} & (
| {
readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>
readonly durable?: Durable<InputType<I>, ResultType<O>, R>
}
| { readonly execute?: undefined; readonly durable: Durable<InputType<I>, ResultType<O>, R> }
)
export const isTool = <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined): value is Tool<R> =>
value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool"
@@ -70,14 +99,23 @@ export const isTool = <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | 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 = <I extends SchemaType, const O extends SchemaType | undefined = undefined, R = never>(
options: Options<I, O, R>,
): Tool<R> => ({
_tag: "CodeModeTool",
description: options.description,
input: options.input,
output: options.output,
execute: (input) => options.execute(input as InputType<I>),
})
): Tool<R> => {
const durable = options.durable as Durable<unknown, unknown, R> | undefined
const execute = options.execute as ((input: unknown) => Effect.Effect<unknown, unknown, R>) | 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 }),
}
}
+3 -2
View File
@@ -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<string>()
const previous = stats.inspect
stats.inspect = (stack) => {
const seen = new Set<unknown>()
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",