diff --git a/bun.lock b/bun.lock index 631d9ded9aa..3a0a9482a20 100644 --- a/bun.lock +++ b/bun.lock @@ -200,6 +200,7 @@ "dependencies": { "acorn": "8.15.0", "effect": "catalog:", + "luaparse": "0.3.1", }, "devDependencies": { "@tsconfig/bun": "catalog:", diff --git a/packages/codemode/README.md b/packages/codemode/README.md index 83e2408bd64..ee85e6ee3c6 100644 --- a/packages/codemode/README.md +++ b/packages/codemode/README.md @@ -1,8 +1,9 @@ # @opencode/codemode -This is our take on code mode: a lightweight, pure interpreter for a JavaScript-like language built around calling -tools. It supports familiar JavaScript syntax with a few key differences and limitations. See the -[interpreter support checklist](./interpreter-support.md) for more details. +Code Mode runs small programs over tools supplied by the host. OpenCode's agent-facing `execute` tool runs **Lua**. +The package also supports its existing JavaScript interpreter: `CodeMode.make` and `CodeMode.execute` default to +JavaScript for compatibility. Set `language: "lua"` for Lua or `language: "javascript"` to pin JavaScript. Neither +parser retries a failed program in the other language. Stored schedule checks remain JavaScript. Rather than trying to sandbox arbitrary JavaScript, CodeMode only runs the language features we implement. Programs cannot directly access the network, filesystem, processes, or application APIs. They can interact with the outside @@ -11,7 +12,32 @@ world only through tools provided by the host, which can also limit execution ti The idea of code mode was originally introduced by Cloudflare. See [their post](https://blog.cloudflare.com/code-mode/) to learn more about the concept and their isolate-based approach. -## How it differs from JavaScript +## Writing a Lua program + +```lua +local matches = search({ query = "order lookup" }) +local order = tools.orders["lookup-by-id"]({ id = "order_42" }) +return { id = order.id, needsAttention = order.status ~= "complete" } +``` + +Use the exact path returned by `search`; the input is a Lua table, not a JavaScript object literal. Calls wait for the +tool's Effect in the execution's environment, so the next statement sees the result. Calls within one Lua program +are sequential: there is no `await`, `Promise.all`, detached work, or parallel Lua task API. Independent executions +still have separate state and can run concurrently. + +- Use an explicit `return`: only the first value is exported. Falling off the end or returning `nil` yields JSON null. +- Tables with contiguous integer keys starting at **1** are arrays; tables with string keys are objects. `{}` makes + an empty object; `json.array()` makes an empty array. Arrays and objects received from a tool keep their shape + even when empty. Mixed-key, sparse, cyclic and non-data results cannot cross to the host. +- `nil` removes a table field. Use `json.null` to keep a JSON null in a field or array slot. +- Use `local ok, result = pcall(tools.ns.lookup, { id = id })` to recover from an ordinary failed call. On failure + the program sees a message, not a host exception. Interruption and resource exhaustion cannot be caught this way. +- Only explicit capabilities can enter host code. Tools, search, bindings and extension results cross as plain data, + never a host object, function, Promise or proxy. Declare Lua globals with `Extension.lua({ name, globals })`: + each function returns an Effect producing JSON (or `undefined`), not an object with callable methods. In + OpenCode `fetch(url, init)` returns data (`body` is text), not a JavaScript `Response`. + +## JavaScript compatibility - **Only supported APIs are available.** Programs can use the provided tools, supported JavaScript built-ins, and the globals the host adds through extensions. Timers, `process`, filesystem access, packages, and `export` are @@ -24,7 +50,7 @@ The idea of code mode was originally introduced by Cloudflare. See Unsupported syntax returns an `UnsupportedSyntax` diagnostic with a source location. Current gaps are tracked in the [interpreter support checklist](./interpreter-support.md). -## Quick Start +## Quick Start (host API) ```ts import { CodeMode, Namespace, Tool } from "@opencode/codemode" @@ -38,13 +64,14 @@ const lookupOrder = Tool.make({ }) const runtime = CodeMode.make({ + language: "lua", tools: { orders: { lookup: lookupOrder } }, }) const result = await Effect.runPromise( runtime.execute(` - const order = await tools.orders.lookup({ id: "order_42" }) - return { id: order.id, needsAttention: order.status !== "complete" } + local order = tools.orders.lookup({ id = "order_42" }) + return { id = order.id, needsAttention = order.status ~= "complete" } `), ) ``` @@ -85,7 +112,7 @@ bracket notation, such as `tools.context7["resolve-library-id"](...)`. ```ts const runtime = CodeMode.make({ tools, limits: { timeoutMs: 30_000 } }) -runtime.catalog() // structured tool descriptions +runtime.catalog // structured tool descriptions runtime.execute(source) // Effect ``` @@ -107,7 +134,7 @@ const web = Extension.make({ name: "web", globals: { fetch: async (url: string) const runtime = CodeMode.make({ tools, extensions: [web] }) ``` -A global is synchronous unless it is an `async` function or is marked with `Extension.async`. Mark a plain function +In the JavaScript interpreter, a global is synchronous unless it is an `async` function or is marked with `Extension.async`. Mark a plain function that returns a Promise or an Effect, so a denied call rejects its promise like any other failure: ```ts @@ -130,7 +157,11 @@ const web = Extension.make({ ), }, }) -const result = yield* CodeMode.make({ extensions: [web] }).execute(code).pipe(Effect.provideService(Session, session)) +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 @@ -158,7 +189,7 @@ create namespaces: ```ts const api = OpenAPI.fromSpec({ spec, auth: { resolve } }) -const runtime = CodeMode.make({ tools: { opencode: api.tools } }) +const runtime = CodeMode.make({ language: "lua", tools: { opencode: api.tools } }) ``` The synchronous result is `{ tools, skipped }`. Operations with unsupported parameter encodings, request bodies @@ -217,26 +248,30 @@ copying error. Interruption propagates without becoming an error diagnostic. ## Discovery -`runtime.catalog()` returns structured descriptors — exact path, description, and generated TypeScript signature — for -every visible tool. Hosts render their own model-facing instructions from these descriptors; `CodeMode.searchSignature` -and `CodeMode.toolExpression(path)` supply the exact callable forms. +`runtime.catalog` returns structured descriptors for every visible tool (path, description and signature in the +selected language). For Lua instructions use `CodeMode.luaSearchSignature` and `CodeMode.toolExpression(path, "lua")`; +`CodeMode.searchSignature` and `CodeMode.toolExpression(path)` retain their JavaScript meanings. The synchronous `search(...)` built-in is always available. It supports exact-path lookup, namespace-scoped search, -empty-query browsing, and pagination, and returns callable paths with full signatures. Its result can be used directly, -awaited, or chained with `then`, `catch`, and `finally`, so programs work whichever way they treat it. Search counts toward +empty-query browsing, and pagination, and returns callable paths with full signatures. Lua sees the result directly. +In JavaScript it can also be awaited or chained with `then`, `catch`, and `finally`. Search counts toward `maxToolCalls`. Search also matches descriptions from enclosing `Namespace` values. ## Execution Limits -| Limit | Default | Controls | -| ---------------- | --------- | ------------------------------- | -| `timeoutMs` | unlimited | Total execution time. | -| `maxToolCalls` | unlimited | Admitted tool calls. | -| `maxOutputBytes` | unlimited | Retained result value and logs. | +| Limit | Lua default | JavaScript default | Controls | +| ---------------- | ----------- | ------------------ | --------------------------------------------------------------------------------- | +| `timeoutMs` | 120,000 | unlimited | Total execution time. | +| `maxToolCalls` | 128 | unlimited | Lua host call attempts (tools, search and extensions); JavaScript admitted tools. | +| `maxOutputBytes` | 65,536 | unlimited | Retained result value and logs. | -Execution limits have no default values. +Lua also enforces non-configurable bounds on source and syntax depth, interpreter work and call frames, string and +table growth, and expanded data copies. These bounds apply even when the host raises its configured limits. The +production evaluator shares the [Lua interpreter](./lua/README.md)'s frames and call loop but installs only metered +operations: no prototype libraries, dynamic loading, I/O, metatables, regex/pattern engine or coroutines. Lua strings +are byte strings; strings crossing JSON boundaries must be valid UTF-8. Invalid limit configuration throws `RangeError`. Warnings receive a separate budget equal to `maxOutputBytes`. Truncation does not fail execution; an oversized value becomes a string with an in-band marker. Timeouts interrupt -tool calls and busy loops, while a result returned before cleanup times out remains successful with a -`TimeoutExceeded` warning. Tool-call concurrency is unrestricted. Boundary data is limited to 32 nested levels. +tool calls and busy loops. In JavaScript a result returned before cleanup times out remains successful with a +`TimeoutExceeded` warning; JavaScript tool calls may run concurrently. diff --git a/packages/codemode/interpreter-support.md b/packages/codemode/interpreter-support.md index f0664313199..c70d0e1f343 100644 --- a/packages/codemode/interpreter-support.md +++ b/packages/codemode/interpreter-support.md @@ -3,7 +3,9 @@ This is the checkable support matrix for CodeMode's confined JavaScript interpreter. It tracks the language and standard-library surface that programs can use today, plus concrete gaps that may be implemented later. -There is also a [standalone Lua 5.1 interpreter written in JavaScript](lua/README.md). Its synchronous `runLua(source)` API supports Lua coroutines and multiple results without native code or Wasm. It is not selectable in Code Mode and does not change the JavaScript support described here. See the experiment's README for its tested subset and limitations. +The agent-facing `execute` tool uses the [confined Lua profile](lua/README.md). Library callers can select it with +`language: "lua"`; this checklist covers the existing JavaScript profile only. The unmetered `runLua(source)` entry +point is for trusted compatibility testing, not agent programs. - `[x]` means the feature is implemented at the scope described here. - `[ ]` means a concrete compatibility gap remains. diff --git a/packages/codemode/lua/README.md b/packages/codemode/lua/README.md index 48045e14640..6f8e87ed3fa 100644 --- a/packages/codemode/lua/README.md +++ b/packages/codemode/lua/README.md @@ -1,6 +1,18 @@ # Lua in JavaScript -`runLua(source)` evaluates Lua 5.1 source synchronously **in the calling JavaScript process**. Each call starts with fresh globals. There is no native executable, Wasm, generated JavaScript, or runtime build step. The experiment is not imported by Code Mode; its existing JavaScript interpreter is unchanged. +There are two entry points sharing the same Lua AST evaluator, lexical cells, activation frames and call trampoline in `evaluate.js`. Neither runs generated JavaScript, Wasm or a native executable. + +## Code Mode sandbox + +`sandbox.js` is the Lua execution profile for Code Mode. It uses fresh, Map-backed tables and an explicit native-function allowlist, **not** the prototype's v8lua runtime or standard libraries. `evaluateLua` advances a generator; it yields either a scheduler checkpoint or a capability path with detached JSON arguments. While the caller awaits a tool, no Lua executes and no ambient state is installed. The bridge resumes that same generator with validated inert JSON or closes it on interruption. `pcall` can recover from ordinary Lua and host errors, never resource exhaustion or interruption. + +Source is limited to 32 KiB, 8,192 AST nodes and 48 levels of syntax. The evaluator caps normal activations at 96 and nested protected calls at 24. Each execution has 500,000 weighted work units, with checkpoints after 256 units at evaluator boundaries. Table writes, local lookup, argument copying and boundary traversal consume fuel too. Tables have at most 8,192 entries; string-producing operations check a 256 KiB per-string limit and a cumulative 8 MiB budget before materialization. Boundary output is capped at 1 MiB per call/result and 32 levels, including repeated expansion of shared references. These are implementation budgets, not an OS heap or CPU-time quota. Host tool execution, canonicalization of host-owned objects, timeout handling and log retention belong to the bridge. + +The allowlist includes `type`, `tostring`, base-10 `tonumber`, `assert`, `error`, `pcall`, `pairs`, `ipairs`, `math.{abs,ceil,floor,sqrt,min,max,pi,huge}`, `string.{len,sub,rep,lower,upper}`, append-only `table.insert` and `table.concat`. Calls to `print` are capabilities rather than access to the host console. No patterns, format strings, metatables, dynamic loading, debug library, coroutine library or ambient JS objects. Source and JSON use Unicode; inside the VM strings are UTF-8 bytes. Exporting an invalid byte sequence as JSON fails. See the [Code Mode guide](../README.md) for table/JSON conventions. + +## Trusted compatibility prototype + +`runLua(source)` evaluates Lua 5.1 source synchronously **in the calling JavaScript process**. It starts with fresh globals but is unmetered. Code Mode does not import this entry point. **Trusted programs only.** From the repository root: @@ -18,10 +30,10 @@ The result is an array, not just the first Lua value. `return` produces `[]`; `r ## Implementation - [luaparse](https://github.com/fstirlitz/luaparse) parses in 5.1 mode. The small local patch records grouped expressions (the difference between `return f()` and `return (f())`) and fixes parsing of `break;` and `return 'end'`. -- `evaluate.js` evaluates the parsed tree, with lexical cells for captures. Each Lua activation is a generator that yields **call requests** to `vm.js`; calls do not recurse down the JS stack. The VM replaces frames for tail calls and owns the frame stack, resume values, protected-call boundaries and lifecycle of each coroutine. +- `evaluate.js` evaluates the parsed tree, with lexical cells for captures. Each Lua activation is a generator that yields **call requests** to the shared frame trampoline; calls do not recurse down the JS stack. The trusted VM in `vm.js` owns prototype-specific values, coroutine state and native dispatch. - `library.js` provides the base and coroutine functions. Tables, operators and the string/pattern, table and math libraries reuse the MIT-licensed [v8lua](https://github.com/takano32/v8lua) modules. The runtime patch scopes their dynamic bindings to each synchronous invocation and uses the actual string metatable for indexing. We don't use v8lua's evaluator, CLI or host libraries. -`coroutine.create`, `resume`, `yield`, `wrap`, `status` and `running` follow the 5.1 model: the main thread is reported as nil, yielded values and resume arguments retain their arity, and a yield across `pcall`, a metamethod invoked by an operator, or a native callback fails instead of suspending. A protected call can still resume a *different* thread that yields. +`coroutine.create`, `resume`, `yield`, `wrap`, `status` and `running` follow the 5.1 model: the main thread is reported as nil, yielded values and resume arguments retain their arity, and a yield across `pcall`, a metamethod invoked by an operator, or a native callback fails instead of suspending. A protected call can still resume a _different_ thread that yields. ## Compatibility and tests @@ -31,4 +43,4 @@ The result is an array, not just the first Lua value. `return` produces `[]`; `r - No `io`, `os`, `package`/`require`, `debug`, C API, bytecode loading or `string.dump`. `load`/`loadstring` accept text; `print` writes to the host console. - GC belongs to JavaScript. `collectgarbage` is a compatibility stub; weak tables, finalizers and Lua allocator behavior aren't implemented. -- Parser limits, stack limits, diagnostics, locale behavior and some library argument checks and numeric edge cases differ from PUC Lua. The interpreter has no instruction, time or allocation budget. Run **trusted** code only; this is not a sandbox. +- Parser limits, stack limits, diagnostics, locale behavior and some library argument checks and numeric edge cases differ from PUC Lua. `runLua` has no instruction, time or allocation budget. Run **trusted** code only with the prototype. diff --git a/packages/codemode/lua/evaluate.js b/packages/codemode/lua/evaluate.js index 7fada7bc1fb..7987468401b 100644 --- a/packages/codemode/lua/evaluate.js +++ b/packages/codemode/lua/evaluate.js @@ -1,16 +1,4 @@ -import { - LuaClosure, - LuaError, - LuaTable, - arith, - compare, - concat, - index, - len, - luaToNumber, - newindex, - truthy, -} from "v8lua/src/runtime.js" +export const checkpoint = Symbol("checkpoint") // One generator per active Lua function. Expressions delegate within this frame; // calls yield a request to the VM rather than delegating to another Lua frame. @@ -24,6 +12,43 @@ export class Call { const stop = Symbol("break") const arithmetic = { "+": "add", "-": "sub", "*": "mul", "/": "div", "%": "mod", "^": "pow" } +// Both profiles use this trampoline. Only native calls, resource policy and +// the value operations differ; a suspended event never contains a Lua frame. +export function* runFrames(vm, frames, call) { + const base = frames.length + let values + for (;;) { + if (call) { + const target = vm.resolveCall(call) + if (vm.isClosure(target.fn)) { + if (frames.length > base && frames.at(-1).tail) frames.pop() + if (frames.length >= vm.frameLimit) throw vm.ops.stackOverflow() + frames.push(new Frame(vm, target.fn, target.args)) + values = undefined + } else values = yield* vm.native(target.fn, target.args) + call = undefined + } + if (frames.length === base) return values + const frame = frames.at(-1) + if (frame.tail) { + frames.pop() + continue + } + const step = frame.code.next(values) + if (step.value instanceof Call) { + frame.tail = step.done + call = step.value + } else if (!step.done && step.value === checkpoint) { + yield checkpoint + values = undefined + } else { + if (!step.done) throw new Error("invalid Lua frame suspension") + values = step.value ?? [] + frames.pop() + } + } +} + function isCall(node) { return node.type === "CallExpression" || node.type === "StringCallExpression" || node.type === "TableCallExpression" } @@ -34,26 +59,31 @@ function bind(parent, name, value) { return { parent, name, value } } -function lookup(scope, name) { - for (let cell = scope; cell; cell = cell.parent) if (cell.name === name) return cell +function lookup(vm, scope, name) { + for (let cell = scope; cell; cell = cell.parent) { + vm.charge(1) + if (cell.name === name) return cell + } } export class Frame { constructor(vm, closure, args) { this.vm = vm + this.ops = vm.ops this.closure = closure this.line = closure.proto.loc.start.line let scope = closure.scope const proto = closure.proto let i = 0 if (proto.identifier?.indexer === ":") scope = bind(scope, "self", args[i++]) + vm.charge((proto.parameters?.length ?? 0) + args.length + 1) for (const param of proto.parameters ?? []) { if (param.type === "VarargLiteral") break scope = bind(scope, param.name, args[i++]) } this.varargs = args.slice(i) if (proto.legacyArg) { - const arg = new LuaTable() + const arg = this.ops.table() this.varargs.forEach((v, i) => arg.set(i + 1, v)) arg.set("n", this.varargs.length) scope = bind(scope, "arg", arg) @@ -62,7 +92,7 @@ export class Frame { } close(proto, scope) { - const fn = new LuaClosure(proto, scope, proto.identifier?.name, this.vm) + const fn = this.ops.closure(proto, scope, proto.identifier?.name, this.vm) fn.chunkname = this.closure.chunkname fn.env = this.closure.env return fn @@ -73,8 +103,11 @@ export class Frame { for (let i = 0; i < nodes.length; i++) { const node = nodes[i] if (i === nodes.length - 1 && !node.inParens) { - if (node.type === "VarargLiteral") return result.concat(this.varargs) - if (isCall(node)) return result.concat(yield* this.call(node, scope)) + if (node.type === "VarargLiteral" || isCall(node)) { + const tail = node.type === "VarargLiteral" ? this.varargs : yield* this.call(node, scope) + this.vm.charge(result.length + tail.length + 1) + return result.concat(tail) + } } result.push(yield* this.expr(node, scope)) } @@ -89,7 +122,7 @@ export class Frame { *prepareCall(node, scope) { const method = node.base.indexer === ":" const self = method ? yield* this.expr(node.base.base, scope) : undefined - const fn = method ? this.vm.atomic(index(self, node.base.identifier.name)) : yield* this.expr(node.base, scope) + const fn = method ? this.ops.index(self, node.base.identifier.name) : yield* this.expr(node.base, scope) const args = node.type === "CallExpression" ? yield* this.args(node.arguments, scope) @@ -100,7 +133,7 @@ export class Frame { *ref(node, scope) { if (node.type === "Identifier") { - const cell = lookup(scope, node.name) + const cell = lookup(this.vm, scope, node.name) return cell ? { cell } : { obj: this.closure.env, key: node.name } } const obj = yield* this.expr(node.base, scope) @@ -110,10 +143,12 @@ export class Frame { store(ref, value) { if (ref.cell) ref.cell.value = value - else this.vm.atomic(newindex(ref.obj, ref.key, value)) + else this.ops.newindex(ref.obj, ref.key, value) } *expr(node, scope) { + if (this.vm.poll(node)) yield checkpoint + const ops = this.ops switch (node.type) { case "NilLiteral": return undefined @@ -128,7 +163,7 @@ export class Frame { case "MemberExpression": { const ref = yield* this.ref(node, scope) this.line = node.loc.start.line - return ref.cell ? ref.cell.value : this.vm.atomic(index(ref.obj, ref.key)) + return ref.cell ? ref.cell.value : ops.index(ref.obj, ref.key) } case "FunctionDeclaration": return this.close(node, scope) @@ -137,7 +172,7 @@ export class Frame { case "StringCallExpression": return (yield* this.call(node, scope))[0] case "TableConstructorExpression": { - const table = new LuaTable() + const table = ops.table() let at = 1 for (let i = 0; i < node.fields.length; i++) { const field = node.fields[i] @@ -154,12 +189,12 @@ export class Frame { } case "UnaryExpression": { const value = yield* this.expr(node.argument, scope) - if (node.operator === "not") return !truthy(value) - return this.vm.atomic(node.operator === "#" ? len(value) : arith("unm", value, value)) + if (node.operator === "not") return !ops.truthy(value) + return node.operator === "#" ? ops.len(value) : ops.arith("unm", value, value) } case "LogicalExpression": { const left = yield* this.expr(node.left, scope) - return truthy(left) === (node.operator === "and") ? yield* this.expr(node.right, scope) : left + return ops.truthy(left) === (node.operator === "and") ? yield* this.expr(node.right, scope) : left } case "BinaryExpression": { const a = yield* this.expr(node.left, scope) @@ -167,21 +202,21 @@ export class Frame { this.line = node.loc.start.line switch (node.operator) { case "..": - return this.vm.atomic(concat(a, b)) + return ops.concat(a, b) case "==": - return this.vm.atomic(compare("eq", a, b)) + return ops.compare("eq", a, b) case "~=": - return !this.vm.atomic(compare("eq", a, b)) + return !ops.compare("eq", a, b) case "<": - return this.vm.atomic(compare("lt", a, b)) + return ops.compare("lt", a, b) case ">": - return this.vm.atomic(compare("lt", b, a)) + return ops.compare("lt", b, a) case "<=": - return this.vm.atomic(compare("le", a, b)) + return ops.compare("le", a, b) case ">=": - return this.vm.atomic(compare("le", b, a)) + return ops.compare("le", b, a) default: - return this.vm.atomic(arith(arithmetic[node.operator], a, b)) + return ops.arith(arithmetic[node.operator], a, b) } } default: @@ -190,7 +225,10 @@ export class Frame { } *block(nodes, scope, until) { + // Empty loop bodies still consume work and can suspend. + if (this.vm.poll()) yield checkpoint for (const node of nodes) { + if (this.vm.poll(node)) yield checkpoint this.line = node.loc.start.line switch (node.type) { case "CallStatement": @@ -198,6 +236,7 @@ export class Frame { break case "LocalStatement": { const values = yield* this.args(node.init, scope) + this.vm.charge(node.variables.length) for (const [i, variable] of node.variables.entries()) scope = bind(scope, variable.name, values[i]) break } @@ -227,7 +266,7 @@ export class Frame { } case "IfStatement": { for (const clause of node.clauses) { - if (clause.condition && !truthy(yield* this.expr(clause.condition, scope))) continue + if (clause.condition && !this.ops.truthy(yield* this.expr(clause.condition, scope))) continue const result = yield* this.block(clause.body, scope) if (result !== undefined) return result break @@ -237,7 +276,7 @@ export class Frame { case "WhileStatement": case "RepeatStatement": { const repeat = node.type === "RepeatStatement" - while (repeat || truthy(yield* this.expr(node.condition, scope))) { + while (repeat || this.ops.truthy(yield* this.expr(node.condition, scope))) { const result = yield* this.block(node.body, scope, repeat && node.condition) if (result === stop) break if (result !== undefined) return result @@ -245,10 +284,10 @@ export class Frame { break } case "ForNumericStatement": { - const start = luaToNumber(yield* this.expr(node.start, scope)) - const limit = luaToNumber(yield* this.expr(node.end, scope)) - const step = node.step ? luaToNumber(yield* this.expr(node.step, scope)) : 1 - if ([start, limit, step].includes(undefined)) throw new LuaError("'for' values must be numbers") + const start = this.ops.number(yield* this.expr(node.start, scope)) + const limit = this.ops.number(yield* this.expr(node.end, scope)) + const step = node.step ? this.ops.number(yield* this.expr(node.step, scope)) : 1 + if ([start, limit, step].includes(undefined)) throw this.ops.error("'for' values must be numbers") for (let i = start; step > 0 ? i <= limit : i >= limit; i += step) { const result = yield* this.block(node.body, bind(scope, node.variable.name, i)) if (result === stop) break @@ -260,9 +299,10 @@ export class Frame { const [iterator, state, first] = yield* this.args(node.iterators, scope) let control = first for (;;) { - const values = this.vm.atomic(this.vm.invoke(iterator, [state, control])) + const values = yield* this.vm.iterate(iterator, [state, control]) control = values[0] if (control === undefined) break + this.vm.charge(node.variables.length) const locals = node.variables.reduce((s, v, i) => bind(s, v.name, values[i]), scope) const result = yield* this.block(node.body, locals) if (result === stop) break @@ -275,6 +315,6 @@ export class Frame { } } // The repeat condition is inside the body's lexical scope. - if (until && truthy(yield* this.expr(until, scope))) return stop + if (until && this.ops.truthy(yield* this.expr(until, scope))) return stop } } diff --git a/packages/codemode/lua/sandbox.d.ts b/packages/codemode/lua/sandbox.d.ts new file mode 100644 index 00000000000..1c0cd46f098 --- /dev/null +++ b/packages/codemode/lua/sandbox.d.ts @@ -0,0 +1,23 @@ +type Json = null | string | boolean | number | ReadonlyArray | { readonly [key: string]: Json } + +export class LuaFault extends Error { + readonly kind: "ParseError" | "UnsupportedSyntax" | "ExecutionFailure" | "InvalidDataValue" + readonly location?: { line: number; column: number } +} + +export const luaBuiltins: readonly string[] + +declare class LuaHostFailure { + private readonly brand: never +} +export function hostFailure(message: string): LuaHostFailure + +/** Inputs must already be inert JSON, never JS proxies. Discard/return the iterator on interruption. */ +export function evaluateLua( + source: string, + options: { paths: ReadonlyArray>; bindings?: Readonly> }, +): Generator< + { type: "tick" } | { type: "call"; path: string[]; args: (Json | undefined)[]; protected: boolean }, + Json | undefined, + Json | undefined | LuaHostFailure +> diff --git a/packages/codemode/lua/sandbox.js b/packages/codemode/lua/sandbox.js new file mode 100644 index 00000000000..e454e067016 --- /dev/null +++ b/packages/codemode/lua/sandbox.js @@ -0,0 +1,571 @@ +import { Buffer } from "node:buffer" +import luaparse from "luaparse" +import { Call, checkpoint, runFrames } from "./evaluate.js" + +// Limits are per invocation, including host arguments, replies and the final +// result. Work is cumulative (not refunded by deleting a key or tail-calling). +const sourceLimit = 32768 +const stringLimit = 256 * 1024 +const entriesLimit = 8192 +const depthLimit = 48 +const jsonNull = Symbol("json.null") +const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }) +const tick = Object.freeze({ type: "tick" }) +const truthy = (v) => v !== undefined && v !== false + +export class LuaFault extends Error { + constructor(kind, message, location) { + super(message) + this.kind = kind + this.location = location + } +} + +function failure(message) { + const e = new LuaFault("ExecutionFailure", message) + e.catchable = true + return e +} + +function limit(message) { + return new LuaFault("ExecutionFailure", message) +} + +function invalid(message) { + const e = new LuaFault("InvalidDataValue", message) + e.catchable = true + return e +} + +// luaparse's lexer stores its state at module scope. Finish parsing before +// yielding; never leave a partially parsed chunk suspended during a host call. +function parse(source) { + if (typeof source !== "string") throw new LuaFault("ParseError", "Expected Lua source text") + if (source.length > sourceLimit || Buffer.byteLength(source) > sourceLimit) + throw new LuaFault("ParseError", "Lua source exceeds the size limit") + if (!source.isWellFormed()) throw new LuaFault("ParseError", "Lua source must be valid Unicode") + // Its long-string scanner compares every '=' on every closing bracket. + if (/\[={33}/.test(source)) throw new LuaFault("ParseError", "Lua long-bracket delimiter exceeds the limit") + let count = 0 + const depths = new WeakMap() + try { + return luaparse.parse(Buffer.from(source).toString("latin1"), { + luaVersion: "5.1", + encodingMode: "pseudo-latin1", + comments: false, + locations: true, + onCreateNode(node) { + if (++count > 8192) throw new LuaFault("ParseError", "Lua syntax tree exceeds the size limit") + let depth = 1 + for (const child of Object.values(node)) { + if (Array.isArray(child)) { + for (const item of child) depth = Math.max(depth, 1 + (depths.get(item) ?? 0)) + } else depth = Math.max(depth, 1 + (depths.get(child) ?? 0)) + } + if (depth > depthLimit) throw new LuaFault("ParseError", "Lua syntax nesting exceeds the depth limit") + depths.set(node, depth) + }, + }) + } catch (e) { + if (e instanceof LuaFault) throw e + if (e instanceof RangeError) throw new LuaFault("ParseError", "Lua syntax nesting exceeds the depth limit") + throw new LuaFault( + "ParseError", + e.message.slice(0, 512), + e.line ? { line: e.line, column: e.column + 1 } : undefined, + ) + } +} + +class Table { + data = new Map() + constructor(vm, array = false) { + vm.charge(8) + this.vm = vm + this.array = array + } + get(key) { + this.vm.key(key) + return this.data.get(key) + } + set(key, value) { + this.vm.key(key) + if (key === undefined || Number.isNaN(key)) throw failure("Invalid Lua table key") + if (this.locked) throw failure("Cannot change a read-only Lua table") + if (value === undefined) return this.data.delete(key) + if (this.data.size >= entriesLimit && !this.data.has(key)) throw limit("Lua table exceeds the entry limit") + this.vm.charge(4) + this.data.set(key, value) + } +} + +class Closure { + constructor(proto, scope) { + this.proto = proto + this.scope = scope + } +} +class Host { + constructor(path) { + this.path = path + } +} +class Native { + constructor(run) { + this.run = run + } +} + +class LuaHostFailure { + constructor(message) { + this.message = message + } +} +export function hostFailure(message) { + return new LuaHostFailure(message) +} + +// Account for JSON escaping as well as UTF-8: a control byte can expand to +// six ASCII bytes. One request shares its budget across all its arguments. +class Boundary { + bytes = 1024 * 1024 + charge(n) { + this.bytes -= n + if (this.bytes < 0) throw new LuaFault("InvalidDataValue", "Lua JSON exceeds the boundary byte limit") + } +} + +function type(v) { + if (v === undefined) return "nil" + if (v === jsonNull) return "userdata" + if (v instanceof Table) return "table" + if (v instanceof Closure || v instanceof Native || v instanceof Host) return "function" + return typeof v +} + +function text(v) { + if (v === jsonNull) return "null" + if (["number", "string", "boolean"].includes(typeof v)) return String(v) + return type(v) +} + +function string(v) { + if (typeof v !== "string" && typeof v !== "number") throw failure("Expected a Lua string or number") + return String(v) +} + +function table(v) { + if (!(v instanceof Table)) throw failure("Expected a Lua table") + return v +} + +class Sandbox { + fuel = 500_000 + slice = 256 + bytes = 8 * 1024 * 1024 + frameLimit = 96 + globals = new Table(this) + protected = new Set() + frames = [] + barriers = 0 + charge(work) { + this.fuel -= work + this.slice -= work + if (this.fuel < 0) throw limit("Lua execution work limit exceeded") + } + poll(node) { + this.node = node ?? this.node + this.charge(1) + if (this.slice > 0) return false + this.slice = 256 + return true + } + // Charge before materializing a string, including in JS-native operations. + size(length) { + if (!Number.isSafeInteger(length) || length < 0 || length > stringLimit) + throw limit("Lua string exceeds the size limit") + this.bytes -= length + if (this.bytes < 0) throw limit("Lua allocation limit exceeded") + this.charge(1 + Math.ceil(length / 32)) + } + key(key) { + this.charge(typeof key === "string" ? 1 + Math.ceil(key.length / 32) : 1) + } + number(v) { + if (typeof v === "number") return v + if (typeof v !== "string") return undefined + this.key(v) + const trimmed = v.trim() + if (!/^[+-]?(?:0[xX][\da-fA-F]+|(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)$/.test(trimmed)) return undefined + if (/^[+-]0[xX]/.test(trimmed)) return (trimmed[0] === "-" ? -1 : 1) * Number(trimmed.slice(1)) + return Number(trimmed) + } + numeric(v) { + const n = this.number(v) + if (n === undefined) throw failure("Expected a Lua number") + return n + } + length(v) { + if (typeof v === "string") return v.length + const seq = table(v) + let i = 0 + while (seq.get(i + 1) !== undefined) i++ + return i + } + ops = { + truthy, + error: failure, + stackOverflow: () => limit("Lua stack overflow"), + table: () => new Table(this), + closure: (proto, scope) => new Closure(proto, scope), + number: (v) => this.number(v), + len: (v) => this.length(v), + index: (v, k) => { + if (v instanceof Table) return v.get(k) + if (typeof v === "string") return this.strings.get(k) + if (v instanceof Host && v.path[0] === "tools" && typeof k === "string") { + if (v.path.length >= 32 || k.length > 256) throw limit("Lua tool path exceeds the size limit") + this.charge(v.path.length) + return new Host([...v.path, this.decode(k)]) + } + throw failure(`Cannot index Lua ${type(v)}`) + }, + newindex: (v, k, value) => { + if (v === this.globals && this.protected.has(k)) throw failure("Cannot overwrite a reserved Lua global") + table(v).set(k, value) + }, + compare: (op, a, b) => { + this.key(a) + this.key(b) + if (op === "eq") return a === b + if (typeof a !== typeof b || (typeof a !== "number" && typeof a !== "string")) + throw failure("Incompatible Lua comparison") + return op === "lt" ? a < b : a <= b + }, + concat: (a, b) => { + const left = string(a), + right = string(b) + this.size(left.length + right.length) + return left + right + }, + arith: (op, a, b) => { + const x = this.numeric(a), + y = this.numeric(b) + switch (op) { + case "unm": + return -x + case "add": + return x + y + case "sub": + return x - y + case "mul": + return x * y + case "div": + return x / y + case "pow": + return x ** y + case "mod": + return x - Math.floor(x / y) * y + default: + throw failure("Unknown arithmetic operator") + } + }, + } + isClosure(fn) { + return fn instanceof Closure + } + resolveCall(call) { + this.charge(1 + call.args.length) + if (call.args.length > 1024) throw limit("Lua call argument limit exceeded") + return call + } + *iterate(fn, args) { + return yield new Call(fn, args) + } + *native(fn, args) { + if (fn === this.pcall) { + // A second trampoline shares the same frame stack and all budgets. + // Bound nested protection separately: even pcall(pcall, ...) with no + // Lua activations uses another JS generator delegation. + if (this.barriers >= 24) throw limit("Lua protected call depth limit exceeded") + this.barriers++ + const base = this.frames.length + try { + const result = yield* runFrames(this, this.frames, new Call(args[0], args.slice(1))) + this.charge(result.length + 1) + return [true, ...result] + } catch (e) { + if (!(e instanceof LuaFault) || !e.catchable) throw e + return [false, Object.hasOwn(e, "value") ? e.value : this.encode(e.message)] + } finally { + this.barriers-- + this.frames.length = base + } + } + if (fn instanceof Native) return fn.run(args) + if (!(fn instanceof Host)) throw failure(`Cannot call Lua ${type(fn)}`) + const data = [] + const budget = new Boundary() + for (const arg of args) data.push(yield* this.export(arg, new Set(), 0, budget)) + const reply = yield { type: "call", path: fn.path.slice(), args: data, protected: this.barriers > 0 } + if (reply instanceof LuaHostFailure) throw failure(reply.message) + return [yield* this.import(reply, 0)] + } + encode(s) { + if (s.length > stringLimit) throw limit("Lua string exceeds the size limit") + if (!s.isWellFormed()) throw invalid("Lua input must be valid Unicode") + this.size(Buffer.byteLength(s)) + return Buffer.from(s).toString("latin1") + } + decode(s) { + this.size(s.length) + try { + return utf8.decode(Buffer.from(s, "latin1")) + } catch { + throw invalid("Lua byte string is not valid UTF-8") + } + } + *import(v, depth) { + if (this.poll()) yield checkpoint + if (depth > depthLimit) throw new LuaFault("InvalidDataValue", "Lua input exceeds the depth limit") + if (v === undefined || typeof v === "boolean" || Number.isFinite(v)) return v + if (v === null) return jsonNull + if (typeof v === "string") return this.encode(v) + if (typeof v !== "object") throw invalid("Expected JSON data") + const array = Array.isArray(v) + const result = new Table(this, array) + // The driver owns validating/canonicalizing host objects before it resumes + // us. Never put the host container or function itself into the Lua heap. + if (array) { + if (v.length > entriesLimit) throw new LuaFault("InvalidDataValue", "Lua input exceeds the entry limit") + for (let i = 0; i < v.length; i++) result.set(i + 1, yield* this.import(v[i], depth + 1)) + } else { + for (const key in v) + if (Object.hasOwn(v, key)) result.set(this.encode(key), yield* this.import(v[key], depth + 1)) + } + return result + } + *export(v, seen, depth, budget) { + if (this.poll()) yield checkpoint + if (depth > 32) throw new LuaFault("InvalidDataValue", "Lua result exceeds the depth limit") + if (v === undefined || v === jsonNull || typeof v === "boolean" || Number.isFinite(v)) { + budget.charge(v === undefined || v === jsonNull ? 4 : String(v).length) + return v === jsonNull ? null : v + } + if (typeof v === "string") { + const value = this.decode(v) + budget.charge(Buffer.byteLength(JSON.stringify(value))) + return value + } + if (!(v instanceof Table)) throw invalid(`Cannot pass Lua ${type(v)} as JSON`) + if (seen.has(v)) throw invalid("Circular Lua table cannot cross the JSON boundary") + seen.add(v) + const first = v.data.keys().next() + const array = first.done ? v.array : typeof first.value === "number" + const out = array ? [] : Object.create(null) + budget.charge(2 + Math.max(0, v.data.size - 1)) + for (const [k, item] of v.data) { + // Charge each expanded edge, not just unique VM tables. Never size a + // JS array from a Lua index: sparse integer keys can be enormous. + this.charge(16) + if (array) { + if (!Number.isSafeInteger(k) || k < 1 || k > v.data.size) + throw invalid("Expected contiguous Lua array keys from 1") + out[k - 1] = yield* this.export(item, seen, depth + 1, budget) + } else { + if (typeof k !== "string" || k === "__proto__") throw invalid("Invalid Lua JSON object key") + const key = this.decode(k) + budget.charge(1 + Buffer.byteLength(JSON.stringify(key))) + out[key] = yield* this.export(item, seen, depth + 1, budget) + } + } + seen.delete(v) + return out + } +} + +export const luaBuiltins = Object.freeze([ + "assert", + "error", + "type", + "tostring", + "tonumber", + "pairs", + "ipairs", + "string", + "table", + "math", + "json", + "pcall", +]) + +function install(vm) { + // Case conversion is ASCII-only on byte strings. Avoid a regex callback + // and temporary match allocation for each individual byte. + function changeCase(v, start, delta) { + const s = string(v) + vm.size(s.length) + const bytes = Buffer.from(s, "latin1") + for (let i = 0; i < bytes.length; i++) if (bytes[i] >= start && bytes[i] < start + 26) bytes[i] += delta + return bytes.toString("latin1") + } + function raised(value) { + // Rendering for diagnostics must not truncate a UTF-8 character into a + // second error. Protected handlers get the original value, even nil. + const e = failure(Buffer.from(text(value).slice(0, 512), "latin1").toString("utf8")) + e.value = value + return e + } + function library(methods) { + const lib = new Table(vm) + for (const [k, v] of Object.entries(methods)) lib.set(k, typeof v === "function" ? new Native(v) : v) + lib.locked = true + return lib + } + const base = { + type: ([v]) => [type(v)], + tostring: ([v]) => [text(v)], + tonumber: ([v, radix]) => { + if (radix !== undefined && radix !== 10) throw failure("Only base 10 tonumber is supported") + return [vm.number(v)] + }, + assert: (args) => { + if (!truthy(args[0])) throw raised(args[1] ?? "assertion failed!") + return args + }, + error: ([value]) => { + throw raised(value) + }, + pairs: ([v]) => { + vm.charge(table(v).data.size) + const iterator = table(v).data.entries() + return [new Native(() => iterator.next().value ?? []), v] + }, + ipairs: ([v]) => { + const seq = table(v) + return [ + new Native(([, i]) => { + const key = vm.numeric(i) + 1 + const value = seq.get(key) + return value === undefined ? [] : [key, value] + }), + seq, + 0, + ] + }, + } + for (const [name, fn] of Object.entries(base)) vm.globals.set(name, new Native(fn)) + vm.pcall = new Native() + vm.globals.set("pcall", vm.pcall) + vm.strings = library({ + len: ([v]) => [string(v).length], + sub: ([v, start, end = -1]) => { + const s = string(v) + const pos = (v) => { + const n = Math.trunc(vm.numeric(v)) + return n < 0 ? s.length + n + 1 : n + } + const i = Math.max(1, pos(start)), + j = Math.min(s.length, pos(end)) + vm.size(Math.max(0, j - i + 1)) + return [s.slice(i - 1, Math.max(0, j))] + }, + rep: ([v, count]) => { + const s = string(v), + n = Math.max(0, Math.trunc(vm.numeric(count))) + vm.size(s.length * n) + return [s.length ? s.repeat(n) : ""] + }, + lower: ([v]) => [changeCase(v, 65, 32)], + upper: ([v]) => [changeCase(v, 97, -32)], + // Deliberately no Lua patterns, regex translation or printf formatting. + }) + vm.globals.set("string", vm.strings) + vm.globals.set( + "table", + library({ + insert: ([v, ...args]) => { + if (args.length !== 1) throw failure("Only table.insert(table, value) is supported") + table(v).set(vm.length(v) + 1, args[0]) + return [] + }, + concat: ([v, sep = "", first = 1, last]) => { + const seq = table(v), + delimiter = string(sep) + const i = vm.numeric(first), + j = last === undefined ? vm.length(v) : vm.numeric(last) + if (!Number.isSafeInteger(i) || !Number.isSafeInteger(j) || j - i >= entriesLimit) + throw limit("Invalid table.concat range") + const parts = [] + let length = 0 + for (let k = i; k <= j; k++) { + const part = string(seq.get(k)) + length += part.length + (parts.length ? delimiter.length : 0) + if (length > stringLimit) throw limit("Lua string exceeds the size limit") + parts.push(part) + } + vm.size(length) + return [parts.join(delimiter)] + }, + }), + ) + vm.globals.set( + "json", + library({ + array: (args) => { + if (args.length) throw failure("json.array() takes no arguments") + return [new Table(vm, true)] + }, + null: jsonNull, + }), + ) + vm.globals.set( + "math", + library({ + ...Object.fromEntries(["abs", "ceil", "floor", "sqrt"].map((k) => [k, ([v]) => [Math[k](vm.numeric(v))]])), + min: (args) => [Math.min(...args.map((v) => vm.numeric(v)))], + max: (args) => [Math.max(...args.map((v) => vm.numeric(v)))], + pi: Math.PI, + huge: Infinity, + }), + ) + for (const k of luaBuiltins) vm.protected.add(k) +} + +export function* evaluateLua(source, options) { + const proto = parse(source) + const vm = new Sandbox() + install(vm) + function global(name, value) { + if (vm.protected.has(name)) throw failure("Duplicate or reserved Lua global") + vm.globals.set(name, value) + vm.protected.add(name) + } + // Only 'tools' is an extensible namespace. Every other host function must + // be explicitly admitted, and indexing it cannot manufacture capabilities. + for (const path of options.paths) { + if (path.length !== 1) throw failure("Expected a top-level Lua capability name") + global(vm.encode(path[0]), new Host([path[0]])) + } + const program = new Closure(proto, null) + program.env = vm.globals + const run = (function* () { + for (const name of Object.keys(options.bindings ?? {})) + global(vm.encode(name), yield* vm.import(options.bindings[name], 0)) + const values = yield* runFrames(vm, vm.frames, new Call(program, [])) + return yield* vm.export(values[0], new Set(), 0, new Boundary()) + })() + try { + let step = run.next() + while (!step.done) step = run.next(yield step.value === checkpoint ? tick : step.value) + return step.value + } catch (e) { + if (e instanceof LuaFault && !e.location && vm.node) { + const loc = vm.node.loc.start + e.location = { line: loc.line, column: loc.column + 1 } + } + throw e + } finally { + run.return() + } +} diff --git a/packages/codemode/lua/test/sandbox.test.mjs b/packages/codemode/lua/test/sandbox.test.mjs new file mode 100644 index 00000000000..a20adca0a8d --- /dev/null +++ b/packages/codemode/lua/test/sandbox.test.mjs @@ -0,0 +1,145 @@ +import assert from "node:assert/strict" +import test from "node:test" +import { evaluateLua, hostFailure, LuaFault } from "../sandbox.js" + +const options = { paths: [["tools"]] } +function resume(vm, reply) { + let step = vm.next(reply) + while (!step.done && step.value.type === "tick") step = vm.next() + return step +} +function run(source, bindings) { + const step = resume(evaluateLua(source, { ...options, bindings })) + assert.equal(step.done, true) + return step.value +} +function fault(source, kind, message) { + assert.throws( + () => run(source), + (e) => e instanceof LuaFault && e.kind === kind && message.test(e.message), + ) +} + +test("host suspension preserves frames, locals and multiple return values across interleaved VMs", () => { + const source = `local function invoke(n) + local function nested() return tools.ns["fetch-item"]({n=n}), n end + return nested() + end + local item,n=invoke(input); item.n=n; return item` + const a = evaluateLua(source, { ...options, bindings: { input: "雪" } }) + const b = evaluateLua(source, { ...options, bindings: { input: 2 } }) + const first = resume(a).value + assert.deepEqual(first.path, ["tools", "ns", "fetch-item"]) + assert.equal(first.args[0].n, "雪") + assert.equal(resume(b).value.args[0].n, 2) + const original = { n: 9 } + assert.equal(resume(b, original).value.n, 2) + assert.equal(resume(a, original).value.n, "雪") + assert.deepEqual(original, { n: 9 }) +}) + +test("cancellation at either checkpoint cannot run the next statement", () => { + const busy = evaluateLua("for i=1,200000 do end; return tools.finished()", options) + assert.equal(busy.next().value.type, "tick") + assert.deepEqual(busy.return(), { done: true, value: undefined }) + assert.equal(busy.next().done, true) + const parked = evaluateLua("pcall(tools.first); return tools.second()", options) + assert.deepEqual(resume(parked).value.path, ["tools", "first"]) + assert.equal(parked.return().done, true) + assert.equal(parked.next("late reply").done, true) +}) + +test("protected host calls unwind on ordinary errors, not interruption; errors keep Lua identity", () => { + const vm = evaluateLua( + `local function f() return tools.fail() end + local ok,err=pcall(f) + assert(not ok and err == 'unavailable 雪') + local obj={}; local good,same=pcall(error,obj); assert(not good and same==obj) + local outer,inner,num=pcall(pcall,function() return 12 end); assert(outer and inner and num==12) + return tools.done()`, + options, + ) + assert.equal(resume(vm).value.protected, true) + const done = resume(vm, hostFailure("unavailable 雪")) + assert.deepEqual(done.value.path, ["tools", "done"]) + assert.equal(done.value.protected, false) + assert.equal(resume(vm, true).value, true) +}) + +test("finite work budgets cover empty bodies, tail calls, scopes and nested pcall", () => { + for (const source of [ + "for i=1,1000000 do end", + "local i=0; repeat i=i+1 until i==1000000", + "local i=0; while i<1000000 do i=i+1 end", + "local function tail(n) if n==0 then return end; return tail(n-1) end; tail(1000000)", + ]) + fault(`return pcall(function() ${source} end)`, "ExecutionFailure", /work limit/) + fault("local function f() return 1+f() end; return pcall(f)", "ExecutionFailure", /stack overflow/) + fault("local function f() return pcall(f) end; return pcall(f)", "ExecutionFailure", /depth limit/) +}) + +test("growing tables, strings and native operations charge before materialization", () => { + for (const [source, msg] of [ + ["return string.rep('x',2^40)", /size limit/], + ["local t={} for i=1,9000 do t[i]=i end", /entry limit/], + ["local s='a' for i=1,22 do s=s..s end", /size limit/], + ["return table.concat({}, '', 1, 2^50)", /concat range/], + ["local s=string.rep('x',200000); for i=1,64 do string.lower(s) end", /allocation limit/], + ["local t=tools; for i=1,64 do t=t.x end", /path exceeds/], + ]) + fault(`return pcall(function() ${source} end)`, "ExecutionFailure", msg) + assert.equal(run('return table.concat({("abc"):upper(),("world"):sub(2,-2),string.rep("!",2)}, " ")'), "ABC orl !!") + assert.equal( + run("return string.find == nil and string.gsub == nil and string.format == nil and table.sort == nil"), + true, + ) +}) + +test("the JSON boundary preserves data, rejects unsafe values and bounds expanded DAGs", () => { + assert.deepEqual(run("return {x[1],x[2],json.null,json.array()}", { x: [null, "λ"] }), [null, "λ", null, []]) + assert.deepEqual(run("return {}"), Object.create(null)) + assert.equal(run("return #{'a'}, 200"), 1) + assert.equal(run("return #'💫'"), 4) + assert.equal(run("return nil"), undefined) + for (const source of [ + "return {[2]=1}", + "return {1,b=2}", + "return {tool=tools.call}", + "return 0/0", + "local t={};t.self=t;return t", + "return '\\255'", + "return {__proto__={}}", + ]) + fault(source, "InvalidDataValue", /Lua|JSON|Circular|contiguous/) + fault("local t=1; for i=1,30 do t={t,t} end return t", "ExecutionFailure", /work limit/) + fault("local s=string.rep('\\000',200000); return s", "InvalidDataValue", /boundary byte limit/) +}) + +test("no JS prototypes, ambient libraries, loaders, raw VM objects or host method lookup", () => { + assert.equal( + run( + `return os==nil and io==nil and require==nil and package==nil and debug==nil and coroutine==nil and load==nil and loadstring==nil and _G==nil and getfenv==nil and setmetatable==nil and string.dump==nil and ({}).constructor==nil and ('').constructor==nil and ('').__proto__==nil`, + ), + true, + ) + assert.throws( + () => resume(evaluateLua("return fetch.constructor()", { paths: [["fetch"]] })), + /Cannot index Lua function/, + ) + assert.throws(() => run("return string.rep.constructor"), /Cannot index Lua function/) + assert.throws(() => run("table.insert = 1"), /read-only/) + assert.throws(() => run("tools = {}"), /reserved/) + assert.equal(run("local tools=5; return tools"), 5) +}) + +test("parser limits run before evaluation and diagnostics retain the failing line", () => { + fault("return '" + "x".repeat(32768) + "'", "ParseError", /source exceeds/) + fault("return " + "{".repeat(10000) + "1" + "}".repeat(10000), "ParseError", /nesting/) + fault("return " + "1+".repeat(2000) + "1", "ParseError", /nesting/) + fault("--[" + "=".repeat(1000) + "[", "ParseError", /delimiter/) + assert.throws( + () => run("local a={}\nreturn a.missing()"), + (e) => e.location.line === 2, + ) + assert.equal(run("return 7"), 7) +}) diff --git a/packages/codemode/lua/vm.js b/packages/codemode/lua/vm.js index 6b164225705..af5fb21db8a 100644 --- a/packages/codemode/lua/vm.js +++ b/packages/codemode/lua/vm.js @@ -5,15 +5,61 @@ import { LuaError, LuaTable, NativeFunction, + arith, + compare, + concat, getMetatable, + index, + len, + luaToNumber, + newindex, shortSrc, + truthy, typeName, } from "v8lua/src/runtime.js" -import { Call, Frame } from "./evaluate.js" +import { Call, runFrames } from "./evaluate.js" const boundaryError = "attempt to yield across metamethod/C-call boundary" export class VM { + ops = { + table: () => new LuaTable(), + closure: (...args) => new LuaClosure(...args), + error: (message) => new LuaError(message), + stackOverflow: () => new LuaError("stack overflow"), + number: luaToNumber, + truthy, + index: (a, b) => this.atomic(index(a, b)), + newindex: (a, b, c) => this.atomic(newindex(a, b, c)), + len: (a) => this.atomic(len(a)), + arith: (op, a, b) => this.atomic(arith(op, a, b)), + compare: (op, a, b) => this.atomic(compare(op, a, b)), + concat: (a, b) => this.atomic(concat(a, b)), + } + poll() { + return false + } + charge() {} + *iterate(fn, args) { + return this.atomic(this.invoke(fn, args)) + } + frameLimit = 20000 + isClosure(fn) { + return fn instanceof LuaClosure + } + resolveCall(call) { + const fn = call.fn + if (fn instanceof LuaClosure || fn instanceof NativeFunction) return call + const handler = getMetatable(fn)?.get("__call") + if (!(handler instanceof LuaClosure || handler instanceof NativeFunction)) + throw new LuaError(`attempt to call a ${typeName(fn)} value`) + return new Call(handler, [fn, ...call.args]) + } + *native(fn, args) { + if (fn !== this.yieldFn) return this.atomic(fn.fn(this, args)) ?? [] + if (this.thread === this.main || this.thread.barriers) throw new LuaError(boundaryError) + return yield args + } globals = new LuaTable() main = { frames: [], barriers: 0 } thread = this.main @@ -61,49 +107,8 @@ export class VM { const thread = this.thread const frames = thread.frames const base = frames.length - let call = new Call(fn, args) - let values try { - for (;;) { - if (call) { - let { fn, args } = call - if (!(fn instanceof LuaClosure || fn instanceof NativeFunction)) { - const handler = getMetatable(fn)?.get("__call") - if (!(handler instanceof LuaClosure || handler instanceof NativeFunction)) - throw new LuaError(`attempt to call a ${typeName(fn)} value`) - args = [fn, ...args] - fn = handler - } - if (fn instanceof LuaClosure) { - if (frames.length > base && frames.at(-1).tail) frames.pop() - if (frames.length >= 20000) throw new LuaError("stack overflow") - frames.push(new Frame(this, fn, args)) - values = undefined - } else if (fn === this.yieldFn) { - if (thread === this.main || thread.barriers) throw new LuaError(boundaryError) - values = yield args - } else { - values = this.atomic(fn.fn(this, args)) ?? [] - } - call = undefined - } - - if (frames.length === base) return values - const frame = frames.at(-1) - if (frame.tail) { - frames.pop() // a tail-called native just returned - continue - } - const step = frame.code.next(values) - if (step.value instanceof Call) { - frame.tail = step.done - call = step.value - continue - } - if (!step.done) throw new Error("invalid Lua frame suspension") - values = step.value ?? [] - frames.pop() - } + return yield* runFrames(this, frames, new Call(fn, args)) } catch (e) { const err = e instanceof RangeError ? new LuaError("stack overflow") : e if (err instanceof LuaError && !err.positioned && frames.length > base) { diff --git a/packages/codemode/package.json b/packages/codemode/package.json index 34a41d3b3b3..27d0820916a 100644 --- a/packages/codemode/package.json +++ b/packages/codemode/package.json @@ -28,7 +28,8 @@ }, "dependencies": { "acorn": "8.15.0", - "effect": "catalog:" + "effect": "catalog:", + "luaparse": "0.3.1" }, "devDependencies": { "@tsconfig/bun": "catalog:", diff --git a/packages/codemode/script/build.ts b/packages/codemode/script/build.ts index 323a63ddf96..abe787a52b6 100644 --- a/packages/codemode/script/build.ts +++ b/packages/codemode/script/build.ts @@ -7,3 +7,6 @@ process.chdir(fileURLToPath(new URL("..", import.meta.url))) await $`rm -rf dist` await $`bun tsc -p tsconfig.build.json` +await $`bun build src/lua-sandbox.ts --format=esm --target=node --outfile=dist/lua-sandbox.js` +await Bun.write("dist/lua-sandbox.d.ts", Bun.file("lua/sandbox.d.ts")) +await Bun.write("dist/LICENSE.luaparse", Bun.file("node_modules/luaparse/LICENSE")) diff --git a/packages/codemode/script/pack.ts b/packages/codemode/script/pack.ts index 28c039c7157..162d26c6d30 100644 --- a/packages/codemode/script/pack.ts +++ b/packages/codemode/script/pack.ts @@ -16,8 +16,14 @@ try { JSON.stringify({ private: true, type: "module", dependencies: { "@opencode/codemode": `file:${tarball}` } }), ) await $`npm install --ignore-scripts --no-audit --no-fund`.cwd(consumer) - await $`node --input-type=module -e ${'await import("@opencode/codemode")'}`.cwd(consumer) - await $`bun --conditions=workerd -e ${'await import("@opencode/codemode")'}`.cwd(consumer) + const smoke = ` + import { CodeMode } from "@opencode/codemode" + import { Effect } from "effect" + const result = await Effect.runPromise(CodeMode.execute({ language: "lua", code: "local x = 2; return x + 3" })) + if (!result.ok || result.value !== 5) throw Error(JSON.stringify(result)) + ` + await $`node --input-type=module -e ${smoke}`.cwd(consumer) + await $`bun --conditions=workerd -e ${smoke}`.cwd(consumer) } finally { await rm(consumer, { recursive: true, force: true }) } diff --git a/packages/codemode/src/codemode.ts b/packages/codemode/src/codemode.ts index f9d7a877029..41e877dc3a7 100644 --- a/packages/codemode/src/codemode.ts +++ b/packages/codemode/src/codemode.ts @@ -1,6 +1,7 @@ import { Effect, Schema } from "effect" import { fromJson } from "./data.js" import type { Extension } from "./extension.js" +import { isLua } from "./extension.js" import { executeProgram } from "./interpreter/execute.js" import { extensionGlobals } from "./interpreter/extensions.js" import { globalNames } from "./interpreter/globals.js" @@ -20,20 +21,20 @@ export type { ToolInvocation, } from "./tool-runtime.js" /** Signature-construction helpers for host-owned catalog instructions. */ -export { searchSignature, toolExpression } from "./tool-runtime.js" +export { luaSearchSignature, searchSignature, toolExpression } from "./tool-runtime.js" /** Resource budgets enforced independently during each CodeMode program execution. */ export type ExecutionLimits = { /** * Wall-clock milliseconds before interruption. Result delivery waits for tool cleanup. - * No default: absent means no timeout. + * Defaults to two minutes in Lua, no timeout in JavaScript. */ readonly timeoutMs?: number - /** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */ + /** Lua: host call attempts (tools, search and extensions), default 128. JavaScript: admitted tools, unlimited by default. */ readonly maxToolCalls?: number /** * Maximum UTF-8 bytes retained from the result and logs. Warnings have a separate equal budget; - * truncation notices and host formatting are additional. + * truncation notices and host formatting are additional. Defaults to 64 KiB in Lua, unlimited in JavaScript. */ readonly maxOutputBytes?: number } @@ -46,6 +47,8 @@ export type ResolvedExecutionLimits = { /** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */ export type Options = {}, Extensions extends ReadonlyArray = []> = { + /** Select the parser and runtime explicitly. Existing library callers default to JavaScript. */ + language?: "javascript" | "lua" /** Explicit tools exposed to the program as `tools`. */ tools?: Provided & Tools> /** Hooks around every tool and extension call the program makes; see `Hooks`. */ @@ -66,7 +69,7 @@ export type ExecuteOptions< Provided extends Record = {}, Extensions extends ReadonlyArray = [], > = Options & { - /** Source for one program in the supported JavaScript subset. */ + /** Source for one program in the selected language. No syntax detection or fallback. */ code: string /** Read-only JSON values bound in the program's outer global scope (shadowable by top-level declarations). */ bindings?: Readonly> @@ -166,13 +169,37 @@ export const make = < >( options: Options = {}, ): Runtime> => { + if (options.language !== undefined && options.language !== "lua" && options.language !== "javascript") { + throw new TypeError(`Unsupported Code Mode language '${options.language}'.`) + } const prepared = ToolRuntime.prepare>( (options.tools ?? {}) as Tools>, + options.language, ) const limits = resolveExecutionLimits(options.limits) const extensions = options.extensions ?? [] + if (options.language === "lua") { + const hooks = options.hooks ?? {} + const globals = luaGlobals(extensions, hooks) + const budget = { + timeoutMs: limits.timeoutMs ?? 120_000, + maxToolCalls: limits.maxToolCalls ?? 128, + maxOutputBytes: limits.maxOutputBytes ?? 65_536, + } + return { + get catalog() { + return prepared.catalog + }, + execute: (code, bindings) => + Effect.gen(function* () { + const { executeLua } = yield* Effect.promise(() => import("./lua.js")) + return yield* executeLua(code, prepared, budget, hooks, bindings, globals) + }), + } + } const bound = new Set(globalNames) for (const extension of extensions) { + if (isLua(extension)) throw new TypeError("A Lua extension requires language: 'lua'.") for (const name of Object.keys(extension.globals)) { if (bound.has(name)) throw new TypeError(`Extension "${extension.name}" global "${name}" is already defined.`) bound.add(name) @@ -189,3 +216,27 @@ export const make = < ]), } } + +// Only these exact names may enter host code. The Lua bridge copies arguments and checks +// return values as bounded JSON; unlike the JavaScript extension API there are no object methods. +function luaGlobals(extensions: ReadonlyArray, hooks: ToolRuntime.Hooks) { + const globals = new Map) => Effect.Effect>() + for (const extension of extensions) { + if (!isLua(extension)) + throw new TypeError(`Declare Lua capabilities with Extension.lua (extension '${extension.name}').`) + for (const [name, fn] of Object.entries(extension.globals)) { + if (globals.has(name)) throw new TypeError(`Duplicate Lua extension global '${name}'.`) + // The extension's concrete environment is already included in R by Extension.Services. + const call = fn as (...args: Array) => Effect.Effect + globals.set(name, (args) => + ToolRuntime.hooked( + { extension: extension.name, name, args }, + hooks["extension.before"], + hooks["extension.after"], + Effect.suspend(() => call(...args)), + ), + ) + } + } + return globals +} diff --git a/packages/codemode/src/extension.ts b/packages/codemode/src/extension.ts index e7a6103e7a2..3c9c642c766 100644 --- a/packages/codemode/src/extension.ts +++ b/packages/codemode/src/extension.ts @@ -1,6 +1,6 @@ export * as Extension from "./extension.js" -import type { Effect } from "effect" +import type { Effect, Schema } from "effect" /** * Host values a program reaches directly as globals: functions, or objects of functions such as `fs`. Values crossing @@ -52,3 +52,19 @@ export const async = (global: F): F => { } export const isAsync = (global: Function) => global instanceof AsyncFunction || asyncGlobals.has(global) + +const luaExtensions = new WeakSet() +type LuaGlobal = (...args: Array) => Effect.Effect + +/** Declare named Lua capabilities. The trusted callback returns an Effect, never a guest-selected thenable or host handle. */ +export const lua = >>(options: Extension) => { + for (const [name, fn] of Object.entries(options.globals)) { + if (typeof fn !== "function") throw new TypeError(`Lua global '${name}' must be an Effect-returning function.`) + } + const extension = make(options) + luaExtensions.add(extension) + return extension +} + +export const isLua = (extension: Extension): extension is Extension> => + luaExtensions.has(extension) diff --git a/packages/codemode/src/index.ts b/packages/codemode/src/index.ts index 650483f030a..6bed53d7925 100644 --- a/packages/codemode/src/index.ts +++ b/packages/codemode/src/index.ts @@ -3,5 +3,5 @@ export * as Extension from "./extension.js" export * as Namespace from "./namespace.js" export * as Tool from "./tool.js" export * as OpenAPI from "./openapi/index.js" -export { searchSignature, toolExpression } from "./codemode.js" +export { luaSearchSignature, searchSignature, toolExpression } from "./codemode.js" export { ToolError, toolError } from "./tool-error.js" diff --git a/packages/codemode/src/interpreter/execute.ts b/packages/codemode/src/interpreter/execute.ts index 79af64cdb0b..09f98d1a87d 100644 --- a/packages/codemode/src/interpreter/execute.ts +++ b/packages/codemode/src/interpreter/execute.ts @@ -167,7 +167,7 @@ const utf8Truncate = (value: string, maxBytes: number): string => { } // Warnings have a separate budget so result data cannot starve diagnostics. -const boundOutput = (result: Result, maxOutputBytes: number): Result => { +export const boundOutput = (result: Result, maxOutputBytes: number): Result => { let truncated = false let value: DataValue = null diff --git a/packages/codemode/src/lua-data.ts b/packages/codemode/src/lua-data.ts new file mode 100644 index 00000000000..63d74ddd2ff --- /dev/null +++ b/packages/codemode/src/lua-data.ts @@ -0,0 +1,99 @@ +import { Buffer } from "node:buffer" +import { isProxy } from "node:util/types" +import type { Json } from "./data.js" + +// Bound the expanded tree, not just distinct JS objects. A tiny DAG can otherwise +// become gigabytes during schema decoding, Lua table construction, or stringify. +const maxNodes = 32_768 +const maxBytes = 1_048_576 +const maxDepth = 32 + +export class LuaDataError extends Error {} +export class LuaDataLimit extends LuaDataError {} + +export function isLuaDataLimit(error: unknown): boolean { + return ( + error !== null && + typeof error === "object" && + !isProxy(error) && + Object.getPrototypeOf(error) === LuaDataLimit.prototype + ) +} + +export function copyLuaData(input: unknown): Json | undefined { + if (input === undefined) return undefined // a void host call, not a nested JSON value + const active = new Set() + let nodes = 0 + let bytes = 0 + + function charge(size: number) { + bytes += size + if (bytes > maxBytes) throw new LuaDataLimit("Lua data exceeds the byte limit.") + } + + function string(text: string) { + // Reject huge host strings before encoding. JSON escaping (including lone + // surrogates) counts against the same limit as literal UTF-8 bytes. + if (text.length + bytes + 2 > maxBytes) throw new LuaDataLimit("Lua data exceeds the byte limit.") + // The VM uses UTF-8 byte strings. Replacing a lone surrogate could silently + // merge two distinct JSON keys into the same Lua table entry. + if (!text.isWellFormed()) throw new LuaDataError("Lua JSON strings must contain valid Unicode.") + charge(Buffer.byteLength(JSON.stringify(text))) + } + + function copy(value: unknown, depth: number): Json { + if (++nodes > maxNodes) throw new LuaDataLimit("Lua data exceeds the node limit.") + if (depth > maxDepth) throw new LuaDataLimit("Lua data exceeds the nesting limit.") + if (typeof value === "string") { + string(value) + return value + } + if (value === null || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) { + charge(String(value).length) + return value === 0 ? 0 : value + } + if (typeof value !== "object" || isProxy(value)) throw new LuaDataError("Expected plain JSON data.") + if (active.has(value)) throw new LuaDataError("Cyclic Lua data.") + active.add(value) + const array = Array.isArray(value) + const proto = Object.getPrototypeOf(value) + if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) + throw new LuaDataError("Expected a plain JSON array or record.") + if (array && value.length > maxNodes - nodes) throw new LuaDataLimit("Lua data exceeds the node limit.") + // oxlint-disable-next-line no-restricted-globals -- reject symbol/nonenumerable keys without invoking getters. + const keys = Reflect.ownKeys(value) + const count = keys.length - Number(array) + if (count > maxNodes - nodes) throw new LuaDataLimit("Lua data exceeds the node limit.") + if (array && count !== value.length) throw new LuaDataError("Expected a dense JSON array.") + charge(2 + Math.max(0, count - 1)) + const items: Array = [] + const record: Record = Object.create(null) + for (const key of keys) { + if (array && key === "length") continue + if (typeof key !== "string" || (array && key !== String(items.length))) + throw new LuaDataError("Expected JSON data keys.") + const descriptor = Object.getOwnPropertyDescriptor(value, key) + if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) + throw new LuaDataError("Expected enumerable JSON data properties, not accessors.") + if (!array) { + string(key) + charge(1) + } + const child = copy(descriptor.value, depth + 1) + if (array) items.push(child) + else record[key] = child + } + active.delete(value) + return array ? items : record + } + + return copy(input, 0) +} + +/** Never format the host's arbitrary thrown object (toString, getters or proxy traps). */ +export function luaErrorMessage(error: unknown, fallback = "Host call failed."): string { + if (typeof error === "string") return error.slice(0, 2048) + if (error === null || typeof error !== "object" || isProxy(error)) return fallback + const message: unknown = Object.getOwnPropertyDescriptor(error, "message")?.value + return typeof message === "string" ? message.slice(0, 2048) : fallback +} diff --git a/packages/codemode/src/lua-sandbox.ts b/packages/codemode/src/lua-sandbox.ts new file mode 100644 index 00000000000..2e7517fa645 --- /dev/null +++ b/packages/codemode/src/lua-sandbox.ts @@ -0,0 +1,2 @@ +// The published build bundles this entry so consumers use the same patched parser and VM as the workspace. +export * from "../lua/sandbox.js" diff --git a/packages/codemode/src/lua.ts b/packages/codemode/src/lua.ts new file mode 100644 index 00000000000..181c8fc871b --- /dev/null +++ b/packages/codemode/src/lua.ts @@ -0,0 +1,175 @@ +import { Buffer } from "node:buffer" +import { isProxy } from "node:util/types" +import { Cause, Effect } from "effect" +import { evaluateLua, hostFailure, LuaFault } from "./lua-sandbox.js" +import type { Diagnostic, ResolvedExecutionLimits, Result } from "./codemode.js" +import type { Json } from "./data.js" +import { boundOutput } from "./interpreter/execute.js" +import { copyLuaData, isLuaDataLimit, LuaDataError, luaErrorMessage } from "./lua-data.js" +import { ToolError } from "./tool-error.js" +import { ToolRuntime } from "./tool-runtime.js" + +/** Each next() runs guest instructions until a slice, an explicit capability call, or return. + * Host work stays on this fiber: interruption/timeout waits for the same hook and tool cleanup as JS. */ +export function executeLua( + code: string, + prepared: ToolRuntime.Prepared, + limits: ResolvedExecutionLimits, + hooks: ToolRuntime.Hooks, + bindings?: Readonly>, + globals?: ReadonlyMap) => Effect.Effect>, +): Effect.Effect { + return Effect.suspend(() => { + const tools = ToolRuntime.make(prepared, limits.maxToolCalls, hooks, { + copy: copyLuaData, + message: luaErrorMessage, + isLimit: isLuaDataLimit, + }) + const logs: Array = [] + const logLimit = Math.min(1_048_576, limits.maxOutputBytes ?? Infinity) + let logBytes = 0 + let omitted = 0 + const metadata = () => ({ + toolCalls: tools.calls, + ...(omitted + ? { logs: [...logs, `[logs truncated: ${omitted} lines omitted]`], truncated: true } + : logs.length + ? { logs } + : {}), + }) + + const run = Effect.gen(function* () { + const data = copyLuaData(bindings === undefined ? {} : bindings) + if (!isRecord(data)) throw new LuaDataError("Expected Lua bindings to be a JSON record.") + const paths = [["tools"], ["search"], ["print"], ...Array.from(globals?.keys() ?? [], (key) => [key])] + const vm = evaluateLua(code, { paths, bindings: data }) + return yield* Effect.gen(function* () { + let resume: Json | undefined | ReturnType + while (true) { + const step = vm.next(resume) + if (step.done) return { ok: true, value: step.value ?? null, ...metadata() } satisfies Result + resume = undefined + if (step.value.type === "tick") { + yield* Effect.yieldNow + continue + } + const { path, args } = step.value + if (path.length === 1 && path[0] === "print") { + if (omitted || logBytes >= logLimit) { + omitted++ + continue + } + const line = args + .map((v) => (v === undefined ? "nil" : typeof v === "string" ? v : JSON.stringify(v))) + .join("\t") + logBytes += Buffer.byteLength(line) + 1 + if (logBytes <= logLimit) logs.push(line) + else omitted++ + continue + } + const dispatch = Effect.suspend(() => { + if (path[0] === "tools") return tools.execute(path.slice(1), args) + if (path.length !== 1) throw new Error("Unknown Lua capability.") + if (path[0] === "search") return tools.search(args) + const call = globals?.get(path[0]) + if (!call) throw new Error("Unknown Lua capability.") + tools.admit() + return Effect.map(call(args), copyLuaData) + }) + resume = yield* step.value.protected ? dispatch.pipe(Effect.catchCause(recoverHostFailure)) : dispatch + } + }).pipe(Effect.ensuring(Effect.sync(() => vm.return(undefined)))) + }) + + const timeout = limits.timeoutMs + return ( + timeout === undefined + ? run + : run.pipe( + Effect.timeoutOrElse({ + duration: timeout, + orElse: () => + Effect.succeed({ + ok: false, + error: { kind: "TimeoutExceeded", message: `Execution timed out after ${timeout}ms.` }, + ...metadata(), + } satisfies Result), + }), + ) + ).pipe( + Effect.catchCause((cause) => + Cause.hasInterrupts(cause) + ? Effect.interrupt + : Effect.succeed({ + ok: false, + error: diagnostic(Cause.squash(cause)), + ...metadata(), + } satisfies Result), + ), + Effect.map((result) => + limits.maxOutputBytes === undefined ? result : boundOutput(result, limits.maxOutputBytes), + ), + ) + }) +} + +function recoverHostFailure(cause: Cause.Cause) { + // A hook/finalizer can contribute a second reason. A budget or interruption + // remains fatal even if it isn't the reason squash() would select. + for (const reason of cause.reasons) { + if (reason._tag === "Interrupt") return Effect.failCause(cause) + const error = reason._tag === "Fail" ? reason.error : reason.defect + if (isLuaDataLimit(error) || ToolRuntime.isBudgetFailure(error)) return Effect.failCause(cause) + } + return Effect.succeed(hostFailure(luaErrorMessage(Cause.squash(cause)))) +} + +function isRecord(value: Json | undefined): value is Readonly> { + return typeof value === "object" && value !== null && !Array.isArray(value) +} + +function diagnostic(error: unknown): Diagnostic { + const message = luaErrorMessage(error) + if (error !== null && typeof error === "object" && !isProxy(error)) { + const proto = Object.getPrototypeOf(error) + if (proto === LuaDataError.prototype || isLuaDataLimit(error)) return { kind: "InvalidDataValue", message } + if (proto === ToolError.prototype) return { kind: "ToolFailure", message } + // Hooks can fail with any value, including an error with forged prototype + // or accessor properties. Read diagnostic metadata as bounded own data. + const kind: unknown = Object.getOwnPropertyDescriptor(error, "kind")?.value + if ( + proto === LuaFault.prototype && + (kind === "ParseError" || + kind === "UnsupportedSyntax" || + kind === "ExecutionFailure" || + kind === "InvalidDataValue") + ) { + const loc: unknown = Object.getOwnPropertyDescriptor(error, "location")?.value + if (typeof loc === "object" && loc !== null && !isProxy(loc)) { + const line: unknown = Object.getOwnPropertyDescriptor(loc, "line")?.value + const column: unknown = Object.getOwnPropertyDescriptor(loc, "column")?.value + if ( + typeof line === "number" && + typeof column === "number" && + Number.isSafeInteger(line) && + Number.isSafeInteger(column) + ) + return { kind, message, location: { line, column } } + } + return { kind, message } + } + if ( + proto === ToolRuntime.ToolRuntimeError.prototype && + (kind === "UnknownTool" || + kind === "InvalidToolInput" || + kind === "InvalidToolOutput" || + kind === "ToolCallLimitExceeded") + ) { + const hints: unknown = Object.getOwnPropertyDescriptor(error, "suggestions")?.value + const hint: unknown = + hints && !isProxy(hints) && Array.isArray(hints) && Object.getOwnPropertyDescriptor(hints, "0")?.value + return { kind, message, ...(typeof hint === "string" ? { suggestions: [hint.slice(0, 2048)] } : {}) } + } + } + return { kind: "ExecutionFailure", message } +} diff --git a/packages/codemode/src/tool-runtime.ts b/packages/codemode/src/tool-runtime.ts index 8660d4fd630..1a9d4fd36c8 100644 --- a/packages/codemode/src/tool-runtime.ts +++ b/packages/codemode/src/tool-runtime.ts @@ -5,11 +5,12 @@ import { toolError } from "./tool-error.js" import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, - identifierSegment, + type Language, + member, inputProperties, - inputTypeScript, + inputType, isEmptyInput, - outputTypeScript, + outputType, } from "./tool-schema.js" import { isNamespace, type Namespace } from "./namespace.js" import { isTool, type Tool } from "./tool.js" @@ -98,6 +99,15 @@ const SearchInput = Schema.Struct({ limit: Schema.optionalKey(PositiveInt), offset: Schema.optionalKey(NonNegativeInt), }) +// A guest query is ranked against the entire host catalog before the VM can yield again. +const luaSearchLength = 512 +const luaSearchText = Schema.String.check(Schema.isMaxLength(luaSearchLength)) +const LuaSearchInput = Schema.Struct({ + query: Schema.optionalKey(luaSearchText), + namespace: Schema.optionalKey(luaSearchText), + limit: Schema.optionalKey(PositiveInt.check(Schema.isLessThanOrEqualTo(50))), + offset: Schema.optionalKey(NonNegativeInt), +}) const SearchItem = Schema.Struct({ path: Schema.String, description: Schema.String, @@ -108,11 +118,11 @@ const SearchOutput = Schema.Struct({ remaining: NonNegativeInt, next: Schema.NullOr(Schema.Struct({ offset: NonNegativeInt })), }) -export const toolExpression = (path: string) => +export const toolExpression = (path: string, language: Language = "javascript") => "tools" + path .split(".") - .map((segment) => (identifierSegment.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`)) + .map((segment) => member(segment, language)) .join("") export class ToolReference { @@ -169,7 +179,7 @@ const flattenTools = ( ] } -const describeTool = (visible: VisibleTool): ToolDescription => { +const describeTool = (visible: VisibleTool, language: Language): ToolDescription => { let signature: string | undefined return { path: visible.path, @@ -177,17 +187,14 @@ const describeTool = (visible: VisibleTool): ToolDescription => { get signature() { // Search ranks paths and descriptions first; only returned matches need their schemas rendered. // Joining the final fragments avoids retaining the rendering's intermediate string ropes in JSC. - return (signature ??= [ - toolExpression(visible.path), - isEmptyInput(visible.tool) ? "()" : `(${inputTypeScript(visible.tool, true)})`, - `: Promise<${outputTypeScript(visible.tool, true)}>`, - ].join("")) + return (signature ??= signatureOf(toolExpression(visible.path, language), visible.tool, language)) }, } } /** Tools indexed once per runtime, with discovery materialized on demand. */ export type Prepared = { + readonly language: Language readonly root: ToolNode readonly catalog: ReadonlyArray readonly searchIndex: ReadonlyArray @@ -214,8 +221,9 @@ const termForms = (term: string): Array => { return forms } -const rank = (entries: ReadonlyArray, query: string): Array => { - const terms = tokenize(query).map(termForms) +const rank = (entries: ReadonlyArray, query: string, language: Language): Array => { + const words = tokenize(query) + const terms = (language === "lua" ? words.slice(0, 16) : words).map(termForms) return entries .map((entry) => { const path = entry.description.path.toLowerCase() @@ -240,10 +248,10 @@ const rank = (entries: ReadonlyArray, query: string): Array entry) } -const makeSearchTool = (searchIndex: ReadonlyArray): Tool => ({ +const makeSearchTool = (searchIndex: ReadonlyArray, language: Language): Tool => ({ _tag: "CodeModeTool", description: "Search available tools", - input: SearchInput, + input: language === "lua" ? LuaSearchInput : SearchInput, output: SearchOutput, execute: (input) => Effect.sync(() => { @@ -265,12 +273,13 @@ const makeSearchTool = (searchIndex: ReadonlyArray): Tool => ({ pathQuery === "" ? undefined : scoped.find( - (entry) => entry.description.path === pathQuery || toolExpression(entry.description.path) === trimmed, + (entry) => + entry.description.path === pathQuery || toolExpression(entry.description.path, language) === trimmed, ) - const ranked = exact !== undefined ? [exact] : rank(scoped, query) + const ranked = exact !== undefined ? [exact] : rank(scoped, query, language) const items = ranked.slice(offset, offset + (request.limit ?? defaultSearchLimit)).map(({ description }) => ({ ...description, - path: toolExpression(description.path), + path: toolExpression(description.path, language), })) const remaining = Math.max(0, ranked.length - offset - items.length) return { @@ -281,14 +290,24 @@ const makeSearchTool = (searchIndex: ReadonlyArray): Tool => ({ }), }) -/** Exact callable signature of the built-in `search` function, for host-owned instructions. */ -export const searchSignature = (() => { - const tool = makeSearchTool([]) - return `search(${inputTypeScript(tool, true)}): ${outputTypeScript(tool, true)}` -})() +function signatureOf(name: string, tool: Tool, language: Language, global = false) { + const input = isEmptyInput(tool) ? "" : inputType(tool, true, language) + const output = outputType(tool, true, language) + return [ + name, + "(", + input, + ")", + language === "lua" ? ` -> ${output}` : global ? `: ${output}` : `: Promise<${output}>`, + ].join("") +} -const toSearchEntry = (visible: VisibleTool): SearchEntry => ({ - description: describeTool(visible), +/** Exact callable signatures of the built-in `search` function, for host-owned instructions. */ +export const searchSignature = signatureOf("search", makeSearchTool([], "javascript"), "javascript", true) +export const luaSearchSignature = signatureOf("search", makeSearchTool([], "lua"), "lua", true) + +const toSearchEntry = (visible: VisibleTool, language: Language): SearchEntry => ({ + description: describeTool(visible, language), pathWords: tokenize(visible.path), searchText: [ visible.path, @@ -302,11 +321,12 @@ const toSearchEntry = (visible: VisibleTool): SearchEntry => ({ .toLowerCase(), }) -export const prepare = (tools: Tools): Prepared => { +export const prepare = (tools: Tools, language: Language = "javascript"): Prepared => { const root = toolTrie(tools) let searchIndex: ReadonlyArray | undefined let catalog: ReadonlyArray | undefined return { + language, root, get catalog() { return (catalog ??= this.searchIndex.map((entry) => entry.description)) @@ -316,7 +336,7 @@ export const prepare = (tools: Tools): Prepared => { // ordering after canonical-path collisions settle so instruction bytes stay deterministic. return (searchIndex ??= flattenTools(root) .sort((left, right) => compareText(left.path, right.path)) - .map(toSearchEntry)) + .map((visible) => toSearchEntry(visible, language))) }, } } @@ -333,20 +353,26 @@ const namespaceKeys = (root: ToolNode, path: ReadonlyArray): Reado return Array.from(node.children.keys()) } -const resolve = (root: ToolNode, path: ReadonlyArray, index: ReadonlyArray): Tool => { +const resolve = (prepared: Prepared, path: ReadonlyArray): Tool => { const segments = canonicalSegments(path) - const node = lookup(root, segments) + const node = lookup(prepared.root, segments) if (node === undefined) { const name = segments.join(".") - const ns = segments.length > 1 && root.children.has(segments[0]) ? segments[0] : undefined + if (prepared.language === "lua" && name.length > luaSearchLength) + throw new ToolRuntimeError("UnknownTool", "Unknown tool (path too long for suggestions).", [ + "Use search to find available tools.", + ]) + const ns = segments.length > 1 && prepared.root.children.has(segments[0]) ? segments[0] : undefined + const index = prepared.searchIndex const closest = rank( ns ? index.filter((entry) => entry.description.path.startsWith(`${ns}.`)) : index, ns ? segments.slice(1).join(" ") : name, + prepared.language, )[0] throw new ToolRuntimeError( "UnknownTool", closest - ? `Unknown tool '${name}'. Did you mean ${toolExpression(closest.description.path)}?` + ? `Unknown tool '${name}'. Did you mean ${toolExpression(closest.description.path, prepared.language)}?` : `Unknown tool '${name}'.`, ["Use search to find available tools."], ) @@ -357,6 +383,12 @@ const resolve = (root: ToolNode, path: ReadonlyArray, index: Reado return node.tool } +// Errors can be observed by hooks before the Lua driver sees them. Keep the +// budget marker outside the value so rewriting an error can't make it catchable. +const budgetFailures = new WeakSet() +export const isBudgetFailure = (error: unknown) => + typeof error === "object" && error !== null && budgetFailures.has(error) + export class ToolRuntimeError extends Error { constructor( readonly kind: Extract< @@ -365,15 +397,19 @@ export class ToolRuntimeError extends Error { >, message: string, readonly suggestions: ReadonlyArray = [], + fatal = false, ) { super(message) this.name = "ToolRuntimeError" + if (fatal || kind === "ToolCallLimitExceeded") budgetFailures.add(this) } } /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */ export type ToolRuntime = { readonly calls: Array + /** Charge a non-tool host capability against this execution's call budget. */ + readonly admit: () => void readonly hooks: Hooks readonly execute: ( path: ReadonlyArray, @@ -388,15 +424,21 @@ export const make = ( prepared: Prepared, maxToolCalls: number | undefined, hooks: Hooks = {}, + boundary?: { + copy: (value: unknown) => Json | undefined + message: (error: unknown, fallback?: string) => string + isLimit: (error: unknown) => boolean + }, ): ToolRuntime => { const calls: Array = [] const root = prepared.root - const recordCall = (call: ToolCall): void => { - if (maxToolCalls !== undefined && calls.length >= maxToolCalls) { + let admitted = 0 + const admit = (): void => { + if (maxToolCalls !== undefined && admitted >= maxToolCalls) { throw new ToolRuntimeError("ToolCallLimitExceeded", `Execution exceeded its tool-call limit of ${maxToolCalls}.`) } - calls.push(call) + admitted++ } const executeTool = (name: string, tool: Tool, args: Array) => @@ -409,19 +451,26 @@ export const make = ( catch: (cause) => new ToolRuntimeError( "InvalidToolInput", - `Invalid input for tool '${name}': ${String(cause)}`, + `Invalid input for tool '${name}': ${boundary ? boundary.message(cause, "Value does not match the input schema.") : String(cause)}`, name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."], ), }) - yield* Effect.sync(() => recordCall({ name })) + if (!boundary) admit() + calls.push({ name }) + const after = hooks["tool.after"] return yield* hooked( { name, input }, hooks["tool.before"], - hooks["tool.after"], + // Do not give a hook a reference to data the suspended Lua VM will import. + boundary && after + ? (call, result) => + after(call, result.status === "success" ? { ...result, value: boundary.copy(result.value) } : result) + : after, Effect.gen(function* () { const raw = yield* Effect.suspend(() => tool.execute(input)).pipe( Effect.catchCause((cause) => { - if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt + if (boundary ? Cause.hasInterrupts(cause) : Cause.hasInterruptsOnly(cause)) return Effect.interrupt + if (boundary) return Effect.fail(toolError(boundary.message(Cause.squash(cause)))) return Effect.fail( toolError( Cause.prettyErrors(cause) @@ -431,13 +480,22 @@ export const make = ( ) }), ) - // The same round trip a tool result would take through text: exact JSON.stringify semantics. return yield* Effect.try({ try: (): Json | undefined => { + // A schema decoder can traverse the entire value (and may transform it). + // Confined Lua requires bounded plain data on both sides of that decoder. + if (boundary) return boundary.copy(decodeToolOutput(tool, boundary.copy(raw))) + // Preserve the JavaScript bridge's JSON.stringify semantics. const text = JSON.stringify(decodeToolOutput(tool, raw)) return text === undefined ? undefined : JSON.parse(text) }, - catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`), + catch: (cause) => + new ToolRuntimeError( + "InvalidToolOutput", + `Invalid output from tool '${name}': ${boundary ? boundary.message(cause, "Value does not match the output schema.") : String(cause)}`, + [], + boundary?.isLimit(cause), + ), }) }), ) @@ -445,16 +503,23 @@ export const make = ( return { calls, + admit, hooks, keys: (path) => namespaceKeys(root, path), - search: (args) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args)), + search: (args) => + Effect.suspend(() => { + if (boundary) admit() + return executeTool("search", makeSearchTool(prepared.searchIndex, prepared.language), args) + }), execute: (path, args) => Effect.suspend(() => { + // Even a failed lookup ranks the catalog. In Lua, pcall can repeat it. + if (boundary) admit() const segments = canonicalSegments(path) // Models often write `tools.search(...)` for the bare `search(...)`; honor it unless a tool owns that path. if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined) - return executeTool("search", makeSearchTool(prepared.searchIndex), args) - return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args) + return executeTool("search", makeSearchTool(prepared.searchIndex, prepared.language), args) + return executeTool(segments.join("."), resolve(prepared, path), args) }), } } diff --git a/packages/codemode/src/tool-schema.ts b/packages/codemode/src/tool-schema.ts index 04e8bb5e1ed..52a66c0c20b 100644 --- a/packages/codemode/src/tool-schema.ts +++ b/packages/codemode/src/tool-schema.ts @@ -3,11 +3,46 @@ import type { Tool, JsonSchema, SchemaType } from "./tool.js" const isEffectSchema = (schema: SchemaType): schema is Schema.Decoder & Schema.Top => Schema.isSchema(schema) -const renderLiteral = (value: unknown): string => JSON.stringify(value) ?? "unknown" +export type Language = "javascript" | "lua" export const identifierSegment = /^[A-Za-z_$][A-Za-z0-9_$]*$/ -const renderKey = (name: string): string => (identifierSegment.test(name) ? name : JSON.stringify(name)) +const luaKeywords = new Set( + "and break do else elseif end false for function if in local nil not or repeat return then true until while".split( + " ", + ), +) + +// Lua 5.1 uses decimal byte escapes, not JSON's \uXXXX escapes. Three digits avoid swallowing a following digit. +const luaString = (text: string) => + `"${text.replace(/["\\\x00-\x1f\x7f]/g, (char) => + char === '"' || char === "\\" ? `\\${char}` : `\\${char.charCodeAt(0).toString().padStart(3, "0")}`, + )}"` + +const luaKey = (name: string) => + /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !luaKeywords.has(name) ? name : `[${luaString(name)}]` + +export const member = (name: string, language: Language): string => { + if (language === "lua") { + const key = luaKey(name) + return key === name ? `.${name}` : key + } + return identifierSegment.test(name) ? `.${name}` : `[${JSON.stringify(name)}]` +} + +const renderLiteral = (value: unknown, language: Language): string => { + if (language === "lua") { + if (value === null) return "json.null" + if (typeof value === "string") return luaString(value) + if (Array.isArray(value) && value.length === 0) return "json.array()" + if (Array.isArray(value)) return `{${value.map((item) => renderLiteral(item, language)).join(", ")}}` + if (value !== null && typeof value === "object") + return `{${Object.entries(value) + .map(([key, item]) => `${luaKey(key)} = ${renderLiteral(item, language)}`) + .join(", ")}}` + } + return JSON.stringify(value) ?? "unknown" +} const definitionName = (ref: string): string | undefined => { const tokens = JsonPointer.parseUriFragment(ref) @@ -41,6 +76,7 @@ const intersection = (members: ReadonlyArray): string => { const MAX_RENDER_DEPTH = 8 type RenderContext = { + readonly language: Language readonly definitions: Readonly> readonly pretty: boolean } @@ -68,12 +104,12 @@ const hasUnresolvedRef = ( ].some((item) => hasUnresolvedRef(item, definitions, seen, nextVisited)) } -const docTags = (schema: JsonSchema): Array => { +const docTags = (schema: JsonSchema, language: Language): Array => { const tags: Array = [] if (schema.deprecated === true) tags.push("@deprecated") if (schema.default !== undefined) { try { - const rendered = JSON.stringify(schema.default) + const rendered = language === "lua" ? renderLiteral(schema.default, language) : JSON.stringify(schema.default) if (rendered !== undefined) tags.push(`@default ${rendered}`) } catch {} } @@ -96,8 +132,8 @@ const docTags = (schema: JsonSchema): Array => { return tags } -const docLines = (schema: JsonSchema, width: number): Array => { - const summary = docTags(schema).join(" ") +const docLines = (schema: JsonSchema, width: number, language: Language): Array => { + const summary = docTags(schema, language).join(" ") const lines = (schema.description ?? "").split("\n").map((line) => line.replace(/\s+$/, "")) while (lines.length > 0 && lines[0]!.trim() === "") lines.shift() while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop() @@ -108,12 +144,12 @@ const docLines = (schema: JsonSchema, width: number): Array => { } // Neutralize `*\/` so model-provided schema text cannot terminate generated documentation. -const jsdoc = (schema: JsonSchema, pad: string): string => { - const content = docLines(schema, pad.length) +const documentation = (schema: JsonSchema, pad: string, language: Language): string => { + const content = docLines(schema, pad.length, language) const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []) const append = (label: string, child: JsonSchema) => { - docLines(child, pad.length + label.length + 2).forEach((line, index) => { + docLines(child, pad.length + label.length + 2, language).forEach((line, index) => { if (index === 0) { content.push(`${label}: ${line}`) return @@ -130,6 +166,7 @@ const jsdoc = (schema: JsonSchema, pad: string): string => { } if (content.length === 0) return "" + if (language === "lua") return content.map((line) => `${pad}-- ${line}\n`).join("") const escaped = content.map((line) => line.replaceAll("*/", "* /")) if (escaped.length === 1 && pad.length + escaped[0].length + 7 <= 120) return `${pad}/** ${escaped[0]} */\n` const body = escaped.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n") @@ -155,8 +192,8 @@ const renderSchema = ( renderSchema({ ...schema, $ref: undefined }, nested, depth + 1, seen), ]) } - if (schema.const !== undefined) return renderLiteral(schema.const) - if (schema.enum) return schema.enum.map(renderLiteral).join(" | ") + if (schema.const !== undefined) return renderLiteral(schema.const, ctx.language) + if (schema.enum) return schema.enum.map((value) => renderLiteral(value, ctx.language)).join(" | ") const listed = schema.anyOf ?? schema.oneOf const alternatives = listed?.some((item) => item.type === "number") ? listed.filter((item) => !effectNumberSentinel(item)) @@ -195,34 +232,41 @@ const renderSchema = ( if (schema.type === "string") return "string" if (schema.type === "number" || schema.type === "integer") return "number" if (schema.type === "boolean") return "boolean" - if (schema.type === "null") return "null" - if (schema.type === "array") return `Array<${renderSchema(schema.items ?? {}, nested, depth + 1, seen)}>` + if (schema.type === "null") return ctx.language === "lua" ? "json.null" : "null" + if (schema.type === "array") { + const item = renderSchema(schema.items ?? {}, nested, depth + 1, seen) + return ctx.language === "lua" ? `{ ${item}, ... }` : `Array<${item}>` + } if (schema.type === "object" || schema.properties) { const required = new Set(schema.required ?? []) const properties = Object.entries(schema.properties ?? {}) const additional = schema.additionalProperties const indexType = additional && typeof additional === "object" ? renderSchema(additional, nested, depth + 1, seen) : undefined - const field = ([name, value]: readonly [string, JsonSchema]) => - `${renderKey(name)}${required.has(name) ? "" : "?"}: ${renderSchema(value, nested, depth + 1, seen)}` + const lua = ctx.language === "lua" + const field = ([name, value]: readonly [string, JsonSchema]) => { + const key = lua ? luaKey(name) : identifierSegment.test(name) ? name : JSON.stringify(name) + return `${key}${required.has(name) ? "" : "?"}${lua ? " = " : ": "}${renderSchema(value, nested, depth + 1, seen)}` + } + const indexField = lua ? `[string] = ${indexType}` : `[key: string]: ${indexType}` if (!ctx.pretty) { const fields = properties.map(field) - if (indexType !== undefined) fields.push(`[key: string]: ${indexType}`) - return fields.length === 0 ? "{}" : `{ ${fields.join("; ")} }` + if (indexType !== undefined) fields.push(indexField) + return fields.length === 0 ? "{}" : `{ ${fields.join(lua ? ", " : "; ")} }` } if (properties.length === 0 && indexType === undefined) return "{}" const pad = " ".repeat(depth + 1) - const lines = properties.map((entry) => `${jsdoc(entry[1], pad)}${pad}${field(entry)},`) - if (indexType !== undefined) lines.push(`${pad}[key: string]: ${indexType},`) + const lines = properties.map((entry) => `${documentation(entry[1], pad, ctx.language)}${pad}${field(entry)},`) + if (indexType !== undefined) lines.push(`${pad}${indexField},`) return `{\n${lines.join("\n")}\n${" ".repeat(depth)}}` } if (isEffectEmptyStruct(schema)) return "{}" return "unknown" } -export const toTypeScript = (schema: Schema.Top, decoded = false, pretty = false): string => { +const effectType = (schema: Schema.Top, decoded: boolean, pretty: boolean, language: Language): string => { try { const document = Schema.toJsonSchemaDocument(decoded ? Schema.toType(schema) : schema, { onExcessProperty: "error", @@ -230,20 +274,24 @@ export const toTypeScript = (schema: Schema.Top, decoded = false, pretty = false readonly schema: JsonSchema readonly definitions: Readonly> } - return renderSchema(document.schema, { definitions: document.definitions, pretty }) + return renderSchema(document.schema, { definitions: document.definitions, pretty, language }) } catch { return "unknown" } } -export const jsonSchemaToTypeScript = (schema: JsonSchema, pretty = false): string => { +const jsonType = (schema: JsonSchema, pretty: boolean, language: Language): string => { try { - return renderSchema(schema, { definitions: {}, pretty }) + return renderSchema(schema, { definitions: {}, pretty, language }) } catch { return "unknown" } } +export const toTypeScript = (schema: Schema.Top, decoded = false, pretty = false) => + effectType(schema, decoded, pretty, "javascript") +export const jsonSchemaToTypeScript = (schema: JsonSchema, pretty = false) => jsonType(schema, pretty, "javascript") + export type InputProperty = { readonly name: string readonly description: string | undefined @@ -279,8 +327,8 @@ export const inputProperties = (tool: Tool): Array => { } } -export const inputTypeScript = (tool: Tool, pretty = false): string => - isEffectSchema(tool.input) ? toTypeScript(tool.input, false, pretty) : jsonSchemaToTypeScript(tool.input, pretty) +export const inputType = (tool: Tool, pretty: boolean, language: Language): string => + isEffectSchema(tool.input) ? effectType(tool.input, false, pretty, language) : jsonType(tool.input, pretty, language) // Effect inputs are empty only when their encoded root is Effect's empty-struct marker, which records and checked // structs never are. Raw JSON Schema inputs keep the `{}` rendering check, which treats `{ type: "object" }` as empty. @@ -289,14 +337,19 @@ export const isEmptyInput = (tool: Tool): boolean => ? isEffectEmptyStruct( Schema.toJsonSchemaDocument(tool.input, { referencePolicy: () => undefined }).schema as JsonSchema, ) - : inputTypeScript(tool) === "{}" + : inputType(tool, false, "javascript") === "{}" -export const outputTypeScript = (tool: Tool, pretty = false): string => +export const outputType = (tool: Tool, pretty: boolean, language: Language): string => tool.output === undefined - ? "void" + ? language === "lua" + ? "nil" + : "void" : isEffectSchema(tool.output) - ? toTypeScript(tool.output, true, pretty) - : jsonSchemaToTypeScript(tool.output, pretty) + ? effectType(tool.output, true, pretty, language) + : jsonType(tool.output, pretty, language) + +export const inputTypeScript = (tool: Tool, pretty = false) => inputType(tool, pretty, "javascript") +export const outputTypeScript = (tool: Tool, pretty = false) => outputType(tool, pretty, "javascript") export const decodeInput = (tool: Tool, value: unknown): unknown => isEffectSchema(tool.input) ? Schema.decodeUnknownSync(tool.input)(value) : value diff --git a/packages/codemode/test/lua-bridge.test.ts b/packages/codemode/test/lua-bridge.test.ts new file mode 100644 index 00000000000..47fa7fdcb38 --- /dev/null +++ b/packages/codemode/test/lua-bridge.test.ts @@ -0,0 +1,306 @@ +import { expect, test } from "bun:test" +import { Deferred, Effect, Fiber, Schema } from "effect" +import { CodeMode, Extension, Tool } from "../src/index.js" +import { executeLua } from "../src/lua.js" +import { copyLuaData } from "../src/lua-data.js" +import { ToolRuntime } from "../src/tool-runtime.js" + +const limits = { timeoutMs: undefined, maxToolCalls: undefined, maxOutputBytes: undefined } + +test("strict host import never invokes accessors, toJSON, or proxy traps", () => { + const unexpected = () => { + throw new Error("host code was invoked") + } + const revoked = Proxy.revocable({}, {}) + revoked.revoke() + for (const value of [ + { + get field() { + return unexpected() + }, + }, + { toJSON: unexpected }, + Object.create({ inherited: true }), + new Proxy({}, { getPrototypeOf: unexpected, ownKeys: unexpected }), + revoked.proxy, + [undefined], + new Array(3), + Object.assign([1], { extra: 2 }), + Symbol(), + Infinity, + Object.defineProperty({}, "hidden", { value: 1 }), + ]) + expect(() => copyLuaData(value)).toThrow(/JSON/) + + const value = JSON.parse('{"__proto__":{"marker":true},"constructor":null}') + const copied = copyLuaData(value) + expect(Object.getPrototypeOf(copied)).toBeNull() + expect(JSON.stringify(copied)).toBe(JSON.stringify(value)) +}) + +test("strict host import charges depth, expanded nodes and serialized UTF-8 bytes", () => { + let nested: unknown = 0 + let shared: unknown = 0 + for (let i = 0; i < 32; i++) { + nested = { nested } + shared = [shared, shared] + } + expect(() => copyLuaData({ nested })).toThrow("nesting limit") + expect(() => copyLuaData(shared)).toThrow("node limit") + expect(() => copyLuaData("\u0000".repeat(180_000))).toThrow("byte limit") + expect(() => copyLuaData("💫".repeat(270_000))).toThrow("byte limit") + expect(() => copyLuaData({ "\ud800": true, "\ud801": false })).toThrow("valid Unicode") + const cycle: unknown[] = [] + cycle.push(cycle) + expect(() => copyLuaData(cycle)).toThrow("Cyclic") +}) + +test("search, calls, and snapshots resume in order; Effect reuse allocates fresh state", async () => { + const observed: string[] = [] + const runtime = CodeMode.make({ + language: "lua", + limits: { maxToolCalls: 2 }, + tools: { + api: { + echo: Tool.make({ + description: "Echo a number", + input: Schema.Struct({ n: Schema.Number }), + output: Schema.Number, + execute: ({ n }) => Effect.andThen(Effect.yieldNow, Effect.succeed(n + 1)), + }), + }, + }, + hooks: { + "tool.before": (call) => + Effect.sync(() => { + observed.push(call.name) + }), + }, + }) + const run = runtime.execute( + 'local hit = search({query="echo"}).items[1]; print(hit.path); return tools.api.echo({n = n})', + { n: 8 }, + ) + const result = { + ok: true, + value: 9, + logs: ["tools.api.echo"], + toolCalls: [{ name: "search" }, { name: "api.echo" }], + } satisfies CodeMode.Result + expect(await Effect.runPromise(run)).toEqual(result) + expect(await Effect.runPromise(run)).toEqual(result) + expect(observed).toEqual(["search", "api.echo", "search", "api.echo"]) + expect(await Effect.runPromise(runtime.execute("search(); search(); return search()"))).toMatchObject({ + ok: false, + error: { kind: "ToolCallLimitExceeded" }, + toolCalls: [{ name: "search" }, { name: "search" }], + }) +}) + +test("bindings, global results and raw tool output all pass strict import", async () => { + let read = false + const invalid = { + get field() { + read = true + return 2 + }, + } + const prepared = ToolRuntime.prepare( + { + fn: Tool.make({ + description: "Accessor", + input: Schema.Struct({}), + output: Schema.Struct({ field: Schema.Number }), + execute: () => Effect.succeed(invalid), + }), + }, + "lua", + ) + const ext = new Map([["fetchValue", () => Effect.succeed(invalid)]]) + for (const [run, kind] of [ + [executeLua("return field", prepared, limits, {}, invalid), "InvalidDataValue"], + [executeLua("return fetchValue()", prepared, limits, {}, undefined, ext), "InvalidDataValue"], + [executeLua("return tools.fn()", prepared, limits, {}), "InvalidToolOutput"], + ] as const) + expect(await Effect.runPromise(run)).toMatchObject({ ok: false, error: { kind } }) + expect(read).toBe(false) +}) + +test("a thrown host value is not inspected through accessors or string conversion", async () => { + const unexpected = () => { + throw new Error("Unexpected coercion") + } + const prepared = ToolRuntime.prepare( + { + fail: Tool.make({ + description: "Fail", + input: {}, + execute: () => + Effect.fail({ + get message() { + return unexpected() + }, + toString: unexpected, + }), + }), + }, + "lua", + ) + expect(await Effect.runPromise(executeLua("return tools.fail()", prepared, limits, {}))).toMatchObject({ + ok: false, + error: { kind: "ToolFailure", message: "Host call failed." }, + }) +}) + +test("a tool.after observer cannot mutate the result imported by Lua", async () => { + const runtime = CodeMode.make({ + language: "lua", + tools: { + read: Tool.make({ + description: "Read", + input: {}, + output: Schema.Unknown, + execute: () => Effect.succeed({ n: 1 }), + }), + }, + hooks: { + "tool.after": (_, result) => + Effect.sync(() => { + if (result.status === "success" && typeof result.value === "object" && result.value !== null) + Object.defineProperty(result.value, "n", { + get() { + throw new Error("host getter reached") + }, + }) + }), + }, + }) + expect(await Effect.runPromise(runtime.execute("return tools.read().n"))).toMatchObject({ ok: true, value: 1 }) +}) + +test("invalid protected lookups consume the Lua call budget without appearing as admitted tools", async () => { + const runtime = CodeMode.make({ language: "lua", limits: { maxToolCalls: 2 } }) + expect(await Effect.runPromise(runtime.execute("for i=1,3 do pcall(tools.missing) end"))).toMatchObject({ + ok: false, + error: { kind: "ToolCallLimitExceeded" }, + toolCalls: [], + }) +}) + +test("tool output DAGs are bounded before schema decoding or JSON stringify", async () => { + let shared: unknown = 1 + for (let i = 0; i < 20; i++) shared = { left: shared, right: shared } + const runtime = CodeMode.make({ + language: "lua", + tools: { + large: Tool.make({ + description: "DAG", + input: {}, + output: Schema.Unknown, + execute: () => Effect.succeed(shared), + }), + }, + }) + expect(await Effect.runPromise(runtime.execute("return pcall(tools.large)"))).toMatchObject({ + ok: false, + error: { kind: "InvalidToolOutput", message: expect.stringContaining("node limit") }, + toolCalls: [{ name: "large" }], + }) +}) + +test("pcall resumes ordinary tool and extension failures with only a bounded message", async () => { + const runtime = CodeMode.make({ + language: "lua", + tools: { deny: Tool.make({ description: "Deny", input: {}, execute: () => Effect.fail(new Error("denied")) }) }, + extensions: [Extension.lua({ name: "test", globals: { fail: () => Effect.fail("nope") } })], + }) + expect( + await Effect.runPromise( + runtime.execute("local a,b = pcall(tools.deny); local c,d = pcall(fail); return {a,b,c,d}"), + ), + ).toEqual({ + ok: true, + value: [false, "denied", false, "nope"], + toolCalls: [{ name: "deny" }], + }) +}) + +test("tools and named extension globals share the default 128-call budget; pcall cannot bypass it", async () => { + let calls = 0 + const hit = () => Effect.sync(() => ++calls) + const runtime = CodeMode.make({ + language: "lua", + tools: { hit: Tool.make({ description: "Count", input: {}, output: Schema.Number, execute: hit }) }, + extensions: [Extension.lua({ name: "test", globals: { hit } })], + }) + for (const last of ["tools.hit", "hit"]) { + calls = 0 + const result = await Effect.runPromise( + runtime.execute(`for i=1,64 do tools.hit(); hit() end; return pcall(${last})`), + ) + expect(result).toMatchObject({ ok: false, error: { kind: "ToolCallLimitExceeded" } }) + expect(result.toolCalls).toHaveLength(64) + expect(calls).toBe(128) + } +}) + +test("output budgets truncate both returned data and accumulated print lines", async () => { + const runtime = CodeMode.make({ language: "lua", limits: { maxOutputBytes: 6 } }) + expect( + await Effect.runPromise(runtime.execute('print("a"); print("bcdef"); print("g"); return "1234567890"')), + ).toMatchObject({ + ok: true, + value: expect.stringContaining("6-byte output limit"), + truncated: true, + logs: [expect.stringContaining("logs truncated")], + }) +}) + +test("the wall-clock timeout interrupts a CPU-only Lua loop at a slice", async () => { + expect( + await Effect.runPromise(CodeMode.make({ language: "lua", limits: { timeoutMs: 1 } }).execute("while true do end")), + ).toMatchObject({ + ok: false, + error: { kind: "TimeoutExceeded" }, + }) +}) + +test("interrupting a suspended Lua call runs cleanup before returning and does not resume the program", async () => { + const events: string[] = [] + await Effect.runPromise( + Effect.gen(function* () { + const started = yield* Deferred.make() + const prepared = ToolRuntime.prepare( + { + block: Tool.make({ + description: "Wait", + input: {}, + execute: () => + Effect.andThen(Deferred.succeed(started, undefined), Effect.never).pipe( + Effect.ensuring( + Effect.sync(() => { + events.push("clean") + }), + ), + ), + }), + }, + "lua", + ) + const run = executeLua("pcall(tools.block); tools.block()", prepared, limits, { + "tool.before": () => + Effect.sync(() => { + events.push("before") + }), + "tool.after": (_, result) => + Effect.sync(() => { + events.push(result.status) + }), + }) + const fiber = yield* Effect.forkChild(run) + yield* Deferred.await(started) + yield* Fiber.interrupt(fiber) + }), + ) + expect(events).toEqual(["before", "clean", "interrupted"]) +}) diff --git a/packages/codemode/test/lua-extension.test.ts b/packages/codemode/test/lua-extension.test.ts new file mode 100644 index 00000000000..37f244ad6a4 --- /dev/null +++ b/packages/codemode/test/lua-extension.test.ts @@ -0,0 +1,72 @@ +import { expect, test } from "bun:test" +import { Effect, Schema } from "effect" +import { CodeMode, Extension, Tool } from "../src/index.js" + +test("Lua calls only declared capabilities; denied calls can be recovered without crossing a host error object", async () => { + const calls: string[] = [] + const extensions = [ + Extension.lua({ + name: "example", + globals: { + lookup: (id) => + Effect.sync(() => { + if (typeof id !== "string") throw new TypeError("expected an id") + calls.push(id) + return { id } + }), + }, + }), + ] + const run = CodeMode.make({ + language: "lua", + extensions, + hooks: { + "extension.before": (call) => + call.args[0] === "denied" ? Effect.fail(new Error("permission denied")) : Effect.void, + }, + }) + expect( + await Effect.runPromise( + run.execute(` + local ok, message = pcall(lookup, "denied") + return { ok = ok, message = message, id = lookup("allowed").id } + `), + ), + ).toMatchObject({ ok: true, value: { ok: false, message: "permission denied", id: "allowed" } }) + expect(calls).toEqual(["allowed"]) + expect(() => CodeMode.make({ extensions })).toThrow("requires language") + expect(() => + CodeMode.make({ language: "lua", extensions: [Extension.make({ name: "js", globals: { fs: {} } })] }), + ).toThrow("Extension.lua") +}) + +test("Lua table shapes survive a validated tool round trip, including empty containers and nested nulls", async () => { + const shape = Schema.Struct({ + list: Schema.Array(Schema.NullOr(Schema.String)), + record: Schema.Record(Schema.String, Schema.Json), + }) + const runtime = CodeMode.make({ + language: "lua", + tools: { echo: Tool.make({ description: "Echo", input: shape, output: shape, execute: Effect.succeed }) }, + }) + expect( + await Effect.runPromise( + runtime.execute(` + local a = tools.echo({ list = {json.null}, record = { omitted = nil, kept = json.null } }) + a.list[1] = nil + return { tools.echo(a), tools.echo({ list = json.array(), record = {} }) } + `), + ), + ).toMatchObject({ + ok: true, + value: [ + { list: [], record: { kept: null } }, + { list: [], record: {} }, + ], + }) + expect(await Effect.runPromise(runtime.execute("return tools.echo({list = {}, record = {}})"))).toMatchObject({ + ok: false, + error: { kind: "InvalidToolInput" }, + toolCalls: [], + }) +}) diff --git a/packages/codemode/test/openapi.test.ts b/packages/codemode/test/openapi.test.ts index 5a70ae71e72..9ed98559c1e 100644 --- a/packages/codemode/test/openapi.test.ts +++ b/packages/codemode/test/openapi.test.ts @@ -111,7 +111,7 @@ const directionalSpec = (openapi: string): Document => ({ }) describe("OpenAPI.fromSpec", () => { - test("covers a representative API from generation through execution", async () => { + test.each(["javascript", "lua"] as const)("runs authenticated generated tools in %s", async (language) => { const resolutions: Array = [] const client = recordingClient((request) => { const url = Option.getOrElse(HttpClientRequest.toUrl(request), () => new URL(request.url)) @@ -162,9 +162,19 @@ describe("OpenAPI.fromSpec", () => { expect(outputTypeScript(remove)).toBe("null") const result = await Effect.runPromise( - CodeMode.make({ tools: { api: api.tools } }) + CodeMode.make({ language, tools: { api: api.tools } }) .execute( - ` + language === "lua" + ? ` + local user = tools.api.users.get({ + userId = "user-1", include = {"profile", "permissions"}, verbose = true, ["X-Trace-ID"] = "trace-1" + }) + local created = tools.api.users.create({ name = "Grace", email = "grace@example.test", role = "admin" }) + local summary = tools.api.search.run({ filter = { query = "effect", page = 2 }, tags = {"typescript", "runtime"} }) + local removed = tools.api.users.remove({ userId = user.id }) + return { user = user, created = created, summary = summary, removed = removed } + ` + : ` const user = await tools.api.users.get({ userId: "user-1", include: ["profile", "permissions"], diff --git a/packages/codemode/test/signature.test.ts b/packages/codemode/test/signature.test.ts index ed41e9b02c2..5f9de04340f 100644 --- a/packages/codemode/test/signature.test.ts +++ b/packages/codemode/test/signature.test.ts @@ -1083,3 +1083,52 @@ describe("non-identifier tool paths", () => { expect(value.items[0]?.signature).toContain('tools.context7["resolve-library-id"]({') }) }) + +describe("Lua discovery", () => { + const echo = Tool.make({ + description: "Echo an item list", + input: Schema.Struct({ + end: Schema.Array(Schema.NullOr(Schema.String)).annotate({ description: "Items to echo" }), + $tag: Schema.optionalKey(Schema.String), + }), + output: Schema.Array(Schema.NullOr(Schema.String)), + execute: (input) => Effect.succeed(input.end), + }) + const runtime = CodeMode.make({ language: "lua", tools: { "repeat.$echo\u00011": echo } }) + const path = 'tools["repeat"]["$echo\\0011"]' + + test("catalog and search describe Lua-callable paths, table shapes and nullable values", async () => { + const signature = `${path}({\n -- Items to echo\n ["end"] = { string | json.null, ... },\n ["$tag"]? = string,\n}) -> { string | json.null, ... }` + expect(runtime.catalog[0]?.signature).toBe(signature) + expect(await Effect.runPromise(runtime.execute('return search({ query = "echo" }).items[1]'))).toMatchObject({ + ok: true, + value: { path, signature }, + }) + expect(await Effect.runPromise(runtime.execute(`return ${path}({ ["end"] = { "hi", json.null } })`))).toMatchObject( + { + ok: true, + value: ["hi", null], + }, + ) + }) + + test("bounds guest search input and suggestions before ranking or materializing signatures", async () => { + for (const input of ["limit = 51", 'query = string.rep("a", 513)', 'namespace = string.rep("a", 513)']) { + expect(await Effect.runPromise(runtime.execute(`return search({ ${input} })`))).toMatchObject({ + ok: false, + error: { kind: "InvalidToolInput" }, + }) + } + expect( + await Effect.runPromise( + runtime.execute('return #search({ query = string.rep("unrelated ", 16) .. "echo" }).items'), + ), + ).toMatchObject({ ok: true, value: 0 }) + expect( + await Effect.runPromise(runtime.execute('local k = string.rep("x", 180); return tools[k][k][k]()')), + ).toMatchObject({ + ok: false, + error: { kind: "UnknownTool", message: "Unknown tool (path too long for suggestions)." }, + }) + }) +}) diff --git a/packages/core/src/codemode/catalog.ts b/packages/core/src/codemode/catalog.ts index 07dfe59c5ad..917ac28a9c8 100644 --- a/packages/core/src/codemode/catalog.ts +++ b/packages/core/src/codemode/catalog.ts @@ -34,6 +34,8 @@ const NamespaceSummary = Schema.Struct({ }) export const Summary = Schema.Struct({ + // Old snapshots contain JavaScript call signatures. Never render them alongside Lua instructions. + language: Schema.Literal("lua"), total: Schema.Number, shown: Schema.Number, namespaces: Schema.Array(NamespaceSummary), @@ -66,7 +68,7 @@ export function summarize(inventory: Inventory, options: Options = {}): Summary const firstLine = entry.description.split("\n", 1)[0]?.trim() ?? "" const description = firstLine.length > DESCRIPTION_LIMIT ? firstLine.slice(0, DESCRIPTION_LIMIT - 3) + "..." : firstLine - const suffix = description.length === 0 ? "" : ` // ${description}` + const suffix = description.length === 0 ? "" : ` -- ${description}` return { path: entry.path, line: ` - ${entry.signature}${suffix}` } }) .toSorted((left, right) => { @@ -132,6 +134,7 @@ export function summarize(inventory: Inventory, options: Options = {}): Summary entries: namespace.listings.filter((listing) => namespace.selectedListings.has(listing)), })) return { + language: "lua", total: flattened.tools.length, shown: namespaceSummaries.reduce((total, namespace) => total + namespace.entries.length, 0), namespaces: namespaceSummaries, @@ -169,7 +172,7 @@ export function namespaceLine(namespace: typeof NamespaceSummary.Type) { : namespace.entries.length === 0 ? `${count}, none shown` : `${count}, ${namespace.entries.length} shown` - return `- ${namespace.name} (${label})${namespace.description === undefined ? "" : ` // ${namespace.description}`}` + return `- ${namespace.name} (${label})${namespace.description === undefined ? "" : ` -- ${namespace.description}`}` } function rankListings(listings: ReadonlyArray) { diff --git a/packages/core/src/codemode/fetch.ts b/packages/core/src/codemode/fetch.ts index f8dfdd1a549..6ee004a78c3 100644 --- a/packages/core/src/codemode/fetch.ts +++ b/packages/core/src/codemode/fetch.ts @@ -2,7 +2,7 @@ export * as CodeModeFetch from "./fetch.js" import { Extension } from "@opencode/codemode" import { isRecord } from "@opencode/util/record" -import { Effect } from "effect" +import { Effect, Schema } from "effect" import { Permission } from "../permission.js" import { CodeModeExecution } from "./execution.js" @@ -14,13 +14,10 @@ type Init = { readonly body?: string | Uint8Array | URLSearchParams } -const fetch = (input: string | URL, init: Init = {}) => +type Result = { response: Response; url: string; redirects: number } + +const request = (url: string, init: Init, read: (result: Result) => Promise) => Effect.gen(function* () { - // Rules are matched against the URL that is requested, so `HTTPS://EVIL.COM` meets a rule for `https://evil.com/*`. - const parsed = URL.parse(String(input)) - if (parsed === null) return yield* Effect.fail(new TypeError(`fetch received an invalid URL: ${String(input)}`)) - if (parsed.protocol === "file:") return yield* Effect.fail(new Error("fetch cannot be used for filesystem access.")) - const url = parsed.href const execution = yield* CodeModeExecution.Service const permission = yield* Permission.Service const source = { type: "tool" as const, messageID: execution.messageID, id: execution.id } @@ -51,33 +48,36 @@ const fetch = (input: string | URL, init: Init = {}) => agent: execution.agent, source, }) - const signal = AbortSignal.timeout(TIMEOUT_MS) - const follow = ( - target: string, - request: Init, - redirects: number, - ): Effect.Effect<{ response: Response; url: string; redirects: number }, unknown> => - Effect.tryPromise({ - try: () => globalThis.fetch(target, { ...request, redirect: "manual", signal }), + // One scope and deadline cover the entire chain, including reads after fetch resolves. + const signal = AbortSignal.any([yield* Effect.abortSignal, AbortSignal.timeout(TIMEOUT_MS)]) + let target = url + let current = init + for (let redirects = 0; ; redirects++) { + const response = yield* Effect.tryPromise({ + try: () => globalThis.fetch(target, { ...current, redirect: "manual", signal }), catch: (error) => error, - }).pipe( - Effect.flatMap((response) => { - const location = response.headers.get("location") - if (!redirectStatuses.has(response.status) || location === null) - return Effect.succeed({ response, url: target, redirects }) - if (redirects >= MAX_REDIRECTS) - return Effect.fail(new Error(`Too many redirects (more than ${MAX_REDIRECTS})`)) - const next = new URL(location, target) - if (next.protocol !== "http:" && next.protocol !== "https:") - return Effect.fail(new Error(`fetch cannot follow a redirect to ${next.protocol} URLs.`)) - return check(next.href).pipe( - Effect.andThen(follow(next.href, redirected(request, response.status, target, next), redirects + 1)), - ) - }), - ) - const result = yield* follow(url, init, 0) - return yield* Effect.tryPromise({ try: () => read(result), catch: (error) => error }) - }) + }) + const location = response.headers.get("location") + if (!redirectStatuses.has(response.status) || location === null) + return yield* Effect.tryPromise({ + try: () => read({ response, url: target, redirects }), + catch: (error) => error, + }) + const body = response.body + if (body) yield* Effect.tryPromise(() => body.cancel()) + if (redirects >= MAX_REDIRECTS) + return yield* Effect.fail(new Error(`Too many redirects (more than ${MAX_REDIRECTS})`)) + const next = URL.parse(location, target) + if (!next) return yield* Effect.fail(new TypeError("fetch received an invalid redirect URL")) + if (next.protocol !== "http:" && next.protocol !== "https:") + return yield* Effect.fail(new Error(`fetch cannot follow a redirect to ${next.protocol} URLs.`)) + if (next.username || next.password) + return yield* Effect.fail(new Error("fetch cannot follow a redirect with credentials")) + yield* check(next.href) + current = redirected(current, response.status, target, next) + target = next.href + } + }).pipe(Effect.scoped) export const MAX_REDIRECTS = 20 const redirectStatuses = new Set([301, 302, 303, 307, 308]) @@ -101,7 +101,7 @@ const redirected = (request: Init, status: number, from: string, to: URL): Init } } -const read = async (result: { response: Response; url: string; redirects: number }) => { +const read = async (result: Result) => { const response = result.response const bytes = await response.bytes() const headers = Object.fromEntries(response.headers) @@ -123,8 +123,71 @@ const read = async (result: { response: Response; url: string; redirects: number } } +const fetch = (input: string | URL, init: Init = {}) => { + const parsed = URL.parse(String(input)) + if (!parsed) return Effect.fail(new TypeError(`fetch received an invalid URL: ${String(input)}`)) + if (parsed.protocol === "file:") return Effect.fail(new Error("fetch cannot be used for filesystem access.")) + return request(parsed.href, init, read) +} + export const extension = Extension.make({ name: "fetch", globals: { fetch: Extension.async(fetch) } }) +const decodeInit = Schema.decodeUnknownEffect( + Schema.Struct({ + method: Schema.optionalKey(Schema.String), + headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)), + body: Schema.optionalKey(Schema.String), + }), + { onExcessProperty: "error" }, +) + +const luaFetch = Effect.fnUntraced(function* (...args: unknown[]) { + const [input, init] = args + if (typeof input !== "string" || args.length > 2) + return yield* Effect.fail(new TypeError("Expected fetch(url[, init])")) + const parsed = URL.parse(input) + if (parsed?.protocol === "file:") return yield* Effect.fail(new Error("fetch cannot be used for filesystem access.")) + if (!parsed || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) + return yield* Effect.fail(new TypeError("fetch requires an HTTP or HTTPS URL")) + if (parsed.username || parsed.password) + return yield* Effect.fail(new TypeError("fetch URL must not contain credentials")) + const options = yield* decodeInit(init === undefined ? {} : init).pipe( + Effect.mapError( + () => new TypeError("fetch init accepts only method (string), headers (string record), and body (string)"), + ), + ) + return yield* request(parsed.href, options, readLua).pipe( + // The Lua bridge exposes only own data properties of host errors, not prototype accessors. + Effect.mapError((error) => (error instanceof Permission.BlockedError ? new Error(error.message) : error)), + ) +}) + +const MAX_BODY_BYTES = 1024 * 1024 + +async function readLua({ response, url, redirects }: Result) { + const decoder = new TextDecoder() + let size = 0 + let body = "" + if (response.body) { + for await (const chunk of response.body) { + size += chunk.byteLength + if (size > MAX_BODY_BYTES) throw new RangeError("fetch response body exceeds 1 MiB") + body += decoder.decode(chunk, { stream: true }) + } + } + return { + status: response.status, + statusText: response.statusText, + ok: response.ok, + url, + redirected: redirects > 0, + headers: Object.fromEntries(response.headers), + body: body + decoder.decode(), + } +} + +export const luaExtension = Extension.lua({ name: "fetch", globals: { fetch: luaFetch } }) + /** What to show for a fetch call: its method and URL. */ export const display = (args: ReadonlyArray) => { const [input, init] = args diff --git a/packages/core/src/codemode/instructions.ts b/packages/core/src/codemode/instructions.ts index 2f93d261325..2e4c000f67e 100644 --- a/packages/core/src/codemode/instructions.ts +++ b/packages/core/src/codemode/instructions.ts @@ -1,6 +1,6 @@ export * as CodeModeInstructions from "./instructions.js" -import { searchSignature, toolExpression } from "@opencode/codemode" +import { luaSearchSignature, toolExpression } from "@opencode/codemode" import { Effect, Schema } from "effect" import { Instructions } from "../instructions/index.js" import { CodeModeCatalog } from "./catalog.js" @@ -8,11 +8,13 @@ import { CodeModeCatalog } from "./catalog.js" // prettier-ignore const prompt = (hasMoreTools: boolean) => `# Code Mode -The tools listed below${hasMoreTools ? ", and \`search\`," : ""} cannot be called directly: they only work as JavaScript inside the \`execute\` tool. Every other tool you have is a normal tool call: call it directly, never inside \`execute\`. +The tools listed below${hasMoreTools ? ", and \`search\`," : ""} cannot be called directly: they only work as Lua inside the \`execute\` tool. Every other tool you have is a normal tool call: call it directly, never inside \`execute\`. -${hasMoreTools ? `The catalog is partial. Before calling a tool that is not listed below, find it with the global \`search(...)\` function. Do not guess tool names. Each result's \`path\` is the complete call expression: write it out as code, for example \`await tools.ns.tool_name({ ... })\`. Do not use it as a key such as \`tools[path]\`. +Signatures describe Lua table shapes, not executable declarations: \`?\` marks optional fields and \`->\` shows the result. Pass actual values, e.g. \`{ name = "notes" }\`. -- ${searchSignature}` : "The catalog is complete. Do not guess tool names."} +${hasMoreTools ? `The catalog is partial. Before calling a tool that is not listed below, find it with the global \`search(...)\` function. Do not guess tool names. For example, \`return search({ query = "notes", limit = 5 }).items\`. Query and namespace are limited to 512 characters; searches rank the first 16 words and return at most 50 items per page. Each result's \`path\` is the complete call expression: write it out as code, for example \`return tools.ns.tool_name({ id = "123" })\`. Do not use it as a key such as \`tools[path]\`. + +- ${luaSearchSignature}` : "The catalog is complete. Do not guess tool names."} ## Code Mode tools (call only inside \`execute\`)` @@ -33,7 +35,7 @@ export function update(previous: CodeModeCatalog.Summary, current: CodeModeCatal const replacement = `The Code Mode tool catalog has changed. This catalog supersedes the previous Code Mode tool catalog. ${render(current)}` - if (current.total === 0) return replacement + if (previous.total === 0 || current.total === 0) return replacement const previousComplete = previous.shown === previous.total const currentComplete = current.shown === current.total if (previousComplete !== currentComplete) return replacement @@ -114,7 +116,7 @@ ${render(current)}` if (diff.removed.length > 0) { parts.push( `The following tools are no longer available and must not be called: ${diff.removed - .map((entry) => toolExpression(entry.path)) + .map((entry) => toolExpression(entry.path, "lua")) .join(", ")}.`, ) } diff --git a/packages/core/src/codemode/tool.ts b/packages/core/src/codemode/tool.ts index 1fd67439350..a6ed9505091 100644 --- a/packages/core/src/codemode/tool.ts +++ b/packages/core/src/codemode/tool.ts @@ -33,6 +33,12 @@ const ExecuteCall = Schema.Struct({ type ExecuteCall = typeof ExecuteCall.Type +const ExecuteInput = Schema.Struct({ + code: Schema.String.annotate({ + description: "Lua program (up to 32 KiB). Use an explicit return to send back a result.", + }), +}) + const ExecuteOutput = Schema.Struct({ output: Schema.String, toolCalls: Schema.Array(ExecuteCall), @@ -73,12 +79,11 @@ export type Inventory = { // Invariant model-facing guidance; the changing tool catalog is delivered through Instructions. const description = [ - "Run JavaScript in a confined Code Mode runtime to script tool calls and HTTP requests and compose their results.", - "`fetch` is available for HTTP requests. Imports, direct filesystem access, and timers are unavailable: there is no `setTimeout` or sleep. All other external access goes through `tools`.", - "Within `{ code }`, the only callable tools are those explicitly listed in the Code Mode catalog instructions or returned by the `search` function. Inside `{ code }`, ignore tools shown outside the Code Mode catalog. They are not available in the Code Mode runtime.", - 'Call tools through `tools` using only exact paths and signatures from the catalog. Do not infer or normalize tool names; preserve bracket notation such as `tools.["tool-name"](input)`.', - "Prefer an explicit `return`; if omitted, the final top-level expression becomes the result.", - "Await every call whose completion matters; pending calls are interrupted when execution ends. Run independent calls concurrently with `Promise.allSettled`.", + "Run a confined subset of Lua 5.1 in Code Mode. Calls finish before the next statement; use `local` for variables and `return` to send the first returned value back.", + 'Only call tools listed in the Code Mode catalog or returned by `search`. Copy their exact paths, e.g. `return tools.ns["tool-name"]({ id = "123" })`. Call tools outside the catalog directly, never here.', + "Use `ipairs` for 1-based arrays and `pairs` for objects. Use `json.array()` for an empty array, `{}` for an empty object and `json.null` for JSON null.", + '`fetch(url[, init])` accepts HTTP(S) and an optional table with method (string), headers (string keys and values), and body (string). It returns a table with status, ok, url, statusText, redirected, lower-case headers, and body (text). Example: `return fetch("https://example.com").body`.', + "No direct filesystem access, imports, or timers. All other external access goes through catalog tools.", ].join("\n") export const create = ( @@ -89,7 +94,7 @@ export const create = ( return { name: "execute", description, - input: CodeMode.Input, + input: ExecuteInput, output: ExecuteOutput, execute: ({ code }, context) => Effect.gen(function* () { @@ -268,9 +273,10 @@ function runtime(inventory: Inventory) { const cached = runtimes.get(inventory) if (cached) return cached const tools = inventoryTools(inventory) - const created = CodeMode.make({ + const created = CodeMode.make({ + language: "lua", tools, - extensions: [CodeModeFetch.extension], + extensions: [CodeModeFetch.luaExtension], hooks: runHooks, }) runtimes.set(inventory, created) @@ -287,7 +293,7 @@ export const check = ( limits: CodeMode.ExecutionLimits, executeTool: (name: string, tool: Info, input: unknown) => Effect.Effect, ) => - CodeMode.make({ tools: inventoryTools(inventory), hooks: runHooks, limits }) + CodeMode.make({ language: "javascript", tools: inventoryTools(inventory), hooks: runHooks, limits }) .execute(code, bindings) .pipe( Effect.provideService(Run, { diff --git a/packages/core/test/artifact.test.ts b/packages/core/test/artifact.test.ts index 5cbc5a4b2a0..053f1ec01b0 100644 --- a/packages/core/test/artifact.test.ts +++ b/packages/core/test/artifact.test.ts @@ -19,7 +19,7 @@ import { tmpdirScoped } from "./fixture/tmpdir" import { testEffect } from "./lib/effect" import { imagePassthrough } from "./lib/image" import { permissionLayer } from "./lib/permission" -import { codeModeListings, executeTool, registerToolPlugin, toolIdentity } from "./lib/tool" +import { codeModeListings, executeTool, luaLiteral, registerToolPlugin, toolIdentity } from "./lib/tool" const toolPaths = [ "opencode.artifact_create", @@ -60,7 +60,7 @@ const callCodeMode = (registry: Tool.Interface, sessionID: Session.ID, name: str type: "tool-call", id: `call-${name}`, name: "execute", - input: { code: `return await tools.opencode.${name}(${JSON.stringify(input)})` }, + input: { code: `return tools.opencode.${name}(${luaLiteral(input)})` }, }, }).pipe( Effect.map((result) => { diff --git a/packages/core/test/codemode-lua-fetch.test.ts b/packages/core/test/codemode-lua-fetch.test.ts new file mode 100644 index 00000000000..b7d6f9a348a --- /dev/null +++ b/packages/core/test/codemode-lua-fetch.test.ts @@ -0,0 +1,193 @@ +import { expect } from "bun:test" +import { CodeMode } from "@opencode/codemode" +import { CodeModeExecution } from "@opencode/core/codemode/execution" +import { CodeModeFetch } from "@opencode/core/codemode/fetch" +import { Permission } from "@opencode/core/permission" +import { Session } from "@opencode/schema/session" +import { Tool } from "@opencode/schema/tool" +import { Effect, Fiber, Layer } from "effect" +import { testEffect } from "./lib/effect" +import { permissionLayer } from "./lib/permission" +import { toolIdentity } from "./lib/tool" + +const fetch = CodeModeFetch.luaExtension.globals.fetch +const it = testEffect( + Layer.merge( + Layer.succeed(CodeModeExecution.Service, { + ...toolIdentity, + id: Tool.CallID.make("call_fetch"), + sessionID: Session.ID.make("ses_fetch"), + progress: () => Effect.void, + }), + permissionLayer({ assert: () => Effect.void, assertNotDenied: () => Effect.void }), + ), +) + +const serve = (handle: (req: Request) => Response | Promise) => + Effect.acquireRelease( + Effect.sync(() => Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: handle })), + (server) => Effect.promise(() => server.stop(true)), + ) + +it.live("returns only JSON data and follows a checked redirect", () => + Effect.gen(function* () { + const seen: string[] = [] + const server = yield* serve(async (req) => { + if (new URL(req.url).pathname === "/start") + return new Response("unused", { status: 307, headers: { location: "/end" } }) + return new Response(`${req.method} ${req.headers.get("x-test")} ${await req.text()}`, { + status: 409, + statusText: "Conflict", + headers: { "x-result": "done" }, + }) + }) + const url = server.url.origin + const result = yield* fetch(`${url}/not-used/../start`, { + method: "POST", + body: "café", + headers: { "x-test": "yes" }, + }).pipe( + Effect.provide( + permissionLayer({ + assert: (input) => + Effect.sync(() => { + seen.push(`${input.action} ${input.resources[0]}`) + }), + assertNotDenied: (input) => + Effect.sync(() => { + seen.push(`redirect ${input.resources[0]}`) + }), + }), + ), + ) + expect(seen).toEqual([`webfetch ${url}/start`, `redirect ${url}/end`]) + expect(result).toEqual({ + status: 409, + statusText: "Conflict", + ok: false, + redirected: true, + url: `${url}/end`, + headers: expect.objectContaining({ "x-result": "done" }), + body: "POST yes café", + }) + expect(JSON.parse(JSON.stringify(result))).toEqual(result) + }), +) + +it.effect("rejects unsupported arguments before checking permission or opening a connection", () => + Effect.gen(function* () { + const url = "http://127.0.0.1/" + for (const args of [ + [], + [3], + ["file:///etc/passwd"], + ["data:text/plain,wrong"], + ["http://user:pass@localhost/"], + [url, {}, 42], + [url, null], + [url, []], + [url, { method: 1 }], + [url, { body: {} }], + [url, { headers: { bad: 3 } }], + ...["auth", "proxy", "tls", "unix", "signal", "redirect"].map((key) => [url, { [key]: "bad" }]), + ]) { + yield* Effect.flip(fetch(...args)) + } + }).pipe(Effect.provide(permissionLayer())), +) + +it.live("never requests a denied redirect target and closes its streaming predecessor", () => + Effect.gen(function* () { + const closed = Promise.withResolvers() + const hits: string[] = [] + const server = yield* serve((req) => { + hits.push(new URL(req.url).pathname) + req.signal.addEventListener("abort", () => closed.resolve()) + return new Response( + new ReadableStream({ + start(controller) { + controller.enqueue(new Uint8Array([1])) + }, + }), + { + status: 302, + headers: { location: "/denied" }, + }, + ) + }) + const error = yield* fetch(server.url.href).pipe( + Effect.flip, + Effect.provide( + permissionLayer({ + assert: () => Effect.void, + assertNotDenied: (input) => + Effect.fail( + new Permission.BlockedError({ permission: input.action, resources: input.resources, rules: [] }), + ), + }), + ), + ) + expect(String(error)).toContain("Permission denied: webfetch") + expect(hits).toEqual(["/"]) + yield* Effect.promise(() => closed.promise) + }), +) + +it.live("the legacy JavaScript extension still returns callable response and header methods", () => + Effect.gen(function* () { + const server = yield* serve(() => Response.json({ answer: 42 }, { headers: { "x-test": "legacy" } })) + const result = yield* CodeMode.execute({ + extensions: [CodeModeFetch.extension], + bindings: { url: server.url.href }, + code: `const r = await fetch(url); return [r.headers.get("X-Test"), (await r.json()).answer]`, + }) + expect(result).toMatchObject({ ok: true, value: ["legacy", 42] }) + }), +) + +it.live("rejects a chunked body over 1 MiB without waiting for EOF", () => + Effect.gen(function* () { + const closed = Promise.withResolvers() + const server = yield* serve((req) => { + req.signal.addEventListener("abort", () => closed.resolve()) + return new Response( + new ReadableStream({ + start(controller) { + // No Content-Length or EOF, and fewer than 1 MiB of decoded characters. + controller.enqueue(new TextEncoder().encode("é".repeat(512 * 1024 + 1))) + }, + }), + ) + }) + expect(String(yield* Effect.flip(fetch(server.url.href)))).toContain("exceeds 1 MiB") + yield* Effect.promise(() => closed.promise) + }), +) + +for (const phase of ["headers", "body"]) { + it.live(`interrupting fetch aborts a request stalled at ${phase}`, () => + Effect.gen(function* () { + const started = Promise.withResolvers() + const closed = Promise.withResolvers() + const server = yield* serve((req) => { + req.signal.addEventListener("abort", () => closed.resolve()) + if (phase === "headers") { + started.resolve() + return closed.promise.then(() => new Response()) + } + return new Response( + new ReadableStream({ + start(controller) { + controller.enqueue(new Uint8Array([1])) + started.resolve() + }, + }), + ) + }) + const fiber = yield* fetch(server.url.href).pipe(Effect.forkChild) + yield* Effect.promise(() => started.promise) + yield* Fiber.interrupt(fiber) + yield* Effect.promise(() => closed.promise) + }), + ) +} diff --git a/packages/core/test/codemode.test.ts b/packages/core/test/codemode.test.ts index dda8eb982cf..25443cd0501 100644 --- a/packages/core/test/codemode.test.ts +++ b/packages/core/test/codemode.test.ts @@ -35,7 +35,7 @@ describe("CodeMode", () => { type: "tool", name: "echo", description: "Echo text", - signature: "tools.echo({\n text: string,\n}): Promise", + signature: "tools.echo({\n text = string,\n}) -> string", pinned: true, }, { @@ -74,14 +74,14 @@ describe("CodeMode", () => { description: "Measure", signature: [ "tools.measure({", - " /** Element ref */", - " ref: string,", - " amount: number,", - ' sentinel: "NaN" | "Infinity" | "-Infinity",', - "}): Promise<{", - " exit?: number,", - ' sentinel: "NaN" | "Infinity" | "-Infinity",', - "}>", + " -- Element ref", + " ref = string,", + " amount = number,", + ' sentinel = "NaN" | "Infinity" | "-Infinity",', + "}) -> {", + " exit? = number,", + ' sentinel = "NaN" | "Infinity" | "-Infinity",', + "}", ].join("\n"), pinned: false, }, diff --git a/packages/core/test/codemode/catalog.test.ts b/packages/core/test/codemode/catalog.test.ts index fe483102a60..c8e7367608c 100644 --- a/packages/core/test/codemode/catalog.test.ts +++ b/packages/core/test/codemode/catalog.test.ts @@ -6,14 +6,14 @@ const entry = (path: string, description: string, signature?: string, pinned = f type: "tool", name: path, description, - signature: signature ?? `tools.${path}({\n q: string,\n}): Promise`, + signature: signature ?? `tools.${path}({\n q = string,\n}) -> string`, pinned, }) const lookup = entry( "orders.lookup", "Look up an order by ID", - "tools.orders.lookup({\n id: string,\n}): Promise<{\n id: string,\n status: string,\n}>", + "tools.orders.lookup({\n id = string,\n}) -> {\n id = string,\n status = string,\n}", ) const render = (tools: CodeModeCatalog.Inventory["tools"], budget?: number) => @@ -36,6 +36,7 @@ describe("CodeModeCatalog.summarize", () => { { budget: 0 }, ) expect(catalog).toEqual({ + language: "lua", total: 10_000, shown: 0, namespaces: [{ name: "bulk", count: 10_000, entries: [] }], @@ -68,8 +69,8 @@ describe("CodeModeCatalog.summarize", () => { test("spends the budget remaining after pinned tools on unpinned tools", () => { const pinned = entry("alpha.pinned", "Pinned", undefined, true) const unpinned = entry("beta.unpinned", "Unpinned") - const pinCost = Math.round(` - ${pinned.signature} // Pinned`.length / 4) - const unpinnedCost = Math.round(` - ${unpinned.signature} // Unpinned`.length / 4) + const pinCost = Math.round(` - ${pinned.signature} -- Pinned`.length / 4) + const unpinnedCost = Math.round(` - ${unpinned.signature} -- Unpinned`.length / 4) const namespaceCost = [ { name: "alpha", count: 1, entries: [] }, { name: "beta", count: 1, entries: [] }, @@ -89,19 +90,19 @@ describe("CodeModeCatalog.summarize", () => { const catalog = CodeModeCatalog.summarize({ tools: [entry("alpha.one", `Summary\n${"detail".repeat(10_000)}`)], }) - expect(catalog.namespaces[0]?.entries[0]?.line).toEndWith("// Summary") + expect(catalog.namespaces[0]?.entries[0]?.line).toEndWith("-- Summary") }) test("limits inline descriptions to 120 characters", () => { const catalog = CodeModeCatalog.summarize({ tools: [entry("alpha.one", "x".repeat(121))] }) - const description = catalog.namespaces[0]?.entries[0]?.line.split(" // ")[1] + const description = catalog.namespaces[0]?.entries[0]?.line.split(" -- ")[1] expect(description).toHaveLength(120) expect(description).toEndWith("...") }) test("always retains namespace descriptions and charges them before tool listings", () => { const tool = entry("alpha.one", "One") - const listingCost = Math.round(` - ${tool.signature} // One`.length / 4) + const listingCost = Math.round(` - ${tool.signature} -- One`.length / 4) const namespaceCost = Math.round(CodeModeCatalog.namespaceLine({ name: "alpha", count: 1, entries: [] }).length / 4) const description = "A namespace description that stays visible beyond the available tool budget" const namespace = { type: "namespace" as const, name: "alpha", description, tools: [tool] } @@ -110,7 +111,7 @@ describe("CodeModeCatalog.summarize", () => { const catalog = CodeModeCatalog.summarize({ tools: [namespace] }, { budget: namespaceCost + listingCost }) expect(catalog.shown).toBe(0) expect(catalog.namespaces[0]?.description).toBe(description) - expect(CodeModeInstructions.render(catalog)).toContain(`- alpha (1 tool, none shown) // ${description}`) + expect(CodeModeInstructions.render(catalog)).toContain(`- alpha (1 tool, none shown) -- ${description}`) }) }) @@ -119,10 +120,10 @@ describe("CodeModeInstructions.render", () => { const instructions = render([lookup]) expect(instructions).toContain("## Code Mode tools (call only inside `execute`)") expect(instructions).toContain("- orders (1 tool)") - expect(instructions).toContain(` - ${lookup.signature} // Look up an order by ID`) + expect(instructions).toContain(` - ${lookup.signature} -- Look up an order by ID`) expect(instructions).not.toContain("search") expect(instructions).toContain( - "The tools listed below cannot be called directly: they only work as JavaScript inside the `execute` tool. Every other tool you have is a normal tool call: call it directly, never inside `execute`.", + "The tools listed below cannot be called directly: they only work as Lua inside the `execute` tool. Every other tool you have is a normal tool call: call it directly, never inside `execute`.", ) expect(instructions).toContain("The catalog is complete. Do not guess tool names.") }) @@ -132,14 +133,14 @@ describe("CodeModeInstructions.render", () => { expect(partial).toContain("## Code Mode tools (call only inside `execute`)") expect(partial).toContain("- orders (1 tool, none shown)") expect(partial).toContain( - "The tools listed below, and `search`, cannot be called directly: they only work as JavaScript inside the `execute` tool.", + "The tools listed below, and `search`, cannot be called directly: they only work as Lua inside the `execute` tool.", ) expect(partial).toContain( "The catalog is partial. Before calling a tool that is not listed below, find it with the global `search(...)` function. Do not guess tool names.", ) expect(partial).toContain("- search({") - expect(partial).toContain(" /** @integer @exclusiveMinimum 0 */\n limit?: number,") - expect(partial).toContain(" /** @integer @minimum 0 */\n offset?: number,") + expect(partial).toContain(" -- @integer @maximum 50 @exclusiveMinimum 0\n limit? = number,") + expect(partial).toContain(" -- @integer @minimum 0\n offset? = number,") expect(partial).not.toContain("tools.orders.lookup(input:") }) @@ -149,7 +150,7 @@ describe("CodeModeInstructions.render", () => { const expensive = entry( "alpha.expensive", "Expensive", - `tools.alpha.expensive({\n aVeryLongParameterName: string,\n anotherEvenLongerParameterName: number,\n yetAnotherExtremelyVerboseParameterName: string,\n}): Promise`, + `tools.alpha.expensive({\n aVeryLongParameterName = string,\n anotherEvenLongerParameterName = number,\n yetAnotherExtremelyVerboseParameterName = string,\n}) -> string`, ) // Round 1 places alpha.cheap and beta.cheap; in round 2 alpha.expensive does not fit, // which marks only alpha done - it must NOT prevent other namespaces from inlining. @@ -160,17 +161,17 @@ describe("CodeModeInstructions.render", () => { const instructions = render([cheapAlpha, expensive, cheapBeta], 40 + namespaceCost) expect(instructions).toContain("The catalog is partial.") expect(instructions).toContain("- alpha (2 tools, 1 shown)") - expect(instructions).toContain(` - ${cheapAlpha.signature} // Cheap`) + expect(instructions).toContain(` - ${cheapAlpha.signature} -- Cheap`) expect(instructions).not.toContain("tools.alpha.expensive(") expect(instructions).toContain("- beta (1 tool)") - expect(instructions).toContain(` - ${cheapBeta.signature} // Cheap`) + expect(instructions).toContain(` - ${cheapBeta.signature} -- Cheap`) }) - test("charges inline JSDoc in signatures against the catalog token budget", () => { + test("charges inline documentation in signatures against the catalog token budget", () => { const documented = entry( "records.lookup", "Look up a record", - `tools.records.lookup({\n /** ${"A detailed identifier description. ".repeat(20).trim()} */\n id: string,\n}): Promise`, + `tools.records.lookup({\n -- ${"A detailed identifier description. ".repeat(20).trim()}\n id = string,\n}) -> string`, ) const instructions = render([documented], 40) expect(instructions).toContain("- records (1 tool, none shown)") @@ -188,14 +189,14 @@ describe("CodeModeInstructions.update", () => { const echo = entry("notes.echo", "Echo text") test("renders additions, changes, and removals as a compact semantic delta", () => { - const changed = { ...echo, signature: "tools.notes.echo({\n text: string,\n}): Promise" } + const changed = { ...echo, signature: "tools.notes.echo({\n text = string,\n}) -> string" } const added = entry("notes.list", "List notes") const unchanged = Array.from({ length: 5 }, (_, index) => entry(`stable.tool${index}`, `Stable ${index}`)) const text = update([echo, lookup, ...unchanged], [changed, added, ...unchanged]) expect(text).toContain("The Code Mode tool catalog has changed.") expect(text).toContain(`New tools are available in addition to those previously listed:\n - ${added.signature}`) expect(text).toContain( - `Changed tool listings supersede the previously listed ones:\n - ${changed.signature} // Echo text`, + `Changed tool listings supersede the previously listed ones:\n - ${changed.signature} -- Echo text`, ) expect(text).toContain("The following tools are no longer available and must not be called: tools.orders.lookup.") expect(text).not.toContain("## Code Mode tools (call only inside `execute`)") @@ -218,7 +219,7 @@ describe("CodeModeInstructions.update", () => { }) const text = CodeModeInstructions.update(previous, current) expect(text).toContain("This catalog supersedes the previous Code Mode tool catalog.") - expect(text).toContain("- notes (1 tool) // New description") + expect(text).toContain("- notes (1 tool) -- New description") expect(text).not.toContain("Old description") }) diff --git a/packages/core/test/codemode/instructions.test.ts b/packages/core/test/codemode/instructions.test.ts index f128b8ac0d9..d1211d7879e 100644 --- a/packages/core/test/codemode/instructions.test.ts +++ b/packages/core/test/codemode/instructions.test.ts @@ -13,14 +13,14 @@ const echo: CodeModeCatalog.Tool = { type: "tool", name: "notes.echo", description: "Echo text", - signature: "tools.notes.echo({\n text: string,\n}): Promise", + signature: "tools.notes.echo({\n text = string,\n}) -> string", } const lookup: CodeModeCatalog.Tool = { type: "tool", name: "orders.lookup", description: "Look up an order", - signature: "tools.orders.lookup({\n id: string,\n}): Promise", + signature: "tools.orders.lookup({\n id = string,\n}) -> unknown", } describe("CodeModeInstructions", () => { @@ -32,7 +32,7 @@ describe("CodeModeInstructions", () => { ) const added = yield* readUpdate(CodeModeInstructions.make({ tools: [echo] }), initialized) - expect(added.text).toContain("New tools are available in addition to those previously listed:") + expect(added.text).toContain("they only work as Lua inside the `execute` tool") expect(added.text).toContain(echo.signature) expect(yield* readUpdate(CodeModeInstructions.make({ tools: [] }), { values: added.values })).toMatchObject({ @@ -47,16 +47,16 @@ describe("CodeModeInstructions", () => { Effect.gen(function* () { const initialized = yield* readInitial(CodeModeInstructions.make({ tools: [echo] })) expect(initialized.text).toContain( - "The tools listed below cannot be called directly: they only work as JavaScript inside the `execute` tool.", + "The tools listed below cannot be called directly: they only work as Lua inside the `execute` tool.", ) expect(initialized.text).toContain("The catalog is complete.") expect(initialized.text).toContain("## Code Mode tools (call only inside `execute`)") - expect(initialized.text).toContain(` - ${echo.signature} // Echo text`) + expect(initialized.text).toContain(` - ${echo.signature} -- Echo text`) const added = yield* readUpdate(CodeModeInstructions.make({ tools: [echo, lookup] }), initialized) expect(added.text).toContain("The Code Mode tool catalog has changed.") expect(added.text).toContain("New tools are available in addition to those previously listed:") - expect(added.text).toContain(` - ${lookup.signature} // Look up an order`) + expect(added.text).toContain(` - ${lookup.signature} -- Look up an order`) expect(added.text).not.toContain("## Code Mode tools (call only inside `execute`)") const removed = yield* readUpdate(CodeModeInstructions.make({ tools: [echo] }), { values: added.values }) @@ -115,9 +115,21 @@ describe("CodeModeInstructions", () => { }), ) - expect(initialized.text).toContain("- tools (2 tools) // Project utilities") + expect(initialized.text).toContain("- tools (2 tools) -- Project utilities") expect(reordered.changed).toBe(false) expect(reordered.text).toBe("") }).pipe(Effect.provide(layer)) }) + + it.effect("refreshes a persisted pre-Lua catalog even if no listing changed", () => + Effect.gen(function* () { + // A namespace-only (or empty) catalog can be byte-identical across runtimes except for the language. + const old = { total: 0, shown: 0, namespaces: [] } + const current = CodeModeInstructions.make({ tools: [] }) + expect(current[0]?.initial(old)).toBeUndefined() + const update = yield* readUpdate(current, { values: { "core/codemode": old } }) + expect(update.changed).toBe(true) + expect(update.text).toContain("No Code Mode tools are currently available") + }), + ) }) diff --git a/packages/core/test/lib/tool.ts b/packages/core/test/lib/tool.ts index 23263202e19..9ddebfa8e9c 100644 --- a/packages/core/test/lib/tool.ts +++ b/packages/core/test/lib/tool.ts @@ -20,6 +20,14 @@ export const toolDefinitions = (registry: Tool.Interface, permissions?: Permissi export const codeModeListings = (catalog: CodeModeCatalog.Inventory) => CodeModeCatalog.summarize(catalog, { budget: Infinity }).namespaces.flatMap((namespace) => namespace.entries) +/** A Lua table literal for fixture inputs, including dynamic paths and keys like `in` or `index.html`. */ +export function luaLiteral(value: unknown): string { + if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return JSON.stringify(value) + if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a fixture record or scalar") + const fields = Object.entries(value).map(([key, entry]) => `[${luaLiteral(key)}] = ${luaLiteral(entry)}`) + return `{${fields.join(", ")}}` +} + export function waitForTool(registry: Tool.Interface, name: string, remaining = 1000): Effect.Effect { return Effect.gen(function* () { if ((yield* toolDefinitions(registry)).some((tool) => tool.name === name)) return diff --git a/packages/core/test/mcp-attach.test.ts b/packages/core/test/mcp-attach.test.ts index 44825d0147f..93542b0b613 100644 --- a/packages/core/test/mcp-attach.test.ts +++ b/packages/core/test/mcp-attach.test.ts @@ -126,7 +126,7 @@ const call = (path: string, sessionID = Session.ID.make("ses_client_mcp")) => type: "tool-call", id: "call_client_mcp", name: "execute", - input: { code: `return await tools.${path}({})` }, + input: { code: `return tools.${path}({})` }, }, }) }) diff --git a/packages/core/test/mcp.test.ts b/packages/core/test/mcp.test.ts index 1e32da07e3e..0009a08760d 100644 --- a/packages/core/test/mcp.test.ts +++ b/packages/core/test/mcp.test.ts @@ -1641,7 +1641,7 @@ it.live("discovers and reads MCP resources through Code Mode", () => }) // The SDK walks every page, so one call returns the full catalog. - const listed = yield* run('return await tools.opencode.list_mcp_resources({ server: "resources" })') + const listed = yield* run('return tools.opencode.list_mcp_resources({ server = "resources" })') expect(JSON.parse(listed.output.output)).toEqual({ resources: [ { server: "resources", name: "Guide", uri: "docs://guide" }, @@ -1656,7 +1656,7 @@ it.live("discovers and reads MCP resources through Code Mode", () => // Omitting the server lists every server, so the model can find which one owns a URI. assertion = yield* Deferred.make() - const everywhere = yield* run("return await tools.opencode.list_mcp_resources({})") + const everywhere = yield* run("return tools.opencode.list_mcp_resources({})") expect(yield* Deferred.await(assertion)).toMatchObject({ action: "opencode_list_mcp_resources", resources: ["resources"], @@ -1675,7 +1675,7 @@ it.live("discovers and reads MCP resources through Code Mode", () => // A server may declare resources without implementing template listing. server.state.templatesUnsupported = true - const untemplated = yield* run('return await tools.opencode.list_mcp_resources({ server: "resources" })') + const untemplated = yield* run('return tools.opencode.list_mcp_resources({ server = "resources" })') expect(JSON.parse(untemplated.output.output)).toEqual({ resources: [ { server: "resources", name: "Guide", uri: "docs://guide" }, @@ -1687,7 +1687,12 @@ it.live("discovers and reads MCP resources through Code Mode", () => assertion = yield* Deferred.make() const read = yield* run( - 'const resource = await tools.opencode.read_mcp_resource({ server: "resources", uri: "docs://readme" }); return resource.contents.filter(part => part.type === "text").map(part => part.text).join("\\n")', + `local resource = tools.opencode.read_mcp_resource({ server = "resources", uri = "docs://readme" }) + local lines = {} + for _, part in ipairs(resource.contents) do + if part.type == "text" then table.insert(lines, part.text) end + end + return table.concat(lines, "\\n")`, ) expect(read.content).toEqual([ { type: "text", text: "hello" }, @@ -1711,9 +1716,11 @@ it.live("discovers and reads MCP resources through Code Mode", () => source: { type: "tool", messageID: toolIdentity.messageID, id: "call_resource" }, }) - server.state.contents = [{ uri: "docs://readme", text: "line\n".repeat(20_000), mimeType: "text/plain" }] + // Exercise outer tool-output truncation without exceeding the Lua result's own byte budget. + const fullText = "line\n".repeat(ToolOutput.MAX_LINES + 1) + server.state.contents = [{ uri: "docs://readme", text: fullText, mimeType: "text/plain" }] const large = yield* run( - 'const resource = await tools.opencode.read_mcp_resource({ server: "resources", uri: "docs://readme" }); return resource.contents[0].text', + 'return tools.opencode.read_mcp_resource({ server = "resources", uri = "docs://readme" }).contents[1].text', ) const bounded = yield* ToolOutput.Service.use((output) => output.truncate(large)).pipe( Effect.provide(AppNodeBuilder.build(ToolOutput.node)), @@ -1723,23 +1730,23 @@ it.live("discovers and reads MCP resources through Code Mode", () => const outputPath = bounded.metadata?.outputPath expect(typeof outputPath).toBe("string") if (typeof outputPath !== "string") throw new Error("Missing full resource output") - expect(yield* Effect.promise(() => Bun.file(outputPath).text())).toBe("line\n".repeat(20_000)) + expect(yield* Effect.promise(() => Bun.file(outputPath).text())).toBe(fullText) // An empty contents array means the resource exists without content, not that it is missing. server.state.contents = [] const empty = yield* run( - 'return await tools.opencode.read_mcp_resource({ server: "resources", uri: "docs://empty" })', + 'return tools.opencode.read_mcp_resource({ server = "resources", uri = "docs://empty" })', ) expect(empty.metadata?.error).toBeUndefined() expect(JSON.parse(empty.output.output)).toEqual({ server: "resources", uri: "docs://empty", contents: [] }) server.state.missing = ["docs://gone"] const gone = yield* run( - 'return await tools.opencode.read_mcp_resource({ server: "resources", uri: "docs://gone" })', + 'return tools.opencode.read_mcp_resource({ server = "resources", uri = "docs://gone" })', ) expect(gone.metadata?.error).toBe(true) expect(gone.output.output).toContain("Resource not found") const missing = yield* run( - 'return await tools.opencode.read_mcp_resource({ server: "missing", uri: "docs://readme" })', + 'return tools.opencode.read_mcp_resource({ server = "missing", uri = "docs://readme" })', ) expect(missing.metadata?.error).toBe(true) expect(missing.output.output).toContain("MCP server not found: missing") @@ -1749,7 +1756,7 @@ it.live("discovers and reads MCP resources through Code Mode", () => new Permission.BlockedError({ rules: [], permission: "opencode_read_mcp_resource", resources: ["*"] }), ) const denied = yield* run( - 'return await tools.opencode.read_mcp_resource({ server: "resources", uri: "docs://denied" })', + 'return tools.opencode.read_mcp_resource({ server = "resources", uri = "docs://denied" })', ) expect(denied.metadata?.error).toBe(true) expect(server.state.resourceReads).toHaveLength(reads) @@ -2690,7 +2697,7 @@ it.effect("advertises MCP output schemas to Code Mode", () => "execute", ]) expect(codeModeListings(toolSet.codeModeCatalog!).find((tool) => tool.path === "demo.search")?.line).toContain( - "ok: boolean", + "ok = boolean", ) expect(execute?.description).not.toContain("tools.demo.search") }), @@ -2734,7 +2741,7 @@ it.effect("forwards the invoking session through direct and Code Mode MCP tools" type: "tool-call", id: "call_mcp_codemode", name: "execute", - input: { code: "return await tools.demo.search({})" }, + input: { code: "return tools.demo.search({})" }, }, }) expect(invocations[1]).toEqual({ @@ -2764,7 +2771,7 @@ it.effect("returns content-only MCP results through Code Mode", () => type: "tool-call", id: "call_mcp_content_only", name: "execute", - input: { code: "return await tools.demo.status({})" }, + input: { code: "return tools.demo.status({})" }, }, }) @@ -2793,9 +2800,9 @@ it.effect("parses JSON text results from MCP tools without an output schema", () }) .pipe(Effect.map((execution) => execution.output.output)) - expect(yield* run("return (await tools.demo.issues({})).issues[0].id")).toBe("1") - expect(yield* run("return typeof (await tools.demo.count({}))")).toBe("string") - expect(yield* run("return typeof (await tools.demo.typed({}))")).toBe("string") + expect(yield* run("return tools.demo.issues({}).issues[1].id")).toBe("1") + expect(yield* run("return type(tools.demo.count({}))")).toBe("string") + expect(yield* run("return type(tools.demo.typed({}))")).toBe("string") // Outside Code Mode the content the model reads is the original text. expect( @@ -2909,7 +2916,7 @@ it.effect("waits for permission before calling an MCP tool", () => type: "tool-call", id: "call_mcp_permission", name: "execute", - input: { code: 'return await tools.demo.search({ query: "open issues" })' }, + input: { code: 'return tools.demo.search({ query = "open issues" })' }, }, }) .pipe(Effect.forkScoped) @@ -2959,7 +2966,7 @@ it.effect("does not call MCP when permission is blocked", () => type: "tool-call", id: "call_mcp_blocked", name: "execute", - input: { code: "return await tools.demo.search({})" }, + input: { code: "return tools.demo.search({})" }, }, }) expect(execution.content).toEqual([{ type: "text", text: "Search is disabled in this workspace" }]) @@ -2998,7 +3005,7 @@ it.effect("returns permission feedback instead of calling MCP", () => type: "tool-call", id: "call_mcp_corrected", name: "execute", - input: { code: "return await tools.demo.search({})" }, + input: { code: "return tools.demo.search({})" }, }, }) expect(execution.content).toEqual([{ type: "text", text: "Search the docs folder instead" }]) diff --git a/packages/core/test/plugin/tool-input-repair-integration.test.ts b/packages/core/test/plugin/tool-input-repair-integration.test.ts index 38578f105c8..0062db361f5 100644 --- a/packages/core/test/plugin/tool-input-repair-integration.test.ts +++ b/packages/core/test/plugin/tool-input-repair-integration.test.ts @@ -147,7 +147,7 @@ it.effect("repairs namespaced inner tool input called from Code Mode", () => type: "tool-call", id: "call-codemode-repair", name: "execute", - input: { code: 'return await tools.example.count({ count: "3" })' }, + input: { code: 'return tools.example.count({ count = "3" })' }, }, }) expect(executed).toEqual([{ count: 3 }]) diff --git a/packages/core/test/session-generate.test.ts b/packages/core/test/session-generate.test.ts index b509525b851..af9602280d4 100644 --- a/packages/core/test/session-generate.test.ts +++ b/packages/core/test/session-generate.test.ts @@ -127,7 +127,7 @@ const tools = Layer.mock(Tool.Service, { type: "tool", name: "captured.lookup", description: "Captured Code Mode catalog", - signature: "tools.captured.lookup(): Promise", + signature: "tools.captured.lookup() -> string", }, ], }, @@ -344,7 +344,7 @@ it.effect( ) expect(instructionUpdates).toHaveLength(1) expect(instructionUpdates?.[0]).toContain("Changed context") - expect(instructionUpdates?.[0]).toContain("tools.captured.lookup(): Promise") + expect(instructionUpdates?.[0]).toContain("tools.captured.lookup() -> string") expect(userTexts(requests[0])).toEqual(["Existing durable context", "Summarize privately"]) expect( requests[0]?.messages.flatMap((message) => diff --git a/packages/core/test/session-runner.test.ts b/packages/core/test/session-runner.test.ts index 99ca1729921..de0ef998d05 100644 --- a/packages/core/test/session-runner.test.ts +++ b/packages/core/test/session-runner.test.ts @@ -88,7 +88,7 @@ import { permissionLayer } from "./lib/permission" import { agentHost, modelHost, host, noProviders } from "./plugin/host" import { CodeModeInstructions } from "@opencode/core/codemode/instructions" -const emptyCodeMode = `${CodeModeInstructions.render({ total: 0, shown: 0, namespaces: [] })}\n\n` +const emptyCodeMode = `${CodeModeInstructions.render({ language: "lua", total: 0, shown: 0, namespaces: [] })}\n\n` type ToolBarrier = { readonly count: number readonly started: Deferred.Deferred diff --git a/packages/core/test/tool-execute.test.ts b/packages/core/test/tool-execute.test.ts index b8a16732e24..789d50988e3 100644 --- a/packages/core/test/tool-execute.test.ts +++ b/packages/core/test/tool-execute.test.ts @@ -26,38 +26,53 @@ const createCodeMode = (tools: ReadonlyMap, permission = allowAll) CodeModeTool.create({ tools }, (_, tool, input, context) => execute(tool, input, context), permission) test("execute describes invariant Code Mode behavior", () => { - expect(createCodeMode(new Map()).description).toBe( - [ - "Run JavaScript in a confined Code Mode runtime to script tool calls and HTTP requests and compose their results.", - "`fetch` is available for HTTP requests. Imports, direct filesystem access, and timers are unavailable: there is no `setTimeout` or sleep. All other external access goes through `tools`.", - "Within `{ code }`, the only callable tools are those explicitly listed in the Code Mode catalog instructions or returned by the `search` function. Inside `{ code }`, ignore tools shown outside the Code Mode catalog. They are not available in the Code Mode runtime.", - 'Call tools through `tools` using only exact paths and signatures from the catalog. Do not infer or normalize tool names; preserve bracket notation such as `tools.["tool-name"](input)`.', - "Prefer an explicit `return`; if omitted, the final top-level expression becomes the result.", - "Await every call whose completion matters; pending calls are interrupted when execution ends. Run independent calls concurrently with `Promise.allSettled`.", - ].join("\n"), - ) + const description = createCodeMode(new Map()).description + expect(description).toContain("Lua") + expect(description).toContain("fetch") + expect(description).toContain("search") + expect(description).not.toContain("Promise.allSettled") }) test("execute rejects filesystem fetches", async () => { const result = await Effect.runPromise( - createCodeMode(new Map()).execute({ code: 'return await fetch("file:///blocked.txt")' }, context), + createCodeMode(new Map()).execute({ code: 'return fetch("file:///blocked.txt")' }, context), ) expect(result.output.error).toBe(true) expect(result.output.output).toContain("fetch cannot be used for filesystem access.") }) +test("execute rejects wrong-language source before admitting even its first tool call", async () => { + let calls = 0 + const touch: Info = { + name: "touch", + description: "Record a call", + input: Schema.Struct({}), + execute: () => Effect.sync(() => ({ content: String(++calls) })), + } + const result = await Effect.runPromise( + createCodeMode(new Map([["touch", touch]])).execute( + // The first statement is valid Lua. The JavaScript-only second statement must reject the whole chunk. + { code: "tools.touch({}); const answer = 42; return answer" }, + context, + ), + ) + expect(result.output.error).toBe(true) + expect(result.output.toolCalls).toEqual([]) + expect(calls).toBe(0) +}) + describe("fetch permissions", () => { const hits: Array = [] let server: ReturnType beforeAll(() => { server = Bun.serve({ port: 0, - fetch: (request) => { + fetch: async (request) => { const url = new URL(request.url) hits.push(`${request.method} ${url.pathname}`) if (url.pathname === "/redirect") return Response.redirect(`${url.origin}/blocked`, 302) - return new Response("ok") + return new Response(await request.text(), { status: 201, statusText: "Created", headers: { "x-test": "ok" } }) }, }) }) @@ -71,10 +86,18 @@ describe("fetch permissions", () => { createCodeMode( new Map(), permissionService({ assert: (input) => Effect.sync(() => void asked.push(input)) }), - ).execute({ code: `return await (await fetch("${url}", { method: "POST" })).text()` }, context), + ).execute({ code: `return fetch("${url}", { method = "POST", body = "posted" })` }, context), ) - expect(result.output.output).toBe("ok") + expect(JSON.parse(result.output.output)).toMatchObject({ + status: 201, + statusText: "Created", + url, + redirected: false, + ok: true, + headers: { "x-test": "ok" }, + body: "posted", + }) expect(hits).toEqual(["POST /allowed"]) expect(asked).toEqual([ { @@ -97,34 +120,30 @@ describe("fetch permissions", () => { Effect.fail(new Permission.BlockedError({ rules: [], permission: input.action, resources: input.resources })), }) const result = await Effect.runPromise( - createCodeMode(new Map(), denied).execute( - { code: `try { await fetch("${server.url.origin}/redirect") } catch (e) { return e.message }` }, - context, - ), + createCodeMode(new Map(), denied).execute({ code: `return fetch("${server.url.origin}/redirect")` }, context), ) + expect(result.output.error).toBe(true) expect(result.output.output).toContain("Permission denied") expect(hits).toEqual(["GET /redirect"]) }) - test("a rejection with feedback reaches the program as the error message", async () => { + test("a rejection with feedback reaches the model as the execute error", async () => { hits.length = 0 const url = `${server.url.origin}/corrected` const corrected = permissionService({ assert: () => Effect.fail(new Permission.CorrectedError({ feedback: "use the docs site instead" })), }) const result = await Effect.runPromise( - createCodeMode(new Map(), corrected).execute( - { code: `try { await fetch("${url}") } catch (e) { return e.message }` }, - context, - ), + createCodeMode(new Map(), corrected).execute({ code: `return fetch("${url}")` }, context), ) + expect(result.output.error).toBe(true) expect(result.output.output).toBe(`The user rejected fetching ${url}: use the docs site instead`) expect(hits).toEqual([]) }) - test("a URL denied for webfetch is never requested and rejects like a failed fetch", async () => { + test("a URL denied for webfetch fails execute without making a request", async () => { hits.length = 0 const url = `${server.url.origin}/denied` const denied = permissionService({ @@ -132,13 +151,11 @@ describe("fetch permissions", () => { Effect.fail(new Permission.BlockedError({ rules: [], permission: input.action, resources: input.resources })), }) const result = await Effect.runPromise( - createCodeMode(new Map(), denied).execute( - { code: `const [denied] = await Promise.allSettled([fetch("${url}")]); return denied.status` }, - context, - ), + createCodeMode(new Map(), denied).execute({ code: `return fetch("${url}")` }, context), ) - expect(result.output.output).toBe("rejected") + expect(result.output.error).toBe(true) + expect(result.output.output).toContain("Permission denied") expect(hits).toEqual([]) }) }) @@ -245,7 +262,7 @@ test("execute supports callable namespace tools", async () => { ]), ) const result = await Effect.runPromise( - codeMode.execute({ code: "return [await tools.slack.admin({}), await tools.slack.admin.create({})]" }, context), + codeMode.execute({ code: "return {tools.slack.admin({}), tools.slack.admin.create({})}" }, context), ) expect(result.metadata).toEqual({ @@ -284,7 +301,7 @@ test("executions share the prepared runtime of an inventory while keeping per-ca const progress: Array = [] return CodeModeTool.create(inventory, (_, tool, input, context) => execute(tool, input, context), allowAll) .execute( - { code: `return await tools.echo({ value: "${id}" })` }, + { code: `return tools.echo({ value = "${id}" })` }, { ...context, id: Tool.CallID.make(id), progress: (update) => Effect.sync(() => progress.push(update)) }, ) .pipe(Effect.map((result) => ({ output: result.output.output, progress }))) @@ -301,13 +318,13 @@ test("executions share the prepared runtime of an inventory while keeping per-ca })), ) expect( - (await Effect.runPromise(codeMode.execute({ code: 'return await tools.echo({ value: "x" })' }, context))).output + (await Effect.runPromise(codeMode.execute({ code: 'return tools.echo({ value = "x" })' }, context))).output .output, ).toBe("call_execute:x") expect(conversions).toBe(1) await Effect.runPromise( - createCodeMode(new Map(inventory.tools)).execute({ code: 'return await tools.echo({ value: "next" })' }, context), + createCodeMode(new Map(inventory.tools)).execute({ code: 'return tools.echo({ value = "next" })' }, context), ) expect(conversions).toBe(2) }) @@ -346,7 +363,7 @@ it.effect("execute sends at most one progress update per 100 ms with the latest const progress: Array = [] const fiber = yield* progressCodeMode(started, Effect.sleep("250 millis")) .execute( - { code: "for (const i of [1, 2, 3]) await tools.step({}); await tools.wait({}); return await tools.step({})" }, + { code: "for i = 1, 3 do tools.step({}) end; tools.wait({}); return tools.step({})" }, { ...context, progress: (update) => Effect.sync(() => progress.push(update)) }, ) .pipe(Effect.forkChild({ startImmediately: true })) @@ -373,7 +390,7 @@ it.effect("interrupted execute sends its latest progress rows before it settles" const progress: Array = [] const fiber = yield* progressCodeMode(started, Effect.never) .execute( - { code: "await tools.step({}); await tools.step({}); return await tools.wait({})" }, + { code: "tools.step({}); tools.step({}); return tools.wait({})" }, { ...context, progress: (update) => Effect.sync(() => progress.push(update)) }, ) .pipe(Effect.forkChild({ startImmediately: true })) diff --git a/packages/core/test/tool-image-generate.test.ts b/packages/core/test/tool-image-generate.test.ts index ddc16f83f3a..57fe2689316 100644 --- a/packages/core/test/tool-image-generate.test.ts +++ b/packages/core/test/tool-image-generate.test.ts @@ -23,7 +23,7 @@ import { Global } from "@opencode/util/global" import { Effect, Layer, Schedule, Stream } from "effect" import { testEffect } from "./lib/effect" import { permissionLayer } from "./lib/permission" -import { executeTool, toolDefinitions, toolIdentity } from "./lib/tool" +import { executeTool, luaLiteral, toolDefinitions, toolIdentity } from "./lib/tool" import { makePluginTestLayer } from "./plugin/fixture" const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" @@ -487,7 +487,7 @@ describe("experimental_image_generate", () => { type: "tool-call", id: `models-${JSON.stringify(input)}`, name: "execute", - input: { code: `return await tools.opencode.models(${JSON.stringify(input)})` }, + input: { code: `return tools.opencode.models(${luaLiteral(input)})` }, }, }).pipe( Effect.map((result) => diff --git a/packages/core/test/tool-opencode.test.ts b/packages/core/test/tool-opencode.test.ts index 869b7b26595..1a292059614 100644 --- a/packages/core/test/tool-opencode.test.ts +++ b/packages/core/test/tool-opencode.test.ts @@ -20,7 +20,7 @@ import { initRepo } from "./fixture/git" import { tmpdirScoped } from "./fixture/tmpdir" import { testEffect } from "./lib/effect" import { permissionLayer } from "./lib/permission" -import { executeTool, toolIdentity } from "./lib/tool" +import { executeTool, luaLiteral, toolIdentity } from "./lib/tool" import { makePluginTestLayer, PluginTestLayer } from "./plugin/fixture" const it = testEffect(PluginTestLayer) @@ -88,7 +88,7 @@ it.effect("groups available models by provider with paging", () => type: "tool-call", id: `call-${JSON.stringify(input)}`, name: "execute", - input: { code: `return await tools.opencode.models(${JSON.stringify(input)})` }, + input: { code: `return tools.opencode.models(${luaLiteral(input)})` }, }, }).pipe(Effect.map((result) => JSON.parse(result.content?.[0]?.type === "text" ? result.content[0].text : ""))) @@ -191,14 +191,17 @@ worktreeIt.live("creates, lists, and removes worktrees for the plugin's project" yield* OpenCodeTools.Plugin.effect(yield* PluginHost.make(plugins, "test")) const session = yield* sessions.create({ location: Location.Ref.make({ directory: location.directory }) }) const registry = yield* Tool.Service - const program = (code: string) => + const call = (name: string, input: Record) => executeTool(registry, { sessionID: session.id, ...toolIdentity, - call: { type: "tool-call", id: `call-${code}`, name: "execute", input: { code } }, + call: { + type: "tool-call", + id: `call-${name}`, + name: "execute", + input: { code: `return tools.opencode.${name}(${luaLiteral(input)})` }, + }, }) - const call = (name: string, input: Record) => - program(`return await tools.opencode.${name}(${JSON.stringify(input)})`) const run = (name: string, input: Record) => call(name, input).pipe( Effect.map((result) => JSON.parse(result.content?.[0]?.type === "text" ? result.content[0].text : "")), @@ -229,19 +232,13 @@ worktreeIt.live("creates, lists, and removes worktrees for the plugin's project" expect(yield* Effect.promise(() => Bun.file(path.join(directory, "draft.txt")).exists())).toBe(true) yield* Effect.promise(() => fs.rm(path.join(directory, "draft.txt"))) - // Removal requires the same approval as editing files in the worktree. Rejection feedback reaches the - // program and the execute result, as it would reach the model from a direct call. + // Removal requires edit approval. Its rejection feedback reaches the model through execute. approvals.assertions.length = 0 approvals.rejectEdit = true expect(yield* call("worktree_remove", { directory })).toMatchObject({ content: [{ type: "text", text: "Keep this worktree" }], metadata: { error: true }, }) - expect( - yield* program( - `try { await tools.opencode.worktree_remove(${JSON.stringify({ directory })}) } catch (error) { return error.message }`, - ), - ).toMatchObject({ content: [{ type: "text", text: "Keep this worktree" }] }) expect(yield* Effect.promise(() => Bun.file(path.join(directory, ".git")).exists())).toBe(true) approvals.rejectEdit = false @@ -256,7 +253,6 @@ worktreeIt.live("creates, lists, and removes worktrees for the plugin's project" expect(approvals.assertions).toMatchObject([ { action: "edit", resources: [resource], save: ["*"], sessionID: session.id }, { action: "edit", resources: [resource], save: ["*"], sessionID: session.id }, - { action: "edit", resources: [resource], save: ["*"], sessionID: session.id }, ]) expect((yield* run("worktree_list", {})).worktrees).not.toContainEqual({ directory, strategy: "git" }) }), diff --git a/packages/core/test/tool-registry.test.ts b/packages/core/test/tool-registry.test.ts index 3e68b22c4e9..bd98108be46 100644 --- a/packages/core/test/tool-registry.test.ts +++ b/packages/core/test/tool-registry.test.ts @@ -402,18 +402,18 @@ describe("Tool", () => { }), ) - it.effect("executes Code Mode tools without requiring letter-leading names or namespace segments", () => + it.effect("executes Code Mode tools whose names or namespace segments are not Lua identifiers", () => Effect.gen(function* () { const service = yield* Tool.Service yield* transform(service, { "2d_get_scene": make(), "123": make(), _lookup: make(), "-lookup": make() }) - yield* transform(service, { "2d_get_scene": make() }, { namespace: "123._private.-tools", codemode: true }) + yield* transform(service, { end: make() }, { namespace: "123._private.-tools", codemode: true }) const snapshot = yield* service.snapshot() expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["execute"]) expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual([ "-lookup", "123", - "123._private.-tools.2d_get_scene", + "123._private.-tools.end", "2d_get_scene", "_lookup", ]) @@ -424,13 +424,15 @@ describe("Tool", () => { id: "call-nonletter-names", name: "execute", input: { - code: `const results = await Promise.all([ - tools["2d_get_scene"]({ text: "digit" }), - tools["123"]({ text: "numeric" }), - tools._lookup({ text: "underscore" }), - tools["-lookup"]({ text: "hyphen" }), - tools["123"]._private["-tools"]["2d_get_scene"]({ text: "namespaced" }), - ]); return results.map(result => result.text).join(",");`, + code: `local match = search({ query = "123._private.-tools.end" }).items[1] + assert(match.path == 'tools["123"]._private["-tools"]["end"]') + return table.concat({ + tools["2d_get_scene"]({ text = "digit" }).text, + tools["123"]({ text = "numeric" }).text, + tools._lookup({ text = "underscore" }).text, + tools["-lookup"]({ text = "hyphen" }).text, + tools["123"]._private["-tools"]["end"]({ text = "namespaced" }).text, + }, ",")`, }, }, }) @@ -502,7 +504,7 @@ describe("Tool", () => { type: "tool-call", id: "namespace-search", name: "execute", - input: { code: 'return search({ query: "pricing operations" })' }, + input: { code: 'return search({ query = "pricing operations" })' }, }, }) expect(result.output).toMatchObject({ output: expect.stringContaining("tools.registry.search") }) @@ -513,10 +515,10 @@ describe("Tool", () => { id: "callable-namespace", name: "execute", input: { - code: `return await Promise.all([ - tools.registry.search({ text: "search" }), - tools.registry.search.sales({ text: "sales" }), - ])`, + code: `return { + tools.registry.search({ text = "search" }), + tools.registry.search.sales({ text = "sales" }), + }`, }, }, }) @@ -554,7 +556,7 @@ describe("Tool", () => { id: `namespace-${query}`, name: "execute", input: { - code: `return search({ query: ${JSON.stringify(query)} }).items.map(item => item.path).join(",")`, + code: `local items = search({ query = ${JSON.stringify(query)} }).items; return items[1] and items[1].path or ""`, }, }, }) @@ -583,10 +585,10 @@ describe("Tool", () => { id: "top-level-callable", name: "execute", input: { - code: `return await Promise.all([ - tools.pricing({ text: "pricing" }), - tools.pricing.sales({ text: "sales" }), - ])`, + code: `return { + tools.pricing({ text = "pricing" }), + tools.pricing.sales({ text = "sales" }), + }`, }, }, }) @@ -1198,7 +1200,7 @@ describe("Tool", () => { const toolSet = yield* service.snapshot() const execute = toolSet.definitions.find((tool) => tool.name === "execute") expect(codeModeListings(toolSet.codeModeCatalog!)[0]?.line).toContain("tools.echo") - expect(execute?.description).toContain("confined Code Mode runtime") + expect(execute?.description).toContain("Lua") expect(execute?.description).not.toContain("Echo text") yield* Scope.close(scope, Exit.void) yield* transform(service, { @@ -1218,7 +1220,7 @@ describe("Tool", () => { type: "tool-call", id: "call-execute", name: "execute", - input: { code: 'return await tools.echo({ text: "request" })' }, + input: { code: 'return tools.echo({ text = "request" })' }, }, progress: (update) => Effect.sync(() => progress.push(update)), }) diff --git a/packages/core/test/tool-schedule.test.ts b/packages/core/test/tool-schedule.test.ts index 63b7dd83e5a..02157ac8256 100644 --- a/packages/core/test/tool-schedule.test.ts +++ b/packages/core/test/tool-schedule.test.ts @@ -14,7 +14,7 @@ import type { CommandDefinition } from "@opencode/plugin/effect/command" import { testEffect } from "./lib/effect" import { imagePassthrough } from "./lib/image" import { permissionLayer } from "./lib/permission" -import { codeModeListings, executeTool, registerToolPlugin, toolIdentity } from "./lib/tool" +import { codeModeListings, executeTool, luaLiteral, registerToolPlugin, toolIdentity } from "./lib/tool" const sessionID = Session.ID.make("ses_schedule_tool_test") const otherSessionID = Session.ID.make("ses_schedule_tool_other") @@ -109,7 +109,7 @@ const call = (registry: Tool.Interface, name: string, input: unknown, session = type: "tool-call", id: `call-${name}`, name: "execute", - input: { code: `return await tools.opencode.${name}(${JSON.stringify(input)})` }, + input: { code: `return tools.opencode.${name}(${luaLiteral(input)})` }, }, }) const run = (registry: Tool.Interface, name: string, input: unknown, session = sessionID) => diff --git a/packages/core/test/tool-shell.test.ts b/packages/core/test/tool-shell.test.ts index e4879804c58..9ffba8f3779 100644 --- a/packages/core/test/tool-shell.test.ts +++ b/packages/core/test/tool-shell.test.ts @@ -795,7 +795,7 @@ describe("ShellTool ordinary shell syntax", () => { }) describe("ShellTool", () => { - it.live("returns both parallel CodeMode shell results", () => + it.live("returns both sequential Code Mode shell results", () => withTempDir((tmp) => { reset() return withSession(tmp.path, (registry) => @@ -805,16 +805,17 @@ describe("ShellTool", () => { tool.options = { ...tool.options, codemode: true } }), ) - const command = isWindows ? helloCommand : `${helloCommand}; sleep 0.1` - const inputs = ["one", "two"].map((text) => JSON.stringify({ command: command.replace("hello", text) })) + const calls = ["one", "two"].map( + (text) => `tools.shell({ command = ${JSON.stringify(helloCommand.replace("hello", text))} })`, + ) const result = yield* executeTool(registry, { sessionID, ...toolIdentity, call: { type: "tool-call", - id: "call-parallel-shells", + id: "call-shells", name: "execute", - input: { code: `return await Promise.all([tools.shell(${inputs[0]}), tools.shell(${inputs[1]})])` }, + input: { code: `return {${calls.join(", ")}}` }, }, }).pipe(Effect.timeout("3 seconds")) expect(result.status).toBe("completed") diff --git a/packages/plugin-browser/README.md b/packages/plugin-browser/README.md index a80a86a288a..a8ba0df1113 100644 --- a/packages/plugin-browser/README.md +++ b/packages/plugin-browser/README.md @@ -5,14 +5,14 @@ The server owns tools, invocation scope, and permissions; the desktop owns tabs, CDP, captured traffic, evaluations, and capture files. Core only registers the plugin. Neither endpoint imports the other's implementation. -```js -const tab = await tools.browser.tabs.open({ url: "https://example.com" }) -return await tools.browser.snapshot({ tabID: tab.id }) +```lua +local tab = tools.browser.tabs.open({ url = "https://example.com" }) +return tools.browser.snapshot({ tabID = tab.id }) ``` All page operations require a `tabID` returned by `browser.tabs.open/list`. Focus selects the visible Review tab, not an implicit command target. Discover -current signatures with `search({ namespace: "browser" })`. +current signatures with `search({ namespace = "browser" })`. Screenshots require a focused, visible tab; call `browser.tabs.focus` first. ## Tools diff --git a/packages/plugin-browser/src/skill.ts b/packages/plugin-browser/src/skill.ts index 857f272a752..9212067568b 100644 --- a/packages/plugin-browser/src/skill.ts +++ b/packages/plugin-browser/src/skill.ts @@ -16,7 +16,7 @@ export const info = Skill.Info.make({ content: [ "# In-app browser", "", - "The browser tools drive a Chromium browser inside the user's OpenCode desktop app. Its tabs show in the app's Review pane, so the user sees what you do and can use the same tabs. Call the tools from code mode as `tools.browser.*`; `search({ namespace: \"browser\" })` lists their exact signatures.", + "The browser tools drive a Chromium browser inside the user's OpenCode desktop app. Its tabs show in the app's Review pane, so the user sees what you do and can use the same tabs. Call them from Lua Code Mode as `tools.browser.*`; `return search({ namespace = \"browser\" })` lists their exact signatures.", "", "## Basics", "", @@ -29,27 +29,27 @@ export const info = Skill.Info.make({ "", "## Show the user", "", - "- `tools.browser.preview({ path })` opens a file you made, such as an image, HTML, PDF, Markdown, Mermaid diagram, CSV or video, in the Review pane. Use it instead of pasting or describing the file.", - "- New tabs open in front by default so the user can watch. Pass `focus: false` only when the user asked you to work in the background.", + "- `tools.browser.preview({ path = path })` opens a file you made, such as an image, HTML, PDF, Markdown, Mermaid diagram, CSV or video, in the Review pane. Use it instead of pasting or describing the file.", + "- New tabs open in front by default so the user can watch. Pass `focus = false` only when the user asked you to work in the background.", "- `screenshot` needs a focused tab in a visible window: call `tools.browser.tabs.focus` first. It returns the image for you to look at and a server-local file path.", "", "## Recipes", "", "### Check a page or a UI change", "", - "```js", - 'const tab = await tools.browser.tabs.open({ url: "http://localhost:3000/settings" })', - 'await tools.browser.wait({ tabID: tab.id, condition: "load" })', - 'const errors = await tools.browser.console({ tabID: tab.id, level: "error" })', - "const page = await tools.browser.snapshot({ tabID: tab.id })", - "return { errors: errors.messages, page: page.content }", + "```lua", + 'local tab = tools.browser.tabs.open({ url = "http://localhost:3000/settings" })', + 'tools.browser.wait({ tabID = tab.id, condition = "load" })', + 'local errors = tools.browser.console({ tabID = tab.id, level = "error" })', + "local page = tools.browser.snapshot({ tabID = tab.id })", + "return { errors = errors.messages, page = page.content }", "```", "", "Then act on refs from that snapshot, take a fresh snapshot to confirm the result, and screenshot it for the user when it matters visually.", "", "### Debug a request", "", - "`network.list` with `urlContains`, then `network.get` with `includeBody: true` on the request ID it returns. An HTTP 4xx or 5xx is a completed request, not a transport failure.", + "`network.list` with `urlContains`, then `network.get` with `includeBody = true` on the request ID it returns. An HTTP 4xx or 5xx is a completed request, not a transport failure.", "", "### Measure performance", "", diff --git a/services/www/src/docs/content/tools.mdx b/services/www/src/docs/content/tools.mdx index 25ee3b0d6c9..1baa420025c 100644 --- a/services/www/src/docs/content/tools.mdx +++ b/services/www/src/docs/content/tools.mdx @@ -224,18 +224,30 @@ Permission: `subagent` with the selected agent ID as its resource. ### Execute -`execute` runs JavaScript in Code Mode so the agent can call and combine tools -from the catalog. It is useful for parallel independent calls and for processing -results without adding every intermediate value to the model context. +`execute` runs Lua 5.1 so the agent can combine catalog tools without adding every +intermediate value to the model context. Calls run in order. Use `return` to send +the first result back, and use 1-based indices for arrays. -```text -Read package.json and README.md in parallel, then return their relevant setup details. +```lua +local result = tools.opencode.worktree_list() +return result.worktrees[1] ``` -The runtime has no direct filesystem access, imports, or timers. It provides -`fetch` for HTTP requests; everything else goes through tools in its catalog. -Denying `execute` with resource `*` removes Code Mode and every tool reached only -through it, including MCP tools from servers that do not set `codemode: false`. +Use `search({ namespace = "opencode" })` to discover tools omitted from a partial +catalog. Copy the returned path exactly, including any bracket notation. +Scheduled Code Mode checks still use JavaScript, not Lua. + +The runtime has no direct filesystem access, imports, or timers. `fetch` accepts +an HTTP(S) URL and an optional table with `method`, `headers`, and a text `body`. +The response body is text and the header names are lower-case. + +```lua +local response = fetch("https://example.com") +return { status = response.status, body = response.body } +``` + +Denying `execute` with resource `*` removes Code Mode; otherwise eligible tools +are exposed directly instead. Nested built-in and MCP tools still enforce their own permissions, and plugin tools enforce the permissions they assert.