@oisincoveney/pipeline 2.1.0 → 2.2.0

package/dist/runtime/opencode-runtime.js

@@ -0,0 +1,62 @@
+import { OpencodeServerStartupError, openOpencodeServer } from "./opencode-server.js";
+import { createOpencodeExecutor, createOpencodeSessionRegistry } from "./opencode-session-executor.js";
+//#region src/runtime/opencode-runtime.ts
+/**
+* True when the config declares any opencode runner, i.e. the SDK transport is
+* relevant for this run. Command-only configs never start a server.
+*/
+function configUsesOpencode(config) {
+	return Object.values(config.runners).some((runner) => runner.type === "opencode");
+}
+/**
+* Return an SDK-backed executor plus a release() that tears the server down.
+* The opencode server is started LAZILY on the first executor call, not at
+* lease time: a run whose ready nodes are all command/builtin (or that fails
+* before any agent node executes) never spawns opencode, so the binary is only
+* required when an agent node actually runs. release() is a no-op if the server
+* was never started. Caller owns the lifecycle:
+*
+*   const lease = await leaseOpencodeRuntime({ config, worktreePath });
+*   try { ...run with lease.executor... } finally { await lease.release(); }
+*/
+function leaseOpencodeRuntime(input) {
+	const registry = createOpencodeSessionRegistry();
+	const openHandle = input.openServer ?? startServer;
+	let handle;
+	let pending;
+	const ensureExecutor = () => {
+		pending ??= openHandle(input).then((started) => {
+			handle = started;
+			return createOpencodeExecutor({
+				client: started.client,
+				directory: input.worktreePath,
+				registry
+			});
+		});
+		return pending;
+	};
+	return Promise.resolve({
+		executor: async (plan, options) => {
+			return await (await ensureExecutor())(plan, options);
+		},
+		release: async () => {
+			if (handle) {
+				await handle.close();
+				handle = void 0;
+			}
+		}
+	});
+}
+async function startServer(input) {
+	try {
+		return await openOpencodeServer({
+			directory: input.worktreePath,
+			...input.signal ? { signal: input.signal } : {}
+		});
+	} catch (error) {
+		if (error instanceof OpencodeServerStartupError) throw new OpencodeServerStartupError(`${error.message}. Confirm the opencode binary is installed and recent enough to expose 'opencode serve', or set OPENCODE_SERVER_URL to an already-running server.`, { cause: error });
+		throw error;
+	}
+}
+//#endregion
+export { configUsesOpencode, leaseOpencodeRuntime };

package/dist/runtime/opencode-server.js

