mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 13:05:14 +03:00
feat(codemode): idempotent and durable tools, and safe suspension on the VM (#62459)
This commit is contained in:
committed by
GitHub
Unverified
parent
f460ccefcb
commit
c33eaa170e
+109
-21
@@ -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`).
|
||||
|
||||
|
||||
@@ -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
|
||||
})),
|
||||
)
|
||||
|
||||
@@ -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>()
|
||||
|
||||
@@ -12,6 +12,7 @@ export {
|
||||
toolExpression,
|
||||
type Outcome,
|
||||
type Program,
|
||||
type ProgramOptions,
|
||||
type Snapshot,
|
||||
type SnapshotHeader,
|
||||
type Suspended,
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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))
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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. */
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 !== ""
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user