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

package/dist/projection-helpers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Projection Helpers — adapter-internal shared utilities.
+ *
+ * Provides the two helpers that are shared across the OpenCode adapter's
+ * projection modules:
+ *
+ * - `buildProjectEffect` — builds the adapter-owned `projectEffect` callback
+ *   that calls `adapter.spawnSubagent` for each `DispatchAgentEffect`.
+ * - `deriveRunWorkflowResult` — maps `ExecutionStartedData`-shaped data to
+ *   the adapter-owned `RunWorkflowResult` discriminated union.
+ *
+ * ## Boundary rule
+ *
+ * This module is adapter-internal. It must not be imported by engine packages.
+ * It exists solely to eliminate duplication across `run-workflow.ts`,
+ * `start-plan-execution.ts`, and `runtime-command-projection.ts`.
+ *
+ * @see packages/adapters/opencode/src/run-workflow.ts
+ * @see packages/adapters/opencode/src/start-plan-execution.ts
+ * @see packages/adapters/opencode/src/runtime-command-projection.ts
+ * @see docs/adapter-boundary.md
+ */
+import type { DispatchAgentEffect, WorkflowRunnerError } from "@weaveio/weave-engine";
+import type { ResultAsync } from "neverthrow";
+import type { OpenCodeAdapter } from "./adapter.js";
+import type { RunWorkflowResult } from "./run-workflow.js";
+/**
+ * Build the adapter-owned `projectEffect` callback for engine operations.
+ *
+ * The callback calls `adapter.spawnSubagent` for each `DispatchAgentEffect`
+ * emitted by the engine's workflow runner. On failure, maps
+ * `OpenCodeAdapterError` to `WorkflowRunnerError` so the engine can propagate
+ * it as a typed `projection_error`.
+ *
+ * This is adapter-owned — the engine never calls `spawnSubagent` directly.
+ *
+ * @param adapter - The OpenCode adapter instance.
+ * @returns A `projectEffect` callback suitable for engine operation calls.
+ */
+export declare function buildProjectEffect(adapter: OpenCodeAdapter): (effect: DispatchAgentEffect) => ResultAsync<void, WorkflowRunnerError>;
+/**
+ * Derive a `RunWorkflowResult` from the engine's `ExecutionStartedData`.
+ *
+ * `ExecutionStartedData.effects` carries all lifecycle effects emitted during
+ * the run. We derive:
+ * - `status`: "paused" if a `pause-execution` effect is present, else "completed".
+ * - `stepsDispatched`: count of `dispatch-agent` effects.
+ * - `appliedEffects`: all effects (forwarded as-is).
+ *
+ * @param data - Execution data with a `workflowInstanceId` and `effects` array.
+ * @returns A normalized `RunWorkflowResult`.
+ */
+export declare function deriveRunWorkflowResult(data: {
+    readonly workflowInstanceId: string;
+    readonly effects: readonly {
+        readonly kind: string;
+    }[];
+}): RunWorkflowResult;
+//# sourceMappingURL=projection-helpers.d.ts.map

package/dist/projection-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-helpers.d.ts","sourceRoot":"","sources":["../src/projection-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQ3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,GACvB,CAAC,MAAM,EAAE,mBAAmB,KAAK,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAkBzE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxD,GAAG,iBAAiB,CAYpB"}

