@opencode/codemode 0.0.0-dev-176 → 0.0.0-dev-187

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -104,6 +104,25 @@ const web = Extension.make({ name: "web", globals: { fetch: (url: string) => glo
104
104
  const runtime = CodeMode.make({ tools, extensions: [web] })
105
105
  ```
106
106
 
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:
110
+
111
+ ```ts
112
+ const web = Extension.make({
113
+ name: "web",
114
+ globals: {
115
+ fetch: (url: string) =>
116
+ Effect.gen(function* () {
117
+ const session = yield* Session
118
+ yield* session.authorize(url)
119
+ return yield* Effect.promise(() => globalThis.fetch(url))
120
+ }),
121
+ },
122
+ })
123
+ const result = yield* CodeMode.make({ extensions: [web] }).execute(code).pipe(Effect.provideService(Session, session))
124
+ ```
125
+
107
126
  Every value crossing in either direction is converted, never shared: arguments come in as copies, results go out as
108
127
  copies, and a function inside a result is callable the same way. A global that shadows a built-in or another
109
128
  extension throws at `CodeMode.make`.
@@ -179,7 +198,8 @@ every visible tool. Hosts render their own model-facing instructions from these
179
198
  and `CodeMode.toolExpression(path)` supply the exact callable forms.
180
199
 
181
200
  The synchronous `search(...)` built-in is always available. It supports exact-path lookup, namespace-scoped search,
182
- empty-query browsing, and pagination, and returns callable paths with full signatures. Search counts toward
201
+ empty-query browsing, and pagination, and returns callable paths with full signatures. Its result can be used directly,
202
+ awaited, or chained with `then`, `catch`, and `finally`, so programs work whichever way they treat it. Search counts toward
183
203
  `maxToolCalls`. Search also matches descriptions from enclosing `Namespace` values.
184
204
 
185
205
  ## Execution Limits
@@ -27,18 +27,20 @@ export type ResolvedExecutionLimits = {
27
27
  readonly maxOutputBytes: number | undefined;
28
28
  };
29
29
  /** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
30
- export type Options<Provided extends Record<string, unknown> = {}> = {
30
+ export type Options<Provided extends Record<string, unknown> = {}, Extensions extends ReadonlyArray<Extension> = []> = {
31
31
  /** Explicit tools exposed to the program as `tools`. */
32
32
  tools?: Provided & Tools<Services<Provided>>;
33
33
  /** Hooks around every tool and extension call the program makes; see `Hooks`. */
34
- hooks?: ToolRuntime.Hooks<Services<Provided>>;
34
+ hooks?: ToolRuntime.Hooks<Environment<Provided, Extensions>>;
35
35
  /** Host functions exposed as globals; see `Extension.make`. */
36
- extensions?: ReadonlyArray<Extension>;
36
+ extensions?: Extensions;
37
37
  /** Resource limits enforced on each execution. */
38
38
  limits?: ExecutionLimits;
39
39
  };
40
+ /** The Effect environment an execution needs: what the tools and the extensions' Effect globals require. */
41
+ export type Environment<Provided extends Record<string, unknown>, Extensions extends ReadonlyArray<Extension>> = Services<Provided> | Extension.Services<Extensions[number]>;
40
42
  /** Options for one CodeMode execution. */
41
- export type ExecuteOptions<Provided extends Record<string, unknown> = {}> = Options<Provided> & {
43
+ export type ExecuteOptions<Provided extends Record<string, unknown> = {}, Extensions extends ReadonlyArray<Extension> = []> = Options<Provided, Extensions> & {
42
44
  /** Source for one program in the supported JavaScript subset. */
43
45
  code: string;
44
46
  };
@@ -145,6 +147,6 @@ export type Runtime<R = never> = {
145
147
  readonly execute: (code: string) => Effect.Effect<Result, never, R>;
146
148
  };
147
149
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
148
- export declare const execute: <const Provided extends Record<string, unknown>>(options: ExecuteOptions<Provided>) => Effect.Effect<Result, never, Services<Provided>>;
149
- /** Creates an Effect-native runtime over explicit, schema-described tools. */
150
- export declare const make: <const Provided extends Record<string, unknown> = {}>(options?: Options<Provided>) => Runtime<Services<Provided>>;
150
+ export declare const execute: <const Provided extends Record<string, unknown>, const Extensions extends ReadonlyArray<Extension> = []>(options: ExecuteOptions<Provided, Extensions>) => Effect.Effect<Result, never, Environment<Provided, Extensions>>;
151
+ /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
152
+ export declare const make: <const Provided extends Record<string, unknown> = {}, const Extensions extends ReadonlyArray<Extension> = []>(options?: Options<Provided, Extensions>) => Runtime<Environment<Provided, Extensions>>;
package/dist/codemode.js CHANGED
@@ -57,7 +57,7 @@ const resolveExecutionLimits = (limits) => ({
57
57
  });
58
58
  /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
59
59
  export const execute = (options) => make(options).execute(options.code);
60
- /** Creates an Effect-native runtime over explicit, schema-described tools. */
60
+ /** Creates an Effect-native runtime over explicit, schema-described tools and extensions. */
61
61
  export const make = (options = {}) => {
62
62
  const prepared = ToolRuntime.prepare((options.tools ?? {}));
63
63
  const limits = resolveExecutionLimits(options.limits);
@@ -1,11 +1,17 @@
1
1
  export * as Extension from "./extension.js";
2
+ import type { Effect } from "effect";
2
3
  /**
3
4
  * Host functions a program calls directly as globals. Values crossing in either direction are converted, never
4
5
  * shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
5
- * same way. Extension calls are not tool calls.
6
+ * same way. Extension calls are not tool calls. A global may return a value, a Promise, or an Effect; an Effect runs
7
+ * only after the extension hooks admit the call, and its requirements join the runtime's environment.
6
8
  */
7
- export type Extension = {
9
+ export type Extension<Globals extends Readonly<Record<string, Function>> = Readonly<Record<string, Function>>> = {
8
10
  readonly name: string;
9
- readonly globals: Readonly<Record<string, Function>>;
11
+ readonly globals: Globals;
10
12
  };
11
- export declare const make: (options: Extension) => Extension;
13
+ /** The Effect environment required by an extension's Effect-returning globals. */
14
+ export type Services<E> = E extends {
15
+ readonly globals: infer Globals;
16
+ } ? Globals[keyof Globals] extends infer Global ? Global extends (...args: never) => infer Result ? Effect.Services<Result> : never : never : never;
17
+ export declare const make: <const Globals extends Readonly<Record<string, Function>>>(options: Extension<Globals>) => Extension<Globals>;
@@ -4,6 +4,6 @@ import { type Value } from "./objects.js";
4
4
  /**
5
5
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
6
6
  * built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
7
- * host Promise becomes a program promise.
7
+ * host Promise or Effect becomes a program promise.
8
8
  */
9
9
  export declare const extensionGlobals: <R>(ctx: Interpreter<R>, extensions: ReadonlyArray<Extension>) => ReadonlyArray<readonly [string, Value]>;
@@ -9,7 +9,7 @@ import { describeValue, isOpaque } from "./references.js";
9
9
  /**
10
10
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
11
11
  * built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
12
- * host Promise becomes a program promise.
12
+ * host Promise or Effect becomes a program promise.
13
13
  */
14
14
  export const extensionGlobals = (ctx, extensions) => {
15
15
  const builtins = ctx.builtins;
@@ -127,27 +127,43 @@ export const extensionGlobals = (ctx, extensions) => {
127
127
  // program catches a copy. Functions inside results are part of a value's API and skip the hooks.
128
128
  const wrap = (value, label, describe) => fn(builtins, value.name, value.length, (_, values, site) => {
129
129
  const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`));
130
+ const call = callHost(value, args);
130
131
  const hooks = ctx.tools.hooks;
131
- const settle = (run) => (describe === undefined
132
- ? run
133
- : 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)));
134
- let result;
135
- try {
136
- result = value.apply(undefined, args);
137
- }
138
- catch (reason) {
139
- return blocking(ctx.runner.blocking(settle(Effect.fail(reason))));
140
- }
141
- if (!(result instanceof Promise))
142
- return blocking(ctx.runner.blocking(settle(Effect.succeed(result))));
143
- const runner = ctx.runner;
144
- const promise = runner.newPromise();
145
- const resolving = runner.resolving(promise, site);
146
- runner.host(settle(Effect.tryPromise({ try: () => result, catch: (reason) => reason })), (settled) => (settled.ok ? resolving.resolve(settled.value) : resolving.reject(settled.error)), site);
147
- return promise;
132
+ const work = (describe === undefined
133
+ ? call.effect
134
+ : hooked(describe(args), hooks["extension.before"], hooks["extension.after"], call.effect)).pipe(Effect.mapBoth({
135
+ onFailure: (reason) => new Throw(fromHost(reason, label)),
136
+ onSuccess: (result) => fromHost(result, label),
137
+ }));
138
+ return call.async ? pending(work, site) : blocking(ctx.runner.blocking(work));
148
139
  });
