akm-cli 0.8.6 → 0.8.14

package/dist/integrations/harnesses/index.js

@@ -0,0 +1,144 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Single registration point for every akm agent harness (#562).
+ *
+ * `HARNESS_REGISTRY` is the ONE source of truth that replaces the three
+ * previously-disconnected registries (session-logs index, agent profiles,
+ * config/setup platform strings). All derived exports below are computed from
+ * it, so adding a harness is a single entry here instead of ~16 scattered edits.
+ *
+ * This module is a dependency-graph LEAF: it imports nothing from
+ * `core/config`. `core/config/config-types.ts` derives `VALID_HARNESS_IDS`
+ * from here, which keeps the import direction acyclic (config ← harnesses).
+ *
+ * Implementations (session-log readers, agent profiles) are migrated under each
+ * harness in #563/#564; this step only owns ids + capability membership and
+ * wires the existing call sites to consult it (behaviour-preserving).
+ */
+import { ClaudeHarness } from "./claude/index.js";
+import { OpencodeHarness } from "./opencode/index.js";
+import { OpencodeSdkHarness } from "./opencode-sdk/index.js";
+// Each harness descriptor (ClaudeHarness, OpencodeHarness, OpencodeSdkHarness)
+// lives in its own per-harness directory alongside that harness's session-log
+// reader, agent builder, config importer, and/or SDK runner (#563/#564). They
+// are imported above and registered in HARNESS_REGISTRY below.
+/**
+ * The single registration point. Add a harness here (and nothing else) to make
+ * every derived registry pick it up.
+ *
+ * Typed `as const` (not `AkmHarness[]`) so each entry keeps its literal `id`,
+ * which lets `VALID_HARNESS_IDS` stay a literal tuple — `HarnessId`,
+ * `z.enum(...)`, and the `platform` union all need the literal types.
+ */
+// Order is significant: VALID_HARNESS_IDS derives from this array and feeds the
+// committed JSON-schema enum order. Kept as [opencode, claude, opencode-sdk] to
+// match the pre-unification VALID_HARNESS_IDS so the generated schema does not
+// drift (behaviour-preserving, #562).
+export const HARNESS_REGISTRY = Object.freeze([
+    new OpencodeHarness(),
+    new ClaudeHarness(),
+    new OpencodeSdkHarness(),
+]);
+/** Lookup by canonical id. */
+export const HARNESS_BY_ID = new Map(HARNESS_REGISTRY.map((h) => [h.id, h]));
+/**
+ * Lookup by canonical id OR any alias OR runtime id — the normalization bridge
+ * resolver. Both 'claude' and 'claude-code' map to the Claude harness.
+ */
+const HARNESS_BY_ANY_ID = (() => {
+    const m = new Map();
+    for (const h of HARNESS_REGISTRY) {
+        m.set(h.id, h);
+        if (h.runtimeId)
+            m.set(h.runtimeId, h);
+        for (const a of h.aliases)
+            m.set(a, h);
+    }
+    return m;
+})();
+/**
+ * Canonical, ordered list of valid harness / platform ids. The Zod
+ * `AgentPlatformSchema` enum, the `AgentProfileConfigV2` platform union,
+ * `parseAgentProfilesMapV2`'s membership check, and setup's `DetectedHarness`
+ * union all derive from this so they cannot drift.
+ */
+export const VALID_HARNESS_IDS = Object.freeze(HARNESS_REGISTRY.map((h) => h.id));
+/** Harnesses that expose readable native session logs. */
+export const SESSION_LOG_HARNESSES = HARNESS_REGISTRY.filter((h) => h.capabilities.sessionLogs);
+/** Harnesses that can be dispatched as an agent CLI / SDK. */
+export const AGENT_DISPATCH_HARNESSES = HARNESS_REGISTRY.filter((h) => h.capabilities.agentDispatch);
+/** Harnesses that can import an existing harness config into akm. */
+export const CONFIG_IMPORTER_HARNESSES = HARNESS_REGISTRY.filter((h) => h.capabilities.configImport);
+/** Harnesses that participate in `akm setup` detection. */
+export const DETECTION_HARNESSES = HARNESS_REGISTRY.filter((h) => h.capabilities.detection);
+/**
+ * Resolve any id form (canonical id, alias, or runtime id) to the harness
+ * descriptor, or `undefined` if unknown.
+ */
+export function getHarness(id) {
+    return HARNESS_BY_ANY_ID.get(id);
+}
+/**
+ * id normalization bridge — alias → canonical.
+ *
+ * Maps any known alias/runtime id to its canonical persisted id (e.g.
+ * 'claude-code' → 'claude'). Unknown ids pass through unchanged so callers can
+ * still validate them. This is what keeps existing persisted configs that say
+ * 'claude-code' working against the canonical 'claude' registry.
+ */
+export function normalizeHarnessId(id) {
+    return HARNESS_BY_ANY_ID.get(id)?.id ?? id;
+}
+/**
+ * Resolve a legacy v1 agent-profile name to its v2 platform id (#566).
+ *
+ * v1 agent profiles never carried an explicit `platform`; it had to be inferred
+ * from the profile name. This is the SINGLE registry-backed resolver that
+ * replaces both the old standalone `guessAgentPlatform()` in config-migration
+ * and the `name.includes("claude") ? "claude" : "opencode"` heuristic in setup.
+ * Each harness owns its own `matchesV1ProfileName()`; an unknown name matches no
+ * harness and returns `undefined`, so the caller drops it instead of silently
+ * defaulting to `'opencode'`.
+ *
+ * Harnesses are consulted most-specific-id-first (longest id wins) so a
+ * decorated name like `"opencode-sdk-fast"` resolves to `'opencode-sdk'` rather
+ * than being over-matched by OpenCode's `"opencode"` prefix.
+ */
+const V1_RESOLUTION_ORDER = [...HARNESS_REGISTRY].sort((a, b) => b.id.length - a.id.length);
+export function v1ProfilePlatform(name) {
+    for (const h of V1_RESOLUTION_ORDER) {
+        if (h.matchesV1ProfileName(name))
+            return h.id;
+    }
+    return undefined;
+}
+/**
+ * Default agent-profile name for a detected harness id (#566).
+ *
+ * Used by `akm setup`'s headless/recommended-config path so a newly added
+ * dispatch-capable harness gets a usable default profile name (its canonical
+ * id) instead of falling through a hardcoded if-chain with no default. Returns
+ * `undefined` for `"none"` or any id that is unknown / not agent-dispatch
+ * capable.
+ */
+export function defaultProfileName(detected) {
+    const h = HARNESS_BY_ANY_ID.get(detected);
+    if (!h?.capabilities.agentDispatch)
+        return undefined;
+    return h.id;
+}
+/**
+ * id normalization bridge — canonical → runtime identity.
+ *
+ * Maps a canonical id to the string a harness reports at runtime / in its
+ * session logs (e.g. 'claude' → 'claude-code'). Used by workflow run
+ * attribution and the session-logs provider name so the persisted runtime
+ * identity stays stable. Falls back to the canonical id when the harness has no
+ * distinct runtime identity.
+ */
+export function denormalizeRuntimeIdentity(id) {
+    const h = HARNESS_BY_ANY_ID.get(id);
+    return h?.runtimeId ?? h?.id ?? id;
+}

package/dist/integrations/harnesses/opencode/agent-builder.js

@@ -0,0 +1,43 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenCode agent command builder (migrated from `agent/builders.ts`, #564).
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * argv the `opencode` CLI expects. This is the OpenCode-specific slice of the
+ * builder strategy; the shared infrastructure (`AgentCommandBuilder`,
+ * `getCommandBuilder`, the default builder, flag/tool helpers) stays in
+ * `agent/builders.ts`, which imports this builder back into `BUILTIN_BUILDERS`.
+ *
+ * Behaviour-preserving relocation: the produced argv is byte-identical to the
+ * pre-migration `opencodeBuilder`. The builder's `platform` stays `'opencode'`
+ * (the canonical harness id).
+ */
+import { assertNotFlag } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.js";
+/**
+ * OpenCode builder.
+ * Command shape: opencode run [--system-prompt "..."] [--model <m>] "<prompt>"
+ *
+ * Tool policy is omitted — opencode manages tool access through its own agent
+ * config files, not via CLI flags.
+ */
+export const opencodeBuilder = {
+    platform: "opencode",
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args]; // starts with ["run"]
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, "opencode", profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        args.push("--");
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/opencode/config-import.js

@@ -0,0 +1,82 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenCode LLM-config importer (migrated from `setup/harness-config-import.ts`,
+ * #564).
+ *
+ * Detects an OpenCode installation (filesystem only, no network) and reads its
+ * config to extract LLM connection details. API key VALUES are never stored —
+ * only the env var name that holds them. The pluggable registry
+ * (`HARNESS_CONFIG_IMPORTERS`) and the Claude importer stay in their respective
+ * modules; `setup/harness-config-import.ts` imports this importer back.
+ *
+ * Behaviour-preserving relocation.
+ */
+import fs from "node:fs";
+import path from "node:path";
+function homeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? "";
+}
+/**
+ * Imports LLM config from an OpenCode installation.
+ *
+ * OpenCode stores config in `~/.config/opencode/config.json` or
+ * `~/.opencode/config.json`. Its schema has a `providers` array and a
+ * `model` field. API keys in providers appear as `$ENV_VAR_NAME` references.
+ */
+export const openCodeImporter = {
+    harnessName: "OpenCode",
+    detect() {
+        const home = homeDir();
+        return fs.existsSync(path.join(home, ".config", "opencode")) || fs.existsSync(path.join(home, ".opencode"));
+    },
+    importConfig() {
+        const home = homeDir();
+        const candidates = [
+            path.join(home, ".config", "opencode", "config.json"),
+            path.join(home, ".opencode", "config.json"),
+            path.join(process.cwd(), ".opencode", "config.json"),
+        ];
+        for (const filePath of candidates) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+                // OpenCode config shape: { model?: string, providers?: Array<{id, apiKey, baseUrl, ...}> }
+                const model = typeof raw.model === "string" ? raw.model : undefined;
+                // Extract provider info from the first entry in the providers array
+                let provider;
+                let baseUrl;
+                let apiKeyEnvVar;
+                const providers = Array.isArray(raw.providers) ? raw.providers : [];
+                if (providers.length > 0) {
+                    const first = providers[0];
+                    provider = typeof first?.id === "string" ? first.id : undefined;
+                    baseUrl =
+                        typeof first?.baseUrl === "string"
+                            ? first.baseUrl
+                            : typeof first?.base_url === "string"
+                                ? first.base_url
+                                : undefined;
+                    // apiKey is an env var reference like "$OPENAI_API_KEY" — extract the var name
+                    const apiKeyVal = typeof first?.apiKey === "string" ? first.apiKey : "";
+                    if (apiKeyVal.startsWith("$")) {
+                        apiKeyEnvVar = apiKeyVal.slice(1);
+                    }
+                }
+                return {
+                    harnessName: "OpenCode",
+                    provider,
+                    model,
+                    baseUrl,
+                    apiKeyEnvVar,
+                };
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        return null;
+    },
+};

package/dist/integrations/harnesses/opencode/index.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenCode harness (#564).
+ *
+ * Per-harness barrel that gathers the OpenCode integration surfaces previously
+ * scattered across the codebase:
+ *   - session-log reader     → ./session-log.ts   (OpenCodeProvider)
+ *   - agent command builder  → ./agent-builder.ts (opencodeBuilder)
+ *   - config importer        → ./config-import.ts (openCodeImporter)
+ *
+ * It also defines {@link OpencodeHarness}, the {@link AkmHarness} descriptor
+ * that `HARNESS_REGISTRY` registers.
+ *
+ * id normalization: OpenCode's canonical id (`'opencode'`) is also its runtime
+ * identity and session-log provider name — there is no historical split (unlike
+ * Claude Code's 'claude' vs 'claude-code'), so no alias bridge is needed.
+ */
+import { BaseHarness } from "../types.js";
+export { opencodeBuilder } from "./agent-builder.js";
+export { openCodeImporter } from "./config-import.js";
+export { OpenCodeProvider } from "./session-log.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * OpenCode.
+ *
+ * Canonical id is `'opencode'`; it has no distinct runtime identity or alias.
+ */
+export class OpencodeHarness extends BaseHarness {
+    id = "opencode";
+    displayName = "OpenCode";
+    aliases = [];
+    // Home-relative config dir scanned by `akm setup` (#567). OpenCode has a
+    // session-log provider, so offering it as a stash source is functional.
+    setupDetectionDir = ".config/opencode";
+    // Decorated v1 profile names like "opencode-fast" still belong to OpenCode.
+    // `v1ProfilePlatform()` resolves most-specific-id-first, so "opencode-sdk-*"
+    // is claimed by OpencodeSdkHarness before this prefix can over-match it.
+    v1ProfilePrefixes = ["opencode"];
+    capabilities = caps({
+        sessionLogs: true,
+        agentDispatch: true,
+        detection: true,
+        configImport: true,
+        runtimeIdentity: true,
+        v1Migration: true,
+    });
+}

package/dist/integrations/{session-logs/providers/opencode.js → harnesses/opencode/session-log.js}

@@ -4,7 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { extractInlineRefMentions } from "../inline-refs";
+import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
 function getOpenCodeBaseDir() {
     if (process.platform === "darwin") {
         return path.join(os.homedir(), "Library", "Application Support", "opencode");

package/dist/integrations/harnesses/opencode-sdk/index.js

@@ -0,0 +1,49 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenCode SDK harness (#564).
+ *
+ * Per-harness barrel for the SDK-mode dispatch path:
+ *   - agent runner → ./sdk-runner.ts (runOpencodeSdk / runAgentSdk)
+ *
+ * It also defines {@link OpencodeSdkHarness}, the {@link AkmHarness} descriptor
+ * that `HARNESS_REGISTRY` registers.
+ *
+ * Unlike the CLI harnesses, the SDK path has no native session logs of its own
+ * (`capabilities.sessionLogs = false`): it dispatches via the embedded
+ * `@opencode-ai/sdk` and surfaces output directly rather than writing platform
+ * session files. It is still detected at setup and migrated from v1 profile
+ * names. Canonical id is `'opencode-sdk'` with no alias.
+ */
+import { BaseHarness } from "../types.js";
+export { closeServer, runAgentSdk, runOpencodeSdk } from "./sdk-runner.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * OpenCode SDK (embedded-SDK dispatch path).
+ *
+ * Dispatch-only: no native session logs, but detected at setup and migrated
+ * from v1 profile names.
+ */
+export class OpencodeSdkHarness extends BaseHarness {
+    id = "opencode-sdk";
+    displayName = "OpenCode SDK";
+    aliases = [];
+    // Decorated v1 profile names like "opencode-sdk-fast" belong to the SDK path.
+    v1ProfilePrefixes = ["opencode-sdk"];
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+        v1Migration: true,
+    });
+}

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -0,0 +1,234 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenCode SDK agent runner (migrated from `agent/sdk-runner.ts`, #564).
+ *
+ * Uses the embedded `@opencode-ai/sdk` instead of `Bun.spawn`. Requires no
+ * agent CLI binary to be installed. The user provides an OpenAI-compatible
+ * endpoint (or inherits from config.llm) for the SDK.
+ *
+ * This is the runtime surface of the {@link OpencodeSdkHarness} (`id =
+ * 'opencode-sdk'`). It is the dispatch path for `sdkMode` profiles; it exposes
+ * no native session logs of its own (`capabilities.sessionLogs = false`).
+ */
+import { resolveSecret } from "../../../core/config/config.js";
+import { DEFAULT_AGENT_TIMEOUT_MS } from "../../agent/config.js";
+// Singleton server — started once per process, reused across calls
+let _server = null;
+/**
+ * Test-only seam: inject a fake {@link SdkServer} so `runOpencodeSdk` can be
+ * exercised without the real `@opencode-ai/sdk` (which would spin up a server).
+ * Pass `null` to clear. NOT part of the public runtime API — used only to
+ * assert the #564 bug fixes (systemPrompt/tools forwarding + timeout). The
+ * leading underscores mark it as internal.
+ */
+export function __setTestServer(server) {
+    _server = server;
+}
+/**
+ * Close the singleton OpenCode SDK server and reset the handle.
+ * Primarily for use in tests to ensure clean teardown between test runs.
+ */
+export function closeServer() {
+    try {
+        _server?.server.close();
+    }
+    catch {
+        /* ignore */
+    }
+    _server = null;
+}
+/**
+ * Convert an `AgentDispatchRequest.tools` policy into the SDK's tool-allowlist
+ * shape (`{ [toolName]: boolean }`).
+ *
+ * #564 bug fix (2): the tool list was previously dropped entirely. The CLI
+ * builder passes tools as a comma-separated `--allowedTools` flag; the SDK
+ * instead wants a per-tool boolean map. A list/comma-string of tool names is
+ * treated as an allowlist (each name → true). A structured policy object whose
+ * values are already booleans is forwarded as-is.
+ *
+ * Returns `undefined` when there is nothing to forward, so an absent policy
+ * leaves the SDK's own defaults untouched (behaviour-preserving for callers
+ * that pass no tools).
+ */
+function toolsToSdkAllowlist(tools) {
+    if (tools === undefined || tools === null)
+        return undefined;
+    const names = [];
+    if (typeof tools === "string") {
+        names.push(...tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean));
+    }
+    else if (Array.isArray(tools)) {
+        for (const t of tools) {
+            if (typeof t === "string" && t.trim())
+                names.push(t.trim());
+        }
+    }
+    else if (typeof tools === "object") {
+        // Structured policy: forward boolean entries directly.
+        const out = {};
+        for (const [k, v] of Object.entries(tools)) {
+            if (typeof v === "boolean")
+                out[k] = v;
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
+    if (names.length === 0)
+        return undefined;
+    const out = {};
+    for (const n of names)
+        out[n] = true;
+    return out;
+}
+async function getOrStartServer(profile, llmConfig) {
+    if (_server)
+        return _server;
+    const { createOpencode } = await import("@opencode-ai/sdk").catch(() => {
+        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
+    });
+    // Resolve endpoint and model: profile fields take precedence over config.llm
+    const endpoint = profile.endpoint ?? llmConfig?.endpoint;
+    const apiKey = resolveSecret(profile.apiKey ?? llmConfig?.apiKey);
+    const model = profile.model;
+    const sdkConfig = {};
+    if (model)
+        sdkConfig.model = model;
+    if (endpoint || apiKey) {
+        // Configure a custom OpenAI-compatible provider
+        sdkConfig.provider = {
+            "akm-custom": {
+                npm: "@ai-sdk/openai-compatible",
+                options: {
+                    baseURL: endpoint?.replace(/\/chat\/completions$/, "").replace(/\/$/, ""),
+                    ...(apiKey ? { apiKey } : {}),
+                },
+            },
+        };
+        // Use the custom provider's model if not already qualified
+        if (model && !model.includes("/")) {
+            sdkConfig.model = `akm-custom/${model}`;
+        }
+    }
+    _server = (await createOpencode(Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {}));
+    process.once("exit", () => {
+        closeServer();
+    });
+    if (!_server)
+        throw new Error("Failed to initialise OpenCode SDK server.");
+    return _server;
+}
+export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
+    const start = Date.now();
+    let client;
+    try {
+        ({ client } = await getOrStartServer(profile, llmConfig));
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: String(e),
+        };
+    }
+    // One session per call — do NOT reuse (history accumulates, token costs grow)
+    const sessionRes = await client.session.create({ body: { title: "akm" } });
+    const sessionId = sessionRes.data?.id;
+    if (!sessionId) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "Failed to create session",
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: "Failed to create OpenCode session",
+        };
+    }
+    // #564 bug fixes (1) + (2): forward systemPrompt and tools from the abstract
+    // dispatch request. Both were previously accepted on AgentDispatchRequest but
+    // silently dropped on the SDK path, so SDK-mode dispatch ignored agent-asset
+    // system prompts and tool policies entirely (the CLI path honours both).
+    const dispatch = opts.dispatch;
+    const system = dispatch?.systemPrompt;
+    const tools = toolsToSdkAllowlist(dispatch?.tools);
+    const body = { parts: [{ type: "text", text: prompt }] };
+    if (system)
+        body.system = system;
+    if (tools)
+        body.tools = tools;
+    // #564 bug fix (3): enforce a hard timeout like the CLI path (runAgent).
+    // Previously runOpencodeSdk() awaited session.prompt() with no timeout, so a
+    // hung SDK call (e.g. a stalled local-model endpoint) blocked the caller
+    // indefinitely while the CLI path would have killed the process. We resolve
+    // the same budget runAgent uses (opts.timeoutMs override → profile.timeoutMs
+    // → DEFAULT_AGENT_TIMEOUT_MS) and race the prompt against it. null disables
+    // the timer (parity with runAgent's "no timeout" contract). There is no
+    // OS process to SIGTERM/SIGKILL here, so on timeout we best-effort delete the
+    // session (the SDK's equivalent of reaping the in-flight work) and return a
+    // structured `timeout` failure with the same reason vocabulary as the CLI.
+    const timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : (profile.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS);
+    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    let timer;
+    const TIMED_OUT = Symbol("opencode-sdk-timeout");
+    try {
+        const promptPromise = client.session.prompt({ path: { id: sessionId }, body });
+        const result = timeoutMs === null
+            ? await promptPromise
+            : await Promise.race([
+                promptPromise,
+                new Promise((resolve) => {
+                    timer = setTimeoutImpl(() => resolve(TIMED_OUT), timeoutMs);
+                }),
+            ]);
+        if (result === TIMED_OUT) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: "",
+                durationMs: Date.now() - start,
+                exitCode: null,
+                reason: "timeout",
+                error: `opencode-sdk agent "${profile.name}" timed out after ${timeoutMs}ms`,
+            };
+        }
+        const parts = result.data?.parts ?? [];
+        const textPart = parts.find((p) => p.type === "text");
+        const stdout = textPart?.text ?? "";
+        return {
+            ok: true,
+            stdout,
+            stderr: "",
+            durationMs: Date.now() - start,
+            exitCode: 0,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "non_zero_exit",
+            error: String(e),
+        };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeoutImpl(timer);
+        // Clean up session to prevent disk accumulation in ~/.local/share/opencode/
+        await client.session.delete({ path: { id: sessionId } }).catch(() => { });
+    }
+}
+/** @deprecated Use {@link runOpencodeSdk} instead. */
+export const runAgentSdk = runOpencodeSdk;

package/dist/integrations/harnesses/types.js

@@ -0,0 +1,43 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Shared base for harness descriptors (#566).
+ *
+ * Provides the default v1-profile-name matcher so the inference logic lives in
+ * ONE place instead of being duplicated across the old `guessAgentPlatform()`
+ * (config-migration) and the `name.includes("claude")` heuristic (setup). A
+ * concrete harness sets `id`/`aliases`/`capabilities` and, when its v1 profile
+ * names could be decorated (e.g. `"opencode-sdk-fast"`), `v1ProfilePrefixes`.
+ */
+export class BaseHarness {
+    runtimeId;
+    setupDetectionDir;
+    /**
+     * Lowercase prefixes that a decorated v1 profile name may start with and
+     * still belong to this harness (e.g. `["opencode-sdk"]`). The canonical id
+     * and aliases are always matched in addition to these; an empty list means
+     * only exact id/alias matches.
+     */
+    v1ProfilePrefixes = [];
+    matchesV1ProfileName(name) {
+        // Only harnesses with a v1→v2 mapping participate; others never claim a
+        // legacy profile name (so unknown names are dropped, not misclassified).
+        if (!this.capabilities.v1Migration)
+            return false;
+        const lower = name.trim().toLowerCase();
+        if (!lower)
+            return false;
+        if (lower === this.id.toLowerCase())
+            return true;
+        for (const alias of this.aliases) {
+            if (lower === alias.toLowerCase())
+                return true;
+        }
+        for (const prefix of this.v1ProfilePrefixes) {
+            if (lower.startsWith(prefix.toLowerCase()))
+                return true;
+        }
+        return false;
+    }
+}