package/dist/reconcile-agent.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Adapter-local reconciliation logic for Weave-managed OpenCode agents.
+ *
+ * This module encapsulates the `list existing → reconcile decision →
+ * create/update call` flow that `spawnSubagent()` uses to materialize a Weave
+ * agent into a running OpenCode instance.
+ *
+ * ## Reconciliation flow
+ *
+ * ```
+ * 1. listAgents()          — fetch the current agent list from OpenCode
+ * 2. find by name          — look for an existing agent whose name matches
+ *                            descriptor.name (the Canonical Agent Name)
+ * 3. ownership check       — if found, verify the agent is Weave-managed
+ *                            (presence of WEAVE_OWNERSHIP_TAG in description)
+ * 4. create or update      — call createAgent() for new agents, updateAgent()
+ *                            for existing Weave-managed agents
+ * 5. collision error       — return ReconcileCollisionError when a same-named
+ *                            foreign agent is found (no forced takeover)
+ * ```
+ *
+ * ## Ownership marker
+ *
+ * Weave marks every agent it creates by embedding `WEAVE_OWNERSHIP_TAG` in the
+ * agent's `description` field. This is a lightweight, human-readable signal
+ * that lets the reconciler distinguish Weave-managed agents from manually
+ * created ones without requiring a separate metadata store.
+ *
+ * The tag is appended to the description when the agent is first created and
+ * checked on every subsequent reconciliation pass. Agents without the tag are
+ * treated as foreign and protected from overwrite.
+ *
+ * ## First-slice constraints
+ *
+ * - Upsert-only: no automatic delete, prune, or forced takeover.
+ * - Collision errors are returned as typed `Result` values — callers decide
+ *   how to surface them.
+ *
+ * Boundary rule: this module imports SDK types only through `./sdk-types` and
+ * the client facade only through `./opencode-client`. It must not import
+ * directly from `@opencode-ai/sdk`.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { OpenCodeClientFacade } from "./opencode-client.js";
+import type { OpenCodeAgent, OpenCodeAgentConfig } from "./sdk-types.js";
+/**
+ * Ownership tag embedded in the `description` of every Weave-managed agent.
+ *
+ * The tag is a short, human-readable string that signals to the reconciler
+ * (and to human operators) that the agent was created by Weave. It is
+ * intentionally visible in the OpenCode UI so users know which agents are
+ * managed by Weave.
+ */
+export declare const WEAVE_OWNERSHIP_TAG = "[weave-managed]";
+/**
+ * Discriminated union of errors that `reconcileAgent` can return.
+ */
+export type ReconcileAgentError = {
+    /** Listing the current OpenCode agents failed. */
+    type: "ListAgentsError";
+    message: string;
+    cause?: unknown;
+} | {
+    /** Creating a new agent in OpenCode failed. */
+    type: "CreateAgentError";
+    agentName: string;
+    message: string;
+    cause?: unknown;
+} | {
+    /** Updating an existing Weave-managed agent in OpenCode failed. */
+    type: "UpdateAgentError";
+    agentName: string;
+    message: string;
+    cause?: unknown;
+} | {
+    /**
+     * A same-named agent exists in OpenCode but is not Weave-managed.
+     * Weave refuses to overwrite it without explicit ownership.
+     */
+    type: "CollisionError";
+    agentName: string;
+    message: string;
+};
+/**
+ * The decision produced by `classifyExistingAgent`.
+ *
+ * - `"create"` — no existing agent with this name; create a new one.
+ * - `"update"` — an existing Weave-managed agent was found; update it.
+ * - `"collision"` — a same-named foreign agent was found; refuse to overwrite.
+ */
+export type ReconcileDecision = "create" | "update" | "collision";
+/**
+ * Classifies the reconciliation decision for a given agent name against the
+ * current OpenCode agent list.
+ *
+ * @param agentName - The Canonical Agent Name to look up.
+ * @param existingAgents - The current list of agents from OpenCode.
+ * @returns The reconciliation decision.
+ */
+export declare function classifyExistingAgent(agentName: string, existingAgents: OpenCodeAgent[]): ReconcileDecision;
+/**
+ * Returns a copy of `config` with `WEAVE_OWNERSHIP_TAG` appended to the
+ * `description` field.
+ *
+ * The tag is appended only when it is not already present, so calling this
+ * function on an already-tagged config is idempotent.
+ *
+ * @param config - The translated OpenCode agent config.
+ * @returns A new config object with the ownership tag in `description`.
+ */
+export declare function tagWithOwnership(config: OpenCodeAgentConfig): OpenCodeAgentConfig;
+/**
+ * Reconciles a translated OpenCode agent config against the current OpenCode
+ * agent list, then creates or updates the agent via the injected client.
+ *
+ * ## Flow
+ *
+ * 1. Call `client.listAgents()` to fetch the current agent list.
+ * 2. Classify the reconciliation decision using `classifyExistingAgent`.
+ * 3. Tag the config with `WEAVE_OWNERSHIP_TAG` before writing.
+ * 4. Call `client.createAgent()` or `client.updateAgent()` based on the
+ *    decision.
+ * 5. Return `err(CollisionError)` when a foreign agent blocks the write.
+ *
+ * @param agentName - The Canonical Agent Name (matches `descriptor.name`).
+ * @param config - The translated OpenCode agent config to materialize.
+ * @param client - The injected `OpenCodeClientFacade` to use for SDK calls.
+ * @returns `ok(void)` on success, or `err(ReconcileAgentError)` on failure.
+ */
+export declare function reconcileAgent(agentName: string, config: OpenCodeAgentConfig, client: OpenCodeClientFacade): ResultAsync<void, ReconcileAgentError>;
+//# sourceMappingURL=reconcile-agent.d.ts.map

