Skip to content

Commit 1c49e51

Browse files
authored
fix(codemode): run extension before hooks before the host call (#60024)
1 parent 76243df commit 1c49e51

4 files changed

Lines changed: 88 additions & 33 deletions

File tree

‎packages/codemode/README.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,33 +91,42 @@ runtime.execute(source) // Effect<CodeMode.Result, never, ToolServices>
9191
The Effect environment is inferred from the supplied tools. `hooks` surround every call the program makes into the
9292
host: `tool.before`/`tool.after` receive `{ name, input }` with decoded input, `extension.before`/`extension.after`
9393
receive `{ extension, name, args }`. An `after` hook also receives how the call ended (`success` with its value,
94-
`failure` with its error, or `interrupted`). A failing `before` hook denies the call, and the program catches the
95-
failure as a thrown error.
94+
`failure` with its error, or `interrupted`). A `before` hook runs before the call reaches the host, and a failing one
95+
denies it: the host function is never called, and the program catches the failure as a thrown error. A denied call
96+
fails the way the call itself would: a tool call or asynchronous global rejects its promise, and a synchronous global
97+
throws.
9698

9799
### `Extension.make`
98100

99101
Extensions are host functions a program calls directly as globals, such as `fetch`. Unlike tools they are not in the
100102
catalog, not counted against `maxToolCalls`, and not described to the model; the host decides what they mean.
101103

102104
```ts
103-
const web = Extension.make({ name: "web", globals: { fetch: (url: string) => globalThis.fetch(url) } })
105+
const web = Extension.make({ name: "web", globals: { fetch: async (url: string) => globalThis.fetch(url) } })
104106
const runtime = CodeMode.make({ tools, extensions: [web] })
105107
```
106108

107-
A global may return a value, a Promise, or an Effect. An Effect starts only after the `extension.before` hook admits
108-
the call, and its requirements join the runtime's environment the same way a tool's do, so the host can provide
109-
per-execution services such as the calling session:
109+
A global is synchronous unless it is an `async` function or is marked with `Extension.async`. Mark a plain function
110+
that returns a Promise or an Effect, so a denied call rejects its promise like any other failure:
111+
112+
```ts
113+
Extension.make({ name: "web", globals: { fetch: Extension.async((url: string) => globalThis.fetch(url)) } })
114+
```
115+
116+
A global may return a value, a Promise, or an Effect. An Effect's requirements join the runtime's environment the same
117+
way a tool's do, so the host can provide per-execution services such as the calling session:
110118

111119
```ts
112120
const web = Extension.make({
113121
name: "web",
114122
globals: {
115-
fetch: (url: string) =>
123+
fetch: Extension.async((url: string) =>
116124
Effect.gen(function* () {
117125
const session = yield* Session
118126
yield* session.authorize(url)
119127
return yield* Effect.promise(() => globalThis.fetch(url))
120128
}),
129+
),
121130
},
122131
})
123132
const result = yield* CodeMode.make({ extensions: [web] }).execute(code).pipe(Effect.provideService(Session, session))

‎packages/codemode/src/extension.ts‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,12 @@ import type { Effect } from "effect"
55
/**
66
* Host functions a program calls directly as globals. Values crossing in either direction are converted, never
77
* shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
8-
* same way. Extension calls are not tool calls. A global may return a value, a Promise, or an Effect; an Effect runs
9-
* only after the extension hooks admit the call, and its requirements join the runtime's environment.
8+
* same way. Extension calls are not tool calls. A global may return a value, a Promise, or an Effect, and an
9+
* Effect's requirements join the runtime's environment.
10+
*
11+
* A global is synchronous unless it is an `async` function or is marked with `async`. The `extension.before` hook
12+
* runs before the call, so a denied call never reaches the host; it fails the way the global would, by rejecting the
13+
* promise of an asynchronous global and by throwing from a synchronous one.
1014
*/
1115
export type Extension<Globals extends Readonly<Record<string, Function>> = Readonly<Record<string, Function>>> = {
1216
readonly name: string
@@ -32,3 +36,14 @@ export const make = <const Globals extends Readonly<Record<string, Function>>>(
3236
}
3337
return { name: options.name, globals: { ...options.globals } }
3438
}
39+
40+
const asyncGlobals = new WeakSet<Function>()
41+
const AsyncFunction = (async () => {}).constructor
42+
43+
/** Marks a global that returns a Promise or an Effect, so a denied call rejects its promise instead of throwing. */
44+
export const async = <F extends Function>(global: F): F => {
45+
asyncGlobals.add(global)
46+
return global
47+
}
48+
49+
export const isAsync = (global: Function) => global instanceof AsyncFunction || asyncGlobals.has(global)

‎packages/codemode/src/interpreter/extensions.ts‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
import { Effect } from "effect"
2-
import type { Extension } from "../extension.js"
2+
import { type Extension, isAsync } from "../extension.js"
33
import { type ExtensionInvocation, hooked } from "../tool-runtime.js"
44
import type { Interpreter } from "./interpreter.js"
55
import { createErrorValue, isErrorType } from "./intrinsics.js"
66
import { MAX_VALUE_DEPTH } from "./limits.js"
77
import { type AstNode, PendingThrow, Throw, typeError } from "./model.js"
8-
import type { Host } from "./runner.js"
98
import { fn } from "./native.js"
109
import {
1110
define,
@@ -134,25 +133,32 @@ export const extensionGlobals = <R>(
134133
throw typeError(`${label} produced ${describeHost(value)}, which the program cannot hold.`)
135134
}
136135

137-
// A host function as a program function. Arguments cross in; a global's call runs inside the host's extension
138-
// hooks, which see the host's own error on failure; then whatever came back, or was thrown, crosses out so the
139-
// program catches a copy. Functions inside results are part of a value's API and skip the hooks.
136+
// A host function as a program function. Arguments cross in; for a global, the `extension.before` hook runs before
137+
// the host function is called, so a call it denies never reaches the host. The host's result, or what it threw,
138+
// crosses out so the program catches a copy, and `extension.after` sees how the call ended. Functions inside
139+
// results are part of a value's API and skip the hooks.
140140
const wrap = (value: Function, label: string, describe?: (args: ReadonlyArray<unknown>) => ExtensionInvocation) =>
141-
fn(builtins, value.name, value.length, (_, values, site) => {
141+
fn(builtins, value.name, value.length, function* (_, values, site) {
142142
const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`))
143-
const call = callHost<R>(value, args)
143+
const cross = (reason: unknown) => new Throw(fromHost(reason, label))
144+
const call = describe?.(args)
144145
const hooks = ctx.tools.hooks
145-
const work = (
146-
describe === undefined
147-
? call.effect
148-
: hooked(describe(args), hooks["extension.before"], hooks["extension.after"], call.effect)
149-
).pipe(
150-
Effect.mapBoth({
151-
onFailure: (reason) => new Throw(fromHost(reason, label)),
152-
onSuccess: (result) => fromHost(result, label),
153-
}),
154-
)
155-
return call.async ? pending(work, site) : blocking(ctx.runner.blocking(work))
146+
const before = call && hooks["extension.before"]?.(call).pipe(Effect.mapError(cross))
147+
const after = call && hooks["extension.after"]
148+
const settle = (effect: Effect.Effect<unknown, unknown, R>) =>
149+
(after ? hooked(call, undefined, after, effect) : effect).pipe(
150+
Effect.mapBoth({ onFailure: cross, onSuccess: (result) => fromHost(result, label) }),
151+
)
152+
// A denied call fails the way the global would: an async global rejects its promise, a sync one throws.
153+
if (isAsync(value))
154+
return pending(
155+
Effect.andThen(before ?? Effect.void, settle(Effect.suspend(() => callHost<R>(value, args).effect))),
156+
site,
157+
)
158+
if (before) yield ctx.runner.blocking(before)
159+
const host = callHost<R>(value, args)
160+
if (host.async) return pending(settle(host.effect), site)
161+
return (yield ctx.runner.blocking(settle(host.effect))) as Value
156162
})
157163

