@weaveio/weave-adapter-opencode 0.0.0-preview-20260708084849

package/dist/model-resolution.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Adapter-local model resolution for the OpenCode adapter.
+ *
+ * This module gathers OpenCode model context (available models, UI-selected
+ * model, system default) and calls `resolveAdapterModelIntent()` from
+ * `@weaveio/weave-engine` to produce a validated model selection for each agent.
+ *
+ * ## Design
+ *
+ * - Model discovery is adapter-owned: this module is the only place that
+ *   queries OpenCode for available models.
+ * - `resolveAdapterModelIntent()` is engine-owned: it applies the priority
+ *   chain (override → ui-selected → category → agent → system-default →
+ *   constant-fallback) without querying harness state itself.
+ * - Explicit subagent model intent fails fast when the requested model is not
+ *   in the available set. This prevents silent fallback to an unintended model
+ *   when the user has declared a specific model preference.
+ *
+ * ## Fail-fast rule for explicit subagent models
+ *
+ * When an agent's `mode` is `"subagent"` and `agentModels` is non-empty, the
+ * first declared model must be available. If it is not, `resolveModelForAgent`
+ * returns `err(ModelNotAvailableError)` rather than falling back silently.
+ *
+ * This rule is intentionally strict: subagents are typically invoked
+ * programmatically with a specific model in mind, and silent fallback would
+ * produce unexpected behavior that is hard to debug.
+ *
+ * Boundary rule: this module imports engine types only through `@weaveio/weave-engine`
+ * and SDK types only through `./sdk-types`. It must not import directly from
+ * `@opencode-ai/sdk`.
+ */
+import type { AgentDescriptor } from "@weaveio/weave-engine";
+import { type Result } from "neverthrow";
+/**
+ * Discriminated union of errors that model resolution can return.
+ */
+export type ModelResolutionError = {
+    /**
+     * The agent declared an explicit model preference but none of the
+     * declared models are available in the current OpenCode instance.
+     *
+     * This is a hard error for subagent mode — silent fallback is not
+     * permitted when the user has declared explicit model intent.
+     */
+    type: "ModelNotAvailableError";
+    agentName: string;
+    requestedModels: string[];
+    availableModels: string[];
+    message: string;
+} | {
+    /**
+     * The model resolution input was structurally invalid.
+     */
+    type: "ModelResolutionInputError";
+    agentName: string;
+    message: string;
+};
+/**
+ * Adapter-provided OpenCode model context.
+ *
+ * Adapters gather this context from the OpenCode runtime (e.g. via
+ * `client.app.providers()`) and pass it to `resolveModelForAgent()`.
+ * The engine never queries harness state directly.
+ */
+export interface OpenCodeModelContext {
+    /**
+     * Set of model IDs available in the current OpenCode instance.
+     *
+     * Gathered from the OpenCode provider/model list. When `undefined`, model
+     * availability filtering is skipped and any declared model is accepted.
+     */
+    availableModels?: Set<string>;
+    /**
+     * The model currently selected in the OpenCode UI, if the adapter can
+     * supply one.
+     *
+     * Passed as `uiSelectedModel` to `resolveAdapterModelIntent()`. Ignored for
+     * `subagent` mode agents (per engine resolution rules).
+     */
+    uiSelectedModel?: string;
+    /**
+     * The harness/system default model.
+     *
+     * Passed as `systemDefault` to `resolveAdapterModelIntent()`. Used when no
+     * agent preference, category preference, or UI selection is available.
+     */
+    systemDefault?: string;
+}
+/**
+ * Resolve the model for a single agent descriptor using OpenCode model context.
+ *
+ * Calls `resolveAdapterModelIntent()` with the adapter-provided context and
+ * applies the fail-fast rule for explicit subagent model intent.
+ *
+ * ## Fail-fast rule
+ *
+ * When `descriptor.mode === "subagent"` and `descriptor.models` is non-empty,
+ * the first declared model must be present in `context.availableModels`. If it
+ * is not, this function returns `err(ModelNotAvailableError)`.
+ *
+ * This rule only applies when `context.availableModels` is defined. When the
+ * available model set is unknown (undefined), the declared model is accepted
+ * without availability filtering.
+ *
+ * @param descriptor - The normalized agent descriptor from the engine.
+ * @param context - Adapter-provided OpenCode model context.
+ * @returns `ok(resolvedModel)` on success, or `err(ModelResolutionError)` when
+ *   explicit subagent model intent cannot be satisfied.
+ */
+export declare function resolveModelForAgent(descriptor: AgentDescriptor, context: OpenCodeModelContext): Result<string, ModelResolutionError>;
+//# sourceMappingURL=model-resolution.d.ts.map