140
+ // An asynchronous host call: the program holds a promise that settles when the host's work does.
141
+ const pending = (work, site) => {
142
+ const promise = ctx.runner.newPromise();
143
+ const resolving = ctx.runner.resolving(promise, site);
144
+ ctx.runner.host(work, (settled) => (settled.ok ? resolving.resolve(settled.value) : resolving.reject(settled.error)), site);
145
+ return promise;
146
+ };
149
147
  return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, wrap(value, name, (args) => ({ extension: extension.name, name, args }))]));
150
148
  };
149
+ /**
150
+ * Calls a host function and describes what the program waits on. A returned Effect or Promise settles later; a
151
+ * returned value or a throw settles now. An Effect has not started yet, so it runs only once the hooks admit it.
152
+ */
153
+ const callHost = (value, args) => {
154
+ try {
155
+ const result = value.apply(undefined, args);
156
+ // Extension.Services adds an Effect global's requirements to R.
157
+ if (Effect.isEffect(result))
158
+ return { async: true, effect: result };
159
+ if (result instanceof Promise)
160
+ return { async: true, effect: Effect.tryPromise({ try: () => result, catch: (reason) => reason }) };
161
+ return { async: false, effect: Effect.succeed(result) };
162
+ }
163
+ catch (reason) {
164
+ return { async: false, effect: Effect.fail(reason) };
165
+ }
166
+ };
151
167
  // A synchronous host call: its hooks run before any other job, as the call itself did.
