From c33eaa170ed5093c08f1684862a695aae036dcda Mon Sep 17 00:00:00 2001 From: James Long Date: Sat, 7 Nov 2026 13:06:40 -0600 Subject: [PATCH] feat(codemode): idempotent and durable tools, and safe suspension on the VM (#62459) --- packages/codemode/README.md | 130 ++- packages/codemode/src/codemode.ts | 40 +- packages/codemode/src/extension.ts | 20 +- packages/codemode/src/index.ts | 1 + packages/codemode/src/suspend-error.ts | 6 +- packages/codemode/src/tool-runtime.ts | 222 +++- packages/codemode/src/tool.ts | 114 +- packages/codemode/src/vm/host.ts | 15 +- packages/codemode/src/vm/runtime/driver.ts | 115 ++- packages/codemode/src/vm/runtime/execute.ts | 44 +- .../codemode/src/vm/runtime/extensions.ts | 136 ++- .../codemode/src/vm/runtime/interpreter.ts | 3 + packages/codemode/src/vm/scheduler.ts | 14 +- packages/codemode/src/vm/snapshot.ts | 5 +- packages/codemode/src/vm/snapshot/codec.ts | 133 ++- packages/codemode/src/vm/snapshot/snapshot.ts | 17 +- packages/codemode/src/vm/vm.ts | 2 +- packages/codemode/test/codemode.test.ts | 5 +- packages/codemode/test/vm/suspend.test.ts | 977 +++++++++++++++++- 19 files changed, 1850 insertions(+), 149 deletions(-) diff --git a/packages/codemode/README.md b/packages/codemode/README.md index ad070f3bcbf..fec1a09c457 100644 --- a/packages/codemode/README.md +++ b/packages/codemode/README.md @@ -90,12 +90,12 @@ runtime.execute(source) // Effect ``` The Effect environment is inferred from the supplied tools. `hooks` surround every call the program makes into the -host: `tool.before`/`tool.after` receive `{ name, input }` with decoded input, `extension.before`/`extension.after` -receive `{ extension, name, args }`. An `after` hook also receives how the call ended (`success` with its value, -`failure` with its error, or `interrupted`). A `before` hook runs before the call reaches the host, and a failing one -denies it: the host function is never called, and the program catches the failure as a thrown error. A denied call -fails the way the call itself would: a tool call or asynchronous global rejects its promise, and a synchronous global -throws. +host: `tool.before`/`tool.after` receive `{ name, input, key }` with decoded input and the call's `:` +idempotency key, and `extension.before`/`extension.after` receive `{ extension, name, args }`. An `after` hook also +receives how the call ended (`success` with its value, `failure` with its error, or `interrupted`). A `before` hook +runs before the call reaches the host, and a failing one denies it: the host function is never called, and the program +catches the failure as a thrown error. A denied call fails the way the call itself would: a tool call or asynchronous +global rejects its promise, and a synchronous global throws. ### Bytecode VM and suspending/resuming a run (experimental, `engine: "vm"`) @@ -104,8 +104,10 @@ Pass `engine: "vm"` to `CodeMode.make` or `CodeMode.execute` to run programs on both engines. On `engine: "vm"`, `CodeMode.make` returns a `CodeMode.VmRuntime`, which can also run a program step by step: -`runtime.program(code, bindings?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`. `run()` runs it in -the current fiber until it ends or is suspended, and gives a `CodeMode.Outcome`: a `Result`, or: +`runtime.program(code, bindings?, { runId }?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`. Every +host call gets a stable key `:` (using a generated UUID when `runId` is omitted), saved in the snapshot +and passed to tools as `execute(input, { key })` and to hooks as `call.key`. `run()` runs the program in the current +fiber until it ends or is suspended, and gives a `CodeMode.Outcome`: a `Result`, or: ```ts type Suspended = { @@ -119,7 +121,7 @@ const runtime = CodeMode.make({ tools, engine: "vm" }) const outcome = yield* runtime.program(code).run() // in the background, suspended from another fiber -const program = runtime.program(code) +const program = runtime.program(code, undefined, { runId: "run-1" }) const fiber = yield* Effect.forkChild(program.run()) const suspended = yield* program.suspend() // the same Suspended that run() returns const outcome = yield* Fiber.join(fiber) @@ -128,25 +130,80 @@ const outcome = yield* Fiber.join(fiber) yield* runtime.resume(CodeMode.toBytes(suspended.state)).run() ``` -The default runtime has no `program` or `resume`. A program runs once: running it again is a defect, so make another -with `runtime.program` or `runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and -every call in progress. +The default runtime has no `program` or `resume`, and ignores `Tool.idempotent`, `Tool.durable`, and extension +`snapshot` hooks. A program runs once: running it again is a defect, so make another with `runtime.program` or +`runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and every call in progress +(and cancels any started durable tool work). -`program.suspend(options?)` saves the run's state and stops it at once, and `run()` returns the same `Suspended`. It -can be suspended only while no host call (tool, `search`, `fetch`, or extension call) is running. When one is in -progress, `suspend` fails with a `CodeMode.SuspendError` naming each blocking call by its path (`tools.x.y`, `fetch`), -and the run goes on untouched. Tool calls queued but not started don't block: they start on resume. Outcomes already -waiting in the inbox are part of the state. A suspend after the run ended gives its result; one issued before `run()` -has started waits for it to start (and for ever if it never runs). +#### Idempotent and durable tools, and safe suspension + +A tool's `execute` is either a plain function or wrapped with `Tool.idempotent` or `Tool.durable`: + +```ts +// plain (default): a suspend is refused while it runs +Tool.make({ + description: "...", + input: ..., + output: ..., + execute: (input, { key }) => compute(input), +}) + +// idempotent: safe to run again; interrupted on suspend, rerun on resume with the same key +Tool.make({ + description: "...", + input: ..., + output: ..., + execute: Tool.idempotent((input, { key }) => Db.get(input.name)), +}) + +// durable: keeps running across a suspend, reconnected through its JSON data on resume +Tool.make({ + description: "...", + input: ..., + output: ..., + execute: Tool.durable({ + start: (input, { key }) => Jobs.submit(input, key).pipe(Effect.map((id) => ({ id }))), + wait: ({ id }, { key }) => Jobs.wait(id), + cancel: ({ id }) => Jobs.kill(id), + }), +}) +``` + +- **Plain (`execute: (input, { key }) => ...`):** not durable. Suspend is refused while the call is running. +- **`Tool.idempotent(execute)`:** idempotent/read-only work safe to run again. If a suspend lands while the call is + running, the VM detaches and interrupts it without firing `tool.after`, saves the call in the snapshot as queued, and + re-runs it on resume with the same `key` without double-counting it against `maxToolCalls`. +- **`Tool.durable({ start, wait, cancel })`:** work that outlives a suspended run (when run without a suspend or on the + legacy engine, it runs `start` then `wait`): + - `start(input, { key }) => Effect` begins the work and returns JSON `data` (inferred into `wait` + and `cancel`); + - `wait(data, { key }) => Effect` connects to the running work and waits for its result; + - `cancel(data) => Effect` stops the work when the run is interrupted for real or ends, never when it is + suspended. + + While `start` is running, the call blocks suspend. Once `start` returns its JSON data, the call is in the `started` + state with its data saved in the snapshot, and suspend is allowed. `wait` is not tied to the program's JavaScript + `await`: the VM calls `wait(data)` right after `start` returns, and calls `wait(data)` again for every `started` call + right when `resume` starts, whatever the program does with the call's promise (whether it `await`s it immediately, + passes it to `Promise.all`, chains `.then`, or keeps the unawaited promise in a variable and awaits it later). + +`program.suspend(options?)` saves the run's state and stops it at once, and `run()` returns the same `Suspended`. +Suspend is allowed only when every in-flight call is queued, `Tool.idempotent`, or `Tool.durable` in `started`. When +any other host call is in progress — a plain tool, a durable tool still in `start`, `search`, or an async or +synchronous extension call — `suspend` fails with a `CodeMode.SuspendError` naming each blocking call in `running` by +its `key` and `path` (`tools.x.y`, `search`, `fetch`), and the run goes on untouched. Tool calls queued but not started +don't block: they start on resume. Outcomes already waiting in the inbox are part of the state. A suspend after the run +ended gives its result; one issued before `run()` has started waits for it to start (and for ever if it never runs). The suspend is immediate: the program shares the thread with the caller, so it is at a step boundary. Its checks, saving the state, and checking it against `options.maxBytes` all happen before anything about the run changes, so a state that can't be saved or is too large fails the suspend the same way. A resumed run keeps the limits it was saved with: `timeoutMs` counts active time across every resume, and `maxToolCalls` -counts every call of the run. A state resumes only on the same build of this package and with the same extensions. The -state is checked when the resumed program runs: its `run()` fails with a `CodeMode.SnapshotError` when it can't be -resumed here or is malformed. Built-ins are saved by name and only their changes are copied. +counts every admitted call of the run. A state resumes only on the same build of this package and with the same +extensions (and the same extension `snapshot` hooks). The state is checked when the resumed program runs: its `run()` +fails with a `CodeMode.SnapshotError` when it can't be resumed here or is malformed. Built-ins are saved by name and +only their changes are copied. Set `CODEMODE_ROUNDTRIP=1` (`bun run test:roundtrip`) to run the tests on the VM with every run saved to bytes and restored into a brand-new runtime at every host call and every few steps. @@ -191,6 +248,37 @@ Every value crossing in either direction is converted, never shared: arguments c copies, and a function inside a result is callable the same way. A global that shadows a built-in or another extension throws at `CodeMode.make`. +Functions inside a result have no data form, so a suspended VM run loses them by default: after a resume, calling one +throws a `TypeError`. An extension can preserve them across suspend and resume with `snapshot` hooks. `encode` receives +a value one of the extension's functions returned, as the host function returned it, and returns plain data (JSON +values and `Uint8Array`s); on resume, `decode` receives that data once per value and returns a host value of the same +shape, whose functions the restored program copies call from then on: + +```ts +const saved = Symbol("saved") +const makeResponse = (data: { url: string; body: Uint8Array }) => ({ + [saved]: data, + url: data.url, + text: async () => new TextDecoder().decode(data.body), + bytes: async () => data.body, +}) +const web = Extension.make({ + name: "web", + globals: { + fetch: Extension.async(async (url: string) => + makeResponse({ url, body: await (await globalThis.fetch(url)).bytes() }), + ), + }, + snapshot: { + encode: (value) => (value as { [saved]: { url: string; body: Uint8Array } })[saved], + decode: (data) => makeResponse(data as { url: string; body: Uint8Array }), + }, +}) +``` + +A suspend fails (and the run continues) when `encode` throws or returns non-plain data. A snapshot saved with an +extension's hooks resumes only in a runtime whose extension of the same name also provides `snapshot` hooks. + A global can also be an object of functions, such as `fs`. Every function reachable from it is an entry point like a global, so calls fire the `extension` hooks with their path as the name (`fs.readFile`, `fs.promises.readFile`). diff --git a/packages/codemode/src/codemode.ts b/packages/codemode/src/codemode.ts index c31b18d044e..8f48b1a895f 100644 --- a/packages/codemode/src/codemode.ts +++ b/packages/codemode/src/codemode.ts @@ -51,6 +51,12 @@ export type ResolvedExecutionLimits = { /** Execution engine: the default AST generator interpreter (`"legacy"`) or the experimental bytecode VM (`"vm"`). */ export type Engine = "legacy" | "vm" +/** Options for `VmRuntime.program`. */ +export type ProgramOptions = { + /** Names this run's host calls (`:`); a random UUID by default. */ + readonly runId?: string +} + /** How `program.suspend` saves a run's state (`engine: "vm"` only). */ export type SuspendOptions = { /** The most bytes a saved state may take; a larger one fails the suspend, and the run goes on. */ @@ -167,7 +173,11 @@ export type Runtime = { /** A runtime on the bytecode VM (`engine: "vm"`, experimental): it can also suspend runs and resume them. */ export type VmRuntime = Runtime & { /** A program ready to run once; nothing runs until `program.run()`. */ - readonly program: (code: string, bindings?: Readonly>) => Program + readonly program: ( + code: string, + bindings?: Readonly>, + options?: ProgramOptions, + ) => Program /** * A suspended run (its `state`, or that state as bytes) as a program to continue in this runtime, which must be the * same build with the same extensions. The state is checked when it runs: `run()` fails with a `SnapshotError` when @@ -225,7 +235,9 @@ export function make< export function make< const Provided extends Record = {}, const Extensions extends ReadonlyArray = [], ->(options: Options = {}): Runtime> | VmRuntime> { +>( + options: Options = {}, +): Runtime> | VmRuntime> { type R = Environment const prepared = ToolRuntime.prepare((options.tools ?? {}) as Tools>) const limits = resolveExecutionLimits(options.limits) @@ -257,30 +269,27 @@ export function make< limits, hooks: options.hooks ?? {}, globals: extensions.length === 0 ? undefined : (ctx) => vm.extensionGlobals(ctx, extensions), - lossy: extensions.length > 0, + lossy: extensions.some((extension) => extension.snapshot === undefined), }) const data = (vm: typeof VmEngine, bindings: Readonly> | undefined) => bindings === undefined ? undefined : (ctx: Parameters[0]) => Object.entries(bindings).map(([name, value]) => [name, vm.fromJson(ctx, value)] as const) - const program = (code: string, bindings?: Readonly>) => - vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings)))) + const program = (code: string, bindings?: Readonly>, programOptions?: ProgramOptions) => + vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings), programOptions?.runId))) return { get catalog() { return prepared.catalog }, - execute: (code, bindings) => - Effect.flatMap(loadVm(), (vm) => vm.finishExecution(program(code, bindings).run())), + execute: (code, bindings) => Effect.flatMap(loadVm(), (vm) => vm.finishExecution(program(code, bindings).run())), program, resume: (state) => vmProgram((vm) => vm.resumeProgram(getSetup(vm), state)), } satisfies VmRuntime } // A program's one run: `start` makes it once the VM is loaded, and a suspend waits for it. -const vmProgram = ( - start: (vm: typeof VmEngine) => Effect.Effect, E>, -): Program => { +const vmProgram = (start: (vm: typeof VmEngine) => Effect.Effect, E>): Program => { let claimed = false const started = Deferred.makeUnsafe, SuspendError>() return { @@ -318,9 +327,10 @@ let vmEngine: Promise | undefined const loadVm = () => vmLoaded !== undefined ? Effect.succeed(vmLoaded) - : Effect.promise(() => - (vmEngine ??= import("./vm/index.js").then((mod) => { - vmLoaded = mod - return mod - })), + : Effect.promise( + () => + (vmEngine ??= import("./vm/index.js").then((mod) => { + vmLoaded = mod + return mod + })), ) diff --git a/packages/codemode/src/extension.ts b/packages/codemode/src/extension.ts index e7a6103e7a2..3864216e012 100644 --- a/packages/codemode/src/extension.ts +++ b/packages/codemode/src/extension.ts @@ -18,6 +18,20 @@ import type { Effect } from "effect" export type Extension> = Readonly>> = { readonly name: string readonly globals: Globals + /** How a suspended run saves the values this extension's functions returned (`engine: "vm"` only); see `Snapshot`. */ + readonly snapshot?: Snapshot | undefined +} + +/** + * Lets a suspended run keep the functions inside values this extension's functions returned (a response's `text`, + * say). `encode` gets such a value, as the host function returned it, and gives plain data: JSON values and + * `Uint8Array`s. On resume, `decode` gets that data back, once per value, and gives a value of the same shape, whose + * functions the program's copies call from then on. Without it, those functions are lost on resume: calling one + * throws. A suspend fails, and the run goes on, when `encode` throws or gives anything else. + */ +export type Snapshot = { + readonly encode: (value: unknown) => unknown + readonly decode: (data: unknown) => unknown } /** The Effect environment required by an extension's Effect-returning functions, at the top level or one level in. */ @@ -39,7 +53,11 @@ export const make = >>( throw new TypeError(`Extension "${options.name}" global "${name}" must be a function or an object.`) } } - return { name: options.name, globals: { ...options.globals } } + return { + name: options.name, + globals: { ...options.globals }, + ...(options.snapshot === undefined ? {} : { snapshot: options.snapshot }), + } } const asyncGlobals = new WeakSet() diff --git a/packages/codemode/src/index.ts b/packages/codemode/src/index.ts index a1be75ad8c4..bcf1043588c 100644 --- a/packages/codemode/src/index.ts +++ b/packages/codemode/src/index.ts @@ -12,6 +12,7 @@ export { toolExpression, type Outcome, type Program, + type ProgramOptions, type Snapshot, type SnapshotHeader, type Suspended, diff --git a/packages/codemode/src/suspend-error.ts b/packages/codemode/src/suspend-error.ts index 34f3db46870..21a39ccd282 100644 --- a/packages/codemode/src/suspend-error.ts +++ b/packages/codemode/src/suspend-error.ts @@ -2,13 +2,13 @@ import { Schema } from "effect" import type { Snapshot } from "./vm/snapshot/snapshot.js" /** - * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its path - * (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be + * A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its + * path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be * saved or was too large. */ export class SuspendError extends Schema.TaggedError()("SuspendError", { message: Schema.String, - running: Schema.Array(Schema.Struct({ path: Schema.String })), + running: Schema.Array(Schema.Struct({ key: Schema.String, path: Schema.String })), }) {} export class SnapshotError extends Error { diff --git a/packages/codemode/src/tool-runtime.ts b/packages/codemode/src/tool-runtime.ts index 8660d4fd630..ed4b09c4f00 100644 --- a/packages/codemode/src/tool-runtime.ts +++ b/packages/codemode/src/tool-runtime.ts @@ -12,7 +12,7 @@ import { outputTypeScript, } from "./tool-schema.js" import { isNamespace, type Namespace } from "./namespace.js" -import { isTool, type Tool } from "./tool.js" +import { type Durable, type Idempotent, isTool, type Tool, type ToolContext } from "./tool.js" import type { Tools } from "./tools.js" export const compareText = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0) @@ -23,7 +23,7 @@ type ServicesOf> = Depth["length"] exten ? never : T extends { readonly _tag: "CodeModeTool" - readonly execute: (input: unknown) => Effect.Effect + readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect } ? R : T extends object @@ -37,7 +37,12 @@ export type ToolCall = { } /** A tool call the program is making, with its decoded input. */ -export type ToolInvocation = { readonly name: string; readonly input: unknown } +export type ToolInvocation = { + readonly name: string + readonly input: unknown + /** The call's idempotency key, `:`: the same at every hook, and across a suspended run's resumes. */ + readonly key: string +} /** * A call the program is making to an extension global or module function, with its arguments. A module function is @@ -65,17 +70,19 @@ export type Hooks = { | undefined } -/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */ +/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */ export const hooked = ( call: Call, before: ((call: Call) => Effect.Effect) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect) | undefined, run: Effect.Effect, + detaching?: () => boolean, ): Effect.Effect => { const observed = after === undefined ? run : Effect.onExit(run, (exit) => { + if (detaching?.()) return Effect.void if (Exit.isSuccess(exit)) return after(call, { status: "success", value: exit.value }) if (Cause.hasInterruptsOnly(exit.cause)) return after(call, { status: "interrupted" }) return after(call, { status: "failure", error: Cause.squash(exit.cause) }) @@ -371,16 +378,53 @@ export class ToolRuntimeError extends Error { } } +export type ExecuteCallOptions = { + readonly key?: string | undefined + readonly admit?: ((name: string) => void) | undefined + readonly detaching?: (() => boolean) | undefined +} + /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */ export type ToolRuntime = { readonly calls: Array readonly hooks: Hooks + readonly invocations: Map + readonly record: (name: string) => void readonly execute: ( path: ReadonlyArray, args: Array, + options?: ExecuteCallOptions, + ) => Effect.Effect + readonly search: ( + args: Array, + options?: ExecuteCallOptions, ) => Effect.Effect - readonly search: (args: Array) => Effect.Effect readonly keys: (path: ReadonlyArray) => ReadonlyArray + /** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */ + readonly mode: ( + path: ReadonlyArray, + ) => Idempotent | Durable | undefined + /** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */ + readonly start: ( + path: ReadonlyArray, + args: Array, + key: string, + admit?: (name: string) => void, + ) => Effect.Effect + /** + * Waits for a durable tool's running work: its output, as `execute` gives it. `detaching` says whether an + * interruption detaches to suspend the run, which `tool.after` doesn't see, or ends the call, which it sees as + * interrupted. + */ + readonly wait: ( + path: ReadonlyArray, + args: Array, + key: string, + data: Json, + detaching: () => boolean, + ) => Effect.Effect + /** Cancels a durable tool's started work when the run is interrupted or ends. */ + readonly cancel: (path: ReadonlyArray, data: Json) => Effect.Effect } /** Per-execution call state over tools prepared once for the runtime. */ @@ -390,7 +434,10 @@ export const make = ( hooks: Hooks = {}, ): ToolRuntime => { const calls: Array = [] + const invocations = new Map() const root = prepared.root + const runId = crypto.randomUUID() + let nextCallId = 0 const recordCall = (call: ToolCall): void => { if (maxToolCalls !== undefined && calls.length >= maxToolCalls) { @@ -399,12 +446,12 @@ export const make = ( calls.push(call) } - const executeTool = (name: string, tool: Tool, args: Array) => + const decode = (name: string, tool: Tool, args: Array) => Effect.gen(function* () { const normalized = args.length === 0 ? [{}] : args if (normalized.length !== 1) throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`) - const input = yield* Effect.try({ + return yield* Effect.try({ try: () => decodeToolInput(tool, normalized[0]), catch: (cause) => new ToolRuntimeError( @@ -413,48 +460,157 @@ export const make = ( name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."], ), }) - yield* Effect.sync(() => recordCall({ name })) + }) + + // A tool's own failure becomes a ToolError; interruption passes through. + const failure = (effect: Effect.Effect) => + effect.pipe( + Effect.catchCause((cause) => { + if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt + return Effect.fail( + toolError( + Cause.prettyErrors(cause) + .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name)) + .join("\n"), + ), + ) + }), + ) + + // The same round trip a tool result would take through text: exact JSON.stringify semantics. + const output = (name: string, tool: Tool, raw: unknown) => + Effect.try({ + try: (): Json | undefined => { + const text = JSON.stringify(decodeToolOutput(tool, raw)) + return text === undefined ? undefined : JSON.parse(text) + }, + catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`), + }) + + const executeTool = (name: string, tool: Tool, args: Array, options?: ExecuteCallOptions) => + Effect.gen(function* () { + const key = options?.key ?? `${runId}:${nextCallId++}` + const input = yield* decode(name, tool, args) + const admit = options?.admit + yield* Effect.sync(() => (admit !== undefined ? admit(name) : recordCall({ name }))) return yield* hooked( - { name, input }, + { name, input, key }, 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, { key }))) + return yield* output(name, tool, raw) }), + options?.detaching, ) }) + const durableTool = ( + path: ReadonlyArray, + ): { + readonly name: string + readonly tool: Tool + readonly durable: Durable + } => { + const segments = canonicalSegments(path) + const name = segments.join(".") + const tool = lookup(root, segments)?.tool + if (tool?.mode?._tag !== "CodeModeDurable") { + throw new TypeError(`Tool '${name}' is not a durable tool.`) + } + return { name, tool, durable: tool.mode } + } + return { calls, hooks, + invocations, + record: (name) => recordCall({ name }), keys: (path) => namespaceKeys(root, path), - search: (args) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args)), - execute: (path, args) => + search: (args, options) => + Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args, options)), + execute: (path, args, options) => Effect.suspend(() => { const segments = canonicalSegments(path) // Models often write `tools.search(...)` for the bare `search(...)`; honor it unless a tool owns that path. if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined) - return executeTool("search", makeSearchTool(prepared.searchIndex), args) - return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args) + return executeTool("search", makeSearchTool(prepared.searchIndex), args, options) + return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args, options) + }), + mode: (path) => { + const segments = canonicalSegments(path) + if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined) return undefined + return lookup(root, segments)?.tool?.mode + }, + start: (path, args, key, admit) => + Effect.suspend(() => { + const found = durableTool(path) + return Effect.gen(function* () { + const input = yield* decode(found.name, found.tool, args) + yield* Effect.sync(() => (admit !== undefined ? admit(found.name) : recordCall({ name: found.name }))) + const invocation: ToolInvocation = { name: found.name, input, key } + invocations.set(key, invocation) + const before = hooks["tool.before"] + const after = hooks["tool.after"] + const run = failure(Effect.suspend(() => found.durable.start(input, { key }))).pipe( + Effect.flatMap((raw) => + Effect.try({ + try: (): Json => { + const text = JSON.stringify(raw) + return text === undefined ? null : JSON.parse(text) + }, + catch: (cause) => + new ToolRuntimeError("InvalidToolOutput", `Invalid start data from tool '${found.name}': ${cause}`), + }), + ), + ) + const observed = + after === undefined + ? run + : Effect.onError(run, (cause) => { + invocations.delete(key) + if (Cause.hasInterruptsOnly(cause)) return after(invocation, { status: "interrupted" }) + return after(invocation, { status: "failure", error: Cause.squash(cause) }) + }) + return yield* before === undefined ? observed : Effect.andThen(before(invocation), observed) + }) + }), + wait: (path, args, key, data, detaching) => + Effect.suspend(() => { + const found = durableTool(path) + const wait = found.durable.wait as (data: Json, context: ToolContext) => Effect.Effect + const after = hooks["tool.after"] + const run = Effect.gen(function* () { + const raw = yield* failure(Effect.suspend(() => wait(data, { key }))) + return yield* output(found.name, found.tool, raw) + }) + if (after === undefined) return run + const known = invocations.get(key) + const callEffect = + known !== undefined + ? Effect.succeed(known) + : Effect.map( + decode(found.name, found.tool, args), + (input): ToolInvocation => ({ + name: found.name, + input, + key, + }), + ) + return Effect.flatMap(callEffect, (call) => + Effect.onExit(run, (exit) => { + if (detaching()) return Effect.void + invocations.delete(key) + if (Exit.isSuccess(exit)) return after(call, { status: "success", value: exit.value }) + if (Cause.hasInterruptsOnly(exit.cause)) return after(call, { status: "interrupted" }) + return after(call, { status: "failure", error: Cause.squash(exit.cause) }) + }), + ) + }), + cancel: (path, data) => + Effect.suspend(() => { + const cancel = durableTool(path).durable.cancel as (data: Json) => Effect.Effect + return failure(cancel(data)) }), } } diff --git a/packages/codemode/src/tool.ts b/packages/codemode/src/tool.ts index e39138fd595..108bfe25565 100644 --- a/packages/codemode/src/tool.ts +++ b/packages/codemode/src/tool.ts @@ -41,13 +41,64 @@ export type JsonSchema = { /** Either a validating Effect Schema or a render-only JSON Schema document. */ export type SchemaType = Schema.Decoder | JsonSchema +/** Context passed to a tool call: its stable idempotency key (`:`). */ +export type ToolContext = { + readonly key: string +} + +export type ExecuteFn = ( + input: Input, + context: ToolContext, +) => Effect.Effect + +/** + * A tool execution wrapper for idempotent work that is safe to run again. If a suspend lands while the call is running + * (`engine: "vm"`), the VM interrupts it without firing `tool.after`, keeps the call queued in the snapshot, and + * re-runs it on resume with the same `key` without double-counting against `maxToolCalls`. + */ +export type Idempotent = { + (input: Input, context: ToolContext): Effect.Effect + readonly _tag: "CodeModeIdempotent" + readonly execute: ExecuteFn +} + +/** + * Options for `Tool.durable`: `start` begins the work under `key` and returns JSON `data` saved in the snapshot; + * `wait` connects to the running work and waits for its output; `cancel` stops the work when the run is interrupted + * for real or ends, never when it is suspended. `wait` is not tied to the program's JS `await`: the VM calls `wait` + * right after `start` returns, and again for every `started` call right at resume, whatever the program does with the + * promise. + */ +export type DurableOptions< + Data extends Schema.Json, + Input = unknown, + Output = unknown, + RStart = never, + RWait = never, + RCancel = never, +> = { + readonly start: (input: Input, context: ToolContext) => Effect.Effect + readonly wait: (data: NoInfer, context: ToolContext) => Effect.Effect + readonly cancel: (data: NoInfer) => Effect.Effect +} + +/** A tool execution wrapper for work that keeps running across a suspend and reconnects through its JSON data. */ +export type Durable = { + (input: Input, context: ToolContext): Effect.Effect + readonly _tag: "CodeModeDurable" + readonly start: (input: Input, context: ToolContext) => Effect.Effect + readonly wait: (data: never, context: ToolContext) => Effect.Effect + readonly cancel: (data: never) => Effect.Effect +} + /** Executable tool exposed through CodeMode's `tools` object. */ export type Tool = { readonly _tag: "CodeModeTool" readonly description: string readonly input: SchemaType readonly output: SchemaType | undefined - readonly execute: (input: unknown) => Effect.Effect + readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect + readonly mode?: Idempotent | Durable | undefined } type InputType = S extends Schema.Decoder ? S["Type"] : unknown @@ -59,12 +110,52 @@ export type Options) => Effect.Effect, unknown, R> + readonly execute: + | ExecuteFn, ResultType, R> + | Idempotent, ResultType, R> + | Durable, ResultType, R> } export const isTool = (value: Tool | Namespace | Tools | undefined): value is Tool => value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool" +/** Marks a tool's `execute` function as safe to interrupt on suspend and re-run on resume with the same key. */ +export const idempotent = ( + execute: ExecuteFn, +): Idempotent => + Object.assign((input: Input, context: ToolContext) => execute(input, context), { + _tag: "CodeModeIdempotent" as const, + execute, + }) + +/** + * Wraps a tool's execution as `start`, `wait`, and `cancel` so work started before a suspend keeps running and + * reconnects through its JSON data on resume. + */ +export const durable = < + Data extends Schema.Json, + Input = unknown, + Output = unknown, + RStart = never, + RWait = never, + RCancel = never, +>( + options: DurableOptions, +): Durable => { + type R = RStart | RWait | RCancel + const wait = options.wait as (data: Schema.Json, context: ToolContext) => Effect.Effect + return Object.assign( + (input: Input, context: ToolContext): Effect.Effect => + Effect.flatMap(options.start(input, context), (data) => wait(data, context)), + { + _tag: "CodeModeDurable" as const, + start: options.start, + wait: options.wait as (data: never, context: ToolContext) => Effect.Effect, + cancel: options.cancel as (data: never) => Effect.Effect, + }, + ) +} + /** * Declares one schema-described tool available to a CodeMode program through `tools.*`. * @@ -74,10 +165,15 @@ export const isTool = (value: Tool | Namespace | Tools | und */ export const make = ( options: Options, -): Tool => ({ - _tag: "CodeModeTool", - description: options.description, - input: options.input, - output: options.output, - execute: (input) => options.execute(input as InputType), -}) +): Tool => { + const spec = options.execute + const mode = "_tag" in spec ? (spec as Idempotent | Durable) : undefined + return { + _tag: "CodeModeTool", + description: options.description, + input: options.input, + output: options.output, + ...(mode === undefined ? {} : { mode }), + execute: (input, context = { key: crypto.randomUUID() }) => spec(input as InputType, context), + } +} diff --git a/packages/codemode/src/vm/host.ts b/packages/codemode/src/vm/host.ts index a821612732b..67b4fe737d7 100644 --- a/packages/codemode/src/vm/host.ts +++ b/packages/codemode/src/vm/host.ts @@ -57,6 +57,8 @@ export const VISIT_BUDGET = 2048 * waiting in the inbox, and the blocking call the current job waits on. Ids count up in program order. */ export class HostCalls { + /** Names this run's host calls (`:`). */ + runId = "" queued: Array = [] readonly running = new Map() readonly inbox: Array = [] @@ -65,8 +67,8 @@ export class HostCalls { blocked: HostCall | undefined = undefined /** A completed blocking call's outcome, which continues the job on the stack before anything else runs. */ input: { readonly call: HostCall; readonly completion: Completion } | undefined = undefined - /** The synchronous extension call the program is in the middle of: see `Engine.activeExtension`. */ - extension: { readonly path: string } | undefined = undefined + /** The synchronous extension call the program is in the middle of: see `Vm.activeExtension`. */ + extension: { readonly key: string; readonly path: string } | undefined = undefined extensionResume: ((completion: Completion) => HostResult) | undefined = undefined constructor( @@ -94,7 +96,9 @@ export class HostCalls { /** Queues blocking extension work: the job stops until it completes, then continues with `resume`. */ blockExtension(call: ExtensionRequest, resume: (completion: Completion) => HostResult): typeof BLOCK { - return this.block({ kind: "extension", call }, "extension", resume) + this.block({ kind: "extension", call }, "extension", resume) + this.extension = { key: this.blocked!.key, path: call.label } + return BLOCK } private block( @@ -116,7 +120,7 @@ export class HostCalls { site: AstNode | undefined, ): HostCall { const id = this.nextID++ - const call = new HostCall(id, request, label, blocking, result, resolving, site) + const call = new HostCall(id, `${this.runId}:${id}`, request, label, blocking, result, resolving, site) this.queued.push(call) return call } @@ -145,6 +149,7 @@ export class HostCalls { if (call === undefined) return this.running.delete(id) // Its outcome is all that is left: the host function, its arguments, and what it returned are dropped. + call.data = undefined const request = call.request if (request.kind === "extension") { request.call.invocation = undefined @@ -268,9 +273,9 @@ export const callExtension = ( args: slots[1] as ReadonlyArray, label, invocation: slots[3] as ExtensionInvocation | undefined, + extension: slots[4] as string | undefined, } if (call.host instanceof Lost) throw lostError(`The function ${label}`) - hosts.extension = { path: label } const run = (): HostResult => { const started = startExtensionCall(ctx, call.host as Function, call.args, call, site) if (started instanceof PromiseObj) { diff --git a/packages/codemode/src/vm/runtime/driver.ts b/packages/codemode/src/vm/runtime/driver.ts index 30d717ad8a9..f5e77e0e2d5 100644 --- a/packages/codemode/src/vm/runtime/driver.ts +++ b/packages/codemode/src/vm/runtime/driver.ts @@ -1,4 +1,5 @@ import { Cause, type Context, Effect, Exit, Fiber } from "effect" +import type { Json } from "../data.js" import type { HostCall } from "../scheduler.js" import { type ToolRuntime, toolExpression } from "../../tool-runtime.js" import { locate } from "./errors.js" @@ -15,11 +16,15 @@ export const SUSPENDED: unique symbol = Symbol("codemode.suspended") * calls the VM queued, as fibers with the caller's services, reporting each outcome back with `vm.complete`. * Fibers live only here, by host call id, and never become part of the VM's state. * - * The VM and tool bridge can be swapped for restored ones between stops (the round-trip test mode does); a fiber's - * outcome goes to whichever VM is current, by host call id. + * A durable tool's call runs as two fibers, `start` then `wait`, so suspending can detach the second and keep the JSON + * data `start` gave. An idempotent tool's running fiber is detached and interrupted on suspend, and its call is saved + * as queued to run again on resume. The VM and tool bridge can be swapped for restored ones between stops (the + * round-trip test mode does); a fiber's outcome goes to whichever VM is current, by host call id. */ export class Driver { private readonly fibers = new Map>() + // Calls whose fibers were interrupted to suspend or end the run: their outcomes are not reported. + private readonly detached = new Set() private wake: (() => void) | undefined private stopping = false private suspending = false @@ -80,13 +85,20 @@ export class Driver { } /** - * The host calls that block a suspend now: every call in progress, and a queued or synchronous extension call the - * program is in the middle of, which holds live host values. A tool call queued but not started starts on resume. + * The host calls that block a suspend now: every call in progress except an idempotent tool call or a durable tool + * call in `started`, plus any queued or synchronous extension call the program is in the middle of, which holds live + * host values. A tool call queued but not started starts on resume. */ - blocking(): Array<{ readonly path: string }> { + blocking(): Array<{ readonly key: string; readonly path: string }> { const vm = this.vm - const calls = vm.calls().filter((call) => call.status !== "queued" || call.request.kind === "extension") - const running = calls.map((call) => ({ path: callPath(call) })) + const calls = vm.calls().filter((call) => { + if (call.request.kind === "extension") return true + if (call.status === "queued" || call.status === "started") return false + if (call.request.kind === "tool" && this.tools.mode(call.request.path)?._tag === "CodeModeIdempotent") + return false + return true + }) + const running = calls.map((call) => ({ key: call.key, path: callPath(call) })) const active = vm.activeExtension if (active !== undefined && !calls.some((call) => call.blocking && call.request.kind === "extension")) { running.push(active) @@ -99,48 +111,111 @@ export class Driver { return this.vm.calls().some((call) => call.request.kind === "extension") || this.vm.activeExtension !== undefined } - /** Stops the run to suspend it, once its state is saved: `run` returns `SUSPENDED` at its next step. */ + /** + * Stops the run to suspend it, once its state is saved: `run` returns `SUSPENDED` at its next step, and running + * idempotent or durable calls' fibers are detached, so ending them reports nothing. + */ detach(): void { this.suspending = true + for (const id of this.fibers.keys()) this.detached.add(id) this.wake?.() } - /** Stops host work still running, waiting for its cleanup. */ + /** Stops host work still running, waiting for its cleanup; a durable tool's work is cancelled unless detached. */ interrupt(): Effect.Effect { const self = this - return Effect.gen(function* () { - self.stopping = true - while (self.fibers.size > 0) yield* Fiber.interruptAll([...self.fibers.values()]) - }) + return Effect.uninterruptible( + 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 waited on at resume. + if (self.suspending) return + for (const call of self.vm.calls()) { + const request = call.request + if (call.status !== "started" || request.kind !== "tool") continue + call.status = "completed" + yield* Effect.ignore(self.tools.cancel(request.path, call.data as Json)).pipe( + Effect.provideContext(self.services), + ) + } + }), + ) } - /** Starts any tool calls that were queued when the VM was saved. */ + /** Starts tool calls that were queued (including idempotent calls) and waits on durable calls in `started`. */ resume(): void { + if (this.suspending) return for (const call of this.vm.calls()) { if (call.status === "queued") this.launch(call) + else if (call.status === "started") this.wait(call) } } + private admit(id: number, name: string): void { + const call = this.vm.call(id) + if (call?.admitted) return + this.tools.record(name) + if (call !== undefined) call.admitted = true + } + // Starts host work now; its outcome goes back to the VM: 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 = "running" const request = call.request - 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)) + if (request.kind === "tool") { + if (this.tools.mode(request.path)?._tag === "CodeModeDurable") { + const started = this.tools.start(request.path, request.args, call.key, (name) => this.admit(call.id, name)) + return this.fork(call.id, started, (data) => { + const current = this.vm.call(call.id) + if (current === undefined) return + current.status = "started" + current.data = data as Json + if (this.stopping || this.detached.has(call.id)) return + this.wait(current) + }) + } + return this.fork( + call.id, + this.tools.execute(request.path, request.args, { + key: call.key, + admit: (name) => this.admit(call.id, name), + detaching: () => this.suspending, + }), + ) + } + if (request.kind === "search") { + return this.fork( + call.id, + this.tools.search(request.args, { + key: call.key, + admit: (name) => this.admit(call.id, name), + }), + ) + } // An extension's work, made by the extension bridge with the program's services in its requirements. return this.fork(call.id, this.vm.ctx.extensionWork!(request.call) as Effect.Effect) } + private wait(call: HostCall): void { + const request = call.request + if (request.kind !== "tool") return + this.fork( + call.id, + this.tools.wait(request.path, request.args, call.key, call.data as Json, () => this.suspending), + ) + } + // Forks `work` with the caller's services; it starts synchronously, so admission and hooks happen before the VM - // runs another job. - private fork(id: number, work: Effect.Effect): void { + // runs another job. A success goes to `next` when given, otherwise to the VM. + private fork(id: number, work: Effect.Effect, next?: (value: unknown) => void): void { const fiber = Effect.runForkWith(this.services)(work) this.fibers.set(id, fiber) fiber.addObserver((exit) => { if (this.fibers.get(id) === fiber) this.fibers.delete(id) - // Interrupted to end the run: nothing is left to settle. - if (this.stopping) return + if (next !== undefined && Exit.isSuccess(exit)) return next(exit.value) + // Interrupted to end or suspend the run: nothing is left to settle. + if (this.stopping || this.detached.has(id)) return const call = this.vm.call(id) if (call === undefined) return if (call.blocking) { diff --git a/packages/codemode/src/vm/runtime/execute.ts b/packages/codemode/src/vm/runtime/execute.ts index 082d5bbab0c..40104d023bc 100644 --- a/packages/codemode/src/vm/runtime/execute.ts +++ b/packages/codemode/src/vm/runtime/execute.ts @@ -12,7 +12,7 @@ import { createBuiltins } from "./intrinsics.js" import { Interpreter } from "./interpreter.js" import type { Value } from "./objects.js" import { formatLocation, sourceLocation } from "./model.js" -import { Driver, SUSPENDED } from "./driver.js" +import { callPath, Driver, SUSPENDED } from "./driver.js" import { Interruption } from "./signals.js" import { Source } from "./source.js" import type { Vm } from "../vm.js" @@ -59,7 +59,7 @@ export const execute = ( bindings === undefined ? undefined : (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)] as const), - extensions.length > 0, + extensions.some((extension) => extension.snapshot === undefined), ) export const executeProgram = ( @@ -74,7 +74,12 @@ export const executeProgram = ( finishExecution(startProgram({ prepared, limits, hooks, globals, lossy }, code, bindings).run()) /** A program ready to run on the VM: nothing runs until `run`. */ -export const startProgram = (setup: Setup, code: string, bindings?: Globals): Running => +export const startProgram = ( + setup: Setup, + code: string, + bindings?: Globals, + runId: string = crypto.randomUUID(), +): Running => new Running(setup, 0, () => { if (code.trim().length === 0) { return { ok: false, error: { kind: "ParseError", message: "Code cannot be empty." }, toolCalls: [] } @@ -82,6 +87,7 @@ export const startProgram = (setup: Setup, code: string, bindings?: Global const parsed = parseProgram(code) if (!parsed.ok) return { ok: false, error: parsed.error, toolCalls: [] } const runtime = instantiate(setup, bindings) + runtime.vm.hosts.runId = runId runtime.vm.start(parsed.source) return runtime }) @@ -109,6 +115,14 @@ export const resumeProgram = ( } const fresh = instantiate(resumed) const snapshot = restoreInto(state, fresh.vm) + for (const call of fresh.vm.calls()) { + if (call.status !== "started") continue + if (call.request.kind !== "tool" || fresh.tools.mode(call.request.path)?._tag !== "CodeModeDurable") { + throw new SnapshotError( + `The pending durable call ${call.key} (${callPath(call)}) cannot resume because that tool is no longer a durable tool in this runtime.`, + ) + } + } return new Running(resumed, snapshot.header.budget.activeMs, () => fresh, true) }, catch: (error) => (error instanceof SnapshotError ? error : new SnapshotError(String(error))), @@ -191,7 +205,6 @@ export class Running { self.driver = new Driver(prepared.vm, prepared.tools, yield* Effect.context()) if (roundTrip) self.driver.checkpoint = Effect.sync(() => self.trip()) self.startedAt = Date.now() - yield* Deferred.succeed(self.started, undefined) return yield* self.execute() }).pipe( Effect.onExit((exit) => @@ -233,6 +246,7 @@ export class Running { const base = Effect.gen(function* () { const driver = self.driver if (self.resuming) driver.resume() + yield* Deferred.succeed(self.started, undefined) const outcome = yield* driver.run() if (outcome === SUSPENDED) return self.suspended! self.finished = true @@ -315,6 +329,12 @@ export class Running { running, }) } + // Idempotent calls in flight are saved as queued so they run again on resume under the same key. + const idempotent = vm.calls().filter((call) => call.status === "running") + for (const call of idempotent) call.status = "queued" + const restoreRunning = () => { + for (const call of idempotent) call.status = "running" + } const limits = this.setup.limits const saved = attempt(() => vm.capture({ @@ -328,6 +348,7 @@ export class Running { }), ) if (!saved.ok) { + restoreRunning() const error = saved.error return new SuspendError({ message: `The run's state couldn't be saved: ${error instanceof Error ? error.message : String(error)}`, @@ -338,6 +359,7 @@ export class Running { if (maxBytes !== undefined) { const size = toBytes(snapshot).byteLength if (size > maxBytes) { + restoreRunning() return new SuspendError({ message: `The run's state takes ${size} bytes, more than the ${maxBytes}-byte limit, so it couldn't be suspended.`, running: [], @@ -348,8 +370,8 @@ export class Running { } // 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. + // hold live host values (an extension call in flight, a function an extension without `snapshot` hooks 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 driver = this.driver if (this.trips >= ROUND_TRIP_MAX) { @@ -362,12 +384,20 @@ export class Running { } if (driver.holdsHostValues) return this.trips++ - const saved = this.ctx.vm.capture({ strict: !this.setup.lossy }) + const attempted = attempt(() => this.ctx.vm.capture({ strict: !this.setup.lossy })) + // An extension's `snapshot` hooks may refuse to save a value, which fails a suspend, not the run. + if (!attempted.ok) { + const error = attempted.error + if (error instanceof SnapshotError && error.message.startsWith("The extension ")) return + throw error + } + const saved = attempted.value 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(fromBytes(bytes), fresh.vm) + for (const [key, invocation] of this.ctx.tools.invocations) fresh.tools.invocations.set(key, invocation) this.ctx = fresh driver.vm = fresh.vm driver.tools = fresh.tools diff --git a/packages/codemode/src/vm/runtime/extensions.ts b/packages/codemode/src/vm/runtime/extensions.ts index 22a830b1026..1d335deba86 100644 --- a/packages/codemode/src/vm/runtime/extensions.ts +++ b/packages/codemode/src/vm/runtime/extensions.ts @@ -31,6 +31,18 @@ import { import { describeValue, isOpaque } from "./references.js" import { Push } from "./signals.js" import type { ExtensionRequest } from "../scheduler.js" +import { type HostOrigin, SnapshotError } from "../snapshot/codec.js" + +/** + * Where a value crossing from the host is: under an extension's global object (`root` undefined), whose functions are + * entry points that fire the hooks, or inside a value a function of an extension with `snapshot` hooks returned, at + * `path` (undefined inside a Map or a Set, where no path leads). + */ +type Within = { + readonly extension: Extension + readonly root: object | undefined + readonly path: ReadonlyArray | undefined +} /** * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in @@ -42,6 +54,9 @@ export const extensionGlobals = ( extensions: ReadonlyArray, ): ReadonlyArray => { const builtins = ctx.builtins + const byName = new Map(extensions.map((extension) => [extension.name, extension])) + // The program functions wrapping functions inside values a hooked extension returned, by where they came from. + const origins = new WeakMap() const toHost = (value: Value, label: string, depth = 0, seen = new Set()): unknown => { if (depth > MAX_VALUE_DEPTH) throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`) @@ -77,13 +92,23 @@ export const extensionGlobals = ( return copied } - // `extension` is set under an extension's global object, whose functions are entry points that fire the hooks. - const fromHost = (value: unknown, label: string, depth = 0, seen = new Set(), extension?: string): Value => { + // `within` says where the value is, so a function inside it fires the hooks, or can be saved; see `Within`. + const fromHost = (value: unknown, label: string, depth = 0, seen = new Set(), within?: Within): Value => { if (depth > MAX_VALUE_DEPTH) throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`) if (isPrimitive(value)) return value - if (typeof value === "function") return wrap(value, label, extension) + if (typeof value === "function") return wrap(value, label, within) if (value !== null && typeof value === "object") { - const next = (item: unknown, path: string) => fromHost(item, path, depth + 1, seen, extension) + const next = (item: unknown, path: string, key?: string | number) => + fromHost( + item, + path, + depth + 1, + seen, + within && { + ...within, + path: key === undefined || within.path === undefined ? undefined : [...within.path, key], + }, + ) // Nothing a host value hands back is kept: results are read as primitives or copied. Where the value's own // method could hand back host storage or an object (`getTime`, `slice`, `map`), its internal data is read. if (value instanceof Date) return new DateObj(builtins.Date, Date.prototype.getTime.call(value)) @@ -106,7 +131,7 @@ export const extensionGlobals = ( // Read once: a getter could pass the check and then hand back a function. const field = fields[key] if (typeof field === "function") continue - const item = crossing(() => next(field, `${label}.${key}`)) + const item = crossing(() => next(field, `${label}.${key}`, key)) if (item === left) continue define(copied, key, item, key === "cause" ? hidden : undefined) } @@ -138,7 +163,7 @@ export const extensionGlobals = ( // Filled in order so the copy stays a dense array; holes stay holes, as a copy made with `map` would leave them. const items: Array = [] for (let index = 0; index < length; index += 1) { - if (index in value) items[index] = next(value[index], `${label}[${index}]`) + if (index in value) items[index] = next(value[index], `${label}[${index}]`, index) } items.length = length seen.delete(value) @@ -147,7 +172,7 @@ export const extensionGlobals = ( const prototype = Object.getPrototypeOf(value) if (prototype === Object.prototype || prototype === null) { const copied = new Obj(builtins.Object) - for (const [key, item] of Object.entries(value)) define(copied, key, next(item, `${label}.${key}`)) + for (const [key, item] of Object.entries(value)) define(copied, key, next(item, `${label}.${key}`, key)) seen.delete(value) return copied } @@ -158,26 +183,77 @@ export const extensionGlobals = ( // A host function as a program function. Arguments cross in; for a global or a global object's function, the // `extension.before` hook runs before the host function is called, so a call it denies never reaches the host. The // host's result, or what it threw, crosses out so the program catches a copy, and `extension.after` sees how the - // call ended. Functions inside results are part of a value's API and skip the hooks. - const wrap = (value: Function, label: string, extension: string | undefined) => { + // call ended. Functions inside results are part of a value's API and skip the hooks; one inside a value an extension + // with `snapshot` hooks returned is known by where it came from, so a suspended run can save it. + const wrap = (value: Function, label: string, within: Within | undefined) => { // The host function's own `name` and `length` can be anything, even getters: each is read once, and only text // and a count cross. const name: unknown = value.name const length: unknown = value.length - return native(builtins, { + const extension = within?.extension.name + const root = within?.root + const wrapped = native(builtins, { runtime: "extension", name: typeof name === "string" ? name : "", length: typeof length === "number" && Number.isSafeInteger(length) && length >= 0 ? length : 0, call: (_, values, site) => { const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`)) - const invocation = extension === undefined ? undefined : { extension, name: label, args } + const invocation = + within !== undefined && root === undefined ? { extension: extension!, name: label, args } : undefined // A denied call fails the way the global would: an async global rejects its promise, a sync one throws. if (isAsync(value)) { - return pending(ctx, { stage: "run", label, invocation, host: value, args, threw: false }, site) + return pending(ctx, { stage: "run", label, extension, invocation, host: value, args, threw: false }, site) } - return new Push("extension call", [value, args, label, invocation]) + return new Push("extension call", [value, args, label, invocation, extension]) }, }) + if (root !== undefined && within!.path !== undefined) { + origins.set(wrapped, { extension: extension!, root, path: within!.path, label }) + } + return wrapped + } + + ctx.hosts = { + extensions: extensions.map((extension) => ({ name: extension.name, hooked: extension.snapshot !== undefined })), + origin: (value) => origins.get(value), + encode: (name, root) => hostStep(name, "save", () => hooks(name).encode(root)), + decode: (name, data) => { + const root = hostStep(name, "restore", () => hooks(name).decode(data)) + if ((typeof root !== "object" && typeof root !== "function") || root === null) { + throw new SnapshotError( + `The extension "${name}" restored a value it returned as ${typeof root}, not an object.`, + ) + } + return root + }, + rewrap: (target, origin) => { + const host = origin.path.reduce( + (at, key) => + (typeof at === "object" && at !== null) || typeof at === "function" + ? (at as { readonly [key: string | number]: unknown })[key] + : undefined, + origin.root, + ) + if (typeof host !== "function") { + throw new SnapshotError( + `The extension "${origin.extension}" restored a value with no function at ${origin.label}, so this state can't resume.`, + ) + } + const made = wrap(host, origin.label, { + extension: byName.get(origin.extension)!, + root: origin.root, + path: origin.path, + }) + // The restored function keeps its own properties; only what calling it does comes from the new one. + Object.assign(target, { tag: made.tag, call: made.call, construct: made.construct, callback: made.callback }) + origins.set(target, origin) + }, + } + + const hooks = (name: string) => { + const snapshot = byName.get(name)?.snapshot + if (snapshot === undefined) throw new SnapshotError(`The extension "${name}" has no snapshot hooks.`) + return snapshot } // The Effect each step of an extension call runs as, with the program's services in its requirements. @@ -189,9 +265,24 @@ export const extensionGlobals = ( const before = call && hooks["extension.before"]?.(call).pipe(Effect.mapError(cross)) if (request.stage === "before") return before ?? Effect.void const after = call && hooks["extension.after"] + const extension = request.extension === undefined ? undefined : byName.get(request.extension) + // What a function returns is a value of its extension's, which its `snapshot` hooks save, when it has them. const settle = (effect: Effect.Effect) => (after ? hooked(call, undefined, after, effect) : effect).pipe( - Effect.mapBoth({ onFailure: cross, onSuccess: (result) => fromHost(result, label) }), + Effect.mapBoth({ + onFailure: cross, + onSuccess: (result) => + fromHost( + result, + label, + 0, + new Set(), + extension?.snapshot !== undefined && + ((typeof result === "object" && result !== null) || typeof result === "function") + ? { extension, root: result, path: [] } + : undefined, + ), + }), ) if (request.stage === "settle") return settle(outcome(request.host, request.threw)) return Effect.andThen( @@ -202,7 +293,8 @@ export const extensionGlobals = ( return extensions.flatMap((extension) => Object.entries(extension.globals).map( - ([name, value]) => [name, fromHost(value, name, 0, new Set(), extension.name)] as const, + ([name, value]) => + [name, fromHost(value, name, 0, new Set(), { extension, root: undefined, path: undefined })] as const, ), ) } @@ -222,7 +314,7 @@ export const startExtensionCall = ( ctx: Interpreter, host: Function, args: ReadonlyArray, - call: Pick, + call: Pick, site: AstNode | undefined, ): PromiseObj | ExtensionRequest => { const [result, threw] = callHost(host, args) @@ -231,6 +323,18 @@ export const startExtensionCall = ( return request } +// Runs an extension's `snapshot` hook; what goes wrong is the state's problem, said as such. +const hostStep = (extension: string, what: "save" | "restore", step: () => A): A => { + try { + return step() + } catch (error) { + if (error instanceof SnapshotError) throw error + throw new SnapshotError( + `The extension "${extension}" couldn't ${what} a value it returned: ${error instanceof Error ? error.message : String(error)}`, + ) + } +} + /** Calls a host function: what it returned, or what it threw. */ const callHost = (value: Function, args: ReadonlyArray): [result: unknown, threw: boolean] => { try { diff --git a/packages/codemode/src/vm/runtime/interpreter.ts b/packages/codemode/src/vm/runtime/interpreter.ts index 03851cf64e3..8522a6e2b81 100644 --- a/packages/codemode/src/vm/runtime/interpreter.ts +++ b/packages/codemode/src/vm/runtime/interpreter.ts @@ -1,5 +1,6 @@ import type { ToolRuntime } from "../../tool-runtime.js" import type { ExtensionRequest } from "../scheduler.js" +import type { HostBridge } from "../snapshot/codec.js" import { Vm } from "../vm.js" import { globals } from "./globals.js" import type { Builtins } from "./intrinsics.js" @@ -24,6 +25,8 @@ export class Interpreter { readonly prelude: Prelude /** Makes the Effect an extension function's host work runs as; set by the extension bridge. */ extensionWork: ((request: ExtensionRequest) => unknown) | undefined + /** Saves and restores values returned by extensions with `snapshot` hooks; set by the extension bridge. */ + hosts: HostBridge | undefined /** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */ readonly sources = new Map() /** The global bindings: the intrinsics, the host's globals, and the program's bindings. */ diff --git a/packages/codemode/src/vm/scheduler.ts b/packages/codemode/src/vm/scheduler.ts index 6b24eb98179..9de0cddd576 100644 --- a/packages/codemode/src/vm/scheduler.ts +++ b/packages/codemode/src/vm/scheduler.ts @@ -84,6 +84,7 @@ export type HostRequest = export type ExtensionRequest = { readonly stage: "before" | "settle" | "run" readonly label: string + readonly extension?: string | undefined invocation: ExtensionInvocation | undefined host: unknown args: ReadonlyArray @@ -96,10 +97,19 @@ export type ExtensionRequest = { * later job; a blocking call stops the VM, and no other job runs until it ends. */ export class HostCall { - /** Where the call is: `queued` (written ahead, not started), `running`, or `completed`. */ - status: "queued" | "running" | "completed" = "queued" + /** + * Where the call is: `queued` (written ahead, not started), `running` (or in `start` for a durable tool), + * `started` (a durable tool whose `start` returned its `data`, now in `wait`), or `completed`. + */ + status: "queued" | "running" | "started" | "completed" = "queued" + /** The JSON data a durable tool's `start` returned, saved so a resumed run can call `wait(data)`. */ + data: Json | undefined = undefined + /** Whether a tool call has already been counted against `maxToolCalls` and recorded in `toolCalls`. */ + admitted = false constructor( readonly id: number, + /** The call's stable idempotency key, `:`. */ + readonly key: string, readonly request: HostRequest, /** What runs: a tool path, or an extension function's label. */ readonly label: string, diff --git a/packages/codemode/src/vm/snapshot.ts b/packages/codemode/src/vm/snapshot.ts index d4505b472d8..a61d0e920eb 100644 --- a/packages/codemode/src/vm/snapshot.ts +++ b/packages/codemode/src/vm/snapshot.ts @@ -62,7 +62,7 @@ const vmSpecs = (): ReadonlyArray => name: "HostCalls", ctor: HostCalls, anchor: "hosts", - fields: ["queued", "running", "inbox", "nextID", "blocked", "input"], + fields: ["runId", "queued", "running", "inbox", "nextID", "blocked", "input"], skip: ["ctx", "promises", "extension", "extensionResume"], }, { @@ -146,6 +146,7 @@ export const captureVm = ( }, lost, strict: options.strict, + hosts: ctx.hosts, specs: vmSpecs(), external: (value): Json | undefined => { if (value === HOLE) return "hole" @@ -160,6 +161,7 @@ export const captureVm = ( header: { build: buildId(), hosts: hostsId(ctx), + runId: vm.hosts.runId, sources: programs.map((source) => ({ id: source.id, code: source.code, @@ -215,6 +217,7 @@ export const restoreVm = (vm: Vm, saved: unknown, options: RestoreOptions): Snap anchor: (name) => anchors.get(name), node: (source, index) => sources.get(source)?.nodes[index], interruption: options.interruption, + hosts: ctx.hosts, specs: vmSpecs(), external: (data) => { if (data === "hole") return HOLE diff --git a/packages/codemode/src/vm/snapshot/codec.ts b/packages/codemode/src/vm/snapshot/codec.ts index d7f0058c80d..e799f9032e3 100644 --- a/packages/codemode/src/vm/snapshot/codec.ts +++ b/packages/codemode/src/vm/snapshot/codec.ts @@ -70,6 +70,33 @@ import { SnapshotError } from "../../suspend-error.js" export { SnapshotError } +/** + * Where a function inside a value an extension returned came from, so a saved state can name it instead of losing it: + * the extension, the value its function returned (`root`), which the extension's `snapshot` hooks save, and the path + * from there to the function. + */ +export type HostOrigin = { + readonly extension: string + readonly root: object + readonly path: ReadonlyArray + /** What the program calls it, for its errors (`fetch.text`). */ + readonly label: string +} + +/** The extension bridge's side of saving and restoring those functions; see `extensionGlobals`. */ +export type HostBridge = { + /** Each extension's name, and whether it has `snapshot` hooks: a state resumes only where both match. */ + readonly extensions: ReadonlyArray<{ readonly name: string; readonly hooked: boolean }> + /** Where a program function wrapping a host function came from, when its extension can save it. */ + readonly origin: (value: object) => HostOrigin | undefined + /** A returned value as its extension saves it. */ + readonly encode: (extension: string, root: object) => unknown + /** A returned value back from what `encode` gave. */ + readonly decode: (extension: string, data: unknown) => object + /** Makes `target`, a restored program function, call the host function `origin` leads to. */ + readonly rewrap: (target: Native, origin: HostOrigin) => void +} + /** What the encoder asks of the runtime whose state it saves. */ export type EncodeEnv = { /** The name of a built-in or host global object. */ @@ -82,6 +109,7 @@ export type EncodeEnv = { /** Values with no data form are reported here; strict encoding throws on the first instead. */ readonly lost: Array readonly strict: boolean + readonly hosts?: HostBridge | undefined /** More classes to save, an engine's own (the VM's frames and closures), after the built-in ones. */ readonly specs?: ReadonlyArray | undefined /** The data an engine names an object or symbol by, saved as `["x", data]`, instead of copying it. */ @@ -95,6 +123,7 @@ export type DecodeEnv = { readonly node: (source: string, index: number) => AstNode | undefined /** An `Interruption` (it holds an Effect cause, which this module does not make). */ readonly interruption: () => Interruption + readonly hosts?: HostBridge | undefined readonly specs?: ReadonlyArray | undefined /** What `EncodeEnv.external` named. */ readonly external?: ((data: Json) => unknown) | undefined @@ -221,7 +250,7 @@ const builtinSpecs = (): ReadonlyArray => [ { name: "HostCall", ctor: HostCall, - fields: ["status", "id", "request", "label", "blocking", "result", "resolving", "site"], + fields: ["status", "data", "admitted", "id", "key", "request", "label", "blocking", "result", "resolving", "site"], }, { name: "Resolving", ctor: Resolving, fields: ["done", "scheduler", "promise", "site"] }, { name: "Throw", ctor: Throw, fields: ["value"] }, @@ -235,7 +264,7 @@ const builtinSpecs = (): ReadonlyArray => [ ctor: Interpreter, anchor: "ctx", fields: ["logs", "globalScope", "modules", "namespaces"], - skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "sources", "prelude"], + skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "hosts", "sources", "prelude"], }, ] @@ -308,6 +337,8 @@ class Encoder { // A URL's `searchParams` is the same host object its URLSearchParams wraps; it is encoded once every URL is known. private readonly owners = new Map() private readonly params: Array = [] + // One `HostValue` record per value an extension returned, however many of its functions the state holds. + private readonly roots = new Map() private readonly specs: { readonly byCtor: Map; readonly byName: Map } constructor(private readonly env: EncodeEnv) { @@ -409,7 +440,14 @@ class Encoder { return { t: spec.name, ...this.fields(object, spec) } } if (object instanceof Native) { - // A host function made while the program ran, inside a value an extension returned: its name says what was lost. + // A host function made while the program ran: inside a value an extension returned. Its extension saves that + // value when it has `snapshot` hooks; otherwise its name says what was lost. + const origin = this.env.hosts?.origin(object) + if (origin !== undefined) { + const root = this.hostValue(origin.extension, origin.root) + const fields = this.fields(object, hostFunction, hostFunction.fields) + return { t: "HostFunction", e: origin.extension, h: root, k: [...origin.path], l: origin.label, ...fields } + } this.lose(`the function ${functionName(object)}`) return { t: "LostNative", ...this.fields(object, hostFunction, hostFunction.fields) } } @@ -440,6 +478,19 @@ class Encoder { return { t: "Lost", f: [what] } } + // A value an extension returned, as its `snapshot.encode` saves it: plain data, checked before it is copied. + private hostValue(extension: string, root: object): Encoded { + const known = this.roots.get(root) + if (known !== undefined) return known + const data = plainData(this.env.hosts!.encode(extension, root), extension, new Set()) + const id = this.records.length + const ref: Encoded = ["r", id] + this.roots.set(root, ref) + this.records.push(undefined) + this.records[id] = { t: "HostValue", e: extension, d: this.value(data) } + return ref + } + private lose(what: string): void { if (this.env.strict) throw new SnapshotError(`Codec gap: ${what} has no data form.`) this.env.lost.push(what) @@ -544,6 +595,10 @@ class Decoder { private readonly filled: Array // Derived state is rebuilt once every record is filled in, since it reads other records. private readonly resets: Array<() => void> = [] + // Functions inside values extensions returned, wrapped again once every record is filled in. + private readonly hostFunctions: Array = [] + // Those values, given back once each by their extension's `snapshot.decode`, by `HostValue` record. + private readonly hostValues = new Map() private readonly specs: { readonly byCtor: Map; readonly byName: Map } constructor( @@ -589,7 +644,10 @@ class Decoder { return named } case "LostNative": + case "HostFunction": return Object.create(Native.prototype) + case "HostValue": + return {} case "Interruption": return this.env.interruption() case "Error": { @@ -720,6 +778,11 @@ class Decoder { native.callback = true return } + case "HostFunction": + this.fillClass(target, record, hostFunction, false) + this.hostFunctions.push([target as unknown as Native, record]) + return + case "HostValue": case "Interruption": case "URL": case "URLSearchParams": @@ -759,6 +822,34 @@ class Decoder { finish(): void { for (const reset of this.resets) reset() + if (this.hostFunctions.length === 0) return + const hosts = + this.env.hosts ?? invalid("a function from an extension is saved, and this runtime has no extensions.") + for (const [target, record] of this.hostFunctions) { + const extension = text(record.e, "an extension") + const path = list(record.k, "a path").map((key) => + typeof key === "number" ? count(key, "a path index") : text(key, "a path key"), + ) + hosts.rewrap(target, { + extension, + root: this.hostValue(hosts, record.h, extension), + path, + label: text(record.l, "a label"), + }) + } + } + + // A value an extension returned, given back once by its `snapshot.decode` from the data it saved. + private hostValue(hosts: HostBridge, ref: unknown, extension: string): object { + const id = + Array.isArray(ref) && ref[0] === "r" ? count(ref[1], "a record id") : invalid("a host value is not a record.") + const known = this.hostValues.get(id) + if (known !== undefined) return known + const record = id < this.records.length ? this.at(id) : invalid(`record ${id} does not exist.`) + if (record.t !== "HostValue" || record.e !== extension) invalid(`record ${id} is not a value of ${extension}.`) + const root = hosts.decode(extension, this.value(record.d)) + this.hostValues.set(id, root) + return root } // An object's prototype, extensibility, and properties. A named object's accessors stay the ones it was made with. @@ -849,6 +940,42 @@ class Decoder { } } +// What an extension's `snapshot.encode` gives must be plain data the codec copies and hands back to `decode`: JSON +// values and Uint8Arrays. Views (such as a `Buffer` slice on a shared slab) are copied into standalone `Uint8Array`s. +const plainData = (data: unknown, extension: string, seen: Set): unknown => { + if (data === null || typeof data === "string" || typeof data === "boolean") return data + if (typeof data === "number" && Number.isFinite(data)) return data + if (data instanceof Uint8Array) { + return data.constructor === Uint8Array && data.byteOffset === 0 && data.byteLength === data.buffer.byteLength + ? data + : new Uint8Array(data) + } + const fail = (what: string): never => { + throw new SnapshotError( + `The extension "${extension}" saved a value it returned as data holding ${what}; snapshot.encode must give plain data (JSON values and Uint8Arrays).`, + ) + } + if (typeof data !== "object") { + return fail(data === undefined ? "undefined" : typeof data === "number" ? String(data) : `a ${typeof data}`) + } + if (seen.has(data)) return fail("a circular reference") + const proto = Object.getPrototypeOf(data) + if (!Array.isArray(data) && proto !== Object.prototype && proto !== null) { + const name = (data as { constructor?: { name?: string } }).constructor?.name ?? "object" + return fail(`${/^[AEIOU]/.test(name) ? "an" : "a"} ${name}`) + } + seen.add(data) + if (Array.isArray(data)) { + const out = data.map((item) => plainData(item, extension, seen)) + seen.delete(data) + return out + } + const out: { [key: string]: unknown } = proto === null ? Object.create(null) : {} + for (const [key, item] of Object.entries(data)) out[key] = plainData(item, extension, seen) + seen.delete(data) + return out +} + const functionName = (fn: Obj): string => { const slot = fn.props.get("name") return slot !== undefined && "value" in slot && typeof slot.value === "string" && slot.value !== "" diff --git a/packages/codemode/src/vm/snapshot/snapshot.ts b/packages/codemode/src/vm/snapshot/snapshot.ts index f7c4d4efe94..c3bc644d417 100644 --- a/packages/codemode/src/vm/snapshot/snapshot.ts +++ b/packages/codemode/src/vm/snapshot/snapshot.ts @@ -23,8 +23,12 @@ export type Snapshot = { export type Header = { /** The build that wrote it: the package version, and a hash of the opcodes, the prelude's bytecode, codecs, and built-ins. */ readonly build: string - /** A hash of the host's globals (extensions, a test harness), which the restoring runtime must have too. */ + /** + * A hash of the host's globals (extensions, a test harness), and of each extension's name and whether it has + * `snapshot` hooks, which the restoring runtime must have too. + */ readonly hosts: string + readonly runId: string /** The program texts, re-parsed and recompiled on restore, and checked against their hashes and bytecode hashes. */ readonly sources: ReadonlyArray<{ readonly id: string @@ -45,7 +49,15 @@ export type Header = { export type SnapshotHeader = Header -export const hostsId = (ctx: Interpreter): string => hash(ctx.intrinsics.hosts().join("\n")) +export const hostsId = (ctx: Interpreter): string => + hash( + [ + ...ctx.intrinsics.hosts(), + ...(ctx.hosts?.extensions ?? []).map( + (extension) => `${extension.name} ${extension.hooked ? "hooks" : "no hooks"}`, + ), + ].join("\n"), + ) // --- Validation --- @@ -82,6 +94,7 @@ export const validate = (saved: unknown): Snapshot => { 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 { diff --git a/packages/codemode/src/vm/vm.ts b/packages/codemode/src/vm/vm.ts index f274c2966c9..de0842903b7 100644 --- a/packages/codemode/src/vm/vm.ts +++ b/packages/codemode/src/vm/vm.ts @@ -430,7 +430,7 @@ export class Vm { * A synchronous extension call the program is in the middle of, from its `before` hook until its result is a * program value or its concurrent call is running: it holds live host values. */ - get activeExtension(): { readonly path: string } | undefined { + get activeExtension(): { readonly key: string; readonly path: string } | undefined { return this.hosts.extension } diff --git a/packages/codemode/test/codemode.test.ts b/packages/codemode/test/codemode.test.ts index 8392ccf2376..86469953740 100644 --- a/packages/codemode/test/codemode.test.ts +++ b/packages/codemode/test/codemode.test.ts @@ -167,7 +167,8 @@ describe("CodeMode call hooks", () => { } // Every hook logs its event, so the order across tools and extensions is visible. const observe = (events: Array): CodeMode.Hooks => ({ - "tool.before": (call) => Effect.sync(() => void events.push(`tool.before ${JSON.stringify(call)}`)), + "tool.before": (call) => + Effect.sync(() => void events.push(`tool.before ${JSON.stringify({ name: call.name, input: call.input })}`)), "tool.after": (call, result) => Effect.sync(() => void events.push(`tool.after ${call.name} ${ended(result)}`)), "extension.before": (call) => Effect.sync(() => void events.push(`extension.before ${JSON.stringify(call)}`)), "extension.after": (call, result) => @@ -928,7 +929,7 @@ describe("CodeMode public contract", () => { const result = await Effect.runPromise(limited.execute(`search({}); return search({})`)) expect(result.ok).toBe(false) if (!result.ok) expect(result.error.kind).toBe("ToolCallLimitExceeded") - expect(observed).toEqual([{ name: "search", input: {} }]) + expect(observed).toEqual([{ name: "search", input: {}, key: expect.any(String) }]) }) test("search is an opaque, shadowable global like other built-ins", async () => { diff --git a/packages/codemode/test/vm/suspend.test.ts b/packages/codemode/test/vm/suspend.test.ts index cb4e7d55445..3197ccdceac 100644 --- a/packages/codemode/test/vm/suspend.test.ts +++ b/packages/codemode/test/vm/suspend.test.ts @@ -1,7 +1,7 @@ import { describe, expect, test } from "bun:test" import { tmpdir } from "node:os" import path from "node:path" -import { Effect, Fiber, Schema } from "effect" +import { Context, Effect, Fiber, Schema } from "effect" import { CodeMode, Extension, Tool } from "../../src/index.js" // Suspending a run, saving its state, and resuming it in a brand-new runtime. @@ -38,11 +38,9 @@ const manual = () => { input: Value, output: Value, execute: (input) => - Effect.promise(() => { - const answer = latch() - calls.push({ input: input.value, answer: answer.resolve }) + Effect.callback<{ value: number }>((resume) => { + calls.push({ input: input.value, answer: (value) => resume(Effect.succeed({ value })) }) called.resolve() - return answer.promise.then((value) => ({ value })) }), }) return { @@ -77,6 +75,96 @@ const stepTool = () => { } } +/** An idempotent tool that announces each attempt and waits for the test to answer it. */ +const idempotentManual = () => { + const attempts: Array<{ + input: number + key: string + interrupted: boolean + answer: (value: number) => void + }> = [] + let called = latch() + const tool = Tool.make({ + description: "Safe to rerun", + input: Value, + output: Value, + execute: Tool.idempotent((input, { key }) => + Effect.callback<{ value: number }>((resume) => { + const entry = { + input: input.value, + key, + interrupted: false, + answer: (value: number) => resume(Effect.succeed({ value })), + } + attempts.push(entry) + called.resolve() + return Effect.sync(() => { + entry.interrupted = true + }) + }), + ), + }) + return { + tool, + attempts, + called: () => called.promise, + reset: () => { + called = latch() + }, + } +} + +/** A durable tool over an in-memory job table that outlives any one run, as a subagent or job supervisor would. */ +const durableJobs = (options: { startGate?: Promise } = {}) => { + const jobs = new Map< + string, + { input: number; result: ReturnType>; cancelled: number; savedData: Array } + >() + const log: Array = [] + let started = latch() + let waiting = latch() + const tool = Tool.make({ + description: "Runs a durable job", + input: Value, + output: Value, + execute: Tool.durable({ + start: (input, { key }) => + Effect.gen(function* () { + log.push(`start ${key}`) + jobs.set(key, { input: input.value, result: latch(), cancelled: 0, savedData: [] }) + started.resolve() + if (options.startGate !== undefined) yield* Effect.promise(() => options.startGate!) + return { job: key, meta: { input: input.value, tags: ["a", "b"] } } + }), + wait: (data, { key }) => + Effect.promise(() => { + log.push(`wait ${key} ${data.job}`) + const job = jobs.get(data.job)! + job.savedData.push(data) + waiting.resolve() + return job.result.promise.then((value) => ({ value })) + }), + cancel: ({ job }) => + Effect.sync(() => { + log.push(`cancel ${job}`) + jobs.get(job)!.cancelled += 1 + }), + }), + }) + return { + tool, + jobs, + log, + started: () => started.promise, + waiting: () => waiting.promise, + finish: (key: string, value: number) => jobs.get(key)!.result.resolve(value), + reset: () => { + started = latch() + waiting = latch() + }, + } +} + const suspendedOf = (outcome: CodeMode.Result | CodeMode.Suspended): CodeMode.Suspended => { if (outcome.ok !== "suspended") throw new Error(`expected a suspended run, got ${JSON.stringify(outcome)}`) return outcome @@ -260,11 +348,11 @@ describe("suspend", () => { ], ] for (const [name, code, running, release, path, value] of cases) { - const run = background(runtime.program(code)) + const run = background(runtime.program(code, undefined, { runId: "b" })) await running() const error = await blocked(run) expect(error, name).toBeInstanceOf(CodeMode.SuspendError) - expect(error.running, name).toEqual([{ path }]) + expect(error.running, name).toEqual([{ key: "b:0", path }]) expect(error.message, name).toBe(`The run can't be suspended while ${path} is running.`) release() expect(await Effect.runPromise(run.result), name).toMatchObject({ ok: true, value }) @@ -276,10 +364,15 @@ describe("suspend", () => { const run = background( CodeMode.make({ engine: "vm", tools: { slow: slow.tool, "a-b": { work: slow.tool } } }).program( `return await Promise.all([tools["a-b"].work({ value: 1 }), tools.slow({ value: 2 })])`, + undefined, + { runId: "n" }, ), ) while (slow.calls.length < 2) await Bun.sleep(1) - expect((await blocked(run)).running).toEqual([{ path: 'tools["a-b"].work' }, { path: "tools.slow" }]) + expect((await blocked(run)).running).toEqual([ + { key: "n:0", path: 'tools["a-b"].work' }, + { key: "n:1", path: "tools.slow" }, + ]) }) test("a suspend after the run ended gives its result", async () => { @@ -633,3 +726,871 @@ describe("resume", () => { }) }) }) + +describe("idempotent and durable tools", () => { + test("an idempotent tool in flight can be suspended, is interrupted without firing after, and reruns on resume with the same key", async () => { + const read = idempotentManual() + const events: Array = [] + const hooks: CodeMode.Hooks = { + "tool.before": (call) => Effect.sync(() => void events.push(`before ${call.name} ${call.key}`)), + "tool.after": (call, result) => + Effect.sync(() => void events.push(`after ${call.name} ${call.key} ${result.status}`)), + } + const code = ` + const a = await tools.read({ value: 20 }) + const b = await tools.read({ value: 22 }) + return a.value + b.value` + const run = background( + CodeMode.make({ engine: "vm", tools: { read: read.tool }, hooks }).program(code, undefined, { runId: "rr" }), + ) + await read.called() + expect(read.attempts).toHaveLength(1) + expect(read.attempts[0]!.key).toBe("rr:0") + + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(suspendedOf(await Effect.runPromise(run.result))).toBe(suspended) + expect(read.attempts[0]!.interrupted).toBe(true) + // Detaching to suspend does not fire tool.after with interrupted. + expect(events).toEqual(["before read rr:0"]) + + read.reset() + const resumed = background( + CodeMode.make({ engine: "vm", tools: { read: read.tool }, hooks }).resume(CodeMode.toBytes(suspended.state)), + ) + await read.called() + expect(read.attempts).toHaveLength(2) + expect(read.attempts[1]!.key).toBe("rr:0") + + read.reset() + read.attempts[1]!.answer(20) + await read.called() + expect(read.attempts[2]!.key).toBe("rr:1") + read.attempts[2]!.answer(22) + + const outcome = await Effect.runPromise(resumed.result) + expect(outcome).toEqual({ + ok: true, + value: 42, + toolCalls: [{ name: "read" }, { name: "read" }], + }) + expect(events).toEqual([ + "before read rr:0", + "before read rr:0", + "after read rr:0 success", + "before read rr:1", + "after read rr:1 success", + ]) + }) + + test("maxToolCalls is not double-counted when an idempotent call runs again on resume", async () => { + const read = idempotentManual() + const runtime = () => + CodeMode.make({ + engine: "vm", + tools: { read: read.tool }, + limits: { maxToolCalls: 1 }, + }) + const run = background( + runtime().program(`return (await tools.read({ value: 7 })).value`, undefined, { runId: "lim" }), + ) + await read.called() + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(suspended.state.header.budget.toolCalls).toBe(1) + + read.reset() + const resumed = background(runtime().resume(CodeMode.toBytes(suspended.state))) + await read.called() + read.attempts[1]!.answer(7) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: 7, + toolCalls: [{ name: "read" }], + }) + + // A second call after the idempotent call completes still trips the limit of 1. + read.reset() + const twoCalls = background( + runtime().program( + `const first = await tools.read({ value: 1 }); const second = await tools.read({ value: 2 }); return first.value + second.value`, + undefined, + { runId: "lim2" }, + ), + ) + await read.called() + const suspendedTwo = suspendedOf(await Effect.runPromise(twoCalls.suspend)) + read.reset() + const resumedTwo = background(runtime().resume(CodeMode.toBytes(suspendedTwo.state))) + await read.called() + read.attempts[read.attempts.length - 1]!.answer(1) + expect(await Effect.runPromise(resumedTwo.result)).toMatchObject({ + ok: false, + error: { kind: "ToolCallLimitExceeded" }, + toolCalls: [{ name: "read" }], + }) + }) + + test("a durable tool refuses suspend during start, allows it once started, and calls wait(data) on resume", async () => { + const gate = latch() + const jobs = durableJobs({ startGate: gate.promise }) + const events: Array = [] + const hooks: CodeMode.Hooks = { + "tool.before": (call) => Effect.sync(() => void events.push(`before ${call.key}`)), + "tool.after": (call, result) => Effect.sync(() => void events.push(`after ${call.key} ${result.status}`)), + } + const code = ` + const log = ["before"] + const a = await tools.job({ value: 41 }) + log.push("after " + a.value) + return { log, total: a.value + 1 }` + const run = background( + CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, hooks }).program(code, undefined, { runId: "rec" }), + ) + await jobs.started() + const duringStart = await blocked(run) + expect(duringStart.running).toEqual([{ key: "rec:0", path: "tools.job" }]) + + gate.resolve() + await jobs.waiting() + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(suspendedOf(await Effect.runPromise(run.result))).toBe(suspended) + expect(jobs.jobs.get("rec:0")!.cancelled).toBe(0) + expect(events).toEqual(["before rec:0"]) + + jobs.reset() + const bytes = CodeMode.toBytes(suspended.state) + const resumed = background(CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, hooks }).resume(bytes)) + await jobs.waiting() + // The data survived serialization to bytes and was passed to wait(data) without running start again. + expect(jobs.log).toEqual(["start rec:0", "wait rec:0 rec:0", "wait rec:0 rec:0"]) + expect(jobs.jobs.get("rec:0")!.savedData).toEqual([ + { job: "rec:0", meta: { input: 41, tags: ["a", "b"] } }, + { job: "rec:0", meta: { input: 41, tags: ["a", "b"] } }, + ]) + jobs.finish("rec:0", 41) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: { log: ["before", "after 41"], total: 42 }, + toolCalls: [{ name: "job" }], + }) + expect(events).toEqual(["before rec:0", "after rec:0 success"]) + }) + + test("wait runs right after start and right at resume regardless of how the program uses the promise", async () => { + const jobs = durableJobs() + const read = idempotentManual() + const tools = { job: jobs.tool, read: read.tool } + // One durable call is in Promise.all with another call, one is chained with .then, and one is stored + // unawaited in a variable and only awaited after the others settle on resume. + const code = ` + const stored = tools.job({ value: 1 }) + const chained = tools.job({ value: 2 }).then((res) => res.value * 10) + const [allJob, allRead] = await Promise.all([tools.job({ value: 3 }), tools.read({ value: 4 })]) + const chainedValue = await chained + const storedValue = (await stored).value + return [storedValue, chainedValue, allJob.value, allRead.value]` + const run = background(CodeMode.make({ engine: "vm", tools }).program(code, undefined, { runId: "p" })) + await read.called() + // All three durable calls ran start and wait before the suspend, even though `stored` has not been awaited. + expect(jobs.log).toEqual(["start p:0", "wait p:0 p:0", "start p:1", "wait p:1 p:1", "start p:2", "wait p:2 p:2"]) + + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + read.reset() + jobs.reset() + const resumed = background(CodeMode.make({ engine: "vm", tools }).resume(CodeMode.toBytes(suspended.state))) + await read.called() + // Right at resume, the VM calls wait(data) on all three `started` calls before any of them settles. + expect(jobs.log.slice(6)).toEqual(["wait p:0 p:0", "wait p:1 p:1", "wait p:2 p:2"]) + + // Even if the unawaited `stored` job finishes first on resume, its result waits on the promise until awaited later. + jobs.finish("p:0", 10) + jobs.finish("p:1", 2) + jobs.finish("p:2", 30) + read.attempts[1]!.answer(40) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: [10, 20, 30, 40], + toolCalls: [{ name: "job" }, { name: "job" }, { name: "job" }, { name: "read" }], + }) + }) + + test("a durable tool calls cancel(data) on a real interrupt, not on suspend", async () => { + const jobs = durableJobs() + const events: Array = [] + const hooks: CodeMode.Hooks = { + "tool.after": (call, result) => Effect.sync(() => void events.push(`${call.key} ${result.status}`)), + } + const runtime = CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, hooks }) + + // 1. Background work left running when the program returns is interrupted and cancelled once. + const leftRunning = background( + runtime.program(`tools.job({ value: 1 }); return "left"`, undefined, { runId: "c1" }), + ) + expect(await Effect.runPromise(leftRunning.result)).toMatchObject({ ok: true, value: "left" }) + expect(jobs.jobs.get("c1:0")!.cancelled).toBe(1) + expect(events).toEqual(["c1:0 interrupted"]) + + // 2. Interrupting the running fiber cancels the started job once. + jobs.reset() + const program = runtime.program(`return (await tools.job({ value: 2 })).value`, undefined, { runId: "c2" }) + const fiber = Effect.runFork(program.run()) + await jobs.waiting() + await Effect.runPromise(Fiber.interrupt(fiber)) + expect(jobs.jobs.get("c2:0")!.cancelled).toBe(1) + expect(events).toEqual(["c1:0 interrupted", "c2:0 interrupted"]) + + // 3. Suspending does not cancel, and interrupting after resume cancels. + jobs.reset() + const run = background(runtime.program(`return (await tools.job({ value: 3 })).value`, undefined, { runId: "c3" })) + await jobs.waiting() + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(jobs.jobs.get("c3:0")!.cancelled).toBe(0) + + jobs.reset() + const resumedProgram = runtime.resume(CodeMode.toBytes(suspended.state)) + const resumedFiber = Effect.runFork(resumedProgram.run()) + await jobs.waiting() + await Effect.runPromise(Fiber.interrupt(resumedFiber)) + expect(jobs.jobs.get("c3:0")!.cancelled).toBe(1) + }) + + test("a Promise.all combining plain, idempotent, and durable tools suspends once safe and finishes on resume", async () => { + const slow = manual() + const read = idempotentManual() + const jobs = durableJobs() + const tools = { slow: slow.tool, read: read.tool, job: jobs.tool } + const code = ` + const [a, b, c] = await Promise.all([ + tools.slow({ value: 10 }), + tools.read({ value: 20 }), + tools.job({ value: 30 }), + ]) + return [a.value, b.value, c.value]` + const run = background(CodeMode.make({ engine: "vm", tools }).program(code, undefined, { runId: "mix" })) + await Promise.all([slow.called(), read.called(), jobs.waiting()]) + + // While `slow` (plain) is still running, suspend is refused and lists only `tools.slow`. + const error = await blocked(run) + expect(error.running).toEqual([{ key: "mix:0", path: "tools.slow" }]) + + // Once `slow` finishes, only `read` (idempotent) and `job` (durable in started) remain in flight. + slow.calls[0]!.answer(10) + await Promise.resolve() + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(read.attempts[0]!.interrupted).toBe(true) + expect(jobs.jobs.get("mix:2")!.cancelled).toBe(0) + + read.reset() + jobs.reset() + const resumed = background(CodeMode.make({ engine: "vm", tools }).resume(CodeMode.toBytes(suspended.state))) + await Promise.all([read.called(), jobs.waiting()]) + // `slow` was not called again; `read` reran with key `mix:1`; `job` waited on data `mix:2`. + expect(slow.calls).toHaveLength(1) + expect(read.attempts.map((a) => a.key)).toEqual(["mix:1", "mix:1"]) + expect(jobs.log).toEqual(["start mix:2", "wait mix:2 mix:2", "wait mix:2 mix:2"]) + + read.attempts[1]!.answer(20) + jobs.finish("mix:2", 30) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: [10, 20, 30], + toolCalls: [{ name: "slow" }, { name: "read" }, { name: "job" }], + }) + }) + + test("call keys use runId (or a generated UUID), are unique per call, and stay stable across suspend and resume", async () => { + const read = idempotentManual() + const seenKeys: Array = [] + const echo = Tool.make({ + description: "Echoes key", + input: Value, + output: Schema.String, + execute: (_, { key }) => Effect.succeed(key), + }) + const runtime = CodeMode.make({ + engine: "vm", + tools: { read: read.tool, echo }, + hooks: { + "tool.before": (call) => Effect.sync(() => void seenKeys.push(`hook:${call.name}:${call.key}`)), + }, + }) + const code = ` + const k0 = await tools.echo({ value: 1 }) + const v1 = await tools.read({ value: 2 }) + const k2 = await tools.echo({ value: v1.value }) + return [k0, v1.value, k2]` + const run = background(runtime.program(code, undefined, { runId: "custom-run" })) + await read.called() + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(suspended.state.header.runId).toBe("custom-run") + + read.reset() + const resumed = background(runtime.resume(CodeMode.toBytes(suspended.state))) + await read.called() + read.attempts[1]!.answer(42) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: ["custom-run:0", 42, "custom-run:2"], + toolCalls: [{ name: "echo" }, { name: "read" }, { name: "echo" }], + }) + expect(seenKeys).toEqual([ + "hook:echo:custom-run:0", + "hook:read:custom-run:1", + "hook:read:custom-run:1", + "hook:echo:custom-run:2", + ]) + + // Without an explicit runId, a generated UUID prefixes every key. + const auto = await Effect.runPromise(runtime.program(`return await tools.echo({ value: 1 })`).run()) + expect(auto).toMatchObject({ ok: true, value: expect.stringMatching(/^[0-9a-f-]{36}:0$/) }) + }) + + test("Tool.idempotent and Tool.durable infer input from schema, data from start, union services across start/wait/cancel, and check output", async () => { + class StartService extends Context.Service()("test/StartService") {} + class WaitService extends Context.Service()("test/WaitService") {} + class CancelService extends Context.Service void }>()( + "test/CancelService", + ) {} + + const idempotentTyped = Tool.make({ + description: "Typed idempotent tool", + input: Schema.Struct({ name: Schema.String }), + output: Schema.String, + execute: Tool.idempotent((input, { key }) => { + const checkName: string = input.name + // @ts-expect-error input is strictly typed from input schema, not any + void input.nonexistent + return Effect.succeed(`${checkName}:${key}`) + }), + }) + + const durableTyped = Tool.make({ + description: "Typed durable tool", + input: Schema.Struct({ name: Schema.String, count: Schema.Number }), + output: Schema.Struct({ label: Schema.String }), + execute: Tool.durable({ + start: (input, { key }) => + Effect.gen(function* () { + const svc = yield* StartService + const checkName: string = input.name + // @ts-expect-error input is strictly typed from input schema, not any + void input.nonexistent + return { jobId: `${svc.prefix}:${checkName}:${key}`, attempts: input.count } + }), + wait: (data, { key }) => + Effect.gen(function* () { + const svc = yield* WaitService + const checkJobId: string = data.jobId + const checkAttempts: number = data.attempts * svc.multiplier + // @ts-expect-error wait receives start's exact data shape + void data.nonexistent + return { label: `${checkJobId}:${checkAttempts}:${key}` } + }), + cancel: (data) => + Effect.gen(function* () { + const svc = yield* CancelService + const checkJobId: string = data.jobId + // @ts-expect-error cancel receives start's exact data shape + void data.nonexistent + svc.onCancel(checkJobId) + }), + }), + }) + Tool.make({ + description: "Mismatched output", + input: Value, + output: Value, + // @ts-expect-error wait output is checked against the tool's output schema + execute: Tool.durable({ + start: () => Effect.succeed({ id: "1" }), + wait: ({ id }) => Effect.succeed({ wrong: id }), + cancel: () => Effect.void, + }), + }) + expect(idempotentTyped._tag).toBe("CodeModeTool") + expect(durableTyped._tag).toBe("CodeModeTool") + + const runtime = CodeMode.make({ + engine: "vm", + tools: { idem: idempotentTyped, dur: durableTyped }, + }) + const result = await Effect.runPromise( + runtime + .program( + `return [await tools.idem({ name: "a" }), (await tools.dur({ name: "b", count: 3 })).label]`, + undefined, + { runId: "svc" }, + ) + .run() + .pipe( + Effect.provideService(StartService, { prefix: "p" }), + Effect.provideService(WaitService, { multiplier: 10 }), + Effect.provideService(CancelService, { onCancel: () => {} }), + ), + ) + expect(result).toEqual({ + ok: true, + value: ["a:svc:0", "p:b:svc:1:30:svc:1"], + toolCalls: [{ name: "idem" }, { name: "dur" }], + }) + }) + + test("suspending a resumed program before run() starts waits for driver.resume() and leaves nothing running", async () => { + const read = idempotentManual() + const runtime = CodeMode.make({ engine: "vm", tools: { read: read.tool } }) + const initial = background( + runtime.program(`return (await tools.read({ value: 5 })).value`, undefined, { runId: "sr" }), + ) + await read.called() + const firstSuspended = suspendedOf(await Effect.runPromise(initial.suspend)) + + // Re-suspend the resumed program immediately from another fiber before run() begins. + read.reset() + const secondSuspended = suspendedOf( + await Effect.runPromise( + Effect.gen(function* () { + const resumed = runtime.resume(CodeMode.toBytes(firstSuspended.state)) + const fiber = yield* Effect.forkChild(resumed.run()) + const suspended = yield* resumed.suspend() + expect(yield* Fiber.join(fiber)).toBe(suspended) + return suspended + }), + ), + ) + // If driver.resume() launched the idempotent call, suspending detached and interrupted it. + for (const attempt of read.attempts) expect(attempt.interrupted).toBe(true) + + read.reset() + const finalRun = background(runtime.resume(CodeMode.toBytes(secondSuspended.state))) + await read.called() + read.attempts[read.attempts.length - 1]!.answer(5) + expect(await Effect.runPromise(finalRun.result)).toEqual({ + ok: true, + value: 5, + toolCalls: [{ name: "read" }], + }) + }) + + test("a detached idempotent or durable call that settles at a slice before interruption does not fire tool.after twice", async () => { + const afterEvents: Array = [] + let resolveIdem!: (value: number) => void + let idemCalled = latch() + const idem = Tool.make({ + description: "Idempotent settling on detach", + input: Value, + output: Value, + execute: Tool.idempotent((input) => + Effect.promise(() => { + idemCalled.resolve() + return new Promise((r) => { + resolveIdem = r + }).then((v) => ({ value: v + input.value })) + }), + ), + }) + const runtime = CodeMode.make({ + engine: "vm", + tools: { idem }, + hooks: { + "tool.after": (call, res) => Effect.sync(() => void afterEvents.push(`${call.key}:${res.status}`)), + }, + }) + // Run a busy loop alongside the in-flight idempotent call so suspend lands at a slice. + const code = ` + const p = tools.idem({ value: 1 }) + const started = Date.now() + while (Date.now() - started < 300) {} + return (await p).value` + const run = background(runtime.program(code, undefined, { runId: "sl" })) + await idemCalled.promise + // Resolve the underlying promise right as suspend detaches, so the fiber settles with success while detaching. + const suspendPromise = Effect.runPromise(run.suspend) + resolveIdem(41) + const suspended = suspendedOf(await suspendPromise) + expect(afterEvents).toEqual([]) + + idemCalled = latch() + const resumed = background(runtime.resume(CodeMode.toBytes(suspended.state))) + await idemCalled.promise + resolveIdem(41) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: 42, + toolCalls: [{ name: "idem" }], + }) + expect(afterEvents).toEqual(["sl:0:success"]) + }) + + test("invalid start JSON and wait failures fire tool.after with failure", async () => { + // 1. Non-JSON data returned from start fires tool.after with failure. + const badStartEvents: Array = [] + const badStart = Tool.make({ + description: "Bad start data", + input: Value, + output: Value, + execute: Tool.durable({ + start: () => { + const circular: Record = {} + circular.self = circular + return Effect.succeed(circular as unknown as CodeMode.DataValue) + }, + wait: () => Effect.succeed({ value: 1 }), + cancel: () => Effect.void, + }), + }) + const badOutcome = await Effect.runPromise( + CodeMode.make({ + engine: "vm", + tools: { bad: badStart }, + hooks: { + "tool.after": (call, res) => Effect.sync(() => void badStartEvents.push(`${call.key}:${res.status}`)), + }, + }) + .program(`return await tools.bad({ value: 1 })`, undefined, { runId: "bad" }) + .run(), + ) + expect(badOutcome).toMatchObject({ ok: false, error: { kind: "InvalidToolOutput" } }) + expect(badStartEvents).toEqual(["bad:0:failure"]) + + // 2. A failing wait rejects the call's promise with a catchable ToolError and fires tool.after with failure. + const waitEvents: Array = [] + const failingWait = Tool.make({ + description: "Failing wait", + input: Value, + output: Value, + execute: Tool.durable({ + start: (input, { key }) => Effect.succeed({ key, v: input.value }), + wait: ({ key }) => Effect.fail(new Error(`wait boom ${key}`)), + cancel: () => Effect.void, + }), + }) + const caughtWait = await Effect.runPromise( + CodeMode.make({ + engine: "vm", + tools: { failWait: failingWait }, + hooks: { + "tool.after": (call, res) => Effect.sync(() => void waitEvents.push(`${call.key}:${res.status}`)), + }, + }) + .program( + `try { return await tools.failWait({ value: 1 }) } catch (e) { return [e.name, e.message] }`, + undefined, + { runId: "wf" }, + ) + .run(), + ) + expect(caughtWait).toEqual({ + ok: true, + value: ["Error", "wait boom wf:0"], + toolCalls: [{ name: "failWait" }], + }) + expect(waitEvents).toEqual(["wf:0:failure"]) + }) + + test("resuming a started durable call fails with SnapshotError when the tool was removed or is no longer durable, and completed calls clear their data", async () => { + const jobs = durableJobs() + const read = idempotentManual() + const runtime = CodeMode.make({ engine: "vm", tools: { job: jobs.tool, read: read.tool } }) + const run = background( + runtime.program( + `const first = await tools.job({ value: 1 }); const second = await tools.read({ value: 2 }); return first.value + second.value`, + undefined, + { runId: "chg" }, + ), + ) + await jobs.waiting() + const suspendedWhileStarted = suspendedOf(await Effect.runPromise(run.suspend)) + + // Removing the tool or changing it to plain/idempotent refuses resume with SnapshotError. + const plainTool = Tool.make({ + description: "Plain", + input: Value, + output: Value, + execute: (input) => Effect.succeed(input), + }) + const toolSets: ReadonlyArray> = [{}, { job: plainTool }, { job: read.tool }] + for (const tools of toolSets) { + expect( + (await refusal(CodeMode.make({ engine: "vm", tools }).resume(suspendedWhileStarted.state))).message, + ).toContain("cannot resume because that tool is no longer a durable tool") + } + + // Complete `job` while `read` is still running: `job` moves to the inbox with its `data` cleared. + const jobs2 = durableJobs() + const read2 = idempotentManual() + const run2 = background( + CodeMode.make({ engine: "vm", tools: { job: jobs2.tool, read: read2.tool } }).program( + `const [a, b] = await Promise.all([tools.job({ value: 1 }), tools.read({ value: 2 })]); return a.value + b.value`, + undefined, + { runId: "chg2" }, + ), + ) + await Promise.all([jobs2.waiting(), read2.called()]) + jobs2.finish("chg2:0", 10) + await Bun.sleep(10) + const suspendedAfterJob = suspendedOf(await Effect.runPromise(run2.suspend)) + expect(JSON.stringify(suspendedAfterJob.state)).not.toContain('"tags"') + read2.reset() + const resumedAfterJob = background( + CodeMode.make({ engine: "vm", tools: { job: jobs2.tool, read: read2.tool } }).resume(suspendedAfterJob.state), + ) + await read2.called() + read2.attempts[1]!.answer(20) + expect(await Effect.runPromise(resumedAfterJob.result)).toEqual({ + ok: true, + value: 30, + toolCalls: [{ name: "job" }, { name: "read" }], + }) + }) +}) + +describe("extension snapshot hooks", () => { + type Saved = { + readonly url: string + readonly status: number + readonly headers: ReadonlyArray + readonly body: Uint8Array + } + const savedSymbol = Symbol("saved") + + /** A fetch-like extension whose resolved responses save and restore their methods through `snapshot` hooks. */ + const web = (snapshot: Partial = {}) => { + const counts = { encode: 0, decode: 0 } + const makeResponse = (saved: Saved) => { + const headers = Object.fromEntries(saved.headers) + const text = () => new TextDecoder().decode(saved.body) + return { + [savedSymbol]: saved, + url: saved.url, + status: saved.status, + ok: saved.status >= 200 && saved.status <= 299, + headers: { + get: (name: string) => headers[name.toLowerCase()] ?? null, + has: (name: string) => name.toLowerCase() in headers, + }, + text: async () => text(), + json: async () => JSON.parse(text()) as unknown, + bytes: async () => saved.body, + } + } + const extension = Extension.make({ + name: "fetch", + globals: { + fetch: Extension.async(async (url: string) => + makeResponse({ + url, + status: 200, + headers: [["x-id", "7"]], + body: new TextEncoder().encode(JSON.stringify({ url, ok: true })), + }), + ), + }, + snapshot: { + encode: (value) => (counts.encode++, (value as { readonly [savedSymbol]: Saved })[savedSymbol]), + decode: (data) => (counts.decode++, makeResponse(data as Saved)), + ...snapshot, + }, + }) + return { extension, counts } + } + + const code = ` + const res = await fetch("https://a.test/") + const text = res.text + const header = res.headers.get + await tools.job({ value: 1 }) + return [await text(), await res.json(), header("x-id"), res.headers.has("x-id"), [...(await res.bytes())].length, res.url, res.ok]` + + const suspendWith = async (extension: Extension.Extension) => { + const jobs = durableJobs() + const run = background( + CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, extensions: [extension] }).program(code, undefined, { + runId: "h", + }), + ) + await jobs.waiting() + return { jobs, run } + } + + test("methods on an extension-returned response survive suspend and resume in a fresh runtime", async () => { + const { extension, counts } = web() + const { jobs, run } = await suspendWith(extension) + const encodedBefore = counts.encode + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + expect(suspended.state.records.filter((record) => record.t === "HostValue")).toHaveLength(1) + expect(counts.encode - encodedBefore).toBe(1) + + jobs.reset() + const fresh = web() + const resumed = background( + CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, extensions: [fresh.extension] }).resume( + CodeMode.toBytes(suspended.state), + ), + ) + await jobs.waiting() + expect(fresh.counts).toEqual({ encode: 0, decode: 1 }) + jobs.finish("h:1", 1) + const outcome = await Effect.runPromise(resumed.result) + expect(outcome).toEqual({ + ok: true, + value: [ + '{"url":"https://a.test/","ok":true}', + { url: "https://a.test/", ok: true }, + "7", + true, + 35, + "https://a.test/", + true, + ], + toolCalls: [{ name: "job" }], + }) + }) + + test("a suspend fails, and the run goes on, when encode throws or returns non-plain data", async () => { + const cases: ReadonlyArray, string]> = [ + [ + { encode: () => undefined }, + "The run's state couldn't be saved: The extension \"fetch\" saved a value it returned as data holding undefined; snapshot.encode must give plain data (JSON values and Uint8Arrays).", + ], + [ + { encode: () => ({ when: new Date(0) }) }, + "The run's state couldn't be saved: The extension \"fetch\" saved a value it returned as data holding a Date; snapshot.encode must give plain data (JSON values and Uint8Arrays).", + ], + [ + { encode: () => ({ run: () => 1 }) }, + "The run's state couldn't be saved: The extension \"fetch\" saved a value it returned as data holding a function; snapshot.encode must give plain data (JSON values and Uint8Arrays).", + ], + [ + { + encode: () => { + throw new Error("no") + }, + }, + "The run's state couldn't be saved: The extension \"fetch\" couldn't save a value it returned: no", + ], + ] + for (const [snapshot, message] of cases) { + const { jobs, run } = await suspendWith(web(snapshot).extension) + const error = await blocked(run) + expect(error.message).toBe(message) + expect(error.running).toEqual([]) + jobs.finish("h:1", 1) + expect(await Effect.runPromise(run.result)).toMatchObject({ + ok: true, + value: [ + '{"url":"https://a.test/","ok":true}', + { url: "https://a.test/", ok: true }, + "7", + true, + 35, + "https://a.test/", + true, + ], + }) + } + }) + + test("a Buffer or Uint8Array view returned by snapshot.encode copies only its slice, not the underlying slab", async () => { + const slab = new ArrayBuffer(8192) + const view = new Uint8Array(slab, 100, 4) + view.set(new TextEncoder().encode('"hi"')) + const { extension } = web({ + encode: (value) => ({ + ...(value as { readonly [savedSymbol]: Saved })[savedSymbol], + body: Buffer.from(view.buffer, view.byteOffset, view.byteLength), + }), + }) + const { jobs, run } = await suspendWith(extension) + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + // The serialized ArrayBuffer record holds only the 4-byte slice, not the 8 KiB slab. + expect(suspended.state.records.filter((r) => r.t === "ArrayBuffer")).toEqual([ + { t: "ArrayBuffer", d: btoa('"hi"') }, + ]) + const fresh = web() + const resumed = background( + CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, extensions: [fresh.extension] }).resume( + CodeMode.toBytes(suspended.state), + ), + ) + await jobs.waiting() + jobs.finish("h:1", 1) + expect(await Effect.runPromise(resumed.result)).toEqual({ + ok: true, + value: ['"hi"', "hi", "7", true, 4, "https://a.test/", true], + toolCalls: [{ name: "job" }], + }) + }) + + test("a state that holds a hooked value is refused without that extension or without its hooks", async () => { + const { extension } = web() + const { jobs, run } = await suspendWith(extension) + const suspended = suspendedOf(await Effect.runPromise(run.suspend)) + const unhooked = Extension.make({ name: "fetch", globals: extension.globals }) + const other = Extension.make({ name: "other", globals: extension.globals, snapshot: extension.snapshot }) + for (const extensions of [[], [unhooked], [other]]) { + expect( + (await refusal(CodeMode.make({ engine: "vm", tools: { job: jobs.tool }, extensions }).resume(suspended.state))) + .message, + ).toBe("This state was saved by a runtime with other host globals (extensions); resume it with the same ones.") + } + }) +}) + +describe("legacy engine compatibility", () => { + test("tools with Tool.idempotent or Tool.durable and extensions with snapshot hooks behave the same as before on legacy", async () => { + const keys: Array = [] + const idempotentTool = Tool.make({ + description: "Idempotent tool", + input: Value, + output: Value, + execute: Tool.idempotent((input, { key }) => + Effect.sync(() => { + keys.push(key) + return { value: input.value * 2 } + }), + ), + }) + const durableTool = Tool.make({ + description: "Durable tool", + input: Value, + output: Value, + execute: Tool.durable({ + start: (input, { key }) => + Effect.sync(() => { + keys.push(key) + return { n: input.value + 1 } + }), + wait: ({ n }) => Effect.succeed({ value: n * 10 }), + cancel: () => Effect.void, + }), + }) + const extension = Extension.make({ + name: "ext", + globals: { + greet: (name: string) => ({ text: () => `hi ${name}` }), + }, + snapshot: { + encode: (value) => value, + decode: (data) => data, + }, + }) + const runtime = CodeMode.make({ + engine: "legacy", + tools: { idempotent: idempotentTool, durable: durableTool }, + extensions: [extension], + }) + const result = await Effect.runPromise( + runtime.execute(` + const a = await tools.idempotent({ value: 3 }) + const b = await tools.durable({ value: 4 }) + return [a.value, b.value, greet("kit").text()] + `), + ) + expect(result).toEqual({ + ok: true, + value: [6, 50, "hi kit"], + toolCalls: [{ name: "idempotent" }, { name: "durable" }], + }) + expect(keys).toHaveLength(2) + expect(keys[0]).not.toBe(keys[1]) + }) +})