mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-20 18:57:17 +03:00
feat(codemode): let extension globals return Effects (#59948)
This commit is contained in:
committed by
GitHub
Unverified
parent
7461d15208
commit
a882cf98a0
@@ -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`.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.`)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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({
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user