mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 05:01:03 +03:00
feat(codemode): save and restore a run's state as a snapshot, with a round-trip test mode
This commit is contained in:
@@ -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",
|
||||
|
||||
@@ -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),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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.`,
|
||||
)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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 }
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
@@ -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.
|
||||
|
||||
@@ -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))),
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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 }),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user