feat(codemode): let each run pick which of the runtime's extensions it gets (#64482)

This commit is contained in:
Aiden Cline
2026-11-17 11:53:55 -06:00
committed by GitHub
Unverified
parent 2aed8226ee
commit f0def1f86f
4 changed files with 103 additions and 31 deletions
+52 -15
View File
@@ -4,7 +4,14 @@ import { scanTools } from "./scan.js"
import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js"
import type { Tools } from "./tools.js"
import { fromJson } from "./data.js"
import { finishExecution, resumeProgram, type Running, type Setup, startProgram, SuspendError } from "./runtime/execute.js"
import {
finishExecution,
resumeProgram,
type Running,
type Setup,
startProgram,
SuspendError,
} from "./runtime/execute.js"
import { extensionGlobals } from "./runtime/extensions.js"
import { globalNames } from "./runtime/globals.js"
import { fromBytes, type Snapshot, SnapshotError, type SnapshotHeader, toBytes } from "./snapshot/snapshot.js"
@@ -46,8 +53,18 @@ export type ResolvedExecutionLimits = {
readonly maxOutputBytes: number | undefined
}
/** Options for one run of a runtime's program: `Runtime.execute`, `Runtime.program`, and `Runtime.resume`. */
export type RunOptions = {
/**
* Which of the runtime's extensions this run gets as globals; all of them by default. Each must be one the runtime
* was made with, so its services are already part of the runtime's environment. A resumed run needs the ones it
* started with.
*/
readonly extensions?: ReadonlyArray<Extension>
}
/** Options for `Runtime.program`. */
export type ProgramOptions = {
export type ProgramOptions = RunOptions & {
/** Names this run's host calls (`<runId>:<callId>`); a random UUID by default. */
readonly runId?: string
}
@@ -157,7 +174,11 @@ export type Outcome = Result | Suspended
/** Reusable confined runtime over explicit tools and extensions. */
export type Runtime<R = never> = {
readonly catalog: ReadonlyArray<ToolDescription>
readonly execute: (code: string, bindings?: Readonly<Record<string, DataValue>>) => Effect.Effect<Result, never, R>
readonly execute: (
code: string,
bindings?: Readonly<Record<string, DataValue>>,
options?: RunOptions,
) => Effect.Effect<Result, never, R>
/** A program ready to run once; nothing runs until `program.run()`. */
readonly program: (
code: string,
@@ -169,7 +190,7 @@ export type Runtime<R = never> = {
* same build with the same extensions. The state is checked when it runs: `run()` fails with a `SnapshotError` when
* it can't be resumed here.
*/
readonly resume: (state: Snapshot | Uint8Array) => Program<R, SnapshotError>
readonly resume: (state: Snapshot | Uint8Array, options?: RunOptions) => Program<R, SnapshotError>
}
/**
@@ -217,7 +238,7 @@ export function make<
type R = Environment<Provided, Extensions>
const prepared = ToolRuntime.prepare<R>((options.tools ?? {}) as Tools<Services<Provided>>)
const limits = resolveExecutionLimits(options.limits)
const extensions = options.extensions ?? []
const extensions: ReadonlyArray<Extension> = options.extensions ?? []
const bound = new Set(globalNames)
for (const extension of extensions) {
for (const name of Object.keys(extension.globals)) {
@@ -225,27 +246,43 @@ export function make<
bound.add(name)
}
}
const setup: Setup<R> = {
prepared,
limits,
hooks: options.hooks ?? {},
globals: extensions.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, extensions),
lossy: extensions.some((extension) => extension.snapshot === undefined),
const setupFor = (selected: ReadonlyArray<Extension> = extensions): Setup<R> => {
for (const extension of selected) {
if (!extensions.includes(extension)) {
throw new TypeError(`Extension "${extension.name}" isn't one this runtime was made with.`)
}
}
// In the runtime's order, so the same extensions picked in any order give the same globals, and resume alike.
const picked = extensions.filter((extension) => selected.includes(extension))
return {
prepared,
limits,
hooks: options.hooks ?? {},
globals: picked.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, picked),
lossy: picked.some((extension) => extension.snapshot === undefined),
}
}
const setup = setupFor()
const data = (bindings: Readonly<Record<string, DataValue>> | undefined) =>
bindings === undefined
? undefined
: (ctx: Parameters<typeof fromJson>[0]) =>
Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)] as const)
const program = (code: string, bindings?: Readonly<Record<string, DataValue>>, programOptions?: ProgramOptions) =>
makeProgram(() => Effect.succeed(startProgram(setup, code, data(bindings), programOptions?.runId)))
const program = (code: string, bindings?: Readonly<Record<string, DataValue>>, programOptions?: ProgramOptions) => {
const run = programOptions?.extensions === undefined ? setup : setupFor(programOptions.extensions)
return makeProgram(() => Effect.succeed(startProgram(run, code, data(bindings), programOptions?.runId)))
}
return {
get catalog() {
return prepared.catalog
},
execute: (code, bindings) => Effect.suspend(() => finishExecution(program(code, bindings).run())),
execute: (code, bindings, runOptions) =>
Effect.suspend(() => finishExecution(program(code, bindings, runOptions).run())),
program,
resume: (state) => makeProgram(() => resumeProgram(setup, state)),
resume: (state, runOptions) => {
const run = runOptions?.extensions === undefined ? setup : setupFor(runOptions.extensions)
return makeProgram(() => resumeProgram(run, state))
},
}
}
+1
View File
@@ -13,6 +13,7 @@ export {
type Outcome,
type Program,
type ProgramOptions,
type RunOptions,
type Runtime,
type Snapshot,
type SnapshotHeader,
+17
View File
@@ -659,6 +659,23 @@ describe("configuration", () => {
})
})
test("a run can get only some of the runtime's extensions", async () => {
const files = Extension.make({ name: "files", globals: { read: () => "text" } })
const target = CodeMode.make({ extensions: [extension, files] })
expect(await value(`return [typeof read, typeof later]`, target)).toEqual(["function", "function"])
const only = await Effect.runPromise(
target.execute(`return [typeof read, typeof later, await later(1)]`, undefined, { extensions: [extension] }),
)
expect(only).toMatchObject({ ok: true, value: ["undefined", "function", 2] })
const none = await Effect.runPromise(
target.execute(`return [typeof read, typeof later]`, undefined, { extensions: [] }),
)
expect(none).toMatchObject({ ok: true, value: ["undefined", "undefined"] })
expect(() =>
target.program(`1`, undefined, { extensions: [Extension.make({ name: "other", globals: { f: () => 1 } })] }),
).toThrow(`Extension "other" isn't one this runtime was made with.`)
})
test("a global must be a function or an object", () => {
expect(() => Extension.make({ name: "bad", globals: { n: 1 as never } })).toThrow(
'Extension "bad" global "n" must be a function or an object.',
+33 -16
View File
@@ -450,9 +450,7 @@ describe("suspend", () => {
test("the snapshot codec does not import Effect", async () => {
for (const file of ["codec.ts", "snapshot.ts"]) {
expect(await Bun.file(path.join(import.meta.dir, "../src/snapshot", file)).text()).not.toMatch(
/from "effect"/,
)
expect(await Bun.file(path.join(import.meta.dir, "../src/snapshot", file)).text()).not.toMatch(/from "effect"/)
}
})
})
@@ -510,9 +508,7 @@ describe("resume", () => {
)
const saved = suspendedOf(await Effect.runPromise(long.suspend))
expect(
await Effect.runPromise(
background(CodeMode.make({ tools: { step: step2.tool } }).resume(saved.state)).result,
),
await Effect.runPromise(background(CodeMode.make({ tools: { step: step2.tool } }).resume(saved.state)).result),
).toMatchObject({ ok: true, truncated: true })
})
@@ -538,6 +534,31 @@ describe("resume", () => {
expect(timedOut).toMatchObject({ ok: false, error: { kind: "TimeoutExceeded" }, toolCalls: [{ name: "step" }] })
})
test("a run started with some of the runtime's extensions resumes with the same ones, in any order", async () => {
const now = Extension.make({ name: "now", globals: { now: () => 7 } })
const later = Extension.make({ name: "later", globals: { later: () => 8 } })
const unused = Extension.make({ name: "unused", globals: { unused: () => 1 } })
const step = stepTool()
const runtime = CodeMode.make({ tools: { step: step.tool }, extensions: [now, later, unused] })
const run = background(
runtime.program(
`await tools.step({ value: 1 }); const t = Date.now(); while (Date.now() - t < 300) {} return [now(), later(), typeof unused]`,
undefined,
{ extensions: [later, now] },
),
)
await step.called()
await Bun.sleep(10)
const state = suspendedOf(await Effect.runPromise(run.suspend)).state
expect((await refusal(runtime.resume(state))).message).toMatch("saved by a runtime with other host globals")
expect((await refusal(runtime.resume(state, { extensions: [now] }))).message).toMatch(
"saved by a runtime with other host globals",
)
expect(
await Effect.runPromise(background(runtime.resume(state, { extensions: [now, later, now] })).result),
).toMatchObject({ ok: true, value: [7, 8, "undefined"] })
})
test("a state is refused by another build, other extensions, or a changed source", async () => {
const { suspended } = await suspendAt(
`await tools.step({ value: 1 }); const t = Date.now(); while (Date.now() - t < 300) {} return 1`,
@@ -587,9 +608,7 @@ describe("resume", () => {
[extension],
)
const outcome = await Effect.runPromise(
background(
CodeMode.make({ tools: { step: step.tool }, extensions: [extension] }).resume(suspended.state),
).result,
background(CodeMode.make({ tools: { step: step.tool }, extensions: [extension] }).resume(suspended.state)).result,
)
expect(outcome).toMatchObject({
ok: true,
@@ -647,8 +666,7 @@ describe("resume", () => {
}`
const { step, suspended } = await suspendAt(code)
const outcome = await Effect.runPromise(
background(CodeMode.make({ tools: { step: step.tool } }).resume(CodeMode.toBytes(suspended.state)))
.result,
background(CodeMode.make({ tools: { step: step.tool } }).resume(CodeMode.toBytes(suspended.state))).result,
)
expect(outcome).toMatchObject({
ok: true,
@@ -1295,9 +1313,9 @@ describe("idempotent and durable tools", () => {
})
const toolSets: ReadonlyArray<Record<string, Tool.Tool>> = [{}, { job: plainTool }, { job: read.tool }]
for (const tools of toolSets) {
expect(
(await refusal(CodeMode.make({ tools }).resume(suspendedWhileStarted.state))).message,
).toContain("cannot resume because that tool is no longer a durable tool")
expect((await refusal(CodeMode.make({ tools }).resume(suspendedWhileStarted.state))).message).toContain(
"cannot resume because that tool is no longer a durable tool",
)
}
// Complete `job` while `read` is still running: `job` moves to the inbox with its `data` cleared.
@@ -1514,8 +1532,7 @@ describe("extension snapshot hooks", () => {
const other = Extension.make({ name: "other", globals: extension.globals, snapshot: extension.snapshot })
for (const extensions of [[], [unhooked], [other]]) {
expect(
(await refusal(CodeMode.make({ tools: { job: jobs.tool }, extensions }).resume(suspended.state)))
.message,
(await refusal(CodeMode.make({ tools: { job: jobs.tool }, extensions }).resume(suspended.state))).message,
).toBe("This state was saved by a runtime with other host globals (extensions); resume it with the same ones.")
}
})