feat(codemode): idempotent and durable tools, and safe suspension on the VM (#62459)

This commit is contained in:
James Long
2026-11-07 13:06:40 -06:00
committed by GitHub
Unverified
parent f460ccefcb
commit c33eaa170e
19 changed files with 1850 additions and 149 deletions
+109 -21
View File
@@ -90,12 +90,12 @@ runtime.execute(source) // Effect<CodeMode.Result, never, ToolServices>
```
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 `<runId>:<callId>`
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 `<runId>:<callId>` (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<Data /* Json */>` begins the work and returns JSON `data` (inferred into `wait`
and `cancel`);
- `wait(data, { key }) => Effect<Output>` connects to the running work and waits for its result;
- `cancel(data) => Effect<void>` 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`).
+25 -15
View File
@@ -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 (`<runId>:<callId>`); 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<R = never> = {
/** A runtime on the bytecode VM (`engine: "vm"`, experimental): it can also suspend runs and resume them. */
export type VmRuntime<R = never> = Runtime<R> & {
/** A program ready to run once; nothing runs until `program.run()`. */
readonly program: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Program<R>
readonly program: (
code: string,
bindings?: Readonly<Record<string, DataValue>>,
options?: ProgramOptions,
) => Program<R>
/**
* 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<string, unknown> = {},
const Extensions extends ReadonlyArray<Extension> = [],
>(options: Options<Provided, Extensions> = {}): Runtime<Environment<Provided, Extensions>> | VmRuntime<Environment<Provided, Extensions>> {
>(
options: Options<Provided, Extensions> = {},
): Runtime<Environment<Provided, Extensions>> | VmRuntime<Environment<Provided, Extensions>> {
type R = Environment<Provided, Extensions>
const prepared = ToolRuntime.prepare<R>((options.tools ?? {}) as Tools<Services<Provided>>)
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<Record<string, DataValue>> | undefined) =>
bindings === undefined
? undefined
: (ctx: Parameters<typeof vm.fromJson>[0]) =>
Object.entries(bindings).map(([name, value]) => [name, vm.fromJson(ctx, value)] as const)
const program = (code: string, bindings?: Readonly<Record<string, DataValue>>) =>
vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings))))
const program = (code: string, bindings?: Readonly<Record<string, DataValue>>, 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<R>
}
// A program's one run: `start` makes it once the VM is loaded, and a suspend waits for it.
const vmProgram = <R, E>(
start: (vm: typeof VmEngine) => Effect.Effect<VmEngine.Running<R>, E>,
): Program<R, E> => {
const vmProgram = <R, E>(start: (vm: typeof VmEngine) => Effect.Effect<VmEngine.Running<R>, E>): Program<R, E> => {
let claimed = false
const started = Deferred.makeUnsafe<VmEngine.Running<R>, SuspendError>()
return {
@@ -318,9 +327,10 @@ let vmEngine: Promise<typeof VmEngine> | 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
})),
)
+19 -1
View File
@@ -18,6 +18,20 @@ import type { Effect } from "effect"
export type Extension<Globals extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
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 = <const Globals extends Readonly<Record<string, unknown>>>(
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<Function>()
+1
View File
@@ -12,6 +12,7 @@ export {
toolExpression,
type Outcome,
type Program,
type ProgramOptions,
type Snapshot,
type SnapshotHeader,
type Suspended,
+3 -3
View File
@@ -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>()("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 {
+189 -33
View File
@@ -12,7 +12,7 @@ import {
outputTypeScript,
} from "./tool-schema.js"
import { isNamespace, type Namespace } from "./namespace.js"
import { isTool, type Tool } from "./tool.js"
import { type 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<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] exten
? never
: T extends {
readonly _tag: "CodeModeTool"
readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, infer R>
readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, infer R>
}
? 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, `<runId>:<callId>`: 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<R = never> = {
| 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, A, R>(
call: Call,
before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined,
after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined,
run: Effect.Effect<A, unknown, R>,
detaching?: () => boolean,
): Effect.Effect<A, unknown, R> => {
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<R = never> = {
readonly calls: Array<ToolCall>
readonly hooks: Hooks<R>
readonly invocations: Map<string, ToolInvocation>
readonly record: (name: string) => void
readonly execute: (
path: ReadonlyArray<string>,
args: Array<Json | undefined>,
options?: ExecuteCallOptions,
) => Effect.Effect<Json | undefined, unknown, R>
readonly search: (
args: Array<Json | undefined>,
options?: ExecuteCallOptions,
) => Effect.Effect<Json | undefined, unknown, R>
readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>
readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>
/** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */
readonly mode: (
path: ReadonlyArray<string>,
) => Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined
/** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */
readonly start: (
path: ReadonlyArray<string>,
args: Array<Json | undefined>,
key: string,
admit?: (name: string) => void,
) => Effect.Effect<Json, unknown, R>
/**
* 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<string>,
args: Array<Json | undefined>,
key: string,
data: Json,
detaching: () => boolean,
) => Effect.Effect<Json | undefined, unknown, R>
/** Cancels a durable tool's started work when the run is interrupted or ends. */
readonly cancel: (path: ReadonlyArray<string>, data: Json) => Effect.Effect<void, unknown, R>
}
/** Per-execution call state over tools prepared once for the runtime. */
@@ -390,7 +434,10 @@ export const make = <R>(
hooks: Hooks<R> = {},
): ToolRuntime<R> => {
const calls: Array<ToolCall> = []
const invocations = new Map<string, ToolInvocation>()
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 = <R>(
calls.push(call)
}
const executeTool = (name: string, tool: Tool<R>, args: Array<Json | undefined>) =>
const decode = (name: string, tool: Tool<R>, args: Array<Json | undefined>) =>
Effect.gen(function* () {
const normalized = args.length === 0 ? [{}] : args
if (normalized.length !== 1)
throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`)
const input = yield* Effect.try({
return yield* Effect.try({
try: () => decodeToolInput(tool, normalized[0]),
catch: (cause) =>
new ToolRuntimeError(
@@ -413,48 +460,157 @@ export const make = <R>(
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 = <A>(effect: Effect.Effect<A, unknown, R>) =>
effect.pipe(
Effect.catchCause((cause) => {
if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt
return Effect.fail(
toolError(
Cause.prettyErrors(cause)
.map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
.join("\n"),
),
)
}),
)
// The same round trip a tool result would take through text: exact JSON.stringify semantics.
const output = (name: string, tool: Tool<R>, raw: unknown) =>
Effect.try({
try: (): Json | undefined => {
const text = JSON.stringify(decodeToolOutput(tool, raw))
return text === undefined ? undefined : JSON.parse(text)
},
catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
})
const executeTool = (name: string, tool: Tool<R>, args: Array<Json | undefined>, 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<string>,
): {
readonly name: string
readonly tool: Tool<R>
readonly durable: Durable<unknown, unknown, R>
} => {
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<unknown, unknown, R>
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<void, unknown, R>
return failure(cancel(data))
}),
}
}
+105 -9
View File
@@ -41,13 +41,64 @@ export type JsonSchema = {
/** Either a validating Effect Schema or a render-only JSON Schema document. */
export type SchemaType = Schema.Decoder<unknown> | JsonSchema
/** Context passed to a tool call: its stable idempotency key (`<runId>:<callId>`). */
export type ToolContext = {
readonly key: string
}
export type ExecuteFn<Input = unknown, Output = unknown, R = never> = (
input: Input,
context: ToolContext,
) => Effect.Effect<Output, unknown, R>
/**
* 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 = unknown, Output = unknown, R = never> = {
(input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>
readonly _tag: "CodeModeIdempotent"
readonly execute: ExecuteFn<Input, Output, R>
}
/**
* 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<Data, unknown, RStart>
readonly wait: (data: NoInfer<Data>, context: ToolContext) => Effect.Effect<Output, unknown, RWait>
readonly cancel: (data: NoInfer<Data>) => Effect.Effect<void, unknown, RCancel>
}
/** A tool execution wrapper for work that keeps running across a suspend and reconnects through its JSON data. */
export type Durable<Input = unknown, Output = unknown, R = never> = {
(input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>
readonly _tag: "CodeModeDurable"
readonly start: (input: Input, context: ToolContext) => Effect.Effect<Schema.Json, unknown, R>
readonly wait: (data: never, context: ToolContext) => Effect.Effect<Output, unknown, R>
readonly cancel: (data: never) => Effect.Effect<void, unknown, R>
}
/** Executable tool exposed through CodeMode's `tools` object. */
export type Tool<R = never> = {
readonly _tag: "CodeModeTool"
readonly description: string
readonly input: SchemaType
readonly output: SchemaType | undefined
readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, R>
readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, R>
readonly mode?: Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined
}
type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown
@@ -59,12 +110,52 @@ export type Options<I extends SchemaType, O extends SchemaType | undefined, R =
readonly description: string
readonly input: I
readonly output?: O
readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>
readonly execute:
| ExecuteFn<InputType<I>, ResultType<O>, R>
| Idempotent<InputType<I>, ResultType<O>, R>
| Durable<InputType<I>, ResultType<O>, R>
}
export const isTool = <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined): value is Tool<R> =>
value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool"
/** Marks a tool's `execute` function as safe to interrupt on suspend and re-run on resume with the same key. */
export const idempotent = <Input, Output, R = never>(
execute: ExecuteFn<Input, Output, R>,
): Idempotent<Input, Output, R> =>
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<Data, Input, Output, RStart, RWait, RCancel>,
): Durable<Input, Output, RStart | RWait | RCancel> => {
type R = RStart | RWait | RCancel
const wait = options.wait as (data: Schema.Json, context: ToolContext) => Effect.Effect<Output, unknown, R>
return Object.assign(
(input: Input, context: ToolContext): Effect.Effect<Output, unknown, R> =>
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<Output, unknown, R>,
cancel: options.cancel as (data: never) => Effect.Effect<void, unknown, R>,
},
)
}
/**
* Declares one schema-described tool available to a CodeMode program through `tools.*`.
*
@@ -74,10 +165,15 @@ export const isTool = <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | und
*/
export const make = <I extends SchemaType, const O extends SchemaType | undefined = undefined, R = never>(
options: Options<I, O, R>,
): Tool<R> => ({
_tag: "CodeModeTool",
description: options.description,
input: options.input,
output: options.output,
execute: (input) => options.execute(input as InputType<I>),
})
): Tool<R> => {
const spec = options.execute
const mode = "_tag" in spec ? (spec as Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R>) : 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<I>, context),
}
}
+10 -5
View File
@@ -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>:<callId>`). */
runId = ""
queued: Array<HostCall> = []
readonly running = new Map<number, HostCall>()
readonly inbox: Array<Delivery> = []
@@ -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<unknown>,
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) {
+95 -20
View File
@@ -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<R> {
private readonly fibers = new Map<number, Fiber.Fiber<unknown, unknown>>()
// Calls whose fibers were interrupted to suspend or end the run: their outcomes are not reported.
private readonly detached = new Set<number>()
private wake: (() => void) | undefined
private stopping = false
private suspending = false
@@ -80,13 +85,20 @@ export class Driver<R> {
}
/**
* 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<R> {
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<void> {
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<unknown, unknown, R>)
}
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<unknown, unknown, R>): void {
// runs another job. A success goes to `next` when given, otherwise to the VM.
private fork(id: number, work: Effect.Effect<unknown, unknown, R>, next?: (value: unknown) => void): void {
const fiber = Effect.runForkWith(this.services)(work)
this.fibers.set(id, fiber)
fiber.addObserver((exit) => {
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) {
+37 -7
View File
@@ -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 = <R>(
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 = <R>(
@@ -74,7 +74,12 @@ export const executeProgram = <R>(
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 = <R>(setup: Setup<R>, code: string, bindings?: Globals<R>): Running<R> =>
export const startProgram = <R>(
setup: Setup<R>,
code: string,
bindings?: Globals<R>,
runId: string = crypto.randomUUID(),
): Running<R> =>
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 = <R>(setup: Setup<R>, 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 = <R>(
}
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<R> {
self.driver = new Driver(prepared.vm, prepared.tools, yield* Effect.context<R>())
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<R> {
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<R> {
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<R> {
}),
)
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<R> {
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<R> {
}
// 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<R> {
}
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
+120 -16
View File
@@ -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<string | number> | 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 = <R>(
extensions: ReadonlyArray<Extension>,
): ReadonlyArray<readonly [string, Value]> => {
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<object, HostOrigin>()
const toHost = (value: Value, label: string, depth = 0, seen = new Set<object>()): 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 = <R>(
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<object>(), 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<object>(), 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 = <R>(
// 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 = <R>(
// 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<Value> = []
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 = <R>(
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 = <R>(
// 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<unknown>(
(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 = <R>(
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<unknown, unknown, R>) =>
(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<R>(request.host, request.threw))
return Effect.andThen(
@@ -202,7 +293,8 @@ export const extensionGlobals = <R>(
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 = <R>(
ctx: Interpreter<R>,
host: Function,
args: ReadonlyArray<unknown>,
call: Pick<ExtensionRequest, "label" | "invocation">,
call: Pick<ExtensionRequest, "label" | "extension" | "invocation">,
site: AstNode | undefined,
): PromiseObj | ExtensionRequest => {
const [result, threw] = callHost(host, args)
@@ -231,6 +323,18 @@ export const startExtensionCall = <R>(
return request
}
// Runs an extension's `snapshot` hook; what goes wrong is the state's problem, said as such.
const hostStep = <A>(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<unknown>): [result: unknown, threw: boolean] => {
try {
@@ -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<R> {
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<string, Source>()
/** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
+12 -2
View File
@@ -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<unknown>
@@ -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, `<runId>:<callId>`. */
readonly key: string,
readonly request: HostRequest,
/** What runs: a tool path, or an extension function's label. */
readonly label: string,
+4 -1
View File
@@ -62,7 +62,7 @@ const vmSpecs = (): ReadonlyArray<ClassSpec> =>
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
+130 -3
View File
@@ -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<string | number>
/** 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<string>
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<ClassSpec> | 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<ClassSpec> | undefined
/** What `EncodeEnv.external` named. */
readonly external?: ((data: Json) => unknown) | undefined
@@ -221,7 +250,7 @@ const builtinSpecs = (): ReadonlyArray<ClassSpec> => [
{
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<ClassSpec> => [
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<URLSearchParams, URL>()
private readonly params: Array<readonly [number, URLSearchParams]> = []
// One `HostValue` record per value an extension returned, however many of its functions the state holds.
private readonly roots = new Map<object, Encoded>()
private readonly specs: { readonly byCtor: Map<Function, ClassSpec>; readonly byName: Map<string, ClassSpec> }
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<boolean>
// 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<readonly [Native, { readonly [field: string]: unknown }]> = []
// Those values, given back once each by their extension's `snapshot.decode`, by `HostValue` record.
private readonly hostValues = new Map<number, object>()
private readonly specs: { readonly byCtor: Map<Function, ClassSpec>; readonly byName: Map<string, ClassSpec> }
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<object>): 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 !== ""
+15 -2
View File
@@ -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<unknown>): string => hash(ctx.intrinsics.hosts().join("\n"))
export const hostsId = (ctx: Interpreter<unknown>): 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 {
+1 -1
View File
@@ -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
}
+3 -2
View File
@@ -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<string>): 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 () => {
File diff suppressed because it is too large Load Diff