From a882cf98a0f9eb94b2231229159ae6e01d7e4a72 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Wed, 28 Oct 2026 13:56:18 -0500 Subject: [PATCH] feat(codemode): let extension globals return Effects (#59948) --- packages/codemode/README.md | 19 ++++++ packages/codemode/src/codemode.ts | 40 +++++++---- packages/codemode/src/extension.ts | 22 ++++-- .../codemode/src/interpreter/extensions.ts | 67 ++++++++++++------- packages/codemode/test/extensions.test.ts | 65 +++++++++++++++++- packages/core/src/codemode/tool.ts | 6 +- 6 files changed, 176 insertions(+), 43 deletions(-) diff --git a/packages/codemode/README.md b/packages/codemode/README.md index 810945d48cd..2426e466071 100644 --- a/packages/codemode/README.md +++ b/packages/codemode/README.md @@ -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`. diff --git a/packages/codemode/src/codemode.ts b/packages/codemode/src/codemode.ts index edae39aeebf..50bf562a278 100644 --- a/packages/codemode/src/codemode.ts +++ b/packages/codemode/src/codemode.ts @@ -41,19 +41,27 @@ export type ResolvedExecutionLimits = { } /** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */ -export type Options = {}> = { +export type Options = {}, Extensions extends ReadonlyArray = []> = { /** Explicit tools exposed to the program as `tools`. */ tools?: Provided & Tools> /** Hooks around every tool and extension call the program makes; see `Hooks`. */ - hooks?: ToolRuntime.Hooks> + hooks?: ToolRuntime.Hooks> /** Host functions exposed as globals; see `Extension.make`. */ - extensions?: ReadonlyArray + 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, Extensions extends ReadonlyArray> = + | Services + | Extension.Services + /** Options for one CodeMode execution. */ -export type ExecuteOptions = {}> = Options & { +export type ExecuteOptions< + Provided extends Record = {}, + Extensions extends ReadonlyArray = [], +> = Options & { /** 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 = >( - options: ExecuteOptions, -): Effect.Effect> => make(options).execute(options.code) +export const execute = < + const Provided extends Record, + const Extensions extends ReadonlyArray = [], +>( + options: ExecuteOptions, +): Effect.Effect> => make(options).execute(options.code) -/** Creates an Effect-native runtime over explicit, schema-described tools. */ -export const make = = {}>( - options: Options = {}, -): Runtime> => { - const prepared = ToolRuntime.prepare((options.tools ?? {}) as Tools>) +/** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */ +export const make = < + const Provided extends Record = {}, + const Extensions extends ReadonlyArray = [], +>( + options: Options = {}, +): Runtime> => { + const prepared = ToolRuntime.prepare>( + (options.tools ?? {}) as Tools>, + ) const limits = resolveExecutionLimits(options.limits) const extensions = options.extensions ?? [] const bound = new Set(globalNames) diff --git a/packages/codemode/src/extension.ts b/packages/codemode/src/extension.ts index c50f15446d2..dc1493efff0 100644 --- a/packages/codemode/src/extension.ts +++ b/packages/codemode/src/extension.ts @@ -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> = Readonly>> = { readonly name: string - readonly globals: Readonly> + readonly globals: Globals } -export const make = (options: Extension): Extension => { +/** The Effect environment required by an extension's Effect-returning globals. */ +export type Services = E extends { readonly globals: infer Globals } + ? Globals[keyof Globals] extends infer Global + ? Global extends (...args: never) => infer Result + ? Effect.Services + : never + : never + : never + +export const make = >>( + options: Extension, +): Extension => { 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.`) diff --git a/packages/codemode/src/interpreter/extensions.ts b/packages/codemode/src/interpreter/extensions.ts index 93cc7ed76e3..6a2432a3418 100644 --- a/packages/codemode/src/interpreter/extensions.ts +++ b/packages/codemode/src/interpreter/extensions.ts @@ -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 = ( ctx: Interpreter, @@ -140,33 +140,33 @@ export const extensionGlobals = ( const wrap = (value: Function, label: string, describe?: (args: ReadonlyArray) => 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(value, args) const hooks = ctx.tools.hooks - const settle = (run: Effect.Effect) => - (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, 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 = ( ) } +/** + * 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 = (value: Function, args: ReadonlyArray) => { + 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 } + 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 diff --git a/packages/codemode/test/extensions.test.ts b/packages/codemode/test/extensions.test.ts index ab14d9af67c..4f861e75c3b 100644 --- a/packages/codemode/test/extensions.test.ts +++ b/packages/codemode/test/extensions.test.ts @@ -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 = [] @@ -254,6 +254,69 @@ describe("values are converted at the boundary, never shared", () => { }) }) +describe("Effect globals", () => { + class Session extends Context.Service()("test/Session") {} + const sent: Array = [] + 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 = runtime + // @ts-expect-error Session must be provided + const missing: CodeMode.Runtime = 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({ diff --git a/packages/core/src/codemode/tool.ts b/packages/core/src/codemode/tool.ts index 19f2be8b806..97709991184 100644 --- a/packages/core/src/codemode/tool.ts +++ b/packages/core/src/codemode/tool.ts @@ -250,7 +250,11 @@ function runtime(inventory: Inventory) { }) } const tools = renderTools(root) - const created = CodeMode.make({ tools, extensions: [CodeModeWeb.extension], hooks: runHooks }) + const created = CodeMode.make({ + tools, + extensions: [CodeModeWeb.extension], + hooks: runHooks, + }) runtimes.set(inventory, created) return created }