@amends-dev/harness-opencode 0.0.0-stage → 0.1.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/Opencode2Agent.d.ts

@@ -0,0 +1,105 @@
+/**
+ * opencode as an agent that hosts run: opencode 2, driven over its session API, which takes a
+ * turn's prompt with its files, its instructions, given beside opencode's own, the host's tools,
+ * and requests to compact, and records a session started on another agent as opencode's own. It
+ * does not answer in JSON yet, which fails with `UnsupportedError`. opencode works in the sandbox
+ * behind its bridge: the agent's template installs both there, and a session launches the bridge
+ * when none answers. One bridge and one opencode server serve every session that hosts start in a
+ * sandbox with the same options, whichever host started it; other options, such as another model,
+ * get a bridge and a server of their own. What runs in the sandbox is in `internal/bridge/v2/`.
+ *
+ * opencode runs on the model endpoints the agent is made with, which it is configured for.
+ * Their keys reach opencode in its configuration, in the sandbox, where the commands opencode runs
+ * can read them. The host's tools reach opencode as an MCP server the bridge serves on the
+ * sandbox's loopback, which opencode 2's model calls from code it runs; the host runs them, and
+ * nothing they need reaches the sandbox.
+ *
+ * @since 0.1.0
+ */
+import type { Agent } from "@amends-dev/harness";
+import type { Sandbox } from "@amends-dev/sandbox";
+import type * as Redacted from "effect/Redacted";
+import type * as Schema from "effect/Schema";
+/**
+ * What the agent is made with: the endpoints its turns run on, as `Agent.Options` give them, and
+ * what only opencode takes.
+ *
+ * **Details**
+ *
+ * All of it, the keys included, names the bridge, so an agent made with other options gets a bridge
+ * and a server of its own in a sandbox, and never runs on another's.
+ *
+ * @category options
+ * @since 0.1.0
+ */
+export interface Options extends Agent.Options {
+    /**
+     * The token the bridge in the sandbox `id` takes, derived from the id with a secret every host
+     * shares, such as an HMAC of it, so that every host connects to a bridge any of them launched.
+     */
+    readonly token: (id: Sandbox.SandboxId) => Redacted.Redacted<string>;
+    /**
+     * opencode's configuration, as opencode 2 writes its `opencode.json`, which names providers
+     * `providers`; the providers that serve the models replace any it has. It takes effect when the
+     * bridge starts opencode's server; a server already running in the sandbox keeps the one it
+     * started with.
+     */
+    readonly config?: {
+        readonly [key: string]: Schema.Json;
+    };
+    /** Environment variables opencode's server runs with. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The agent, which bundles the bridge program for its template when it is made, with `Bun.build`,
+ * so the host runs on Bun.
+ *
+ * **Details**
+ *
+ * Each session reaches opencode through the bridge in its sandbox, with the `Crypto` and the
+ * `WebSocketConstructor` the agent is made with; the constructor must send headers, as Bun's and
+ * Node's do. Endpoints that opencode cannot serve together fail with `UnsupportedError`.
+ *
+ * **Example** (A turn of opencode 2 in a new sandbox)
+ *
+ * ```ts
+ * import { createHmac } from "node:crypto"
+ * import { Agent, Harness } from "@amends-dev/harness"
+ * import { Opencode2Agent } from "@amends-dev/harness-opencode"
+ * import { SandboxProvider } from "@amends-dev/sandbox"
+ * import { BunServices, BunSocket } from "@effect/platform-bun"
+ * import { Config, Effect, Layer, Redacted } from "effect"
+ *
+ * declare const sandboxes: Layer.Layer<SandboxProvider.SandboxProvider> // a sandbox provider
+ *
+ * const program = Effect.gen(function* () {
+ *   // Every host derives a sandbox's bridge token from its id with a secret the hosts share.
+ *   const secret = yield* Config.Redacted("BRIDGE_SECRET")
+ *   const agent = yield* Opencode2Agent.make({
+ *     model: {
+ *       provider: "anthropic",
+ *       model: "claude-sonnet-5-5",
+ *       protocol: "anthropic-messages",
+ *       url: "https://api.anthropic.com/v1",
+ *       apiKey: yield* Config.Redacted("ANTHROPIC_API_KEY")
+ *     },
+ *     token: (sandboxId) =>
+ *       Redacted.make(createHmac("sha256", Redacted.value(secret)).update(sandboxId).digest("base64url"))
+ *   })
+ *   const harness = Harness.make(agent)
+ *   const sandboxProvider = yield* SandboxProvider.SandboxProvider
+ *   const sandbox = yield* sandboxProvider.createScoped({ template: harness.agent.template })
+ *   const session = yield* harness.createSession({ sandbox, id: Agent.SessionId.make("review") })
+ *   const answer = yield* session.generate({ prompt: "Summarize README.md" })
+ *   return answer.text
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(Layer.mergeAll(sandboxes, BunServices.layer, BunSocket.layerWebSocketConstructor))
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options: Options) => import("effect/Effect").Effect<Agent.Agent, import("@amends-dev/harness/HarnessError").HarnessError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto | import("effect/socket/Socket").WebSocketConstructor>;
+//# sourceMappingURL=Opencode2Agent.d.ts.map

package/Opencode2Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Opencode2Agent.d.ts","sourceRoot":"","sources":["../src/Opencode2Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAG5C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAQ,SAAQ,KAAK,CAAC,OAAO;IAC5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAEpE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;KAAE,CAAA;IAEzD,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,IAAI,YAAa,OAAO,8OAA4D,CAAA"}

package/Opencode2Agent.js

@@ -0,0 +1,72 @@
+/**
+ * opencode as an agent that hosts run: opencode 2, driven over its session API, which takes a
+ * turn's prompt with its files, its instructions, given beside opencode's own, the host's tools,
+ * and requests to compact, and records a session started on another agent as opencode's own. It
+ * does not answer in JSON yet, which fails with `UnsupportedError`. opencode works in the sandbox
+ * behind its bridge: the agent's template installs both there, and a session launches the bridge
+ * when none answers. One bridge and one opencode server serve every session that hosts start in a
+ * sandbox with the same options, whichever host started it; other options, such as another model,
+ * get a bridge and a server of their own. What runs in the sandbox is in `internal/bridge/v2/`.
+ *
+ * opencode runs on the model endpoints the agent is made with, which it is configured for.
+ * Their keys reach opencode in its configuration, in the sandbox, where the commands opencode runs
+ * can read them. The host's tools reach opencode as an MCP server the bridge serves on the
+ * sandbox's loopback, which opencode 2's model calls from code it runs; the host runs them, and
+ * nothing they need reaches the sandbox.
+ *
+ * @since 0.1.0
+ */
+import * as internal from "./internal/agent.js";
+/**
+ * The agent, which bundles the bridge program for its template when it is made, with `Bun.build`,
+ * so the host runs on Bun.
+ *
+ * **Details**
+ *
+ * Each session reaches opencode through the bridge in its sandbox, with the `Crypto` and the
+ * `WebSocketConstructor` the agent is made with; the constructor must send headers, as Bun's and
+ * Node's do. Endpoints that opencode cannot serve together fail with `UnsupportedError`.
+ *
+ * **Example** (A turn of opencode 2 in a new sandbox)
+ *
+ * ```ts
+ * import { createHmac } from "node:crypto"
+ * import { Agent, Harness } from "@amends-dev/harness"
+ * import { Opencode2Agent } from "@amends-dev/harness-opencode"
+ * import { SandboxProvider } from "@amends-dev/sandbox"
+ * import { BunServices, BunSocket } from "@effect/platform-bun"
+ * import { Config, Effect, Layer, Redacted } from "effect"
+ *
+ * declare const sandboxes: Layer.Layer<SandboxProvider.SandboxProvider> // a sandbox provider
+ *
+ * const program = Effect.gen(function* () {
+ *   // Every host derives a sandbox's bridge token from its id with a secret the hosts share.
+ *   const secret = yield* Config.Redacted("BRIDGE_SECRET")
+ *   const agent = yield* Opencode2Agent.make({
+ *     model: {
+ *       provider: "anthropic",
+ *       model: "claude-sonnet-5-5",
+ *       protocol: "anthropic-messages",
+ *       url: "https://api.anthropic.com/v1",
+ *       apiKey: yield* Config.Redacted("ANTHROPIC_API_KEY")
+ *     },
+ *     token: (sandboxId) =>
+ *       Redacted.make(createHmac("sha256", Redacted.value(secret)).update(sandboxId).digest("base64url"))
+ *   })
+ *   const harness = Harness.make(agent)
+ *   const sandboxProvider = yield* SandboxProvider.SandboxProvider
+ *   const sandbox = yield* sandboxProvider.createScoped({ template: harness.agent.template })
+ *   const session = yield* harness.createSession({ sandbox, id: Agent.SessionId.make("review") })
+ *   const answer = yield* session.generate({ prompt: "Summarize README.md" })
+ *   return answer.text
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(Layer.mergeAll(sandboxes, BunServices.layer, BunSocket.layerWebSocketConstructor))
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => internal.make({ id: "opencode2", version: 2 }, options);
+//# sourceMappingURL=Opencode2Agent.js.map

package/Opencode2Agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Opencode2Agent.js","sourceRoot":"","sources":["../src/Opencode2Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA;AAiC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA"}

package/OpencodeAgent.d.ts

@@ -0,0 +1,110 @@
+/**
+ * opencode as an agent that hosts run: opencode 1, driven over its session API, which takes all of
+ * a turn: its instructions, as the system prompt of its prompt, an answer in JSON, the files of its
+ * prompt, the host's tools, and requests to compact. opencode works in the sandbox behind its
+ * bridge: the agent's template installs both there, and a session launches the bridge when none
+ * answers. One bridge and one opencode server serve every session that hosts start in a sandbox
+ * with the same options, whichever host started it; other options, such as another model, get a
+ * bridge and a server of their own. What runs in the sandbox is in `internal/bridge/v1/`.
+ *
+ * opencode runs on the model endpoints the agent is made with, which it is configured for.
+ * Their keys reach opencode in its configuration, in the sandbox, where the commands opencode runs
+ * can read them. The host's tools reach opencode as an MCP server the bridge serves on the
+ * sandbox's loopback, whose tools opencode names `host_<tool>`; the host runs them, and nothing
+ * they need reaches the sandbox.
+ *
+ * A session started on another agent is written into opencode as one message the model reads,
+ * since opencode 1 records no steps but its own. `Opencode2Agent`, over opencode 2's session API,
+ * records them as opencode's own, but does not answer in JSON yet.
+ *
+ * @since 0.1.0
+ */
+import type { Agent } from "@amends-dev/harness";
+import type { Sandbox } from "@amends-dev/sandbox";
+import type * as Redacted from "effect/Redacted";
+import type * as Schema from "effect/Schema";
+/**
+ * What the agent is made with: the endpoints its turns run on, as `Agent.Options` give them, and
+ * what only opencode takes.
+ *
+ * **Details**
+ *
+ * All of it, the keys included, names the bridge, so an agent made with other options gets a bridge
+ * and a server of its own in a sandbox, and never runs on another's.
+ *
+ * @category options
+ * @since 0.1.0
+ */
+export interface Options extends Agent.Options {
+    /**
+     * The token the bridge in the sandbox `id` takes, derived from the id with a secret every host
+     * shares, such as an HMAC of it, so that every host connects to a bridge any of them launched.
+     */
+    readonly token: (id: Sandbox.SandboxId) => Redacted.Redacted<string>;
+    /**
+     * opencode's configuration, as opencode 1 writes its `opencode.json`, which names providers
+     * `provider`; the providers that serve the models replace any it has. It takes effect when the
+     * bridge starts opencode's server; a server already running in the sandbox keeps the one it
+     * started with.
+     */
+    readonly config?: {
+        readonly [key: string]: Schema.Json;
+    };
+    /** Environment variables opencode's server runs with. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The agent, which bundles the bridge program for its template when it is made, with `Bun.build`,
+ * so the host runs on Bun.
+ *
+ * **Details**
+ *
+ * The names of the host's tools fit in 59 characters, as `maxToolNameLength` says, since opencode
+ * puts `host_` before them. Each session reaches opencode through the bridge in its sandbox, with
+ * the `Crypto` and the `WebSocketConstructor` the agent is made with; the constructor must send
+ * headers, as Bun's and Node's do. Endpoints that opencode cannot serve together fail with
+ * `UnsupportedError`.
+ *
+ * **Example** (A turn of opencode in a new sandbox)
+ *
+ * ```ts
+ * import { createHmac } from "node:crypto"
+ * import { Agent, Harness } from "@amends-dev/harness"
+ * import { OpencodeAgent } from "@amends-dev/harness-opencode"
+ * import { SandboxProvider } from "@amends-dev/sandbox"
+ * import { BunServices, BunSocket } from "@effect/platform-bun"
+ * import { Config, Effect, Layer, Redacted } from "effect"
+ *
+ * declare const sandboxes: Layer.Layer<SandboxProvider.SandboxProvider> // a sandbox provider
+ *
+ * const program = Effect.gen(function* () {
+ *   // Every host derives a sandbox's bridge token from its id with a secret the hosts share.
+ *   const secret = yield* Config.Redacted("BRIDGE_SECRET")
+ *   const agent = yield* OpencodeAgent.make({
+ *     model: {
+ *       provider: "anthropic",
+ *       model: "claude-sonnet-5-5",
+ *       protocol: "anthropic-messages",
+ *       url: "https://api.anthropic.com/v1",
+ *       apiKey: yield* Config.Redacted("ANTHROPIC_API_KEY")
+ *     },
+ *     token: (sandboxId) =>
+ *       Redacted.make(createHmac("sha256", Redacted.value(secret)).update(sandboxId).digest("base64url"))
+ *   })
+ *   const harness = Harness.make(agent)
+ *   const sandboxProvider = yield* SandboxProvider.SandboxProvider
+ *   const sandbox = yield* sandboxProvider.createScoped({ template: harness.agent.template })
+ *   const session = yield* harness.createSession({ sandbox, id: Agent.SessionId.make("review") })
+ *   const answer = yield* session.generate({ prompt: "Summarize README.md" })
+ *   return answer.text
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(Layer.mergeAll(sandboxes, BunServices.layer, BunSocket.layerWebSocketConstructor))
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options: Options) => import("effect/Effect").Effect<Agent.Agent, import("@amends-dev/harness/HarnessError").HarnessError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto | import("effect/socket/Socket").WebSocketConstructor>;
+//# sourceMappingURL=OpencodeAgent.d.ts.map

package/OpencodeAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpencodeAgent.d.ts","sourceRoot":"","sources":["../src/OpencodeAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAI5C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAQ,SAAQ,KAAK,CAAC,OAAO;IAC5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAEpE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;KAAE,CAAA;IAEzD,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,eAAO,MAAM,IAAI,YAAa,OAAO,8OASlC,CAAA"}

package/OpencodeAgent.js

@@ -0,0 +1,83 @@
+/**
+ * opencode as an agent that hosts run: opencode 1, driven over its session API, which takes all of
+ * a turn: its instructions, as the system prompt of its prompt, an answer in JSON, the files of its
+ * prompt, the host's tools, and requests to compact. opencode works in the sandbox behind its
+ * bridge: the agent's template installs both there, and a session launches the bridge when none
+ * answers. One bridge and one opencode server serve every session that hosts start in a sandbox
+ * with the same options, whichever host started it; other options, such as another model, get a
+ * bridge and a server of their own. What runs in the sandbox is in `internal/bridge/v1/`.
+ *
+ * opencode runs on the model endpoints the agent is made with, which it is configured for.
+ * Their keys reach opencode in its configuration, in the sandbox, where the commands opencode runs
+ * can read them. The host's tools reach opencode as an MCP server the bridge serves on the
+ * sandbox's loopback, whose tools opencode names `host_<tool>`; the host runs them, and nothing
+ * they need reaches the sandbox.
+ *
+ * A session started on another agent is written into opencode as one message the model reads,
+ * since opencode 1 records no steps but its own. `Opencode2Agent`, over opencode 2's session API,
+ * records them as opencode's own, but does not answer in JSON yet.
+ *
+ * @since 0.1.0
+ */
+import * as internal from "./internal/agent.js";
+import { hostToolName } from "./internal/bridge/v1/session.js";
+/**
+ * The agent, which bundles the bridge program for its template when it is made, with `Bun.build`,
+ * so the host runs on Bun.
+ *
+ * **Details**
+ *
+ * The names of the host's tools fit in 59 characters, as `maxToolNameLength` says, since opencode
+ * puts `host_` before them. Each session reaches opencode through the bridge in its sandbox, with
+ * the `Crypto` and the `WebSocketConstructor` the agent is made with; the constructor must send
+ * headers, as Bun's and Node's do. Endpoints that opencode cannot serve together fail with
+ * `UnsupportedError`.
+ *
+ * **Example** (A turn of opencode in a new sandbox)
+ *
+ * ```ts
+ * import { createHmac } from "node:crypto"
+ * import { Agent, Harness } from "@amends-dev/harness"
+ * import { OpencodeAgent } from "@amends-dev/harness-opencode"
+ * import { SandboxProvider } from "@amends-dev/sandbox"
+ * import { BunServices, BunSocket } from "@effect/platform-bun"
+ * import { Config, Effect, Layer, Redacted } from "effect"
+ *
+ * declare const sandboxes: Layer.Layer<SandboxProvider.SandboxProvider> // a sandbox provider
+ *
+ * const program = Effect.gen(function* () {
+ *   // Every host derives a sandbox's bridge token from its id with a secret the hosts share.
+ *   const secret = yield* Config.Redacted("BRIDGE_SECRET")
+ *   const agent = yield* OpencodeAgent.make({
+ *     model: {
+ *       provider: "anthropic",
+ *       model: "claude-sonnet-5-5",
+ *       protocol: "anthropic-messages",
+ *       url: "https://api.anthropic.com/v1",
+ *       apiKey: yield* Config.Redacted("ANTHROPIC_API_KEY")
+ *     },
+ *     token: (sandboxId) =>
+ *       Redacted.make(createHmac("sha256", Redacted.value(secret)).update(sandboxId).digest("base64url"))
+ *   })
+ *   const harness = Harness.make(agent)
+ *   const sandboxProvider = yield* SandboxProvider.SandboxProvider
+ *   const sandbox = yield* sandboxProvider.createScoped({ template: harness.agent.template })
+ *   const session = yield* harness.createSession({ sandbox, id: Agent.SessionId.make("review") })
+ *   const answer = yield* session.generate({ prompt: "Summarize README.md" })
+ *   return answer.text
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(Layer.mergeAll(sandboxes, BunServices.layer, BunSocket.layerWebSocketConstructor))
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => internal.make({
+    id: "opencode",
+    version: 1,
+    // opencode names a host's tool after the MCP server that offers it, `host_<tool>`.
+    maxToolNameLength: 64 - hostToolName("").length
+}, options);
+//# sourceMappingURL=OpencodeAgent.js.map

package/OpencodeAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpencodeAgent.js","sourceRoot":"","sources":["../src/OpencodeAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAiC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAE,EAAE,CACvC,QAAQ,CAAC,IAAI,CACX;IACE,EAAE,EAAE,UAAU;IACd,OAAO,EAAE,CAAC;IACV,mFAAmF;IACnF,iBAAiB,EAAE,EAAE,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC,MAAM;CAChD,EACD,OAAO,CACR,CAAA"}

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# @amends-dev/harness-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 as an agent for the [`@amends-dev/harness`](../../packages/harness) contract. opencode
+works in the sandbox behind its bridge, a program the agent's template installs there with opencode
+itself: the bridge drives opencode's server, and hosts reach the bridge over a WebSocket on a port
+of the sandbox's. Nothing else of opencode is exposed outside the sandbox, and hosts that start
+sessions in a sandbox with the same options share its bridge and its server, whichever host
+launched them.
+
+opencode has two versions, each with a session API of its own, and the package has an agent for
+each:
+
+| Agent            | Runs                | Takes                                                                    |
+| ---------------- | ------------------- | ------------------------------------------------------------------------ |
+| `OpencodeAgent`  | opencode 1, 1.18.23 | all of a turn                                                            |
+| `Opencode2Agent` | opencode 2, 2.0.26  | all of a turn but an answer in JSON; records other agents' conversations |
+
+opencode 1 is the opencode most people run, from the npm package `opencode-ai`, and opencode 2 is
+its successor, from `@opencode/cli`, whose session API is still taking shape: `Opencode2Agent`
+follows it, taking more of a turn as opencode 2 does. Both agents give a turn its instructions,
+files, and the host's tools, ask the host about the permissions opencode's tools ask, and compact on
+request; they share everything but the opencode they run and the session API they drive.
+
+## Install
+
+```sh
+bun add @amends-dev/harness-opencode @amends-dev/harness @amends-dev/sandbox effect
+```
+
+Add a sandbox provider, such as [`@amends-dev/sandbox-local`](../sandbox-local) for this machine or
+[`@amends-dev/sandbox-daytona`](../sandbox-daytona). The host runs on Bun: `OpencodeAgent.make`
+bundles the bridge program with `Bun.build`. It needs Effect's `Crypto` and a
+`Socket.WebSocketConstructor` that sends headers, as `@effect/platform-bun` provides them.
+
+## Quick start
+
+`OpencodeAgent.make` makes the agent on a model endpoint and a `token` function, which derives
+each sandbox's bridge token from its id with a secret every host shares, so that every host
+connects to a bridge any of them launched. The caller creates each sandbox with the agent's
+`template`, which installs opencode and the bridge, and `Harness.make` runs the agent in it.
+
+```ts
+import { OpencodeAgent } from "@amends-dev/harness-opencode"
+import { Agent, Harness } from "@amends-dev/harness"
+import { SandboxProvider } from "@amends-dev/sandbox"
+import { BunServices, BunSocket } from "@effect/platform-bun"
+import { Config, Effect, Layer, Redacted } from "effect"
+import { createHmac } from "node:crypto"
+
+declare const sandboxes: Layer.Layer<SandboxProvider.SandboxProvider> // a sandbox provider
+
+const program = Effect.gen(function* () {
+  // Every host derives a sandbox's bridge token from its id with a secret the hosts share.
+  const secret = yield* Config.Redacted("BRIDGE_SECRET")
+  const agent = yield* OpencodeAgent.make({
+    model: {
+      provider: "anthropic",
+      model: "claude-sonnet-5-5",
+      protocol: "anthropic-messages",
+      url: "https://api.anthropic.com/v1",
+      apiKey: yield* Config.Redacted("ANTHROPIC_API_KEY")
+    },
+    token: (sandboxId) =>
+      Redacted.make(createHmac("sha256", Redacted.value(secret)).update(sandboxId).digest("base64url"))
+  })
+  const harness = Harness.make(agent)
+  const sandboxProvider = yield* SandboxProvider.SandboxProvider
+  const sandbox = yield* sandboxProvider.createScoped({ template: harness.agent.template })
+  const session = yield* harness.createSession({ sandbox, id: Agent.SessionId.make("review") })
+  const answer = yield* session.generate({ prompt: "Summarize README.md" })
+  return answer.text
+}).pipe(
+  Effect.scoped,
+  Effect.provide(Layer.mergeAll(sandboxes, BunServices.layer, BunSocket.layerWebSocketConstructor))
+)
+```
+
+`config` is opencode's configuration, as its `opencode.json` takes it, whose providers the models'
+replace: `provider` for `OpencodeAgent`, as opencode 1 names them, and `providers` for
+`Opencode2Agent`, as opencode 2 does. `env` is the environment variables opencode's server runs
+with. Both take effect when the bridge starts the server. All of the options, the keys included,
+name the bridge, so an agent made with other options gets a bridge and a server of its own in a
+sandbox, and never runs on another's. [`@amends-dev/harness`](../../packages/harness/README.md) says
+how sessions, turns, and releasing a session work, which these agents do as any agent does.
+`Opencode2Agent.make` takes the same options.
+
+## In the sandbox
+
+Each agent's template installs Bun 1.3.14 and its opencode in the sandbox's home, under
+`~/.amends/opencode/<programs>`, a directory named for their versions: opencode 1.18.23 from
+`opencode-<platform>` for `OpencodeAgent`, and opencode 2.0.26 from `@opencode/cli-<platform>` for
+`Opencode2Agent`. Each comes from its npm package for the sandbox's platform, macOS or Linux with
+glibc on arm64 or x64, which the sandbox downloads from npm and checks against the integrity pinned
+in the package. The agent's bridge program goes beside them as `bridge-<bundle>.js`, named for its
+contents. Preparing a sandbox needs `sh`, `uname`, `curl`, `tar`, `sha512sum` or `shasum`, and
+access to `registry.npmjs.org`. What the sandbox has already is kept: a sandbox whose home has the
+programs, such as every local sandbox after the first on this machine, gets only a new bridge
+program, and a sandbox from a snapshot of a prepared one is ready at once. The template's identity
+changes with the versions and the bundle; the programs and bridge programs of versions no host
+launches any more are not removed.
+
+A session launches the bridge, when none answers, with
+`sh -c 'exec "$HOME/…/bun" "$HOME/…/bridge-<bundle>.js"'`, giving it its launch options on
+standard input. It runs the template first, so that a sandbox a host of another version prepared
+gets this version's bridge program, and Bun and opencode if their versions changed. The bridge
+serves on a port the sandbox picks, which it writes to its state directory for hosts to find, and
+exits once it has been idle for ten minutes or another bridge takes its place.
+
+When the first session starts, the bridge starts opencode's server, `opencode serve`, on
+`127.0.0.1` at a free port it picks, behind a password it makes for that start and gives the
+server only in its environment. The server reads its configuration from a directory the bridge
+makes for it, which only the sandbox's user can read and which the bridge removes when the server
+stops, in place of the configuration under the sandbox user's home; a project's own configuration,
+in a session's directory, applies over it. A server that has not stopped 3 seconds after the
+bridge asks it to is killed. One server serves every session of the bridge, each in its own
+directory. A server that fails to start is started again by the next session; one that exits by
+itself takes the bridge with it, and the next session launches both again. A bridge that dies, as
+when it is killed, leaves its server running, still on the turn the bridge ran, beside the server
+the next bridge starts, and its configuration stays with it. The bridge also serves the host's
+tools to opencode as an MCP server on `127.0.0.1`, behind a token for each session. opencode keeps
+its data where it would for any user of the sandbox, under its home, unless `env` moves it, as with
+`XDG_DATA_HOME`.
+
+## Models
+
+The agents configure opencode for their endpoints. Each endpoint names its provider and model as
+opencode finds them in models.dev, which tells opencode the rest of the model, such as whether it
+calls tools. opencode takes a model that models.dev does not list as one that calls tools but reads
+no files. The configuration serves the model through the endpoint's protocol, at its URL, within its
+limits, and under its key and headers, and asks for the endpoint's effort in a variant of the model,
+which the turn's model names. opencode presents one key, with one set of headers, for each provider
+and serves a model one way, so endpoints that differ there fail `make` with `UnsupportedError`. The
+keys and headers reach opencode in its configuration in the sandbox, where the commands opencode
+runs can read them.
+
+opencode 1 takes a model's output limit only with its context window. An endpoint with an output
+limit gives its context window too, or 0 when it has none, which opencode takes as unknown and
+compacts nothing by itself. An endpoint without an output limit leaves both limits to models.dev.
+opencode 1 writes at most 32,000 tokens in a response unless its server is told otherwise, so
+`OpencodeAgent` raises that ceiling to the highest output limit of its endpoints. opencode 2 takes
+each limit apart, over what models.dev says, and writes as many tokens as the output limit allows.
+
+## Sessions and turns
+
+Each session is an opencode session, and the agent's state names it. A session whose opencode
+session is still there continues it; one that starts in a sandbox whose opencode has no record of
+it, such as one that started on another agent, starts a new opencode session from the
+conversation. Destroying a session deletes it in opencode, and a turn the bridge aborts is
+interrupted there.
+
+### `OpencodeAgent`
+
+A turn is a prompt to the session, on the model the turn names, with the turn's instructions as
+its system prompt, the schema of an answer in JSON, and the prompt's files, which reach opencode
+as data URLs or as the URLs they are. The events opencode publishes for the turn become the
+harness's stream parts as they happen: text and reasoning stream as opencode writes them, a tool's
+input streams whole once the tool runs, and opencode's own tools run inside opencode, so their
+calls and results are `providerExecuted`. A file that opencode's `write` or `edit` tool changes is
+a `file-change` part, with its path relative to the session's directory. An answer in JSON is the
+text of the last step.
+
+The host's tools reach opencode through the bridge's MCP server, which opencode names `host`, so
+it calls a tool `host_<tool>`: the names of the host's tools fit in 59 characters, as the agent's
+`maxToolNameLength` says. The calls stream as the host's, which the host answers, and opencode
+lists the tools again when a turn's tools change. A tool of opencode's own that asks permission,
+as opencode's `permission` configuration says, streams a `tool-approval-request` and waits for
+the host's answer. opencode does not ask the user questions in a turn: its `question` tool is off,
+and a question asked anyway is refused.
+
+`compact` asks opencode to summarize the conversation, on the model of its last step, and returns
+the summary; opencode summarizes without instructions, so instructions fail with
+`UnsupportedError`. opencode also compacts by itself when a turn nears the model's context window,
+which streams as a `compaction` part. A conversation from another agent is written into the new
+opencode session as one message the model reads with the first prompt, the files of its user
+messages beside it, since opencode 1 records no steps but its own.
+
+### `Opencode2Agent`
+
+A turn is a prompt to the session, with the prompt's files as `data:` URLs, after the session is
+given the turn's model and instructions: opencode 2 keeps instructions as an entry of the session's
+own, which the model reads beside opencode's, and which the agent replaces or removes when a turn
+gives others or none. The events opencode publishes for the turn become the harness's stream parts
+as they happen, as for `OpencodeAgent`: text, reasoning, and a tool's input stream as opencode
+writes them, opencode's own tools are `providerExecuted`, and a file that opencode's `write`,
+`edit`, or `patch` tool changes is a `file-change` part.
+
+The host's tools reach opencode 2 through the same MCP server, which opencode 2's model calls from
+code it runs, in its own tool, before the relay streams the call as the host's. When a turn's tools
+change, it waits until opencode has connected to the server, and then half a second more: opencode 2
+gives its turns a server's new tools 100 milliseconds after they change, and does not say when it
+has. A tool that asks permission, as opencode's `permissions` configuration says, streams a
+`tool-approval-request`, and a form the model asks the user to fill is cancelled. `compact` asks
+opencode to summarize the conversation and returns the summary, without instructions. A
+conversation from another agent is imported as the new session's own record, tool calls included,
+with the files of its user messages.
+
+opencode 2's session API does not answer in JSON yet, which fails with `UnsupportedError`, and reads
+a prompt's files only as data, so a file at an `http` URL fails the same way. It does not keep a
+session's events where a client can read them again, so a turn the bridge did not finish is not
+continued from where opencode got to.
+
+## Errors
+
+The agents' operations fail with `HarnessError`, naming the agent `opencode` or `opencode2`:
+`UnsupportedError` for what opencode cannot do, a turn that names a model the agent has none of, or
+endpoints opencode cannot serve together; `UnavailableError` when its server cannot be reached,
+exits, does not listen in time, asks to be retried, or does not connect to the host's tools;
+`NotFoundError` for what the server has no record of; `AgentContractError` for state or events the
+agent cannot read; and `UnknownError` for the rest.
+
+## Development
+
+Run the package's tests with `bun run test adapters/harness-opencode`: each agent's sessions against
+a fake of opencode's server, scripted turn by turn, and the translation of its events and
+conversations, under `test/v1` and `test/v2`; the server and the bridge program as real processes,
+with `test/fake-opencode-server.js` standing in for `opencode serve`; the bridge launched by
+`BridgeClient` in a sandbox on this machine and reached over a WebSocket; and the template with its
+commands answered as a sandbox would answer them. With `AMENDS_TEST_OPENCODE=1`, the live tests run
+`opencode` and `opencode2` from this machine's `PATH` under the agents, whose turns OpenCode Zen's
+free model answers. See [testing](../../docs/testing.md).
+`bun run dist check adapters/harness-opencode` builds the package as npm gets it and checks it as a
+consumer; see [publishing](../../docs/publishing.md).

package/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * opencode as an agent for the `@amends-dev/harness` contract, working in a sandbox behind its
+ * bridge, which the agent's template installs there with opencode itself. opencode has two
+ * versions, each with a session API of its own, and the package an agent for each: `OpencodeAgent`
+ * runs opencode 1, which takes everything a turn gives, and `Opencode2Agent` runs opencode 2, which
+ * records a session started on another agent as its own but does not answer in JSON yet.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @since 0.1.0
+ */
+export * as Opencode2Agent from "./Opencode2Agent.ts";
+/**
+ * @since 0.1.0
+ */
+export * as OpencodeAgent from "./OpencodeAgent.ts";
+//# sourceMappingURL=index.d.ts.map