@amends-dev/codemode-opencode 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarib Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OpencodeCodeRuntime.d.ts

@@ -0,0 +1,52 @@
+/**
+ * opencode's code mode as the runtime of `@amends-dev/toolkit`'s code mode. `@opencode/codemode`
+ * interprets the code a model writes, a subset of JavaScript that it implements itself, so the
+ * code can reach nothing it does not implement: no engine, worker, or serialization stands between
+ * the code and the tools, and what the code is given is only `tools`, `console`, and `search`. `make`
+ * gives the `CodeRuntime` that `CodeMode.toolkit` takes.
+ *
+ * @since 0.1.0
+ */
+import { CodeMode } from "@amends-dev/toolkit";
+/**
+ * What `make` takes.
+ *
+ * @category options
+ * @since 0.1.0
+ */
+export interface Options {
+    /**
+     * The most calls of tools one run may make, which the calls of `search`, the function the
+     * interpreter gives the code to find tools by, count in. Unlimited by default.
+     */
+    readonly maxToolCalls?: number;
+}
+/**
+ * Makes the runtime. A run interprets the code with the tools of its execution as `tools`, each
+ * called as `await tools.<name>(input)`, and gives back what the code returned, as JSON, with what
+ * it logged. A failure of a tool reaches the code as an error whose message names the reason and
+ * what happened. A run that does not finish fails with `CodeError`: what the code threw, code the
+ * interpreter does not run, a call of a tool the run does not have, or more calls than allowed,
+ * each with where in the code when the interpreter knows.
+ *
+ * **Example** (Code mode over opencode's interpreter)
+ *
+ * ```ts
+ * import { OpencodeCodeRuntime } from "@amends-dev/codemode-opencode"
+ * import { Assembly, CodeMode } from "@amends-dev/toolkit"
+ * import { Effect } from "effect"
+ *
+ * declare const members: ReadonlyArray<Assembly.Member>
+ *
+ * const program = Effect.gen(function* () {
+ *   const assembled = yield* Assembly.toolkit(members, () => "allow")
+ *   // The model is shown `execute`, whose code calls the assembled tools on this runtime.
+ *   return yield* CodeMode.toolkit(assembled, OpencodeCodeRuntime.make({ maxToolCalls: 50 }))
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options?: Options) => CodeMode.CodeRuntime;
+//# sourceMappingURL=OpencodeCodeRuntime.d.ts.map

package/OpencodeCodeRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpencodeCodeRuntime.d.ts","sourceRoot":"","sources":["../src/OpencodeCodeRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAK9C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,IAAI,aAAa,OAAO,KAAQ,QAAQ,CAAC,WAQpD,CAAA"}

package/OpencodeCodeRuntime.js

@@ -0,0 +1,79 @@
+/**
+ * opencode's code mode as the runtime of `@amends-dev/toolkit`'s code mode. `@opencode/codemode`
+ * interprets the code a model writes, a subset of JavaScript that it implements itself, so the
+ * code can reach nothing it does not implement: no engine, worker, or serialization stands between
+ * the code and the tools, and what the code is given is only `tools`, `console`, and `search`. `make`
+ * gives the `CodeRuntime` that `CodeMode.toolkit` takes.
+ *
+ * @since 0.1.0
+ */
+import { CodeMode } from "@amends-dev/toolkit";
+import * as Codemode from "@opencode/codemode";
+import * as Effect from "effect/Effect";
+/**
+ * Makes the runtime. A run interprets the code with the tools of its execution as `tools`, each
+ * called as `await tools.<name>(input)`, and gives back what the code returned, as JSON, with what
+ * it logged. A failure of a tool reaches the code as an error whose message names the reason and
+ * what happened. A run that does not finish fails with `CodeError`: what the code threw, code the
+ * interpreter does not run, a call of a tool the run does not have, or more calls than allowed,
+ * each with where in the code when the interpreter knows.
+ *
+ * **Example** (Code mode over opencode's interpreter)
+ *
+ * ```ts
+ * import { OpencodeCodeRuntime } from "@amends-dev/codemode-opencode"
+ * import { Assembly, CodeMode } from "@amends-dev/toolkit"
+ * import { Effect } from "effect"
+ *
+ * declare const members: ReadonlyArray<Assembly.Member>
+ *
+ * const program = Effect.gen(function* () {
+ *   const assembled = yield* Assembly.toolkit(members, () => "allow")
+ *   // The model is shown `execute`, whose code calls the assembled tools on this runtime.
+ *   return yield* CodeMode.toolkit(assembled, OpencodeCodeRuntime.make({ maxToolCalls: 50 }))
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options = {}) => ({
+    run: ({ code, tools, call }) => {
+        const runtime = Codemode.CodeMode.make({
+            tools: Object.fromEntries(tools.map((name) => [name, toolOf(name, call)])),
+            limits: options.maxToolCalls === undefined ? {} : { maxToolCalls: options.maxToolCalls }
+        });
+        return Effect.flatMap(runtime.execute(code), outcomeOf);
+    }
+});
+/** The tool `name` of the execution as the interpreter calls it: an object in, JSON out. */
+const toolOf = (name, call) => Codemode.Tool.make({
+    // What the model reads of the tools is `execute`'s own description, so the interpreter's
+    // `search` tells the code only their names.
+    description: "",
+    // The execution checks the input against the tool's parameters; the interpreter checks nothing,
+    // so what the code gave arrives as it is, an object or not.
+    input: { type: "object" },
+    output: {},
+    execute: (input) => call(name, input).pipe(
+    // The code reads a failure as an error whose message names the reason and what happened.
+    Effect.mapError((failure) => Codemode.toolError(`${failure.code}: ${failure.message}`)))
+});
+/** What a run gave back, as the interpreter reports it: the value and the logs, or why it did not finish. */
+const outcomeOf = (result) => {
+    const logs = result.logs ?? [];
+    if (!result.ok)
+        return Effect.fail(new CodeMode.CodeError({ description: describe(result.error), logs }));
+    // A rejection the code did not await, and work it left running when it returned, are warnings,
+    // which the model reads after the logs.
+    const warnings = (result.warnings ?? []).map((warning) => `Warning: ${warning.message}`);
+    return Effect.succeed({ result: result.value, logs: [...logs, ...warnings] });
+};
+/** A diagnostic on one line: its kind, where in the code, what happened, and what to do about it. */
+const describe = ({ kind, message, location, suggestions }) => [
+    location === undefined
+        ? `${kind}: ${message}`
+        : `${kind} at line ${location.line}, column ${location.column}: ${message}`,
+    ...(suggestions ?? [])
+].join(" ");
+//# sourceMappingURL=OpencodeCodeRuntime.js.map

