@opencode/codemode 0.0.0-dev-970 → 0.0.0-dev-973

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 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, `extension.before`/`extension.after`
94
- receive `{ extension, name, args }`. An `after` hook also receives how the call ended (`success` with its value,
95
- `failure` with its error, or `interrupted`). A `before` hook runs before the call reaches the host, and a failing one
96
- denies it: the host function is never called, and the program catches the failure as a thrown error. A denied call
97
- fails the way the call itself would: a tool call or asynchronous global rejects its promise, and a synchronous global
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()`. `run()` runs it in
108
- the current fiber until it ends or is suspended, and gives a `CodeMode.Outcome`: a `Result`, or:
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`. A program runs once: running it again is a defect, so make another
132
- with `runtime.program` or `runtime.resume`. `run()` owns the run's host calls: interrupting it interrupts the program and
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
- `program.suspend(options?)` saves the run's state and stops it at once, and `run()` returns the same `Suspended`. It
136
- can be suspended only while no host call (tool, `search`, `fetch`, or extension call) is running. When one is in
137
- progress, `suspend` fails with a `CodeMode.SuspendError` naming each blocking call by its path (`tools.x.y`, `fetch`),
138
- and the run goes on untouched. Tool calls queued but not started don't block: they start on resume. Outcomes already
139
- waiting in the inbox are part of the state. A suspend after the run ended gives its result; one issued before `run()`
140
- has started waits for it to start (and for ever if it never runs).
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 extensions. The
148
- state is checked when the resumed program runs: its `run()` fails with a `CodeMode.SnapshotError` when it can't be
149
- resumed here or is malformed. Built-ins are saved by name and only their changes are copied.
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
 