158164
// An asynchronous host call: the program holds a promise that settles when the host's work does.
@@ -176,7 +182,7 @@ export const extensionGlobals = <R>(
176182

177183
/**
178184
* Calls a host function and describes what the program waits on. A returned Effect or Promise settles later; a
179-
* returned value or a throw settles now. An Effect has not started yet, so it runs only once the hooks admit it.
185+
* returned value or a throw settles now.
180186
*/
181187
const callHost = <R>(value: Function, args: ReadonlyArray<unknown>) => {
182188
try {
@@ -191,11 +197,6 @@ const callHost = <R>(value: Function, args: ReadonlyArray<unknown>) => {
191197
}
192198
}
193199

194-
// A synchronous host call: its hooks run before any other job, as the call itself did.
195-
function* blocking(host: Host) {
196-
return (yield host) as Value
197-
}
198-
199200
/**
200201
* An error crosses as its name, message, `cause`, and own enumerable fields, such as Node's `code`, `errno`,
201202
* `syscall`, and `path`. `stack` stays on its own side, and no field may shadow an Error method. A field that cannot

‎packages/codemode/test/codemode.test.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,36 @@ describe("CodeMode call hooks", () => {
285285
})
286286
})
287287

288+
test("a before hook runs before the host function, so a denied call never reaches the host", async () => {
289+
const called: Array<string> = []
290+
const record = <A>(name: string, result: () => A) => {
291+
called.push(name)
292+
return result()
293+
}
294+
const runtime = CodeMode.make({
295+
extensions: [
296+
Extension.make({
297+
name: "host",
298+
globals: {
299+
value: () => record("value", () => 1),
300+
asyncFn: async () => record("asyncFn", () => 1),
301+
promise: Extension.async(() => record("promise", () => Promise.resolve(1))),
302+
effect: Extension.async(() => Effect.sync(() => record("effect", () => 1))),
303+
},
304+
}),
305+
],
306+
hooks: { "extension.before": (call) => Effect.fail(new Error(`${call.name} is not allowed`)) },
307+
})
308+
const run = async (code: string) => (await Effect.runPromise(runtime.execute(code))) as { value?: unknown }
309+
310+
// A denied call fails the way the global would: an async global rejects its promise, a sync one throws.
311+
expect(
312+
await run(`return (await Promise.allSettled([asyncFn(), promise(), effect()])).map((r) => r.reason.message)`),
313+
).toMatchObject({ value: ["asyncFn is not allowed", "promise is not allowed", "effect is not allowed"] })
314+
expect(await run(`try { value() } catch (e) { return e.message }`)).toMatchObject({ value: "value is not allowed" })
315+
expect(called).toEqual([])
316+
})
317+
288318
test("see a tool defect as the failure the program gets, and an interrupted extension call", async () => {
289319
const events: Array<string> = []
290320
const broken = Tool.make({

0 commit comments

Comments
 (0)