akm-cli 0.8.3 → 0.9.0-beta.1

package/dist/integrations/agent/index.js

@@ -1,11 +1,26 @@
 // 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/.
-export { getCommandBuilder } from "./builders";
-export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
-export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
-export { listBuiltinModelAliases, resolveModel } from "./model-aliases";
-export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
-export { runAgentSdk } from "./sdk-runner";
-export { runAgent } from "./spawn";
+/**
+ * Internal entry point for the `agent` integration. CLI-only project — no
+ * public exports map. Other akm modules import from this barrel for the
+ * sake of grouping imports.
+ *
+ * Surface:
+ *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
+ *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
+ *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
+ *   • Spawn: runAgent. Builders: getCommandBuilder, AgentCommandBuilder, AgentDispatchRequest — platform-specific argv construction.
+ *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
+ */
+// The OpenCode SDK runner moved to its harness directory in #564
+// (`harnesses/opencode-sdk/`). Re-exported here so existing `agent/index`
+// import sites keep working.
+export { runAgentSdk } from "../harnesses/opencode-sdk/index.js";
+export { getCommandBuilder } from "./builders.js";
+export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
+export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
+export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
+export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts.js";
+export { runAgent } from "./spawn.js";

package/dist/integrations/agent/prompts.js

@@ -25,8 +25,8 @@
  * `frontmatter` is optional — the proposal queue parses it from `content`
  * during validation. We carry it through if the agent supplies it.
  */
-import { TYPE_DIRS } from "../../core/asset-spec";
-import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
  * the agent can produce content that passes proposal validation. Kept tiny:
@@ -42,7 +42,6 @@ const TYPE_HINTS = {
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
     env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
-    vault: "vault assets are DEPRECATED (use env). They store environment variables (KEY=VALUE pairs); comments use `#`. Never echo secret values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
 };
 function hintForType(type) {

package/dist/integrations/agent/runner.js

@@ -1,8 +1,27 @@
 // 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/.
-import { ConfigError } from "../../core/errors";
-import { warn } from "../../core/warn";
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+// ── RunnerSpec capability predicates (H1) ───────────────────────────────────
+// The `RunnerSpec` union is dispatched ad-hoc across the improve slice. These
+// predicates co-locate the capability questions with the union definition so
+// callers stop hand-inlining `kind !== "llm"` (which couples the call site to
+// the exact shape of the union). They are typed as TypeScript type guards so
+// narrowing flows through to the `connection` / `profile` accessors.
+/** The in-tree LLM HTTP runner (`chatCompletion`); has no filesystem access. */
+export function runnerIsLlm(runner) {
+    return runner.kind === "llm";
+}
+/**
+ * Whether this runner can honour the file-write contract. Agent CLI + OpenCode
+ * SDK runners both have filesystem access; the direct LLM HTTP runner does NOT
+ * (see `src/llm/call-ai.ts`). Equivalent to `!runnerIsLlm(runner)` but names
+ * the capability the callers actually care about.
+ */
+export function runnerSupportsFileWrite(runner) {
+    return runner.kind !== "llm";
+}
 function resolveEffectiveMode(entry, profileName, config) {
     if (entry.mode)
         return entry.mode;
@@ -205,4 +224,4 @@ export function getStalenessDetectionThresholdDays(config) {
 }
 // Re-export `isProcessEnabled` from feature-gate.ts so callers that previously
 // imported it from runner.ts continue to work.
-export { isProcessEnabled } from "../../llm/feature-gate";
+export { isProcessEnabled } from "../../llm/feature-gate.js";

package/dist/integrations/agent/spawn.js

@@ -17,8 +17,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { getCommandBuilder } from "./builders";
-import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
+import { spawn as runtimeSpawn } from "../../runtime.js";
+import { getCommandBuilder } from "./builders.js";
+import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
 /**
  * Kill the process group of `proc` with `signal`, falling back to
  * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
@@ -103,12 +104,10 @@ function pathCandidatesForCurrentPlatform(home) {
 function resolveSpawnFn(options) {
     if (options.spawn)
         return options.spawn;
-    // Pull from globalThis so tests that swap it out at module level are honoured.
-    const bun = globalThis.Bun;
-    if (!bun?.spawn) {
-        throw new Error("Bun.spawn is unavailable; pass options.spawn for non-Bun environments.");
-    }
-    return bun.spawn.bind(bun);
+    // Default to the runtime-boundary spawn, which delegates to the native
+    // subprocess API on each runtime. Tests inject `options.spawn` to avoid
+    // poking real binaries.
+    return runtimeSpawn;
 }
 /**
  * Build the child env. Starts empty and copies through:
@@ -169,7 +168,7 @@ async function readStream(stream, opts) {
  *
  * Failure modes (see {@link AgentFailureReason}):
  *
- *   • `spawn_failed`  — `Bun.spawn` threw synchronously.
+ *   • `spawn_failed`  — the spawn call threw synchronously.
  *   • `timeout`       — exceeded the resolved timeout.
  *   • `non_zero_exit` — child exited with a non-zero code.
  *   • `parse_error`   — `parseOutput === "json"` and stdout was not JSON.
@@ -233,7 +232,7 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     // Hard timeout. We prefer SIGTERM, then SIGKILL if SIGTERM is ignored,
-    // but Bun.spawn only exposes a single .kill() — one signal is enough
+    // but the subprocess only exposes a single .kill() — one signal is enough
     // for the structured-failure contract.
     //
     // BUG-M3: only flag `timedOut` when the child has not already exited. A

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

@@ -0,0 +1,48 @@
+// 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/.
+/**
+ * Claude Code agent command builder (migrated from `agent/builders.ts`, #563).
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * argv the `claude` CLI expects. This is the Claude-specific slice of the
+ * builder strategy; the shared infrastructure (`AgentCommandBuilder`,
+ * `getCommandBuilder`, the OpenCode/default builders, 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 `claudeBuilder`. The builder's `platform` stays `'claude'` (the
+ * canonical harness id).
+ */
+import { assertNotFlag, normalizeTools } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.js";
+/**
+ * Claude Code builder.
+ * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ *
+ * --print switches Claude Code to non-interactive captured output mode.
+ */
+export const claudeBuilder = {
+    platform: "claude",
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        if (req.tools) {
+            args.push("--allowedTools", normalizeTools(req.tools));
+        }
+        // --print = non-interactive, outputs to stdout — required for captured mode
+        args.push("--print");
+        args.push("--");
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};

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

@@ -0,0 +1,70 @@
+// 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/.
+/**
+ * Claude Code LLM-config importer (migrated from `setup/harness-config-import.ts`,
+ * #563).
+ *
+ * Detects a Claude Code 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 OpenCode importer stay in
+ * `setup/harness-config-import.ts`, which 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 a Claude Code installation.
+ *
+ * Claude Code stores settings in `~/.claude/settings.json` or `~/.claude.json`.
+ * The model field may appear at the root or under `env.ANTHROPIC_MODEL`.
+ * The API key is always `ANTHROPIC_API_KEY`.
+ */
+export const claudeCodeImporter = {
+    harnessName: "Claude Code",
+    detect() {
+        const home = homeDir();
+        // Claude Code is installed if the ~/.claude/ directory exists
+        return fs.existsSync(path.join(home, ".claude"));
+    },
+    importConfig() {
+        const home = homeDir();
+        // Try ~/.claude/settings.json, then ~/.claude.json
+        const candidates = [path.join(home, ".claude", "settings.json"), path.join(home, ".claude.json")];
+        for (const filePath of candidates) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+                // Claude Code settings: model may be at root or nested under env
+                const envBlock = raw.env;
+                const model = typeof raw.model === "string"
+                    ? raw.model
+                    : typeof envBlock?.ANTHROPIC_MODEL === "string"
+                        ? String(envBlock.ANTHROPIC_MODEL)
+                        : undefined;
+                return {
+                    harnessName: "Claude Code",
+                    provider: "anthropic",
+                    model: model ?? "claude-sonnet-4-5",
+                    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+                };
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        // ~/.claude exists but no readable settings — still return basic Anthropic config
+        return {
+            harnessName: "Claude Code",
+            provider: "anthropic",
+            model: "claude-sonnet-4-5",
+            apiKeyEnvVar: "ANTHROPIC_API_KEY",
+        };
+    },
+};

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

@@ -0,0 +1,64 @@
+// 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/.
+/**
+ * Claude Code harness (#563).
+ *
+ * This is the per-harness barrel that gathers the Claude Code integration
+ * surfaces that were previously scattered across the codebase:
+ *   - session-log reader     → ./session-log.ts   (ClaudeCodeProvider)
+ *   - agent command builder  → ./agent-builder.ts (claudeBuilder)
+ *   - config importer        → ./config-import.ts (claudeCodeImporter)
+ *
+ * It also defines {@link ClaudeHarness}, the {@link AkmHarness} descriptor that
+ * `HARNESS_REGISTRY` registers.
+ *
+ * ## id normalization bridge ('claude' vs 'claude-code')
+ *
+ * The canonical, persisted id is `'claude'` (used by the agent runner, agent
+ * profiles, the Zod config schema and `--type` resolution after normalization).
+ * `'claude-code'` is the historical RUNTIME identity — the string stamped on
+ * session-log events/refs, the extracted-session dedup key, and the value
+ * `resolveAgentIdentity` reports. It is registered as an `alias` and exposed as
+ * `runtimeId` so BOTH directions round-trip via `normalizeHarnessId()` /
+ * `denormalizeRuntimeIdentity()`. Existing persisted configs and session logs
+ * that say `'claude-code'` keep working unchanged.
+ */
+import { BaseHarness } from "../types.js";
+export { claudeBuilder } from "./agent-builder.js";
+export { claudeCodeImporter } from "./config-import.js";
+export { ClaudeCodeProvider } from "./session-log.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * Claude Code.
+ *
+ * Canonical id is `'claude'`; `'claude-code'` is the runtime/session-log
+ * identity and is registered as an alias so both directions round-trip.
+ */
+export class ClaudeHarness extends BaseHarness {
+    id = "claude";
+    displayName = "Claude Code";
+    aliases = ["claude-code"];
+    runtimeId = "claude-code";
+    // Home-relative config dir scanned by `akm setup` (#567). Claude Code has a
+    // session-log provider, so offering it as a stash source is functional.
+    setupDetectionDir = ".claude";
+    capabilities = caps({
+        sessionLogs: true,
+        agentDispatch: true,
+        detection: true,
+        configImport: true,
+        runtimeIdentity: true,
+        v1Migration: true,
+    });
+}

package/dist/integrations/{session-logs/providers/claude-code.js → harnesses/claude/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";
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
 /**
  * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
@@ -75,7 +75,22 @@ function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
         filePath,
     };
 }
+/**
+ * Claude Code native session-log reader.
+ *
+ * id-normalization note (#563): the canonical harness id is `'claude'`, but
+ * the provider's `name` — which is STAMPED onto every {@link SessionEvent} /
+ * {@link SessionRef} (`harness: this.name`), used as the extracted-session
+ * dedup key, and embedded in `session:<harness>:<id>` proposal refs — stays
+ * `'claude-code'` (the harness runtimeId). Changing it would silently break
+ * round-tripping of already-persisted session-tracking rows and refs. Registry
+ * lookups normalize `'claude-code'` → `'claude'` via the #562 bridge
+ * (`getHarness`), and the `--type` flag accepts both, so the canonical id and
+ * the persisted runtime string coexist without drift.
+ */
 export class ClaudeCodeProvider {
+    // Runtime identity (NOT the canonical id) — see class doc. Equals
+    // HARNESS_BY_ID.get("claude").runtimeId.
     name = "claude-code";
     isAvailable() {
         return fs.existsSync(CLAUDE_PROJECTS_DIR);

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;
+    },
+};