@@ -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>>) => Program<R>;
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.length > 0,
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;
@@ -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 { name: options.name, globals: { ...options.globals } };
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";
@@ -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 path
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 {
@@ -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 path
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 {
@@ -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>) => 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 execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
89
- readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
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>;
@@ -4,11 +4,13 @@ import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, ident
4
4
  import { isNamespace } from "./namespace.js";
5
5
  import { isTool } from "./tool.js";
6
6
  export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
7
- /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
8
- export const hooked = (call, before, after, run) => {
7
+ /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */
8
+ export const hooked = (call, before, after, run, detaching) => {
9
9
  const observed = after === undefined
10
10
  ? run
11
11
  : Effect.onExit(run, (exit) => {
12
+ if (detaching?.())
13
+ return Effect.void;
12
14
  if (Exit.isSuccess(exit))
13
15
  return after(call, { status: "success", value: exit.value });
14
16
  if (Cause.hasInterruptsOnly(exit.cause))
@@ -237,51 +239,139 @@ export class ToolRuntimeError extends Error {
237
239
  /** Per-execution call state over tools prepared once for the runtime. */
238
240
  export const make = (prepared, maxToolCalls, hooks = {}) => {
239
241
  const calls = [];
242
+ const invocations = new Map();
240
243
  const root = prepared.root;
244
+ const runId = crypto.randomUUID();
245
+ let nextCallId = 0;
241
246
  const recordCall = (call) => {
242
247
  if (maxToolCalls !== undefined && calls.length >= maxToolCalls) {
243
248
  throw new ToolRuntimeError("ToolCallLimitExceeded", `Execution exceeded its tool-call limit of ${maxToolCalls}.`);
244
249
  }
245
250
  calls.push(call);
246
251
  };
247
- const executeTool = (name, tool, args) => Effect.gen(function* () {
252
+ const decode = (name, tool, args) => Effect.gen(function* () {
248
253
  const normalized = args.length === 0 ? [{}] : args;
249
254
  if (normalized.length !== 1)
250
255
  throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`);
251
- const input = yield* Effect.try({
256
+ return yield* Effect.try({
252
257
  try: () => decodeToolInput(tool, normalized[0]),
253
258
  catch: (cause) => new ToolRuntimeError("InvalidToolInput", `Invalid input for tool '${name}': ${String(cause)}`, name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."]),
254
259
  });
255
- yield* Effect.sync(() => recordCall({ name }));
256
- return yield* hooked({ name, input }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
257
- const raw = yield* Effect.suspend(() => tool.execute(input)).pipe(Effect.catchCause((cause) => {
258
- if (Cause.hasInterruptsOnly(cause))
259
- return Effect.interrupt;
260
- return Effect.fail(toolError(Cause.prettyErrors(cause)
261
- .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
262
- .join("\n")));
263
- }));
264
- // The same round trip a tool result would take through text: exact JSON.stringify semantics.
265
- return yield* Effect.try({
266
- try: () => {
267
- const text = JSON.stringify(decodeToolOutput(tool, raw));
268
- return text === undefined ? undefined : JSON.parse(text);
269
- },
270
- catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
271
- });
272
- }));
273
260
  });
261
+ // A tool's own failure becomes a ToolError; interruption passes through.
262
+ const failure = (effect) => effect.pipe(Effect.catchCause((cause) => {
263
+ if (Cause.hasInterruptsOnly(cause))
264
+ return Effect.interrupt;
265
+ return Effect.fail(toolError(Cause.prettyErrors(cause)
266
+ .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
267
+ .join("\n")));
268
+ }));
269
+ // The same round trip a tool result would take through text: exact JSON.stringify semantics.
270
+ const output = (name, tool, raw) => Effect.try({
271
+ try: () => {
272
+ const text = JSON.stringify(decodeToolOutput(tool, raw));
273
+ return text === undefined ? undefined : JSON.parse(text);
274
+ },
275
+ catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
276
+ });
277
+ const executeTool = (name, tool, args, options) => Effect.gen(function* () {
278
+ const key = options?.key ?? `${runId}:${nextCallId++}`;
279
+ const input = yield* decode(name, tool, args);
280
+ const admit = options?.admit;
281
+ yield* Effect.sync(() => (admit !== undefined ? admit(name) : recordCall({ name })));
282
+ return yield* hooked({ name, input, key }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
283
+ const raw = yield* failure(Effect.suspend(() => tool.execute(input, { key })));
284
+ return yield* output(name, tool, raw);
285
+ }), options?.detaching);
286
+ });
287
+ const durableTool = (path) => {
288
+ const segments = canonicalSegments(path);
289
+ const name = segments.join(".");
290
+ const tool = lookup(root, segments)?.tool;
291
+ if (tool?.mode?._tag !== "CodeModeDurable") {
292
+ throw new TypeError(`Tool '${name}' is not a durable tool.`);
293
+ }
294
+ return { name, tool, durable: tool.mode };
295
+ };
274
296
  return {
275
297
  calls,
276
298
  hooks,
299
+ invocations,
300
+ record: (name) => recordCall({ name }),
277
301
  keys: (path) => namespaceKeys(root, path),
278
- search: (args) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args)),
279
- execute: (path, args) => Effect.suspend(() => {
302
+ search: (args, options) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args, options)),
303
+ execute: (path, args, options) => Effect.suspend(() => {
280
304
  const segments = canonicalSegments(path);
281
305
  // Models often write `tools.search(...)` for the bare `search(...)`; honor it unless a tool owns that path.
282
306
  if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
283
- return executeTool("search", makeSearchTool(prepared.searchIndex), args);
284
- return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args);
307
+ return executeTool("search", makeSearchTool(prepared.searchIndex), args, options);
308
+ return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args, options);
309
+ }),
310
+ mode: (path) => {
311
+ const segments = canonicalSegments(path);
312
+ if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
313
+ return undefined;
314
+ return lookup(root, segments)?.tool?.mode;
315
+ },
316
+ start: (path, args, key, admit) => Effect.suspend(() => {
317
+ const found = durableTool(path);
318
+ return Effect.gen(function* () {
319
+ const input = yield* decode(found.name, found.tool, args);
320
+ yield* Effect.sync(() => (admit !== undefined ? admit(found.name) : recordCall({ name: found.name })));
321
+ const invocation = { name: found.name, input, key };
322
+ invocations.set(key, invocation);
323
+ const before = hooks["tool.before"];
324
+ const after = hooks["tool.after"];
325
+ const run = failure(Effect.suspend(() => found.durable.start(input, { key }))).pipe(Effect.flatMap((raw) => Effect.try({
326
+ try: () => {
327
+ const text = JSON.stringify(raw);
328
+ return text === undefined ? null : JSON.parse(text);
329
+ },
330
+ catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid start data from tool '${found.name}': ${cause}`),
331
+ })));
332
+ const observed = after === undefined
333
+ ? run
334
+ : Effect.onError(run, (cause) => {
335
+ invocations.delete(key);
336
+ if (Cause.hasInterruptsOnly(cause))
337
+ return after(invocation, { status: "interrupted" });
338
+ return after(invocation, { status: "failure", error: Cause.squash(cause) });
339
+ });
340
+ return yield* before === undefined ? observed : Effect.andThen(before(invocation), observed);
341
+ });
342
+ }),
343
+ wait: (path, args, key, data, detaching) => Effect.suspend(() => {
344
+ const found = durableTool(path);
345
+ const wait = found.durable.wait;
346
+ const after = hooks["tool.after"];
347
+ const run = Effect.gen(function* () {
348
+ const raw = yield* failure(Effect.suspend(() => wait(data, { key })));
349
+ return yield* output(found.name, found.tool, raw);
350
+ });
351
+ if (after === undefined)
352
+ return run;
353
+ const known = invocations.get(key);
354
+ const callEffect = known !== undefined
355
+ ? Effect.succeed(known)
356
+ : Effect.map(decode(found.name, found.tool, args), (input) => ({
357
+ name: found.name,
358
+ input,
359
+ key,
360
+ }));
361
+ return Effect.flatMap(callEffect, (call) => Effect.onExit(run, (exit) => {
362
+ if (detaching())
363
+ return Effect.void;
364
+ invocations.delete(key);
365
+ if (Exit.isSuccess(exit))
366
+ return after(call, { status: "success", value: exit.value });
367
+ if (Cause.hasInterruptsOnly(exit.cause))
368
+ return after(call, { status: "interrupted" });
369
+ return after(call, { status: "failure", error: Cause.squash(exit.cause) });
370
+ }));
371
+ }),
372
+ cancel: (path, data) => Effect.suspend(() => {
373
+ const cancel = durableTool(path).durable.cancel;
374
+ return failure(cancel(data));
285
375
  }),
286
376
  };
287
377
  };