package/OpencodeCodeRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpencodeCodeRuntime.js","sourceRoot":"","sources":["../src/OpencodeCodeRuntime.ts"],"names":[],"mappings":"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"}

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @amends-dev/codemode-opencode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+opencode's code mode as the runtime of [`@amends-dev/toolkit`](../toolkit)'s code mode.
+Code mode presents a toolkit to a model as one tool, `execute`, that runs code the model writes, and
+leaves running the code to a `CodeRuntime`. This runtime is
+[`@opencode/codemode`](https://github.com/anomalyco/opencode/tree/dev/packages/codemode), an
+interpreter of a subset of JavaScript that opencode wrote for the purpose: it implements the
+language itself, so the code can reach nothing the interpreter does not give it, and no engine,
+worker, or serialization stands between the code and the tools. The package depends on Effect,
+the toolkit, and `@opencode/codemode`.
+
+## Install
+
+```sh
+bun add @amends-dev/codemode-opencode @amends-dev/toolkit effect
+```
+
+`@opencode/codemode` names `effect` as a dependency rather than a peer, so a project on another
+Effect 4.0 release gets a second copy of Effect under it, which its types then disagree with. Until
+[the change that makes it a peer](https://github.com/anomalyco/opencode/compare/dev...saribmah:opencode:codemode-effect-peer)
+is published, dedupe it in your manifest:
+
+```json
+{ "overrides": { "effect": "4.0.5" } }
+```
+
+## Quick start
+
+`OpencodeCodeRuntime.make` gives the runtime, and `CodeMode.toolkit` presents a toolkit over it.
+
+```ts
+import { OpencodeCodeRuntime } from "@amends-dev/codemode-opencode"
+import { Assembly, CodeMode } from "@amends-dev/toolkit"
+import { Effect } from "effect"
+
+declare const members: ReadonlyArray<Assembly.Member> // a workspace's sources, from the toolkit
+
+const program = Effect.gen(function* () {
+  const assembled = yield* Assembly.toolkit(members, () => "allow")
+  // The model is shown `execute`, whose code calls the assembled tools on this runtime.
+  return yield* CodeMode.toolkit(assembled, OpencodeCodeRuntime.make({ maxToolCalls: 50 }))
+})
+```
+
+The toolkit's [code mode](../toolkit/README.md#code-mode) says what the model is shown and what a
+run gives back; a [harness](https://github.com/amends-dev/harness/tree/main/packages/harness#host-tools)
+session runs `execute` as it runs any host tool.
+
+## What the code can do
+
+The code is the body of an async function in the JavaScript the interpreter implements, which its
+[support checklist](https://github.com/anomalyco/opencode/blob/dev/packages/codemode/interpreter-support.md)
+lists: the usual statements, functions, promises, and built-ins such as `JSON`, `Math`, `Date`,
+`Map`, `Set`, `RegExp`, and `URL`. It has no modules, imports, timers, `process`, or file system,
+and nothing of the host but what the runtime gives it:
+
+- `tools.<name>(input)`, one function for each tool of the run, which returns a promise of the
+  tool's answer as JSON. The input crosses as `JSON.stringify` would write it, and the answer as
+  `JSON.parse` would read it; nothing is shared. The execution checks the input against the tool's
+  parameters, and a failure reaches the code as an error whose message names the reason and what
+  happened, `CallFailedError: No such repository`, which the code can catch.
+- `console.log`, whose lines come back as the run's logs.
+- `search({ query })`, which finds the run's tools by name, counted as a call of a tool.
+
+What the code returns comes back as JSON, `null` when it returns nothing, with the logs. A
+rejection the code did not await, and work it left running when it returned, are interrupted and
+come back as warnings after the logs. A run fails with the toolkit's `CodeError` when the code
+throws, cannot be parsed or uses syntax the interpreter does not run, calls a tool the run does not
+have, or makes more calls than `maxToolCalls` allows, saying where in the code when the interpreter
+knows. The toolkit's own `timeout` interrupts a run, a busy loop included, since the interpreter
+yields between its steps; one step is bounded in what it may build, so no built-in runs away.
+
+## Development
+
+Run the package's tests with `bun run test packages/codemode-opencode`: the runtime over fake
+tools, and `execute` as `CodeMode.toolkit` presents it.
+`bun run dist check packages/codemode-opencode` builds the package as npm gets it and checks it as
+a consumer. In this repository, the root manifest's
+`overrides` keeps `@opencode/codemode` on the catalog's Effect.

package/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * opencode's code mode as the runtime of `@amends-dev/toolkit`'s code mode: the code a model writes
+ * runs on an interpreter that reaches nothing but the tools it is given.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @since 0.1.0
+ */
+export * as OpencodeCodeRuntime from "./OpencodeCodeRuntime.ts";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,OAAO,KAAK,mBAAmB,MAAM,0BAA0B,CAAA"}

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * opencode's code mode as the runtime of `@amends-dev/toolkit`'s code mode: the code a model writes
+ * runs on an interpreter that reaches nothing but the tools it is given.
+ *
+ * @since 0.1.0
+ */
+// @barrel: Auto-generated exports. Do not edit manually.
+/**
+ * @since 0.1.0
+ */
+export * as OpencodeCodeRuntime from "./OpencodeCodeRuntime.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yDAAyD;AAEzD;;GAEG;AACH,OAAO,KAAK,mBAAmB,MAAM,0BAA0B,CAAA"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@amends-dev/codemode-opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "opencode's code mode as the runtime of @amends-dev/toolkit's code mode: the code a model writes runs on an interpreter that reaches nothing but the tools it is given.",
+  "license": "MIT",
+  "homepage": "https://github.com/amends-dev/toolkit/tree/main/packages/codemode-opencode#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amends-dev/toolkit.git",
+    "directory": "packages/codemode-opencode"
+  },
+  "bugs": {
+    "url": "https://github.com/amends-dev/toolkit/issues"
+  },
+  "keywords": [
+    "agent",
+    "code mode",
+    "effect",
+    "opencode",
+    "tools"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*.js"
+  },
+  "dependencies": {
+    "@amends-dev/toolkit": "^0.2.1",
+    "@opencode/codemode": "^2.0.32"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}