@@ -0,0 +1,67 @@
+import { createOpencode, createOpencodeClient } from "@opencode-ai/sdk";
+//#region src/runtime/opencode-server.ts
+const DEFAULT_STARTUP_TIMEOUT_MS = 3e4;
+var OpencodeServerStartupError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "OpencodeServerStartupError";
+	}
+};
+async function openOpencodeServer(options) {
+	const externalUrl = options.serverUrl ?? process.env.OPENCODE_SERVER_URL ?? "";
+	if (externalUrl.length > 0) return connectExternalServer(externalUrl, options.directory);
+	return await spawnOwnedServer(options);
+}
+function connectExternalServer(url, directory) {
+	return {
+		close: () => Promise.resolve(),
+		client: createOpencodeClient({
+			baseUrl: url,
+			directory
+		}),
+		owned: false,
+		url
+	};
+}
+async function spawnOwnedServer(options) {
+	const spawn = options.spawn ?? createOpencode;
+	try {
+		const { client, server } = await spawn(spawnArgs(options));
+		return ownedHandle(client, server, options.directory);
+	} catch (error) {
+		throw new OpencodeServerStartupError(`Failed to start opencode server: ${errorText(error)}`, { cause: error });
+	}
+}
+function spawnArgs(options) {
+	return {
+		port: 0,
+		...options.signal ? { signal: options.signal } : {},
+		timeout: options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS
+	};
+}
+function ownedHandle(client, server, directory) {
+	return {
+		close: () => {
+			server.close();
+			return Promise.resolve();
+		},
+		client: withDirectory(client, server.url, directory),
+		owned: true,
+		url: server.url
+	};
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function withDirectory(fallback, url, directory) {
+	try {
+		return createOpencodeClient({
+			baseUrl: url,
+			directory
+		});
+	} catch {
+		return fallback;
+	}
+}
+//#endregion
+export { OpencodeServerStartupError, openOpencodeServer };

package/dist/runtime/opencode-session-executor.js

@@ -0,0 +1,206 @@
+import { opencodeAgentName } from "./opencode-agent-name.js";
+//#region src/runtime/opencode-session-executor.ts
+function createOpencodeSessionRegistry() {
+	return { sessions: /* @__PURE__ */ new Map() };
+}
+/**
+* Distinguish infra failure (server/session error -> retry-eligible exit 70)
+* from a normal agent completion (the agent may still have produced a wrong
+* answer; gates decide that, exit 0). This mirrors the EXIT_STARTUP convention
+* in runner-command/run.ts and feeds retry.ts via the node's retry policy.
+*/
+const EXIT_OK = 0;
+const EXIT_AGENT_ERROR = 1;
+const EXIT_INFRA = 70;
+/**
+* SDK-backed replacement for the subprocess `runLaunchPlan`. Conforms to the
+* RuntimeContext.executor seam so agent-node never learns the transport.
+*/
+function createOpencodeExecutor(deps) {
+	return async function execute(plan, options = {}) {
+		if (plan.type !== "opencode") throw new Error(`opencode executor cannot drive runner type '${plan.type}'`);
+		try {
+			return successResult(plan, await driveSession(deps, plan, options));
+		} catch (error) {
+			return failureResult(plan, error);
+		}
+	};
+}
+async function driveSession(deps, plan, options) {
+	const sessionId = await resolveSessionId(deps, plan);
+	deps.onSession?.(plan.nodeId, sessionId);
+	const stream = await streamEventsToOutput(deps, sessionId, plan, options);
+	try {
+		const data = unwrap(await deps.client.session.prompt({
+			body: promptBody(plan),
+			path: { id: sessionId },
+			query: { directory: deps.directory }
+		}));
+		return {
+			...data.info ? { assistant: data.info } : {},
+			parts: data.parts ?? [],
+			sessionId
+		};
+	} finally {
+		await stream.stop();
+	}
+}
+async function resolveSessionId(deps, plan) {
+	const existing = deps.registry.sessions.get(plan.nodeId);
+	if (existing) return existing;
+	const session = unwrap(await deps.client.session.create({
+		body: { title: `moka:${plan.nodeId}` },
+		query: { directory: deps.directory }
+	}));
+	deps.registry.sessions.set(plan.nodeId, session.id);
+	return session.id;
+}
+function promptBody(plan) {
+	const prompt = promptText(plan);
+	const model = parseModel(plan.model);
+	const agent = plan.profileId ? opencodeAgentName(plan.profileId) : void 0;
+	return {
+		parts: [{
+			text: prompt,
+			type: "text"
+		}],
+		...agent ? { agent } : {},
+		...model ? { model } : {}
+	};
+}
+const FLAGS_TAKING_VALUE = new Set([
+	"--model",
+	"--dir",
+	"--file",
+	"--format"
+]);
+/**
+* The launch plan carries the prompt inside the CLI argv (`run <prompt>` or
+* `run <prompt> --file <ctx>`). Recover it as the trailing positional arg
+* (skipping flags and their values) so the adapter boundary is identical
+* regardless of transport.
+*/
+function promptText(plan) {
+	return plan.args.filter((arg, index) => index > 0 && !arg.startsWith("-") && !FLAGS_TAKING_VALUE.has(plan.args[index - 1] ?? "")).at(-1) ?? "";
+}
+function parseModel(model) {
+	if (!model) return;
+	const slash = model.indexOf("/");
+	if (slash === -1) return;
+	return {
+		modelID: model.slice(slash + 1),
+		providerID: model.slice(0, slash)
+	};
+}
+async function streamEventsToOutput(deps, sessionId, plan, options) {
+	if (!options.onOutput) return { stop: () => Promise.resolve() };
+	const iterator = (await deps.client.event.subscribe()).stream;
+	const pump = (async () => {
+		try {
+			for await (const event of iterator) forwardEvent(event, sessionId, plan, options);
+		} catch (error) {
+			options.onOutput?.({
+				chunk: `opencode event stream dropped: ${errorMessage(error)}\n`,
+				nodeId: plan.nodeId,
+				stream: "stderr"
+			});
+		}
+	})();
+	return { stop: async () => {
+		await iterator.return?.(void 0);
+		await pump;
+	} };
+}
+function forwardEvent(event, sessionId, plan, options) {
+	const forwarded = eventChunk(event, sessionId);
+	if (forwarded) options.onOutput?.({
+		chunk: forwarded.chunk,
+		nodeId: plan.nodeId,
+		stream: forwarded.stream
+	});
+}
+function eventChunk(event, sessionId) {
+	if (event.type === "message.part.updated") return partChunk(event.properties.part, sessionId);
+	if (event.type === "session.error" && belongsToSession(event, sessionId)) return {
+		chunk: `opencode session error: ${describeMessageError(event.properties.error)}\n`,
+		stream: "stderr"
+	};
+}
+function belongsToSession(event, sessionId) {
+	return event.properties.sessionID === void 0 || event.properties.sessionID === sessionId;
+}
+function partChunk(part, sessionId) {
+	if (part.sessionID !== sessionId) return;
+	if (part.type === "text") return {
+		chunk: `${JSON.stringify({ part: {
+			text: part.text,
+			type: "text"
+		} })}\n`,
+		stream: "stdout"
+	};
+	if (part.type === "tool") return {
+		chunk: `opencode tool ${part.tool} ${part.state.status}\n`,
+		stream: "stderr"
+	};
+}
+/**
+* Reconstruct the JSONL stdout the existing normalizeOutput/outputCandidates
+* parser already understands, so the structured-output and repair passes work
+* unchanged on top of SDK responses.
+*/
+function successResult(plan, drive) {
+	const stdout = drive.parts.filter((part) => part.type === "text").map((part) => JSON.stringify({ part: {
+		text: part.text,
+		type: "text"
+	} })).join("\n");
+	const assistantError = drive.assistant?.error;
+	if (assistantError) return {
+		argv: plan.args,
+		exitCode: infraErrorExitCode(assistantError),
+		sessionId: drive.sessionId,
+		stderr: describeMessageError(assistantError),
+		stdout
+	};
+	return {
+		argv: plan.args,
+		exitCode: EXIT_OK,
+		sessionId: drive.sessionId,
+		stdout
+	};
+}
+function failureResult(plan, error) {
+	return {
+		argv: plan.args,
+		exitCode: EXIT_INFRA,
+		stderr: `opencode session failed: ${errorMessage(error)}`,
+		stdout: ""
+	};
+}
+/**
+* Map opencode message errors to the runner's infra-vs-agent exit convention.
+* Output-length / aborted are agent-task outcomes (exit 1, gate territory);
+* provider-auth, API, and unknown are infra (exit 70, retry-eligible).
+*/
+function infraErrorExitCode(error) {
+	switch (error.name) {
+		case "MessageOutputLengthError":
+		case "MessageAbortedError": return EXIT_AGENT_ERROR;
+		default: return EXIT_INFRA;
+	}
+}
+function describeMessageError(error) {
+	if (!error) return "unknown opencode error";
+	const data = error.data;
+	const detail = data && typeof data.message === "string" ? `: ${data.message}` : "";
+	return `${error.name}${detail}`;
+}
+function unwrap(response) {
+	if (response.error) throw new Error(typeof response.error === "string" ? response.error : JSON.stringify(response.error));
+	if (response.data === void 0) throw new Error("opencode response contained no data");
+	return response.data;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { createOpencodeExecutor, createOpencodeSessionRegistry };

package/docs/adr-opencode-first-goal-loop-runtime.md

@@ -1,6 +1,6 @@
 # ADR: OpenCode-First Goal Loop Runtime
 
-Status: Accepted
+Status: Accepted (Codex compatibility subsequently removed; OpenCode and Claude Code are the active command hosts)
 
 Date: 2026-06-08
 

package/docs/config-architecture.md

@@ -306,14 +306,19 @@ timeouts, output limits, sanitized env, and explicit trust flags.
 
 ## Host Support Matrix
 
-| Runner   | Native subagents | Rules | Skills | MCP | Outputs                   | Generated resources             |
-| -------- | ---------------- | ----- | ------ | --- | ------------------------- | ------------------------------- |
-| OpenCode | yes              | yes   | yes    | yes | text, JSON, JSONL, schema | commands, agents, skills, plugins, LSP |
-| command  | no               | no    | no     | no  | declared by runner        | subprocess argv                 |
+| Runner      | Native subagents | Rules | Skills | MCP | Outputs                   | Generated resources             |
+| ----------- | ---------------- | ----- | ------ | --- | ------------------------- | ------------------------------- |
+| OpenCode    | yes              | yes   | yes    | yes | text, JSON, JSONL, schema | commands, agents, skills, plugins, LSP |
+| Claude Code | via `opencode run` | yes (skill) | yes | yes | declared by runner | commands, wrapper agents, settings |
+| command     | no               | no    | no     | no  | declared by runner        | subprocess argv                 |
 
 Generated host resources follow a native runner rule. OpenCode runner nodes use
-OpenCode native agents. Unsupported runner or host mappings fail closed instead
-of doing instruction-only translation or generic worker substitution.
+OpenCode native agents. The Claude Code host does not run MoKa profiles natively:
+its generated `.claude/agents/moka-<role>.md` subagents each wrap a single
+`opencode run --agent "MoKa <role>"` subprocess, so the OpenCode runner remains
+the execution surface while Claude Code orchestrates. Unsupported runner or host
+mappings fail closed instead of doing instruction-only translation or generic
+worker substitution.
 
 ## Troubleshooting
 

package/docs/mcp-gateway.md

@@ -9,7 +9,7 @@ Playwright, Qdrant, or Neon.
 ## Target Shape
 
 ```text
-Codex/OpenCode
+OpenCode / Claude Code
         |
         | project-level MCP config
         v
@@ -47,7 +47,7 @@ host-specific MCP config.
 3. Configure `mcp_gateway` in package-owned profile config.
 4. Run `moka mcp gateway reconcile` to render and apply the full ToolHive vMCP
    backend inventory for the current workspace.
-5. Run `moka init` to write project Codex/OpenCode command surfaces and host
+5. Run `moka init` to write project OpenCode and Claude Code command surfaces and host
    MCP config.
 6. Run `moka mcp gateway doctor` to verify gateway health and required tools.
 7. Keep high-risk upstream capabilities controlled by gateway-side policy, not
@@ -88,7 +88,7 @@ orchestrator MCP set * subagent count * host config layers
 ```
 
 With a gateway, the runtime launches zero local upstream MCP processes for
-agents. Codex and OpenCode read the same project-level host config, which
+agents. OpenCode and Claude Code read the same project-level host config, which
 contains only `pipeline-gateway`.
 
 OpenCode receives that gateway through `.opencode/opencode.json` alongside the
@@ -114,7 +114,7 @@ adding one backend must not replace the existing Context7, uidotsh, Qdrant,
 Fallow, Serena, or Backlog declarations. Use `moka mcp gateway doctor` to check
 required environment variables, gateway health, required `tools/list` prefixes,
 local ToolHive availability for local mode, and legacy direct MCP entries. Use
-`moka init` to install generated Codex and OpenCode host surfaces with the
+`moka init` to install generated OpenCode and Claude Code host surfaces with the
 singleton `pipeline-gateway` remote entry. Use `moka install-commands --host all`
 to refresh generated host files after package upgrades, and use
 `moka mcp gateway configure-host` as an explicit migration or repair command

package/docs/operator-guide.md

@@ -302,8 +302,8 @@ Troubleshooting:
 Generated invocations include:
 
 ```text
-OpenCode: /moka-quick, /moka-execute, /moka-inspect
-Codex:    $quick, $execute, $inspect
+OpenCode:    /moka-quick, /moka-execute, /moka-inspect
+Claude Code: /moka-quick, /moka-execute, /moka-inspect
 ```
 
 `moka init` and `moka install-commands --host opencode` generate:
@@ -316,9 +316,11 @@ Codex:    $quick, $execute, $inspect
 - `.opencode/opencode.json` with LSP, the singleton `pipeline-gateway` MCP
   server, and pinned package-selected plugins
 
+`moka install-commands --host claude-code` generates `.claude/commands/moka-<entrypoint>.md`
+slash commands for Claude Code.
+
 Package defaults select OpenCode for built-in profiles and runner-command
-orchestration. Codex compatibility stays generated through `$quick`, `$execute`,
-`$inspect`, and Codex agent config, but it is not the default package runtime.
+orchestration. Codex is not a supported runtime host.
 
 ## How The Package Works
 
@@ -373,7 +375,7 @@ profiles, workflows, or node-level skill overrides.
 
 ## Configuring MCP Gateway
 
-MCP access is host-level and gateway-only. Codex, OpenCode, pipeline agents,
+MCP access is host-level and gateway-only. OpenCode, Claude Code, pipeline agents,
 manual sessions, and CI all connect to one ToolHive/vMCP gateway URL. Do not
 start upstream MCP servers from individual sessions.
 

package/docs/slash-command-adapter-contract.md

@@ -16,6 +16,7 @@ moka install-commands --host all --check
 | Host     | Generated resources                                            | Invocation                        | Mechanical path                                                                                       |
 | -------- | -------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | OpenCode | `.opencode/commands/moka-<entrypoint>.md`, `.opencode/agents/*.md`, `.opencode/opencode.json` | `/moka-quick <task>`, `/moka-execute <task>`, `/moka-inspect <task>` | Project commands run a primary orchestrator and OpenCode native subagents with package-owned skill, MCP, permission, and LSP projection. |
+| Claude Code | `.claude/commands/moka-<entrypoint>.md`, `.claude/agents/moka-<role>.md`, `.claude/settings.json` | `/moka-quick <task>`, `/moka-execute <task>`, `/moka-inspect <task>` | Slash commands load the `execute` skill, then dispatch each agent node to a Claude Code `Task` subagent that wraps a single `opencode run --agent "MoKa <role>"` subprocess. `.claude/settings.json` is merged (gateway MCP + `Bash(opencode run *)` permission), never clobbered. |
 
 ## Projection Rules
 

package/package.json

@@ -2,6 +2,7 @@
   "dependencies": {
     "@dagrejs/graphlib": "^4.0.1",
     "@kubernetes/client-node": "^1.4.0",
+    "@opencode-ai/sdk": "1.17.4",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "commander": "^14.0.3",
@@ -62,6 +63,10 @@
       "types": "./dist/config.d.ts",
       "import": "./dist/config.js"
     },
+    "./events": {
+      "types": "./dist/runner-event-schema.d.ts",
+      "import": "./dist/runner-event-schema.js"
+    },
     "./hooks": {
       "types": "./dist/hooks.d.ts",
       "import": "./dist/hooks.js"
@@ -115,7 +120,7 @@
     "prepack": "bun run build:cli"
   },
   "type": "module",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Config-driven multi-agent pipeline runner for repository work",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/.agents/skills/claude-code-opencode-execute/SKILL.md

@@ -1,116 +0,0 @@
----
-name: claude-code-opencode-execute
-description: Use in Claude Code when executing Moka work locally through OpenCode; loads execute first, then spawns Claude Task agents that run opencode run with the correct MoKa agent prompts.
-allowed-tools: Bash(opencode run *) Bash(pwd) Bash(git status *) Task
----
-
-# Claude Code OpenCode Execute
-
-Use this skill when Claude Code is the interactive host, but the work should be executed by local OpenCode MoKa agents through `opencode run` subprocesses.
-
-This skill is a host adapter. It does not replace [[execute]]. Load and follow [[execute]] first; use this skill only for the Claude Code dispatch mechanics.
-
-## Contract
-
-1. Load [[execute]] and let it classify the request, required companion skills, acceptance criteria, and verification path.
-2. Keep the execution doctrine from [[execute]]: vertical slices, test-first for behavior, root-cause fixes, fidelity checks, critique, and verification.
-3. Use Claude Code `Task` subagents as wrappers around local OpenCode subprocesses when work can be delegated.
-4. Each delegated Task agent should run exactly one MoKa-flavored OpenCode command and return the command, exit status, parsed evidence, touched files, and blockers.
-5. Batch independent nodes in parallel, wait at barriers, synthesize outputs, then decide the next batch.
-
-## OpenCode command shape
-
-Task agents should run OpenCode with this shape from the repository root:
-
-```sh
-opencode run --agent "<MoKa Agent Name>" --format json --dir "$PWD" '<node prompt>'
-```
-
-Use `--format json` so the parent can inspect structured event output. If the output contains multiple assistant text candidates, prefer the latest candidate that satisfies the requested JSON or evidence contract.
-
-Do not use `moka submit` for this local Claude Code adapter unless the user explicitly asks to submit an Argo Workflow. `moka submit` is the durable pipeline path; this skill is for interactive local orchestration through Claude Task agents and `opencode run`.
-
-## Agent Selection
-
-Select the MoKa agent by the slice's role:
-
-| Role | OpenCode agent |
-| --- | --- |
-| Intake, repository research, requirements clarification | `MoKa Researcher` |
-| Read-only code inspection | `MoKa Inspector` |
-| Schedule graph generation or schedule review | `MoKa Schedule Planner` |
-| Focused failing tests | `MoKa Test Writer` |
-| Production implementation | `MoKa Code Writer` |
-| Acceptance criteria audit | `MoKa Acceptance Reviewer` |
-| Final quality review | `MoKa Thermo Nuclear Reviewer` |
-| Verification evidence and command checks | `MoKa Verifier` |
-| Durable lessons after a completed run | `MoKa Learner` |
-
-Do not delegate normal child work to `MoKa Orchestrator`; the Claude Code parent is the local orchestrator for this adapter.
-
-## Prompt Contract
-
-Every `opencode run` prompt must include:
-
-- The original user task.
-- The current execution contract from [[execute]].
-- The node id and role.
-- The selected MoKa agent name and why it was selected.
-- The exact files or modules in scope, or a read-only discovery scope.
-- Dependency outputs from earlier nodes.
-- The acceptance criteria this node owns.
-- The output shape expected by the parent.
-
-Use this template for delegated prompts:
-
-```text
-You are running as <MoKa Agent Name> for a Claude Code local Moka execution.
-
-Original task:
-<user task>
-
-Execution contract:
-<contract produced by execute>
-
-Node:
-- id: <node id>
-- role: <role>
-- selected agent: <MoKa Agent Name>
-- scope: <files/modules/commands>
-
-Dependency outputs:
-<summaries or "none">
-
-Acceptance criteria owned by this node:
-<criteria>
-
-Instructions:
-- Follow the skills and grants configured for this MoKa agent.
-- Stay inside this node's scope.
-- Do not claim completion without fresh evidence.
-- Return only the requested output shape.
-
-Output shape:
-<JSON or concise evidence contract>
-```
-
-## Batching Rules
-
-- Run read-only discovery agents in parallel when their scopes do not require a shared conclusion first.
-- Run test-writing before production implementation for behavior changes.
-- Run multiple `MoKa Code Writer` agents in the same batch only when [[execute]] has produced independent vertical slices with disjoint files or clearly isolated worktrees.
-- Never let two write-capable agents edit the same file in the same batch.
-- Run acceptance review, final quality review, and verifier after implementation outputs have been integrated.
-- If any delegated command fails, stop the batch, read the output, classify the blocker, and return to [[execute]] routing instead of retrying blindly.
-
-## Parent Responsibilities
-
-The Claude Code parent must:
-
-- Inspect outputs before launching the next batch.
-- Integrate or reconcile changes itself when multiple agents wrote code.
-- Run the verification required by [[execute]] in the real repository context.
-- Inspect the final diff for accidental edits, secrets, generated churn, and unrelated changes.
-- Report partial verification honestly if the real command path cannot be exercised.
-
-This skill is complete only when [[execute]] would allow the parent to claim completion.