@opencode/codemode 2.2.6 → 2.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -21
- package/dist/codemode.d.ts +6 -1
- package/dist/codemode.js +2 -2
- package/dist/extension.d.ts +13 -0
- package/dist/extension.js +5 -1
- package/dist/index.d.ts +1 -1
- package/dist/interpreter/callback.d.ts +12 -1
- package/dist/interpreter/callback.js +13 -1
- package/dist/interpreter/interpreter.js +2 -2
- package/dist/interpreter/promises.js +2 -2
- package/dist/interpreter/runner.d.ts +1 -11
- package/dist/interpreter/runner.js +1 -13
- package/dist/stdlib/iterator.js +1 -2
- package/dist/suspend-error.d.ts +3 -2
- package/dist/suspend-error.js +3 -3
- package/dist/tool-runtime.d.ts +27 -6
- package/dist/tool-runtime.js +116 -26
- package/dist/tool.d.ts +45 -2
- package/dist/tool.js +30 -7
- package/dist/vm/host.d.ts +4 -1
- package/dist/vm/host.js +9 -4
- package/dist/vm/runtime/driver.d.ts +17 -7
- package/dist/vm/runtime/driver.js +89 -19
- package/dist/vm/runtime/execute.d.ts +1 -1
- package/dist/vm/runtime/execute.js +35 -7
- package/dist/vm/runtime/extensions.d.ts +1 -1
- package/dist/vm/runtime/extensions.js +82 -15
- package/dist/vm/runtime/interpreter.d.ts +3 -0
- package/dist/vm/runtime/interpreter.js +2 -0
- package/dist/vm/scheduler.d.ts +15 -3
- package/dist/vm/scheduler.js +13 -2
- package/dist/vm/snapshot/codec.d.ts +31 -1
- package/dist/vm/snapshot/codec.js +100 -3
- package/dist/vm/snapshot/snapshot.d.ts +5 -1
- package/dist/vm/snapshot/snapshot.js +5 -1
- package/dist/vm/snapshot.js +4 -1
- package/dist/vm/vm.d.ts +1 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -90,12 +90,12 @@ runtime.execute(source) // Effect<CodeMode.Result, never, ToolServices>
|
|
|
90
90
|
```
|
|
91
91
|
|
|
92
92
|
The Effect environment is inferred from the supplied tools. `hooks` surround every call the program makes into the
|
|
93
|
-
host: `tool.before`/`tool.after` receive `{ name, input }` with decoded input
|
|
94
|
-
receive `{ extension, name, args }`. An `after` hook also
|
|
95
|
-
`failure` with its error, or `interrupted`). A `before` hook
|
|
96
|
-
denies it: the host function is never called, and the program
|
|
97
|
-
fails the way the call itself would: a tool call or asynchronous
|
|
98
|
-
throws.
|
|
93
|
+
host: `tool.before`/`tool.after` receive `{ name, input, key }` with decoded input and the call's `<runId>:<callId>`
|
|
94
|
+
idempotency key, and `extension.before`/`extension.after` receive `{ extension, name, args }`. An `after` hook also
|
|
95
|
+
receives how the call ended (`success` with its value, `failure` with its error, or `interrupted`). A `before` hook
|
|
96
|
+
runs before the call reaches the host, and a failing one denies it: the host function is never called, and the program
|
|
97
|
+
catches the failure as a thrown error. A denied call fails the way the call itself would: a tool call or asynchronous
|
|
98
|
+
global rejects its promise, and a synchronous global throws.
|
|
99
99
|
|
|
100
100
|
### Bytecode VM and suspending/resuming a run (experimental, `engine: "vm"`)
|
|
101
101
|
|
|
@@ -104,8 +104,10 @@ Pass `engine: "vm"` to `CodeMode.make` or `CodeMode.execute` to run programs on
|
|
|
104
104
|
both engines.
|
|
105
105
|
|
|
106
106
|
On `engine: "vm"`, `CodeMode.make` returns a `CodeMode.VmRuntime`, which can also run a program step by step:
|
|
107
|
-
`runtime.program(code, bindings?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`.
|
|
108
|
-
|
|
107
|
+
`runtime.program(code, bindings?, { runId }?)` makes a `CodeMode.Program`, and nothing runs until `program.run()`. Every
|
|
108
|
+
host call gets a stable key `<runId>:<callId>` (using a generated UUID when `runId` is omitted), saved in the snapshot
|
|
109
|
+
and passed to tools as `execute(input, { key })` and to hooks as `call.key`. `run()` runs the program in the current
|
|
110
|
+
fiber until it ends or is suspended, and gives a `CodeMode.Outcome`: a `Result`, or:
|
|
109
111
|
|
|
110
112
|
```ts
|
|
111
113
|
type Suspended = {
|
|
@@ -119,7 +121,7 @@ const runtime = CodeMode.make({ tools, engine: "vm" })
|
|
|
119
121
|
const outcome = yield* runtime.program(code).run()
|
|
120
122
|
|
|
121
123
|
// in the background, suspended from another fiber
|
|
122
|
-
const program = runtime.program(code)
|
|
124
|
+
const program = runtime.program(code, undefined, { runId: "run-1" })
|
|
123
125
|
const fiber = yield* Effect.forkChild(program.run())
|
|
124
126
|
const suspended = yield* program.suspend() // the same Suspended that run() returns
|
|
125
127
|
const outcome = yield* Fiber.join(fiber)
|
|
@@ -128,25 +130,80 @@ const outcome = yield* Fiber.join(fiber)
|
|
|
128
130
|
yield* runtime.resume(CodeMode.toBytes(suspended.state)).run()
|
|
129
131
|
```
|
|
130
132
|
|
|
131
|
-
The default runtime has no `program` or `resume
|
|
132
|
-
|
|
133
|
-
every call in progress
|
|
133
|
+
The default runtime has no `program` or `resume`, and ignores `Tool.idempotent`, `Tool.durable`, and extension
|
|
134
|
+
`snapshot` hooks. A program runs once: running it again is a defect, so make another with `runtime.program` or
|
|
135
|
+
`runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and every call in progress
|
|
136
|
+
(and cancels any started durable tool work).
|
|
134
137
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
138
|
+
#### Idempotent and durable tools, and safe suspension
|
|
139
|
+
|
|
140
|
+
A tool's `execute` is either a plain function or wrapped with `Tool.idempotent` or `Tool.durable`:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
// plain (default): a suspend is refused while it runs
|
|
144
|
+
Tool.make({
|
|
145
|
+
description: "...",
|
|
146
|
+
input: ...,
|
|
147
|
+
output: ...,
|
|
148
|
+
execute: (input, { key }) => compute(input),
|
|
149
|
+
})
|
|
150
|
+
|
|
151
|
+
// idempotent: safe to run again; interrupted on suspend, rerun on resume with the same key
|
|
152
|
+
Tool.make({
|
|
153
|
+
description: "...",
|
|
154
|
+
input: ...,
|
|
155
|
+
output: ...,
|
|
156
|
+
execute: Tool.idempotent((input, { key }) => Db.get(input.name)),
|
|
157
|
+
})
|
|
158
|
+
|
|
159
|
+
// durable: keeps running across a suspend, reconnected through its JSON data on resume
|
|
160
|
+
Tool.make({
|
|
161
|
+
description: "...",
|
|
162
|
+
input: ...,
|
|
163
|
+
output: ...,
|
|
164
|
+
execute: Tool.durable({
|
|
165
|
+
start: (input, { key }) => Jobs.submit(input, key).pipe(Effect.map((id) => ({ id }))),
|
|
166
|
+
wait: ({ id }, { key }) => Jobs.wait(id),
|
|
167
|
+
cancel: ({ id }) => Jobs.kill(id),
|
|
168
|
+
}),
|
|
169
|
+
})
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
- **Plain (`execute: (input, { key }) => ...`):** not durable. Suspend is refused while the call is running.
|
|
173
|
+
- **`Tool.idempotent(execute)`:** idempotent/read-only work safe to run again. If a suspend lands while the call is
|
|
174
|
+
running, the VM detaches and interrupts it without firing `tool.after`, saves the call in the snapshot as queued, and
|
|
175
|
+
re-runs it on resume with the same `key` without double-counting it against `maxToolCalls`.
|
|
176
|
+
- **`Tool.durable({ start, wait, cancel })`:** work that outlives a suspended run (when run without a suspend or on the
|
|
177
|
+
legacy engine, it runs `start` then `wait`):
|
|
178
|
+
- `start(input, { key }) => Effect<Data /* Json */>` begins the work and returns JSON `data` (inferred into `wait`
|
|
179
|
+
and `cancel`);
|
|
180
|
+
- `wait(data, { key }) => Effect<Output>` connects to the running work and waits for its result;
|
|
181
|
+
- `cancel(data) => Effect<void>` stops the work when the run is interrupted for real or ends, never when it is
|
|
182
|
+
suspended.
|
|
183
|
+
|
|
184
|
+
While `start` is running, the call blocks suspend. Once `start` returns its JSON data, the call is in the `started`
|
|
185
|
+
state with its data saved in the snapshot, and suspend is allowed. `wait` is not tied to the program's JavaScript
|
|
186
|
+
`await`: the VM calls `wait(data)` right after `start` returns, and calls `wait(data)` again for every `started` call
|
|
187
|
+
right when `resume` starts, whatever the program does with the call's promise (whether it `await`s it immediately,
|
|
188
|
+
passes it to `Promise.all`, chains `.then`, or keeps the unawaited promise in a variable and awaits it later).
|
|
189
|
+
|
|
190
|
+
`program.suspend(options?)` saves the run's state and stops it at once, and `run()` returns the same `Suspended`.
|
|
191
|
+
Suspend is allowed only when every in-flight call is queued, `Tool.idempotent`, or `Tool.durable` in `started`. When
|
|
192
|
+
any other host call is in progress — a plain tool, a durable tool still in `start`, `search`, or an async or
|
|
193
|
+
synchronous extension call — `suspend` fails with a `CodeMode.SuspendError` naming each blocking call in `running` by
|
|
194
|
+
its `key` and `path` (`tools.x.y`, `search`, `fetch`), and the run goes on untouched. Tool calls queued but not started
|
|
195
|
+
don't block: they start on resume. Outcomes already waiting in the inbox are part of the state. A suspend after the run
|
|
196
|
+
ended gives its result; one issued before `run()` has started waits for it to start (and for ever if it never runs).
|
|
141
197
|
|
|
142
198
|
The suspend is immediate: the program shares the thread with the caller, so it is at a step boundary. Its checks, saving
|
|
143
199
|
the state, and checking it against `options.maxBytes` all happen before anything about the run changes, so a state that
|
|
144
200
|
can't be saved or is too large fails the suspend the same way.
|
|
145
201
|
|
|
146
202
|
A resumed run keeps the limits it was saved with: `timeoutMs` counts active time across every resume, and `maxToolCalls`
|
|
147
|
-
counts every call of the run. A state resumes only on the same build of this package and with the same
|
|
148
|
-
state is checked when the resumed program runs: its `run()`
|
|
149
|
-
resumed here or is malformed. Built-ins are saved by name and
|
|
203
|
+
counts every admitted call of the run. A state resumes only on the same build of this package and with the same
|
|
204
|
+
extensions (and the same extension `snapshot` hooks). The state is checked when the resumed program runs: its `run()`
|
|
205
|
+
fails with a `CodeMode.SnapshotError` when it can't be resumed here or is malformed. Built-ins are saved by name and
|
|
206
|
+
only their changes are copied.
|
|
150
207
|
|
|
151
208
|
Set `CODEMODE_ROUNDTRIP=1` (`bun run test:roundtrip`) to run the tests on the VM with every run saved to bytes and
|
|
152
209
|
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
|
|
|
191
248
|
copies, and a function inside a result is callable the same way. A global that shadows a built-in or another
|
|
192
249
|
extension throws at `CodeMode.make`.
|
|
193
250
|
|
|
251
|
+
Functions inside a result have no data form, so a suspended VM run loses them by default: after a resume, calling one
|
|
252
|
+
throws a `TypeError`. An extension can preserve them across suspend and resume with `snapshot` hooks. `encode` receives
|
|
253
|
+
a value one of the extension's functions returned, as the host function returned it, and returns plain data (JSON
|
|
254
|
+
values and `Uint8Array`s); on resume, `decode` receives that data once per value and returns a host value of the same
|
|
255
|
+
shape, whose functions the restored program copies call from then on:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
const saved = Symbol("saved")
|
|
259
|
+
const makeResponse = (data: { url: string; body: Uint8Array }) => ({
|
|
260
|
+
[saved]: data,
|
|
261
|
+
url: data.url,
|
|
262
|
+
text: async () => new TextDecoder().decode(data.body),
|
|
263
|
+
bytes: async () => data.body,
|
|
264
|
+
})
|
|
265
|
+
const web = Extension.make({
|
|
266
|
+
name: "web",
|
|
267
|
+
globals: {
|
|
268
|
+
fetch: Extension.async(async (url: string) =>
|
|
269
|
+
makeResponse({ url, body: await (await globalThis.fetch(url)).bytes() }),
|
|
270
|
+
),
|
|
271
|
+
},
|
|
272
|
+
snapshot: {
|
|
273
|
+
encode: (value) => (value as { [saved]: { url: string; body: Uint8Array } })[saved],
|
|
274
|
+
decode: (data) => makeResponse(data as { url: string; body: Uint8Array }),
|
|
275
|
+
},
|
|
276
|
+
})
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
A suspend fails (and the run continues) when `encode` throws or returns non-plain data. A snapshot saved with an
|
|
280
|
+
extension's hooks resumes only in a runtime whose extension of the same name also provides `snapshot` hooks.
|
|
281
|
+
|
|
194
282
|
A global can also be an object of functions, such as `fs`. Every function reachable from it is an entry point like a
|
|
195
283
|
global, so calls fire the `extension` hooks with their path as the name (`fs.readFile`, `fs.promises.readFile`).
|
|
196
284
|
|
package/dist/codemode.d.ts
CHANGED
|
@@ -34,6 +34,11 @@ export type ResolvedExecutionLimits = {
|
|
|
34
34
|
};
|
|
35
35
|
/** Execution engine: the default AST generator interpreter (`"legacy"`) or the experimental bytecode VM (`"vm"`). */
|
|
36
36
|
export type Engine = "legacy" | "vm";
|
|
37
|
+
/** Options for `VmRuntime.program`. */
|
|
38
|
+
export type ProgramOptions = {
|
|
39
|
+
/** Names this run's host calls (`<runId>:<callId>`); a random UUID by default. */
|
|
40
|
+
readonly runId?: string;
|
|
41
|
+
};
|
|
37
42
|
/** How `program.suspend` saves a run's state (`engine: "vm"` only). */
|
|
38
43
|
export type SuspendOptions = {
|
|
39
44
|
/** The most bytes a saved state may take; a larger one fails the suspend, and the run goes on. */
|
|
@@ -176,7 +181,7 @@ export type Runtime<R = never> = {
|
|
|
176
181
|
/** A runtime on the bytecode VM (`engine: "vm"`, experimental): it can also suspend runs and resume them. */
|
|
177
182
|
export type VmRuntime<R = never> = Runtime<R> & {
|
|
178
183
|
/** A program ready to run once; nothing runs until `program.run()`. */
|
|
179
|
-
readonly program: (code: string, bindings?: Readonly<Record<string, DataValue
|
|
184
|
+
readonly program: (code: string, bindings?: Readonly<Record<string, DataValue>>, options?: ProgramOptions) => Program<R>;
|
|
180
185
|
/**
|
|
181
186
|
* A suspended run (its `state`, or that state as bytes) as a program to continue in this runtime, which must be the
|
|
182
187
|
* same build with the same extensions. The state is checked when it runs: `run()` fails with a `SnapshotError` when
|
package/dist/codemode.js
CHANGED
|
@@ -91,12 +91,12 @@ export function make(options = {}) {
|
|
|
91
91
|
limits,
|
|
92
92
|
hooks: options.hooks ?? {},
|
|
93
93
|
globals: extensions.length === 0 ? undefined : (ctx) => vm.extensionGlobals(ctx, extensions),
|
|
94
|
-
lossy: extensions.
|
|
94
|
+
lossy: extensions.some((extension) => extension.snapshot === undefined),
|
|
95
95
|
});
|
|
96
96
|
const data = (vm, bindings) => bindings === undefined
|
|
97
97
|
? undefined
|
|
98
98
|
: (ctx) => Object.entries(bindings).map(([name, value]) => [name, vm.fromJson(ctx, value)]);
|
|
99
|
-
const program = (code, bindings) => vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings))));
|
|
99
|
+
const program = (code, bindings, programOptions) => vmProgram((vm) => Effect.succeed(vm.startProgram(getSetup(vm), code, data(vm, bindings), programOptions?.runId)));
|
|
100
100
|
return {
|
|
101
101
|
get catalog() {
|
|
102
102
|
return prepared.catalog;
|
package/dist/extension.d.ts
CHANGED
|
@@ -16,6 +16,19 @@ import type { Effect } from "effect";
|
|
|
16
16
|
export type Extension<Globals extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
|
|
17
17
|
readonly name: string;
|
|
18
18
|
readonly globals: Globals;
|
|
19
|
+
/** How a suspended run saves the values this extension's functions returned (`engine: "vm"` only); see `Snapshot`. */
|
|
20
|
+
readonly snapshot?: Snapshot | undefined;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Lets a suspended run keep the functions inside values this extension's functions returned (a response's `text`,
|
|
24
|
+
* say). `encode` gets such a value, as the host function returned it, and gives plain data: JSON values and
|
|
25
|
+
* `Uint8Array`s. On resume, `decode` gets that data back, once per value, and gives a value of the same shape, whose
|
|
26
|
+
* functions the program's copies call from then on. Without it, those functions are lost on resume: calling one
|
|
27
|
+
* throws. A suspend fails, and the run goes on, when `encode` throws or gives anything else.
|
|
28
|
+
*/
|
|
29
|
+
export type Snapshot = {
|
|
30
|
+
readonly encode: (value: unknown) => unknown;
|
|
31
|
+
readonly decode: (data: unknown) => unknown;
|
|
19
32
|
};
|
|
20
33
|
/** The Effect environment required by an extension's Effect-returning functions, at the top level or one level in. */
|
|
21
34
|
export type Services<E> = E extends {
|
package/dist/extension.js
CHANGED
|
@@ -5,7 +5,11 @@ export const make = (options) => {
|
|
|
5
5
|
throw new TypeError(`Extension "${options.name}" global "${name}" must be a function or an object.`);
|
|
6
6
|
}
|
|
7
7
|
}
|
|
8
|
-
return {
|
|
8
|
+
return {
|
|
9
|
+
name: options.name,
|
|
10
|
+
globals: { ...options.globals },
|
|
11
|
+
...(options.snapshot === undefined ? {} : { snapshot: options.snapshot }),
|
|
12
|
+
};
|
|
9
13
|
};
|
|
10
14
|
const asyncGlobals = new WeakSet();
|
|
11
15
|
const AsyncFunction = (async () => { }).constructor;
|
package/dist/index.d.ts
CHANGED
|
@@ -3,5 +3,5 @@ export * as Extension from "./extension.js";
|
|
|
3
3
|
export * as Namespace from "./namespace.js";
|
|
4
4
|
export * as Tool from "./tool.js";
|
|
5
5
|
export * as OpenAPI from "./openapi/index.js";
|
|
6
|
-
export { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, type Outcome, type Program, type Snapshot, type SnapshotHeader, type Suspended, type SuspendOptions, type VmRuntime, } from "./codemode.js";
|
|
6
|
+
export { fromBytes, searchSignature, SnapshotError, SuspendError, toBytes, toolExpression, type Outcome, type Program, type ProgramOptions, type Snapshot, type SnapshotHeader, type Suspended, type SuspendOptions, type VmRuntime, } from "./codemode.js";
|
|
7
7
|
export { ToolError, toolError } from "./tool-error.js";
|
|
@@ -1,6 +1,17 @@
|
|
|
1
|
+
import type { Cause } from "effect";
|
|
1
2
|
import type { Interpreter } from "./interpreter.js";
|
|
2
3
|
import { Callable, type Cursor, type NativeResult, type Value } from "./objects.js";
|
|
3
|
-
import {
|
|
4
|
+
import type { Eval } from "./runner.js";
|
|
5
|
+
/**
|
|
6
|
+
* Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
|
|
7
|
+
* it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
|
|
8
|
+
* program's body interrupts the execution.
|
|
9
|
+
*/
|
|
10
|
+
export declare class Interruption {
|
|
11
|
+
readonly cause: Cause.Cause<unknown>;
|
|
12
|
+
constructor(cause: Cause.Cause<unknown>);
|
|
13
|
+
}
|
|
14
|
+
export declare const isEval: <A>(value: A | Eval<A>) => value is Eval<A>;
|
|
4
15
|
/** IteratorClose: a consumer failure closes the iterator and wins over any close failure, except that a generator's
|
|
5
16
|
* return() is a return completion, so a failing close wins over it, as after `break`. */
|
|
6
17
|
export declare function preserveConsumerError<A>(close: Cursor["close"], body: Eval<A>): Eval<A>;
|
|
@@ -2,7 +2,19 @@ import { primitivePrototype } from "./intrinsics.js";
|
|
|
2
2
|
import { GeneratorReturn, typeError } from "./model.js";
|
|
3
3
|
import { Callable, get, Native, DateObj, Obj, coerceToNumber, coerceToString, } from "./objects.js";
|
|
4
4
|
import { isOpaque, typeofValue } from "./references.js";
|
|
5
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
|
|
7
|
+
* it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
|
|
8
|
+
* program's body interrupts the execution.
|
|
9
|
+
*/
|
|
10
|
+
export class Interruption {
|
|
11
|
+
cause;
|
|
12
|
+
constructor(cause) {
|
|
13
|
+
this.cause = cause;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
// Program values never have a `next` method of their own: an object's properties live in its property map.
|
|
17
|
+
export const isEval = (value) => typeof value === "object" && value !== null && typeof value.next === "function";
|
|
6
18
|
/** IteratorClose: a consumer failure closes the iterator and wins over any close failure, except that a generator's
|
|
7
19
|
* return() is a return completion, so a failing close wins over it, as after `break`. */
|
|
8
20
|
export function* preserveConsumerError(close, body) {
|
|
@@ -6,8 +6,8 @@ import { locate, materialize } from "./errors.js";
|
|
|
6
6
|
import { primitivePrototype } from "./intrinsics.js";
|
|
7
7
|
import { globals } from "./globals.js";
|
|
8
8
|
import { assign, Callable, define, frozen, get, hostCursor, IteratorObj, has, hasOwn, hidden, hasPrototype, keys, Native, parseArrayIndex, Arguments, Arr, Fn, GeneratorObj, Obj, PromiseObj, iteratorResult, remove, set, coerceToNumber, coerceToString, entries, getOwn, } from "./objects.js";
|
|
9
|
-
import { preserveConsumerError, toPrimitive } from "./callback.js";
|
|
10
|
-
import { AsyncBoundary, Await, Call,
|
|
9
|
+
import { Interruption, isEval, preserveConsumerError, toPrimitive } from "./callback.js";
|
|
10
|
+
import { AsyncBoundary, Await, Call, MAX_CALL_DEPTH, Runner, Slice, Task, Yield, normal, } from "./runner.js";
|
|
11
11
|
import { moduleName, resolveModule } from "./modules.js";
|
|
12
12
|
import { describeValue, isOpaque, rejectCircularInsertion, typeofValue } from "./references.js";
|
|
13
13
|
import { fn } from "./native.js";
|
|
@@ -3,8 +3,8 @@ import { Callable, define, get, hidden, Arr, Fn, Obj, PromiseObj, record } from
|
|
|
3
3
|
import { constructor, fn, methods, native, receiver, requiresNew } from "./native.js";
|
|
4
4
|
import { createAggregateErrorValue, materialize } from "./errors.js";
|
|
5
5
|
import { describeValue, typeofValue } from "./references.js";
|
|
6
|
-
import { isSupportedCallback } from "./callback.js";
|
|
7
|
-
import {
|
|
6
|
+
import { Interruption, isSupportedCallback } from "./callback.js";
|
|
7
|
+
import { normal, Task } from "./runner.js";
|
|
8
8
|
// A `resolve`/`reject` handed to an executor or thenable: calling it settles the capability.
|
|
9
9
|
const resolvingFunctions = (ctx, resolving) => ({
|
|
10
10
|
resolve: fn(ctx.builtins, "resolve", 1, (_, args) => {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { type Context, Effect } from "effect";
|
|
2
2
|
import type { Diagnostic } from "../codemode.js";
|
|
3
3
|
import type { Interpreter } from "./interpreter.js";
|
|
4
4
|
import { type AstNode, type GeneratorRequestKind } from "./model.js";
|
|
@@ -46,15 +46,6 @@ export declare class Host {
|
|
|
46
46
|
readonly effect: Effect.Effect<unknown, unknown>;
|
|
47
47
|
constructor(effect: Effect.Effect<unknown, unknown>);
|
|
48
48
|
}
|
|
49
|
-
/**
|
|
50
|
-
* Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
|
|
51
|
-
* it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
|
|
52
|
-
* program's body interrupts the execution.
|
|
53
|
-
*/
|
|
54
|
-
export declare class Interruption {
|
|
55
|
-
readonly cause: Cause.Cause<unknown>;
|
|
56
|
-
constructor(cause: Cause.Cause<unknown>);
|
|
57
|
-
}
|
|
58
49
|
/** Let the host run; the current job continues before any other job. */
|
|
59
50
|
export declare const Slice: unique symbol;
|
|
60
51
|
export type Signal = Call | Enter | Await | Yield | Host | typeof Slice;
|
|
@@ -110,7 +101,6 @@ export type Resolving = {
|
|
|
110
101
|
type Job = () => Start | void;
|
|
111
102
|
/** Most activations one task may hold, as the call-stack limit. */
|
|
112
103
|
export declare const MAX_CALL_DEPTH = 10000;
|
|
113
|
-
export declare const isEval: <A>(value: A | Eval<A>) => value is Eval<A>;
|
|
114
104
|
/**
|
|
115
105
|
* One execution's job queue. Program code runs only inside a job, one job at a time and each to completion, as in a
|
|
116
106
|
* JavaScript engine: promise reactions and resumed awaits queue in order, host work runs concurrently and settles its
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Cause, Effect, Exit, Fiber } from "effect";
|
|
2
|
+
import { Interruption } from "./callback.js";
|
|
2
3
|
import { locate, normalizeError } from "./errors.js";
|
|
3
4
|
import { MAX_PENDING_PROMISES } from "./limits.js";
|
|
4
5
|
import { PendingThrow, rangeError, Throw, typeError } from "./model.js";
|
|
@@ -48,17 +49,6 @@ export class Host {
|
|
|
48
49
|
this.effect = effect;
|
|
49
50
|
}
|
|
50
51
|
}
|
|
51
|
-
/**
|
|
52
|
-
* Host work that was interrupted on its own. It settles its promise like a rejection, but program code cannot catch
|
|
53
|
-
* it: handlers, `catch`, and `finally` are skipped, an unobserved one is not reported, and one that reaches the
|
|
54
|
-
* program's body interrupts the execution.
|
|
55
|
-
*/
|
|
56
|
-
export class Interruption {
|
|
57
|
-
cause;
|
|
58
|
-
constructor(cause) {
|
|
59
|
-
this.cause = cause;
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
52
|
/** Let the host run; the current job continues before any other job. */
|
|
63
53
|
export const Slice = Symbol("codemode.slice");
|
|
64
54
|
/** The boundary of an async body: the body's completion settles it, and the caller receives `result` at once. */
|
|
@@ -94,8 +84,6 @@ export const MAX_CALL_DEPTH = 10_000;
|
|
|
94
84
|
/** Interpreter steps between clock checks, and how long one slice may run before the host gets a turn. */
|
|
95
85
|
const FUEL = 64;
|
|
96
86
|
const SLICE_MS = 1;
|
|
97
|
-
// Program values never have a `next` method of their own: an object's properties live in its property map.
|
|
98
|
-
export const isEval = (value) => typeof value === "object" && value !== null && typeof value.next === "function";
|
|
99
87
|
/**
|
|
100
88
|
* One execution's job queue. Program code runs only inside a job, one job at a time and each to completion, as in a
|
|
101
89
|
* JavaScript engine: promise reactions and resumed awaits queue in order, host work runs concurrently and settles its
|
package/dist/stdlib/iterator.js
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
import { applyCollectionCallback } from "../interpreter/callback.js";
|
|
1
|
+
import { applyCollectionCallback, Interruption } from "../interpreter/callback.js";
|
|
2
2
|
import { rangeError, typeError } from "../interpreter/model.js";
|
|
3
3
|
import { constructor, fn, methods, receiver, requiresNew } from "../interpreter/native.js";
|
|
4
4
|
import { Arr, coerceToNumber, define, hasPrototype, hidden, iteratorResult, IteratorObj, Obj, } from "../interpreter/objects.js";
|
|
5
5
|
import { describeValue } from "../interpreter/references.js";
|
|
6
|
-
import { Interruption } from "../interpreter/runner.js";
|
|
7
6
|
const finished = { done: true, value: undefined };
|
|
8
7
|
// Every built-in iterator and helper shares the Iterator prototype; JS gives each collection its own, which is only
|
|
9
8
|
// observable through getPrototypeOf.
|
package/dist/suspend-error.d.ts
CHANGED
|
@@ -3,12 +3,13 @@ import type { Snapshot } from "./vm/snapshot/snapshot.js";
|
|
|
3
3
|
declare const SuspendError_base: Schema.Class<SuspendError, Schema.TaggedStruct<"SuspendError", {
|
|
4
4
|
readonly message: Schema.String;
|
|
5
5
|
readonly running: Schema.$Array<Schema.Struct<{
|
|
6
|
+
readonly key: Schema.String;
|
|
6
7
|
readonly path: Schema.String;
|
|
7
8
|
}>>;
|
|
8
9
|
}>, import("effect/Cause").YieldableError>;
|
|
9
10
|
/**
|
|
10
|
-
* A suspend that failed, leaving the run running: `running` names each host call that blocked it by its
|
|
11
|
-
* (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
|
|
11
|
+
* A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
|
|
12
|
+
* path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
|
|
12
13
|
* saved or was too large.
|
|
13
14
|
*/
|
|
14
15
|
export declare class SuspendError extends SuspendError_base {
|
package/dist/suspend-error.js
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
import { Schema } from "effect";
|
|
2
2
|
/**
|
|
3
|
-
* A suspend that failed, leaving the run running: `running` names each host call that blocked it by its
|
|
4
|
-
* (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
|
|
3
|
+
* A suspend that failed, leaving the run running: `running` names each host call that blocked it by its key and its
|
|
4
|
+
* path (`tools.x.y`, `search`, or an extension function's path such as `fetch`). Empty when the state couldn't be
|
|
5
5
|
* saved or was too large.
|
|
6
6
|
*/
|
|
7
7
|
export class SuspendError extends Schema.TaggedError()("SuspendError", {
|
|
8
8
|
message: Schema.String,
|
|
9
|
-
running: Schema.Array(Schema.Struct({ path: Schema.String })),
|
|
9
|
+
running: Schema.Array(Schema.Struct({ key: Schema.String, path: Schema.String })),
|
|
10
10
|
}) {
|
|
11
11
|
}
|
|
12
12
|
export class SnapshotError extends Error {
|
package/dist/tool-runtime.d.ts
CHANGED
|
@@ -2,13 +2,13 @@ import { Effect } from "effect";
|
|
|
2
2
|
import type { Json } from "./data.js";
|
|
3
3
|
import type { DiagnosticKind } from "./codemode.js";
|
|
4
4
|
import { type Namespace } from "./namespace.js";
|
|
5
|
-
import { type Tool } from "./tool.js";
|
|
5
|
+
import { type Durable, type Idempotent, type Tool, type ToolContext } from "./tool.js";
|
|
6
6
|
import type { Tools } from "./tools.js";
|
|
7
7
|
export declare const compareText: (left: string, right: string) => -1 | 0 | 1;
|
|
8
8
|
export type Services<T> = ServicesOf<T, []>;
|
|
9
9
|
type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends {
|
|
10
10
|
readonly _tag: "CodeModeTool";
|
|
11
|
-
readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, infer R>;
|
|
11
|
+
readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, infer R>;
|
|
12
12
|
} ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
|
|
13
13
|
export type ToolCall = {
|
|
14
14
|
readonly name: string;
|
|
@@ -17,6 +17,8 @@ export type ToolCall = {
|
|
|
17
17
|
export type ToolInvocation = {
|
|
18
18
|
readonly name: string;
|
|
19
19
|
readonly input: unknown;
|
|
20
|
+
/** The call's idempotency key, `<runId>:<callId>`: the same at every hook, and across a suspended run's resumes. */
|
|
21
|
+
readonly key: string;
|
|
20
22
|
};
|
|
21
23
|
/**
|
|
22
24
|
* A call the program is making to an extension global or module function, with its arguments. A module function is
|
|
@@ -44,8 +46,8 @@ export type Hooks<R = never> = {
|
|
|
44
46
|
readonly "extension.before"?: ((call: ExtensionInvocation) => Effect.Effect<void, unknown, R>) | undefined;
|
|
45
47
|
readonly "extension.after"?: ((call: ExtensionInvocation, result: CallResult) => Effect.Effect<void, never, R>) | undefined;
|
|
46
48
|
};
|
|
47
|
-
/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
|
|
48
|
-
export declare 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
|
|
49
|
+
/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */
|
|
50
|
+
export declare 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>;
|
|
49
51
|
export type ToolDescription = {
|
|
50
52
|
readonly path: string;
|
|
51
53
|
readonly description: string;
|
|
@@ -81,13 +83,32 @@ export declare class ToolRuntimeError extends Error {
|
|
|
81
83
|
readonly suggestions: ReadonlyArray<string>;
|
|
82
84
|
constructor(kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "ToolCallLimitExceeded">, message: string, suggestions?: ReadonlyArray<string>);
|
|
83
85
|
}
|
|
86
|
+
export type ExecuteCallOptions = {
|
|
87
|
+
readonly key?: string | undefined;
|
|
88
|
+
readonly admit?: ((name: string) => void) | undefined;
|
|
89
|
+
readonly detaching?: (() => boolean) | undefined;
|
|
90
|
+
};
|
|
84
91
|
/** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */
|
|
85
92
|
export type ToolRuntime<R = never> = {
|
|
86
93
|
readonly calls: Array<ToolCall>;
|
|
87
94
|
readonly hooks: Hooks<R>;
|
|
88
|
-
readonly
|
|
89
|
-
readonly
|
|
95
|
+
readonly invocations: Map<string, ToolInvocation>;
|
|
96
|
+
readonly record: (name: string) => void;
|
|
97
|
+
readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
|
|
98
|
+
readonly search: (args: Array<Json | undefined>, options?: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
|
|
90
99
|
readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
|
|
100
|
+
/** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */
|
|
101
|
+
readonly mode: (path: ReadonlyArray<string>) => Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
|
|
102
|
+
/** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */
|
|
103
|
+
readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, admit?: (name: string) => void) => Effect.Effect<Json, unknown, R>;
|
|
104
|
+
/**
|
|
105
|
+
* Waits for a durable tool's running work: its output, as `execute` gives it. `detaching` says whether an
|
|
106
|
+
* interruption detaches to suspend the run, which `tool.after` doesn't see, or ends the call, which it sees as
|
|
107
|
+
* interrupted.
|
|
108
|
+
*/
|
|
109
|
+
readonly wait: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, data: Json, detaching: () => boolean) => Effect.Effect<Json | undefined, unknown, R>;
|
|
110
|
+
/** Cancels a durable tool's started work when the run is interrupted or ends. */
|
|
111
|
+
readonly cancel: (path: ReadonlyArray<string>, data: Json) => Effect.Effect<void, unknown, R>;
|
|
91
112
|
};
|
|
92
113
|
/** Per-execution call state over tools prepared once for the runtime. */
|
|
93
114
|
export declare const make: <R>(prepared: Prepared<R>, maxToolCalls: number | undefined, hooks?: Hooks<R>) => ToolRuntime<R>;
|