feat(codemode): let extension globals return Effects (#59948)

This commit is contained in:
Aiden Cline
2026-10-28 13:56:18 -05:00
committed by GitHub
Unverified
parent 7461d15208
commit a882cf98a0
6 changed files with 176 additions and 43 deletions
+19
View File
@@ -104,6 +104,25 @@ const web = Extension.make({ name: "web", globals: { fetch: (url: string) => glo
const runtime = CodeMode.make({ tools, extensions: [web] })
```
A global may return a value, a Promise, or an Effect. An Effect starts only after the `extension.before` hook admits
the call, and its requirements join the runtime's environment the same way a tool's do, so the host can provide
per-execution services such as the calling session:
```ts
const web = Extension.make({
name: "web",
globals: {
fetch: (url: string) =>
Effect.gen(function* () {
const session = yield* Session
yield* session.authorize(url)
return yield* Effect.promise(() => globalThis.fetch(url))
}),
},
})
const result = yield* CodeMode.make({ extensions: [web] }).execute(code).pipe(Effect.provideService(Session, session))
```
Every value crossing in either direction is converted, never shared: arguments come in as copies, results go out as
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`.
+28 -12
View File
@@ -41,19 +41,27 @@ export type ResolvedExecutionLimits = {
}
/** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
export type Options<Provided extends Record<string, unknown> = {}> = {
export type Options<Provided extends Record<string, unknown> = {}, Extensions extends ReadonlyArray<Extension> = []> = {
/** Explicit tools exposed to the program as `tools`. */
tools?: Provided & Tools<Services<Provided>>
/** Hooks around every tool and extension call the program makes; see `Hooks`. */
hooks?: ToolRuntime.Hooks<Services<Provided>>
hooks?: ToolRuntime.Hooks<Environment<Provided, Extensions>>
/** Host functions exposed as globals; see `Extension.make`. */
extensions?: ReadonlyArray<Extension>
extensions?: Extensions
/** Resource limits enforced on each execution. */
limits?: ExecutionLimits
}
/** The Effect environment an execution needs: what the tools and the extensions' Effect globals require. */
export type Environment<Provided extends Record<string, unknown>, Extensions extends ReadonlyArray<Extension>> =
| Services<Provided>
| Extension.Services<Extensions[number]>
/** Options for one CodeMode execution. */
export type ExecuteOptions<Provided extends Record<string, unknown> = {}> = Options<Provided> & {
export type ExecuteOptions<
Provided extends Record<string, unknown> = {},
Extensions extends ReadonlyArray<Extension> = [],
> = Options<Provided, Extensions> & {
/** Source for one program in the supported JavaScript subset. */
code: string
}
@@ -137,15 +145,23 @@ const resolveExecutionLimits = (limits?: ExecutionLimits): ResolvedExecutionLimi
})
/** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
export const execute = <const Provided extends Record<string, unknown>>(
options: ExecuteOptions<Provided>,
): Effect.Effect<Result, never, Services<Provided>> => make(options).execute(options.code)
export const execute = <
const Provided extends Record<string, unknown>,
const Extensions extends ReadonlyArray<Extension> = [],
>(
options: ExecuteOptions<Provided, Extensions>,
): Effect.Effect<Result, never, Environment<Provided, Extensions>> => make(options).execute(options.code)
/** Creates an Effect-native runtime over explicit, schema-described tools. */
export const make = <const Provided extends Record<string, unknown> = {}>(
options: Options<Provided> = {},
): Runtime<Services<Provided>> => {
const prepared = ToolRuntime.prepare((options.tools ?? {}) as Tools<Services<Provided>>)
/** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
export const make = <
const Provided extends Record<string, unknown> = {},
const Extensions extends ReadonlyArray<Extension> = [],
>(
options: Options<Provided, Extensions> = {},
): Runtime<Environment<Provided, Extensions>> => {
const prepared = ToolRuntime.prepare<Environment<Provided, Extensions>>(
(options.tools ?? {}) as Tools<Services<Provided>>,
)
const limits = resolveExecutionLimits(options.limits)
const extensions = options.extensions ?? []
const bound = new Set(globalNames)
+18 -4
View File
@@ -1,16 +1,30 @@
export * as Extension from "./extension.js"
import type { Effect } from "effect"
/**
* Host functions a program calls directly as globals. Values crossing in either direction are converted, never
* shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
* same way. Extension calls are not tool calls.
* same way. Extension calls are not tool calls. A global may return a value, a Promise, or an Effect; an Effect runs
* only after the extension hooks admit the call, and its requirements join the runtime's environment.
*/
export type Extension = {
export type Extension<Globals extends Readonly<Record<string, Function>> = Readonly<Record<string, Function>>> = {
readonly name: string
readonly globals: Readonly<Record<string, Function>>
readonly globals: Globals
}
export const make = (options: Extension): Extension => {
/** The Effect environment required by an extension's Effect-returning globals. */
export type Services<E> = E extends { readonly globals: infer Globals }
? Globals[keyof Globals] extends infer Global
? Global extends (...args: never) => infer Result
? Effect.Services<Result>
: never
: never
: never
export const make = <const Globals extends Readonly<Record<string, Function>>>(
options: Extension<Globals>,
): Extension<Globals> => {
for (const [name, value] of Object.entries(options.globals)) {
if (typeof value !== "function") {
throw new TypeError(`Extension "${options.name}" global "${name}" must be a function.`)
+42 -25
View File
@@ -4,7 +4,7 @@ import { type ExtensionInvocation, hooked } from "../tool-runtime.js"
import type { Interpreter } from "./interpreter.js"
import { createErrorValue, isErrorType } from "./intrinsics.js"
import { MAX_VALUE_DEPTH } from "./limits.js"
import { PendingThrow, Throw, typeError } from "./model.js"
import { type AstNode, PendingThrow, Throw, typeError } from "./model.js"
import type { Host } from "./runner.js"
import { fn } from "./native.js"
import {
@@ -32,7 +32,7 @@ import { describeValue, isOpaque } from "./references.js"
/**
* The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
* built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
* host Promise becomes a program promise.
* host Promise or Effect becomes a program promise.
*/
export const extensionGlobals = <R>(
ctx: Interpreter<R>,
@@ -140,33 +140,33 @@ export const extensionGlobals = <R>(
const wrap = (value: Function, label: string, describe?: (args: ReadonlyArray<unknown>) => ExtensionInvocation) =>
fn(builtins, value.name, value.length, (_, values, site) => {
const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`))
const call = callHost<R>(value, args)
const hooks = ctx.tools.hooks
const settle = (run: Effect.Effect<unknown, unknown, R>) =>
(describe === undefined
? run
: hooked(describe(args), hooks["extension.before"], hooks["extension.after"], run)
).pipe(
Effect.mapError((reason) => new Throw(fromHost(reason, label))),
Effect.map((settled) => fromHost(settled, label)),
)
let result: unknown
try {
result = value.apply(undefined, args)
} catch (reason) {
return blocking(ctx.runner.blocking(settle(Effect.fail(reason))))
}
if (!(result instanceof Promise)) return blocking(ctx.runner.blocking(settle(Effect.succeed(result))))
const runner = ctx.runner
const promise = runner.newPromise()
const resolving = runner.resolving(promise, site)
runner.host(
settle(Effect.tryPromise({ try: () => result, catch: (reason) => reason })),
(settled) => (settled.ok ? resolving.resolve(settled.value as Value) : resolving.reject(settled.error)),
site,
const work = (
describe === undefined
? call.effect
: hooked(describe(args), hooks["extension.before"], hooks["extension.after"], call.effect)
).pipe(
Effect.mapBoth({
onFailure: (reason) => new Throw(fromHost(reason, label)),
onSuccess: (result) => fromHost(result, label),
}),
)
return promise
return call.async ? pending(work, site) : blocking(ctx.runner.blocking(work))
})
// An asynchronous host call: the program holds a promise that settles when the host's work does.
const pending = (work: Effect.Effect<Value, Throw, R>, site: AstNode | undefined) => {
const promise = ctx.runner.newPromise()
const resolving = ctx.runner.resolving(promise, site)
ctx.runner.host(
work,
(settled) => (settled.ok ? resolving.resolve(settled.value as Value) : resolving.reject(settled.error)),
site,
)
return promise
}
return extensions.flatMap((extension) =>
Object.entries(extension.globals).map(
([name, value]) => [name, wrap(value, name, (args) => ({ extension: extension.name, name, args }))] as const,
@@ -174,6 +174,23 @@ export const extensionGlobals = <R>(
)
}
/**
* Calls a host function and describes what the program waits on. A returned Effect or Promise settles later; a
* returned value or a throw settles now. An Effect has not started yet, so it runs only once the hooks admit it.
*/
const callHost = <R>(value: Function, args: ReadonlyArray<unknown>) => {
try {
const result: unknown = value.apply(undefined, args)
// Extension.Services adds an Effect global's requirements to R.
if (Effect.isEffect(result)) return { async: true, effect: result as Effect.Effect<unknown, unknown, R> }
if (result instanceof Promise)
return { async: true, effect: Effect.tryPromise({ try: () => result, catch: (reason) => reason }) }
return { async: false, effect: Effect.succeed(result) }
} catch (reason) {
return { async: false, effect: Effect.fail(reason) }
}
}
// A synchronous host call: its hooks run before any other job, as the call itself did.
function* blocking(host: Host) {
return (yield host) as Value
+64 -1
View File
@@ -1,5 +1,5 @@
import { describe, expect, test } from "bun:test"
import { Effect, Schema } from "effect"
import { Context, Effect, Schema } from "effect"
import { CodeMode, Extension, Tool } from "../src/index.js"
const held: Array<unknown> = []
@@ -254,6 +254,69 @@ describe("values are converted at the boundary, never shared", () => {
})
})
describe("Effect globals", () => {
class Session extends Context.Service<Session, { readonly id: string }>()("test/Session") {}
const sent: Array<string> = []
const web = Extension.make({
name: "web",
globals: {
fetch: (url: string) =>
Effect.gen(function* () {
const session = yield* Session
sent.push(url)
return { url, session: session.id }
}),
fail: () => Effect.fail(new RangeError("denied")),
},
})
test("the runtime requires what the Effect globals require", () => {
const runtime = CodeMode.make({ extensions: [web] })
const provided: CodeMode.Runtime<Session> = runtime
// @ts-expect-error Session must be provided
const missing: CodeMode.Runtime<never> = runtime
expect([provided, missing]).toEqual([runtime, runtime])
// An explicit tools type argument must name the extensions too, so their requirements are never dropped.
// @ts-expect-error web is not in the default empty extensions list
expect(CodeMode.make<{}>({ extensions: [web] })).toBeDefined()
})
test("an Effect global is a promise that runs with the execution's services", async () => {
sent.length = 0
const result = await Effect.runPromise(
CodeMode.make({ extensions: [web] })
.execute(`const pending = fetch("https://a.test/"); return [pending instanceof Promise, await pending]`)
.pipe(Effect.provideService(Session, { id: "ses_1" })),
)
expect(result).toMatchObject({ ok: true, value: [true, { url: "https://a.test/", session: "ses_1" }] })
expect(sent).toEqual(["https://a.test/"])
})
test("a failing Effect rejects with the host's error", async () => {
const result = await Effect.runPromise(
CodeMode.make({ extensions: [web] })
.execute(`try { await fail() } catch (e) { return [e instanceof RangeError, e.message] }`)
.pipe(Effect.provideService(Session, { id: "ses_1" })),
)
expect(result).toMatchObject({ ok: true, value: [true, "denied"] })
})
test("a denying before hook stops the Effect before it runs", async () => {
sent.length = 0
const runtime = CodeMode.make({
extensions: [web],
hooks: { "extension.before": (call) => Effect.fail(new Error(`${call.name} is not allowed`)) },
})
const result = await Effect.runPromise(
runtime
.execute(`try { await fetch("https://a.test/") } catch (e) { return e.message }`)
.pipe(Effect.provideService(Session, { id: "ses_1" })),
)
expect(result).toMatchObject({ ok: true, value: "fetch is not allowed" })
expect(sent).toEqual([])
})
})
describe("host errors", () => {
test("a synchronous throw becomes the matching program error", async () => {
const target = CodeMode.make({
+5 -1
View File
@@ -250,7 +250,11 @@ function runtime(inventory: Inventory) {
})
}
const tools = renderTools(root)
const created = CodeMode.make<typeof tools>({ tools, extensions: [CodeModeWeb.extension], hooks: runHooks })
const created = CodeMode.make<typeof tools, [typeof CodeModeWeb.extension]>({
tools,
extensions: [CodeModeWeb.extension],
hooks: runHooks,
})
runtimes.set(inventory, created)
return created
}