package/dist/model-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-resolution.d.ts","sourceRoot":"","sources":["../src/model-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAMlD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE;;;;;;OAMG;IACH,IAAI,EAAE,wBAAwB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,2BAA2B,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAMN;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE9B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAqCtC"}

package/dist/opencode-client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Adapter-local OpenCode client facade.
+ *
+ * This module defines the narrow `OpenCodeClientFacade` interface that the
+ * adapter uses to interact with a running OpenCode instance. All SDK-backed
+ * agent list/create/update operations flow through this interface so that the
+ * exact SDK method names and shapes remain adapter-local and can evolve
+ * without changing engine-facing contracts.
+ *
+ * Boundary rule: this module imports SDK types only through `./sdk-types`.
+ * It must not import directly from `@opencode-ai/sdk`.
+ *
+ * Design notes:
+ * - `listAgents()` returns the live agent list from the running OpenCode
+ *   instance via `client.app.agents()`.
+ * - `createAgent(name, config)` and `updateAgent(name, config)` both write
+ *   through `client.config.update()` by patching the `agent` map in the
+ *   current config. OpenCode has no separate create/update agent endpoint;
+ *   both operations are expressed as a config patch.
+ * - The facade does not perform reconciliation logic — that belongs in
+ *   `reconcile-agent.ts` (task 3). The facade only wraps the raw SDK calls.
+ */
+import { ResultAsync } from "neverthrow";
+import type { OpenCodeAgent, OpenCodeAgentConfig, OpencodeClient } from "./sdk-types.js";
+/**
+ * Discriminated union of errors that `OpenCodeClientFacade` methods can return.
+ */
+export type OpenCodeClientError = {
+    type: "ListAgentsError";
+    message: string;
+    cause?: unknown;
+} | {
+    type: "CreateAgentError";
+    agentName: string;
+    message: string;
+    cause?: unknown;
+} | {
+    type: "UpdateAgentError";
+    agentName: string;
+    message: string;
+    cause?: unknown;
+};
+/**
+ * Narrow adapter-local interface for OpenCode agent operations.
+ *
+ * Implementations wrap the `OpencodeClient` SDK calls needed for agent
+ * materialization. Tests provide a mock implementation without a live
+ * OpenCode runtime.
+ */
+export interface OpenCodeClientFacade {
+    /**
+     * Returns the current list of agents known to the running OpenCode instance.
+     *
+     * Corresponds to `client.app.agents()`.
+     */
+    listAgents(): ResultAsync<OpenCodeAgent[], OpenCodeClientError>;
+    /**
+     * Creates a new agent in the running OpenCode instance by patching the
+     * config's `agent` map with the provided config under `name`.
+     *
+     * Corresponds to a `client.config.update()` call that merges `{ agent: { [name]: config } }`.
+     *
+     * @param name - The canonical agent name (used as the config map key).
+     * @param config - The translated OpenCode agent config to write.
+     */
+    createAgent(name: string, config: OpenCodeAgentConfig): ResultAsync<void, OpenCodeClientError>;
+    /**
+     * Updates an existing Weave-managed agent in the running OpenCode instance
+     * by patching the config's `agent` map.
+     *
+     * Semantically identical to `createAgent` at the SDK level — both write
+     * through `config.update()`. The distinction exists at the reconciliation
+     * layer (`reconcile-agent.ts`) where ownership is verified before calling
+     * this method.
+     *
+     * @param name - The canonical agent name (used as the config map key).
+     * @param config - The updated OpenCode agent config to write.
+     */
+    updateAgent(name: string, config: OpenCodeAgentConfig): ResultAsync<void, OpenCodeClientError>;
+}
+/**
+ * SDK-backed implementation of `OpenCodeClientFacade`.
+ *
+ * Wraps an injected `OpencodeClient` instance. Constructed by the adapter
+ * during `init()` when a real SDK client is available.
+ */
+export declare class SdkOpenCodeClient implements OpenCodeClientFacade {
+    private readonly client;
+    constructor(client: OpencodeClient);
+    listAgents(): ResultAsync<OpenCodeAgent[], OpenCodeClientError>;
+    createAgent(name: string, config: OpenCodeAgentConfig): ResultAsync<void, OpenCodeClientError>;
+    updateAgent(name: string, config: OpenCodeAgentConfig): ResultAsync<void, OpenCodeClientError>;
+}
+//# sourceMappingURL=opencode-client.d.ts.map