package/dist/tool.d.ts CHANGED
@@ -38,13 +38,49 @@ export type JsonSchema = {
38
38
  };
39
39
  /** Either a validating Effect Schema or a render-only JSON Schema document. */
40
40
  export type SchemaType = Schema.Decoder<unknown> | JsonSchema;
41
+ /** Context passed to a tool call: its stable idempotency key (`<runId>:<callId>`). */
42
+ export type ToolContext = {
43
+ readonly key: string;
44
+ };
45
+ export type ExecuteFn<Input = unknown, Output = unknown, R = never> = (input: Input, context: ToolContext) => Effect.Effect<Output, unknown, R>;
46
+ /**
47
+ * A tool execution wrapper for idempotent work that is safe to run again. If a suspend lands while the call is running
48
+ * (`engine: "vm"`), the VM interrupts it without firing `tool.after`, keeps the call queued in the snapshot, and
49
+ * re-runs it on resume with the same `key` without double-counting against `maxToolCalls`.
50
+ */
51
+ export type Idempotent<Input = unknown, Output = unknown, R = never> = {
52
+ (input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>;
53
+ readonly _tag: "CodeModeIdempotent";
54
+ readonly execute: ExecuteFn<Input, Output, R>;
55
+ };
56
+ /**
57
+ * Options for `Tool.durable`: `start` begins the work under `key` and returns JSON `data` saved in the snapshot;
58
+ * `wait` connects to the running work and waits for its output; `cancel` stops the work when the run is interrupted
59
+ * for real or ends, never when it is suspended. `wait` is not tied to the program's JS `await`: the VM calls `wait`
60
+ * right after `start` returns, and again for every `started` call right at resume, whatever the program does with the
61
+ * promise.
62
+ */
63
+ export type DurableOptions<Data extends Schema.Json, Input = unknown, Output = unknown, RStart = never, RWait = never, RCancel = never> = {
64
+ readonly start: (input: Input, context: ToolContext) => Effect.Effect<Data, unknown, RStart>;
65
+ readonly wait: (data: NoInfer<Data>, context: ToolContext) => Effect.Effect<Output, unknown, RWait>;
66
+ readonly cancel: (data: NoInfer<Data>) => Effect.Effect<void, unknown, RCancel>;
67
+ };
68
+ /** A tool execution wrapper for work that keeps running across a suspend and reconnects through its JSON data. */
69
+ export type Durable<Input = unknown, Output = unknown, R = never> = {
70
+ (input: Input, context: ToolContext): Effect.Effect<Output, unknown, R>;
71
+ readonly _tag: "CodeModeDurable";
72
+ readonly start: (input: Input, context: ToolContext) => Effect.Effect<Schema.Json, unknown, R>;
73
+ readonly wait: (data: never, context: ToolContext) => Effect.Effect<Output, unknown, R>;
74
+ readonly cancel: (data: never) => Effect.Effect<void, unknown, R>;
75
+ };
41
76
  /** Executable tool exposed through CodeMode's `tools` object. */
42
77
  export type Tool<R = never> = {
43
78
  readonly _tag: "CodeModeTool";
44
79
  readonly description: string;
45
80
  readonly input: SchemaType;
46
81
  readonly output: SchemaType | undefined;
47
- readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, R>;
82
+ readonly execute: (input: unknown, context?: ToolContext) => Effect.Effect<unknown, unknown, R>;
83
+ readonly mode?: Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
48
84
  };
49
85
  type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown;
50
86
  type ResultType<S> = S extends undefined ? void : S extends Schema.Decoder<unknown> ? S["Encoded"] : unknown;
@@ -53,9 +89,16 @@ export type Options<I extends SchemaType, O extends SchemaType | undefined, R =
53
89
  readonly description: string;
54
90
  readonly input: I;
55
91
  readonly output?: O;
56
- readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>;
92
+ readonly execute: ExecuteFn<InputType<I>, ResultType<O>, R> | Idempotent<InputType<I>, ResultType<O>, R> | Durable<InputType<I>, ResultType<O>, R>;
57
93
  };
58
94
  export declare const isTool: <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined) => value is Tool<R>;
95
+ /** Marks a tool's `execute` function as safe to interrupt on suspend and re-run on resume with the same key. */
96
+ export declare const idempotent: <Input, Output, R = never>(execute: ExecuteFn<Input, Output, R>) => Idempotent<Input, Output, R>;
97
+ /**
98
+ * Wraps a tool's execution as `start`, `wait`, and `cancel` so work started before a suspend keeps running and
99
+ * reconnects through its JSON data on resume.
100
+ */
101
+ export declare 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>;
59
102
  /**
60
103
  * Declares one schema-described tool available to a CodeMode program through `tools.*`.
61
104
  *