152
168
  function* blocking(host) {
153
169
  return (yield host);
@@ -83,7 +83,7 @@ const symbolGlobal = (ctx) => {
83
83
  // A table rather than a list so the names are known before any runtime exists.
84
84
  const table = {
85
85
  tools: () => new ToolReference([]),
86
- search: (ctx) => native(ctx.builtins, { name: "search", call: (_, args) => ctx.tool(ctx.tools.search, args), callback: false }),
86
+ search: (ctx) => native(ctx.builtins, { name: "search", call: (_, args) => ctx.search(args), callback: false }),
87
87
  undefined: () => undefined,
88
88
  NaN: () => NaN,
89
89
  Infinity: () => Infinity,
@@ -33,4 +33,6 @@ export declare class Interpreter<R> {
33
33
  iterateDirect(value: Value): Cursor;
34
34
  /** Runs one host call to completion before any other job: arguments cross as JSON, the result comes back as values. */
35
35
  tool(run: ToolRuntime<R>["search"], args: Array<Value>): Generator<import("./runner.js").Signal, Value, import("effect/Schema").Json | undefined>;
36
+ /** The built-in search: its result is usable directly, and can also be awaited or chained like a Promise. */
37
+ search(args: Array<Value>): Generator<import("./runner.js").Signal, Value, import("effect/Schema").Json | undefined>;
36
38
  }
@@ -10,7 +10,7 @@ import { preserveConsumerError, toPrimitive } from "./callback.js";
10
10
  import { AsyncBoundary, Await, Call, Interruption, isEval, MAX_CALL_DEPTH, Runner, Slice, Task, Yield, normal, } from "./runner.js";
11
11
  import { describeValue, isOpaque, rejectCircularInsertion, typeofValue } from "./references.js";
12
12
  import { fn } from "./native.js";
13
- import { capability } from "./promises.js";
13
+ import { capability, promiseLike } from "./promises.js";
14
14
  import { ScopeStack } from "./scope.js";
15
15
  import { constructRegExp } from "../stdlib/regexp.js";
16
16
  import { enumerableSource } from "../stdlib/object.js";
@@ -290,6 +290,10 @@ export class Interpreter {
290
290
  json.push(yield* toBoundary(this, arg));
291
291
  return fromJson(this, (yield this.runner.blocking(run(json))));
292
292
  }
293
+ /** The built-in search: its result is usable directly, and can also be awaited or chained like a Promise. */
294
+ *search(args) {
295
+ return promiseLike(this, yield* this.tool(this.tools.search, args));
296
+ }
293
297
  }
294
298
  /** One activation: the top-level program or a single function call, evaluating against its own scope chain. */
295
299
  class Frame {
@@ -10,4 +10,9 @@ export declare const capability: <R>(ctx: Interpreter<R>, site: AstNode | undefi
10
10
  reject: (reason: unknown) => void;
11
11
  promise: PromiseObj;
12
12
  };
13
+ /**
14
+ * Lets a synchronous object result also be awaited or chained like a Promise. It inherits non-enumerable
15
+ * then/catch/finally that settle with a plain copy, so data views never show them and awaiting does not recurse.
16
+ */
17
+ export declare const promiseLike: <R>(ctx: Interpreter<R>, value: Value) => Value;
13
18
  export declare const promiseGlobal: <R>(ctx: Interpreter<R>) => import("./objects.js").Native;
@@ -1,5 +1,5 @@
1
1
  import { Throw, typeError } from "./model.js";
2
- import { Callable, define, get, hidden, Arr, Fn, PromiseObj, record } from "./objects.js";
2
+ import { Callable, define, get, hidden, Arr, Fn, Obj, PromiseObj, record } from "./objects.js";
3
3
  import { constructor, fn, methods, native, receiver, requiresNew } from "./native.js";
4
4
  import { createAggregateErrorValue, materialize } from "./errors.js";
5
5
  import { describeValue, typeofValue } from "./references.js";
@@ -231,6 +231,37 @@ function* constructPromise(ctx, executor, site) {
231
231
  }
232
232
  return made.promise;
233
233
  }
234
+ const promiseLikePrototypes = new WeakMap();
235
+ /**
236
+ * Lets a synchronous object result also be awaited or chained like a Promise. It inherits non-enumerable
237
+ * then/catch/finally that settle with a plain copy, so data views never show them and awaiting does not recurse.
238
+ */
239
+ export const promiseLike = (ctx, value) => {
240
+ if (!(value instanceof Obj) || value.proto !== ctx.builtins.Object)
241
+ return value;
242
+ value.proto = promiseLikePrototype(ctx);
243
+ return value;
244
+ };
245
+ const promiseLikePrototype = (ctx) => {
246
+ const cached = promiseLikePrototypes.get(ctx);
247
+ if (cached !== undefined)
248
+ return cached;
249
+ const proto = new Obj(ctx.builtins.Object);
250
+ const settled = (thisValue, name) => {
251
+ const source = receiver(Obj, thisValue, name);
252
+ const copy = new Obj(ctx.builtins.Object);
253
+ for (const [key, slot] of source.props)
254
+ copy.props.set(key, { ...slot });
255
+ return ctx.runner.promiseResolve(copy);
256
+ };
257
+ methods(ctx.builtins, proto, ["then", "catch", "finally"].map((name) => [
258
+ name,
259
+ name === "then" ? 2 : 1,
260
+ (thisValue, args, site) => instanceMethod(ctx, name, settled(thisValue, name), args, site),
261
+ ]));
262
+ promiseLikePrototypes.set(ctx, proto);
263
+ return proto;
264
+ };
234
265
  export const promiseGlobal = (ctx) => {
235
266
  const builtins = ctx.builtins;
236
267
  const proto = builtins.Promise;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "@opencode/codemode",
4
- "version": "0.0.0-dev-176",
4
+ "version": "0.0.0-dev-187",
5
5
  "description": "Effect-native confined code execution over schema-described tools",
6
6
  "type": "module",
7
7
  "license": "MIT",