package/dist/opencode-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-client.d.ts","sourceRoot":"","sources":["../src/opencode-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAW,WAAW,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAMxB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAMN;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,UAAU,IAAI,WAAW,CAAC,aAAa,EAAE,EAAE,mBAAmB,CAAC,CAAC;IAEhE;;;;;;;;OAQG;IACH,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,GAC1B,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IAE1C;;;;;;;;;;;OAWG;IACH,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,GAC1B,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;CAC3C;AAMD;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD,UAAU,IAAI,WAAW,CAAC,aAAa,EAAE,EAAE,mBAAmB,CAAC;IAkB/D,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,GAC1B,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAoBzC,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,GAC1B,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC;CAmB1C"}

package/dist/plugin.d.ts

@@ -0,0 +1,184 @@
+/**
+ * OpenCode plugin entry point for `@weaveio/weave-adapter-opencode`.
+ *
+ * This module exports the `Plugin` function that OpenCode loads at startup
+ * when `@weaveio/weave-adapter-opencode` is listed in the `plugin` array of
+ * `opencode.json`. It is the primary runtime integration surface between
+ * Weave and OpenCode.
+ *
+ * ## How it works
+ *
+ * 1. OpenCode calls the exported `server` function (the `Plugin`) with a
+ *    `PluginInput` context that includes a pre-constructed SDK client and the
+ *    project directory.
+ * 2. The plugin loads the Weave config from `input.directory` via
+ *    `loadConfig()`.
+ * 3. It calls `materializeAgents()` to compose all agent descriptors from the
+ *    resolved config.
+ * 4. It translates each descriptor into an `OpenCodeAgentConfig` via
+ *    `translateAgent()` and collects the results into a `translatedMap`.
+ * 5. It returns a `Hooks` object **immediately** with two hooks:
+ *    a. **`config` hook** — injects the translated agent configs into
+ *       `cfg.agent` so that `opencode debug config` reflects all Weave-managed
+ *       agents. This runs once at startup before OpenCode finalises its config.
+ *    b. **`event` hook** — listens for the first `session.created` event and
+ *       then performs SDK-backed reconciliation (`adapter.init()` +
+ *       `spawnSubagent()`) exactly once per plugin activation. This defers the
+ *       SDK/DB path to real session time, so `opencode debug config` is never
+ *       blocked by runtime SDK calls.
+ *
+ * ## Why deferred SDK reconciliation?
+ *
+ * `opencode debug config` calls the plugin function and waits for `Hooks` to
+ * be returned. In the previous design, `adapter.init()` and `spawnSubagent()`
+ * were called eagerly before `Hooks` was returned. Both operations touch the
+ * OpenCode SDK / DB path (`client.app.agents()`, `config.update()`), which
+ * hangs in the `debug config` context because the runtime store is not
+ * available.
+ *
+ * The fix: config loading and agent translation are pure computation (no SDK
+ * calls). `Hooks` is returned immediately after translation. SDK reconciliation
+ * is deferred to the `event` hook, which only fires during a real OpenCode
+ * session — never during `debug config`.
+ *
+ * ## Why both paths?
+ *
+ * The `config` hook and the SDK-backed reconciliation serve different purposes:
+ *
+ * - The `config` hook makes agents visible to `opencode debug config` and to
+ *   any OpenCode subsystem that reads the merged config at startup. It is
+ *   purely additive — it does not persist agents across restarts.
+ * - The SDK-backed reconciliation (`spawnSubagent`) writes agents into
+ *   OpenCode's runtime store via `client.config.update()`. This is the
+ *   durable path that survives config reloads and is the source of truth for
+ *   what OpenCode actually uses at runtime.
+ *
+ * Both paths are required for full materialization: the `config` hook for
+ * observability and startup-time config visibility, and the SDK path for
+ * runtime persistence and ownership-safe upsert.
+ *
+ * ## Installation
+ *
+ * Add `@weaveio/weave-adapter-opencode/plugin` to the `plugin` array in `opencode.json`.
+ * Use the subpath export — **not** the bare package name:
+ *
+ * ```jsonc
+ * // opencode.json
+ * {
+ *   "plugin": ["@weaveio/weave-adapter-opencode/plugin"]
+ * }
+ * ```
+ *
+ * The bare `@weaveio/weave-adapter-opencode` entry (`dist/index.js`) exports non-function
+ * values (constants, type re-exports) that cause OpenCode's `getLegacyPlugins`
+ * loader to throw `TypeError: Plugin export is not a function`. This module
+ * (`dist/plugin.js`) exports only the plugin function and is the correct entry
+ * point for OpenCode.
+ *
+ * Restart OpenCode after adding the plugin. The plugin entry point receives
+ * the runtime context, constructs an `OpenCodeAdapter` with the injected SDK
+ * client, and materializes all agents declared in `.weave/config.weave`.
+ *
+ * ## Boundary rules
+ *
+ * - The plugin entry point is the only place that imports from
+ *   `@opencode-ai/plugin`. All other adapter modules remain plugin-agnostic.
+ * - The `PluginInput.client` is injected into `SdkOpenCodeClient` — the
+ *   adapter never constructs its own SDK client.
+ * - Config loading and agent materialization follow the same path as any
+ *   other adapter consumer: `loadConfig → materializeAgents → spawnSubagent`.
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+import { type FileReader } from "@weaveio/weave-config";
+import { type OpenCodeClientFacade } from "./opencode-client.js";
+/**
+ * Options for `createWeavePlugin`.
+ *
+ * All fields are optional. In production, the defaults are used. In tests,
+ * pass a custom `fileReader` and/or `clientFacade` to isolate the test from
+ * the developer's environment.
+ */
+export interface WeavePluginOptions {
+    /**
+     * Custom file reader for config loading.
+     *
+     * In production, the default `bunFileReader` is used. In tests, pass a
+     * `projectOnlyReader` to prevent the developer's global config from
+     * interfering with test results.
+     *
+     * @example
+     * ```ts
+     * const plugin = createWeavePlugin({ fileReader: projectOnlyReader(root) });
+     * const hooks = await plugin(input);
+     * ```
+     */
+    readonly fileReader?: FileReader;
+    /**
+     * Pre-constructed `OpenCodeClientFacade` to use instead of wrapping
+     * `input.client` in `SdkOpenCodeClient`.
+     *
+     * In production, this is always `undefined` — the plugin wraps `input.client`
+     * (the raw SDK client) in `SdkOpenCodeClient`. In tests, pass a
+     * `MockOpenCodeClient` here to avoid needing a real SDK client.
+     *
+     * @example
+     * ```ts
+     * const mockClient = new MockOpenCodeClient();
+     * const plugin = createWeavePlugin({ clientFacade: mockClient });
+     * const hooks = await plugin(input);
+     * ```
+     */
+    readonly clientFacade?: OpenCodeClientFacade;
+}
+/**
+ * Creates a Weave OpenCode plugin with optional configuration.
+ *
+ * Returns a `Plugin` function that OpenCode can load at startup. In
+ * production, call `createWeavePlugin()` with no arguments (or use the
+ * pre-built `WeavePlugin` export). In tests, pass a custom `fileReader` to
+ * isolate the test from the developer's global `~/.weave/config.weave`.
+ *
+ * The returned plugin function:
+ * 1. Loads Weave config and translates agent descriptors (pure computation).
+ * 2. Returns `Hooks` **immediately** — never blocks on SDK/DB calls.
+ * 3. Defers `adapter.init()` + `spawnSubagent()` to the `event` hook, which
+ *    fires on the first `session.created` event during a real OpenCode session.
+ *
+ * This design ensures `opencode debug config` returns quickly because it only
+ * exercises the `config` hook path, never the deferred SDK reconciliation path.
+ *
+ * @param options - Optional plugin configuration.
+ * @returns A `Plugin` function compatible with `@opencode-ai/plugin`.
+ */
+export declare function createWeavePlugin(options?: WeavePluginOptions): Plugin;
+/**
+ * Weave OpenCode plugin.
+ *
+ * Loaded by OpenCode at startup when `@weaveio/weave-adapter-opencode` is listed in
+ * the `plugin` array of `opencode.json`. Materializes all agents declared in
+ * `.weave/config.weave` into the running OpenCode instance.
+ *
+ * Returns a `Hooks` object **immediately** with:
+ * - `config` hook — injects translated agent configs into `cfg.agent` so that
+ *   `opencode debug config` shows all Weave-managed agents.
+ * - `event` hook — defers SDK-backed reconciliation (`spawnSubagent`) to the
+ *   first `session.created` event, ensuring `opencode debug config` never
+ *   blocks on SDK/DB calls.
+ *
+ * @param input - Runtime context provided by OpenCode, including the SDK
+ *   client and the project directory.
+ * @returns A `Hooks` object with `config` and `event` hooks on success, or an
+ *   empty `Hooks` object when config loading fails.
+ */
+export declare const WeavePlugin: Plugin;
+/**
+ * Named `server` export for `PluginModule` compatibility.
+ *
+ * OpenCode resolves plugins as `PluginModule` objects with a `server` property.
+ * When the module's default export is a function, OpenCode also accepts it
+ * directly as the plugin. Both forms are exported here for maximum
+ * compatibility.
+ */
+export declare const server: Plugin;
+export default WeavePlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AAGH,OAAO,KAAK,EAAS,MAAM,EAAe,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,uBAAuB,CAAC;AAepE,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IAEjC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CA6P1E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,EAAE,MAA4B,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,QAAc,CAAC;AAElC,eAAe,WAAW,CAAC"}