package/dist/reconcile-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-agent.d.ts","sourceRoot":"","sources":["../src/reconcile-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAEV,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAMzE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAMrD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IACE,kDAAkD;IAClD,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACD;IACE,+CAA+C;IAC/C,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACD;IACE,mEAAmE;IACnE,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAMN;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,aAAa,EAAE,GAC9B,iBAAiB,CASnB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,mBAAmB,GAC1B,mBAAmB,CAUrB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,oBAAoB,GAC3B,WAAW,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAkCxC"}

package/dist/run-workflow.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Explicit named-workflow execution loop for the OpenCode adapter.
+ *
+ * `runWorkflow` is the adapter-owned helper for **explicit named-workflow
+ * execution** — the path where a caller (command handler, script, or
+ * user-authorized trigger) names a specific workflow declared in
+ * `.weave/config.weave` and requests that it run end-to-end.
+ *
+ * This is distinct from ordinary Loom-led usage (the `/weave:start` path),
+ * which is plan-first and does not require the caller to name a workflow.
+ * `runWorkflow` is never called from idle hooks, session events, or
+ * continuation hooks — it requires explicit, user-authorized invocation.
+ *
+ * ## Delegation to shared engine operation
+ *
+ * `runWorkflow` delegates lifecycle semantics to the engine's reusable
+ * `runNamedWorkflow` command operation. The adapter supplies a `projectEffect`
+ * callback that calls `adapter.spawnSubagent` for each `DispatchAgentEffect`
+ * emitted by the engine. The engine never applies harness-specific behavior.
+ *
+ * ## Execution lifecycle (engine-owned)
+ *
+ *   1. `startExecution`  — acquire lease, create/update WorkflowInstance
+ *   2. `dispatchStep`    — resolve next step, emit DispatchAgentEffect
+ *   3. Project effects   — call `projectEffect` (→ `adapter.spawnSubagent`)
+ *   4. `completeStep`    — record step completion, advance to next step or finish
+ *
+ * The loop continues until a `complete-execution` or `pause-execution` effect
+ * is emitted, or until an error is returned.
+ *
+ * Boundary rule: this module calls the engine's `runNamedWorkflow` operation
+ * and the adapter interface. It must not import directly from `@opencode-ai/sdk`.
+ *
+ * @see docs/adapter-boundary.md — Execution Lifecycle Surface section
+ * @see start-plan-execution.ts — the `/weave:start` ordinary-usage path
+ * @see packages/engine/src/runtime-command-operations/run-named-workflow.ts
+ */
+import type { WeaveConfig } from "@weaveio/weave-core";
+import type { LifecycleEffect, LifecycleError, PlanStateProvider, RuntimeStore } from "@weaveio/weave-engine";
+import type { ResultAsync } from "neverthrow";
+import type { OpenCodeAdapter } from "./index.js";
+/**
+ * Discriminated union of errors that `runWorkflow` can return.
+ */
+export type RunWorkflowError = {
+    readonly type: "LifecycleError";
+    readonly cause: LifecycleError;
+} | {
+    readonly type: "WorkflowNotFound";
+    readonly workflowName: string;
+} | {
+    readonly type: "MaxStepsExceeded";
+    readonly maxSteps: number;
+};
+/**
+ * Input for `runWorkflow`.
+ *
+ * Provides everything the execution loop needs:
+ * - `config`        — the full WeaveConfig containing workflow definitions
+ * - `workflowName`  — the name of the workflow to execute
+ * - `goal`          — human-readable goal for this execution instance
+ * - `slug`          — URL-safe slug derived from the goal
+ * - `adapter`       — the OpenCode adapter instance (for `spawnSubagent`)
+ * - `store`         — the Runtime Store (defaults to a fresh InMemoryRuntimeStore)
+ * - `planStateProvider` — optional plan state provider for plan_created/plan_complete steps
+ * - `ownerId`       — owner identifier for the execution lease (defaults to "run-workflow")
+ * - `maxSteps`      — safety cap on the number of steps dispatched (default: 100)
+ */
+export interface RunWorkflowInput {
+    /** Full WeaveConfig containing workflow definitions. */
+    readonly config: WeaveConfig;
+    /** Name of the workflow to execute (must exist in `config.workflows`). */
+    readonly workflowName: string;
+    /** Human-readable goal for this execution instance. */
+    readonly goal: string;
+    /** URL-safe slug for this execution instance. */
+    readonly slug: string;
+    /** OpenCode adapter instance — `spawnSubagent` is called for each DispatchAgentEffect. */
+    readonly adapter: OpenCodeAdapter;
+    /** Runtime Store instance. Defaults to a fresh InMemoryRuntimeStore when omitted. */
+    readonly store?: RuntimeStore;
+    /** Optional plan state provider for plan_created/plan_complete completion methods. */
+    readonly planStateProvider?: PlanStateProvider;
+    /** Owner identifier for the execution lease. Defaults to "run-workflow". */
+    readonly ownerId?: string;
+    /** Safety cap on the number of steps dispatched. Defaults to 100. */
+    readonly maxSteps?: number;
+}
+/**
+ * Output from `runWorkflow`.
+ *
+ * Reports the final status of the execution and the effects that were applied.
+ */
+export interface RunWorkflowResult {
+    /** The workflow instance ID that was created. */
+    readonly workflowInstanceId: string;
+    /** All lifecycle effects that were applied during the execution. */
+    readonly appliedEffects: readonly LifecycleEffect[];
+    /** Final execution status. */
+    readonly status: "completed" | "paused";
+    /** Number of steps that were dispatched. */
+    readonly stepsDispatched: number;
+}
+/**
+ * Execute a named workflow end-to-end using the engine's lifecycle surface.
+ *
+ * This is the **explicit named-workflow execution** entry point. The caller
+ * must supply the name of a workflow declared in `config.workflows`. This
+ * function is not the ordinary Loom-led path — for that, see
+ * `startPlanExecution` (the `/weave:start` delivery path).
+ *
+ * `runWorkflow` must be called by a user-authorized trigger (command handler,
+ * script, or UI action). It is never wired to idle hooks, session events, or
+ * continuation hooks.
+ *
+ * ## Delegation
+ *
+ * Lifecycle semantics are delegated to the engine's `runNamedWorkflow`
+ * command operation. The adapter supplies a `projectEffect` callback that
+ * calls `adapter.spawnSubagent` for each `DispatchAgentEffect`. The engine
+ * never applies harness-specific behavior.
+ *
+ * @param input - Named-workflow execution parameters.
+ * @returns `ok(RunWorkflowResult)` on success, or `err(RunWorkflowError)`.
+ */
+export declare function runWorkflow(input: RunWorkflowInput): ResultAsync<RunWorkflowResult, RunWorkflowError>;
+//# sourceMappingURL=run-workflow.d.ts.map

package/dist/run-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-workflow.d.ts","sourceRoot":"","sources":["../src/run-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAEV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAYlD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAMrE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IACxC,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAmDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,gBAAgB,GACtB,WAAW,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAqClD"}