akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/setup/steps/connection.js

@@ -9,7 +9,8 @@ import * as p from "../../cli/clack.js";
 import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../integrations/agent/index.js";
 import { probeLlmCapabilities } from "../../llm/client.js";
 import { detectLMStudio, detectOllama } from "../detect.js";
-import { cloneLlmConfig, getCurrentAgentBlock, getCurrentLlm } from "../legacy-config.js";
+import { verifyOpenAiCompatibleEndpoint } from "../detected-engines.js";
+import { cloneLlmConnection, readAgentEngineSelection, readCurrentLlmEngine, } from "../engine-config.js";
 import { prompt, promptOrBack } from "../prompt.js";
 export async function stepOllama(current) {
     const spin = p.spinner();
@@ -154,7 +155,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
     options.push({ value: "lmstudio", label: "LM Studio / local server", hint: lmStudioHint });
     options.push({ value: "custom", label: "Custom OpenAI-compatible endpoint" });
     options.push({ value: "none", label: "Skip LLM", hint: "no metadata enhancement during indexing" });
-    const currentLlm = getCurrentLlm(current);
+    const currentLlm = readCurrentLlmEngine(current);
     if (currentLlm) {
         options.push({
             value: "keep",
@@ -169,7 +170,7 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
         initialValue,
     }));
     if (choice === "keep")
-        return cloneLlmConfig(currentLlm);
+        return cloneLlmConnection(currentLlm);
     if (choice === "none")
         return undefined;
     // Handle "Import from <Harness>" choices
@@ -180,16 +181,28 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels, lmStudi
         // Show a summary before accepting
         p.log.info(`Importing LLM config from ${harness.harnessName}: ` +
             [harness.provider, harness.model, harness.baseUrl].filter(Boolean).join(", "));
+        if (!harness.baseUrl || !harness.model) {
+            p.log.warn(`Skipping ${harness.harnessName}: no complete endpoint/model was detected.`);
+            return undefined;
+        }
+        const verified = await verifyOpenAiCompatibleEndpoint({
+            endpoint: harness.baseUrl,
+            model: harness.model,
+            apiKeyEnvVar: harness.apiKeyEnvVar,
+        });
+        if (!verified.ok) {
+            p.log.warn(`Skipping ${harness.harnessName}: ${verified.reason}. Fix its endpoint/credential and retry setup.`);
+            return undefined;
+        }
         const llmConfig = {
-            endpoint: harness.baseUrl ?? "",
+            endpoint: verified.endpoint,
             model: harness.model ?? "",
             temperature: 0.3,
             maxTokens: 1024,
+            ...(harness.apiKeyEnvVar ? { apiKey: `\${${harness.apiKeyEnvVar}}` } : {}),
         };
         if (harness.provider)
             llmConfig.provider = harness.provider;
-        if (harness.baseUrl)
-            llmConfig.endpoint = harness.baseUrl;
         return llmConfig;
     }
     let llm;
@@ -376,7 +389,7 @@ export async function stepSmallModelConnection(current) {
         ? `${lmStudio.models.length} model${lmStudio.models.length === 1 ? "" : "s"} detected`
         : "http://localhost:1234";
     providerOptions.push({ value: "openai", label: "OpenAI", hint: "requires AKM_LLM_API_KEY" }, { value: "lmstudio", label: "LM Studio / local server", hint: lmStudioHint }, { value: "custom", label: "Custom OpenAI-compatible endpoint" }, { value: "skip", label: "Skip — disable enrichment features" });
-    const currentLlmSmall = getCurrentLlm(current);
+    const currentLlmSmall = readCurrentLlmEngine(current);
     if (currentLlmSmall) {
         providerOptions.push({
             value: "keep",
@@ -391,7 +404,7 @@ export async function stepSmallModelConnection(current) {
         initialValue,
     }));
     if (providerChoice === "keep") {
-        return { llm: cloneLlmConfig(currentLlmSmall), skipped: false, ollamaEndpoint };
+        return { llm: cloneLlmConnection(currentLlmSmall), skipped: false, ollamaEndpoint };
     }
     if (providerChoice === "skip") {
         p.note([
@@ -539,8 +552,11 @@ export async function stepSmallModelConnection(current) {
             validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
         }));
         const apiKeyInput = await promptOrBack(() => p.text({
-            message: "API key (optional — press Enter to skip):",
-            placeholder: "",
+            message: "API key environment variable name (optional):",
+            placeholder: "CUSTOM_LLM_API_KEY",
+            validate: (value) => value && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
+                ? "Use an environment variable name, not a key value"
+                : undefined,
         }));
         llm = {
             provider: "custom",
@@ -548,7 +564,7 @@ export async function stepSmallModelConnection(current) {
             model: model.trim(),
             temperature: 0.3,
             maxTokens: 1024,
-            ...(apiKeyInput?.trim() ? { apiKey: apiKeyInput.trim() } : {}),
+            ...(apiKeyInput?.trim() ? { apiKey: `\${${apiKeyInput.trim()}}` } : {}),
         };
     }
     // Best-effort probe — never blocks setup.
@@ -584,7 +600,7 @@ export async function stepAgentConnection(current, smallModel) {
     ].join("\n"));
     // Detect available CLI agents.
     const detections = detectAgentCliProfiles(current);
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const availableClis = detections.filter((d) => d.available);
     const agentOptions = [];
     if (!smallModel.skipped && smallModel.llm) {
@@ -606,8 +622,8 @@ export async function stepAgentConnection(current, smallModel) {
     if (currentAgentBlock) {
         const currentDesc = currentAgentBlock.default
             ? `CLI: ${currentAgentBlock.default}`
-            : currentAgentBlock.profiles?.default?.model
-                ? `SDK: ${currentAgentBlock.profiles.default.model}`
+            : currentAgentBlock.engines?.default?.model
+                ? `SDK: ${currentAgentBlock.engines.default.model}`
                 : "configured";
         agentOptions.push({ value: "keep", label: `Keep current: ${currentDesc}` });
     }
@@ -647,9 +663,9 @@ export async function stepAgentConnection(current, smallModel) {
         else {
             const baseEndpoint = smallModel.llm.endpoint.replace("/v1/chat/completions", "");
             p.log.info(`Endpoint: ${baseEndpoint} (from Step 1)`);
-            const profileName = smallModel.llm.provider ?? "default";
+            const profileName = `${smallModel.llm.provider ?? "default"}-agent`;
             // Pre-populate from existing agent profile for this provider, if any.
-            const existingAgentModel = currentAgentBlock?.profiles?.[profileName]?.model ?? smallModel.llm.model ?? undefined;
+            const existingAgentModel = currentAgentBlock?.engines?.[profileName]?.model ?? smallModel.llm.model ?? undefined;
             const agentModel = await prompt(() => p.text({
                 message: "Model to use for agent tasks (same model is fine, larger models work better):",
                 placeholder: existingAgentModel ?? "qwen2.5-coder:32b",
@@ -658,13 +674,14 @@ export async function stepAgentConnection(current, smallModel) {
             }));
             return {
                 ...(currentAgentBlock ?? {}),
-                profiles: {
-                    ...(currentAgentBlock?.profiles ?? {}),
+                engines: {
+                    ...(currentAgentBlock?.engines ?? {}),
                     [profileName]: {
-                        ...(currentAgentBlock?.profiles?.[profileName] ?? {}),
-                        sdkMode: true,
+                        ...(currentAgentBlock?.engines?.[profileName] ?? {}),
+                        kind: "agent",
+                        platform: "opencode-sdk",
                         model: agentModel.trim(),
-                        endpoint: smallModel.llm.endpoint,
+                        ...(current.defaults?.llmEngine ? { llmEngine: current.defaults.llmEngine } : {}),
                     },
                 },
                 default: profileName,
@@ -693,8 +710,8 @@ export async function stepAgentConnection(current, smallModel) {
     }
     // "new-connection" (also fall-through from "same-provider" when Step 1 was skipped)
     // Pre-populate from current "custom" agent profile if available.
-    const currentCustomAgentProfile = currentAgentBlock?.profiles?.custom;
-    const currentNewEndpoint = currentCustomAgentProfile?.endpoint ?? undefined;
+    const currentCustomAgentProfile = currentAgentBlock?.engines?.["custom-agent"];
+    const currentNewEndpoint = undefined;
     const currentNewModel = currentCustomAgentProfile?.model ?? undefined;
     const newEndpoint = await prompt(() => p.text({
         message: "OpenAI-compatible chat completions endpoint:",
@@ -708,8 +725,11 @@ export async function stepAgentConnection(current, smallModel) {
         },
     }));
     const newApiKeyInput = await promptOrBack(() => p.text({
-        message: "API key (optional — press Enter to skip):",
-        placeholder: "",
+        message: "API key environment variable name (optional):",
+        placeholder: "CUSTOM_LLM_API_KEY",
+        validate: (value) => value && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
+            ? "Use an environment variable name, not a key value"
+            : undefined,
     }));
     const newModel = await prompt(() => p.text({
         message: "Model name (larger is better, e.g. gpt-4o):",
@@ -717,18 +737,27 @@ export async function stepAgentConnection(current, smallModel) {
         ...(currentNewModel ? { defaultValue: currentNewModel } : {}),
         validate: (v) => (!v?.trim() ? "Model name cannot be empty" : undefined),
     }));
+    const llmEngineName = "custom-llm";
+    const agentEngineName = "custom-agent";
     const customProfile = {
-        sdkMode: true,
-        endpoint: newEndpoint.trim(),
+        kind: "agent",
+        platform: "opencode-sdk",
+        llmEngine: llmEngineName,
         model: newModel.trim(),
-        ...(newApiKeyInput?.trim() ? { apiKey: newApiKeyInput.trim() } : {}),
     };
     return {
         ...(currentAgentBlock ?? {}),
-        profiles: {
-            ...(currentAgentBlock?.profiles ?? {}),
-            custom: customProfile,
+        engines: {
+            ...(currentAgentBlock?.engines ?? {}),
+            [llmEngineName]: {
+                kind: "llm",
+                provider: "custom",
+                endpoint: newEndpoint.trim(),
+                model: newModel.trim(),
+                ...(newApiKeyInput?.trim() ? { apiKey: `\${${newApiKeyInput.trim()}}` } : {}),
+            },
+            [agentEngineName]: customProfile,
         },
-        default: "custom",
+        default: agentEngineName,
     };
 }

package/dist/setup/steps/platforms.js

@@ -8,7 +8,7 @@
 import * as p from "../../cli/clack.js";
 import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../integrations/agent/index.js";
 import { detectAgentPlatforms } from "../detect.js";
-import { getCurrentAgentBlock } from "../legacy-config.js";
+import { readAgentEngineSelection } from "../engine-config.js";
 import { prompt } from "../prompt.js";
 export async function stepAgentPlatforms(current) {
     const platforms = detectAgentPlatforms();
@@ -66,7 +66,7 @@ export function printCapabilitySummary(smallModelSkipped, agentConfigured) {
     p.note(lines.join("\n"), "Feature Summary");
 }
 export async function stepAgentSelection(current, detections) {
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const available = detections.filter((d) => d.available);
     if (available.length === 0) {
         return currentAgentBlock;
@@ -85,7 +85,7 @@ export async function stepAgentSelection(current, detections) {
         initialValue,
     }));
     if (selectedDefault === "disabled") {
-        if (!currentAgentBlock?.profiles && !currentAgentBlock?.timeoutMs) {
+        if (!currentAgentBlock?.engines) {
             return undefined;
         }
         return {
@@ -110,7 +110,7 @@ export async function stepAgentSelection(current, detections) {
  */
 export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
     const detections = detectFn(current);
-    const currentAgentBlock = getCurrentAgentBlock(current);
+    const currentAgentBlock = readAgentEngineSelection(current);
     const defaultName = pickDefaultAgentProfile(detections, currentAgentBlock?.default);
     // No installed agents found and no existing config → leave block absent.
     if (!defaultName && !currentAgentBlock) {

package/dist/setup/steps.js

@@ -1,20 +1,21 @@
 // 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 { deepMergeConfig } from "../core/config/deep-merge.js";
 /**
  * Build a fresh `SetupContext` over a starting config. The returned context
  * applies deltas in-place onto an internal accumulator and exposes the
  * latest snapshot via `ctx.config`.
  */
 export function createSetupContext(initial, options) {
-    let acc = { ...initial };
+    let acc = deepMergeConfig({}, initial);
     return {
         get config() {
             return acc;
         },
         nonInteractive: options.nonInteractive,
         apply(delta) {
-            acc = { ...acc, ...delta };
+            acc = deepMergeConfig(acc, delta);
         },
     };
 }

package/dist/storage/database.js

@@ -133,5 +133,17 @@ function openNodeDatabase(path, opts) {
     if (opts?.create === false)
         options.fileMustExist = true;
     const db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
-    return db;
+    return {
+        prepare: db.prepare.bind(db),
+        exec: db.exec.bind(db),
+        // better-sqlite3 exposes mutations on prepared statements, while
+        // bun:sqlite also provides db.run(). Normalize the latter at the provider
+        // boundary so callers and maintenance wrappers can rely on one contract.
+        run: (sql, ...params) => db.prepare(sql).run(...params),
+        transaction: db.transaction.bind(db),
+        get inTransaction() {
+            return db.inTransaction;
+        },
+        close: db.close.bind(db),
+    };
 }

package/dist/storage/engines/sqlite-migrations.js

@@ -34,6 +34,7 @@ export function runMigrations(db, migrations, opts) {
     for (const migration of migrations) {
         if (applied.has(migration.id))
             continue;
+        opts?.beforeMigration?.(migration);
         db.transaction(() => {
             db.exec(migration.up);
             db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);

package/dist/storage/repositories/improve-runs-repository.js

@@ -103,10 +103,10 @@ export function recordImproveRun(db, input) {
     const metricsObj = input.metrics ?? computeImproveRunMetrics(input.result);
     db.prepare(`
     INSERT INTO improve_runs
-      (id, started_at, completed_at, stash_dir, dry_run, profile,
+       (id, started_at, completed_at, stash_dir, dry_run, profile, strategy,
        scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.legacyProfile ?? null, input.strategy ?? null, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
 }
 /**
  * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
@@ -124,8 +124,8 @@ export function recordImproveRun(db, input) {
  */
 export function queryImproveRuns(db, since, until) {
     const sql = until
-        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
-        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, profile AS legacyProfile, strategy, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, profile AS legacyProfile, strategy, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
     return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
 }
 /**

package/dist/storage/repositories/task-history-repository.js

@@ -1,6 +1,84 @@
 // 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/.
+function metadataError(message) {
+    throw new Error(`invalid task_history metadata_json: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateDetail(value) {
+    if (value === undefined || value === null)
+        return;
+    if (!isRecord(value))
+        metadataError("detail must be an object or null");
+    const allowed = new Set(["runId", "reason", "error", "exitCode"]);
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        metadataError(`unknown detail fields: ${unknown.sort().join(", ")}`);
+    for (const field of ["runId", "reason", "error"]) {
+        if (value[field] !== undefined && typeof value[field] !== "string")
+            metadataError(`detail.${field} must be a string`);
+    }
+    if (value.exitCode !== undefined && value.exitCode !== null && typeof value.exitCode !== "number") {
+        metadataError("detail.exitCode must be a number or null");
+    }
+}
+/** Decode historical v1 and current v2 metadata without cross-version aliases. */
+export function decodeTaskHistoryMetadata(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            metadataError("not valid JSON");
+        }
+    }
+    if (!isRecord(parsed))
+        metadataError("root must be an object");
+    const version = parsed.metadataVersion ?? 1;
+    if (version === 1) {
+        const allowed = new Set(["metadataVersion", "durationMs", "detail", "profile"]);
+        const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
+        if (unknown.length > 0)
+            metadataError(`unknown v1 fields: ${unknown.sort().join(", ")}`);
+        if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 1)
+            metadataError("invalid v1 metadataVersion");
+        if (parsed.durationMs !== undefined && typeof parsed.durationMs !== "number")
+            metadataError("durationMs must be a number");
+        if (parsed.profile !== undefined && typeof parsed.profile !== "string")
+            metadataError("profile must be a string");
+        validateDetail(parsed.detail);
+        return {
+            metadataVersion: 1,
+            ...(typeof parsed.durationMs === "number" ? { durationMs: parsed.durationMs } : {}),
+            ...(parsed.detail !== undefined && parsed.detail !== null ? { detail: parsed.detail } : {}),
+            ...(typeof parsed.profile === "string" ? { legacyProfile: parsed.profile } : {}),
+        };
+    }
+    if (version === 2) {
+        const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine"]);
+        const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
+        if (unknown.length > 0)
+            metadataError(`unknown v2 fields: ${unknown.sort().join(", ")}`);
+        if (typeof parsed.durationMs !== "number")
+            metadataError("durationMs must be a number");
+        if (!("detail" in parsed))
+            metadataError("detail is required in v2");
+        if (parsed.engine !== undefined && parsed.engine !== null && typeof parsed.engine !== "string") {
+            metadataError("engine must be a string or null");
+        }
+        validateDetail(parsed.detail);
+        return {
+            metadataVersion: 2,
+            durationMs: parsed.durationMs,
+            detail: parsed.detail ?? null,
+            ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
+        };
+    }
+    metadataError(`unsupported metadataVersion: ${String(version)}`);
+}
 /**
  * Upsert a task history row.
  */

package/dist/storage/repositories/workflow-runs-repository.js

@@ -137,10 +137,10 @@ export class WorkflowRunsRepository {
      * `insertRun`, so a run row never exists without its frozen plan. Read back
      * via {@link getRunById} (`plan_json` / `plan_hash` on the row).
      */
-    setRunPlan(runId, planJson, planHash) {
+    setRunPlan(runId, planJson, planHash, planIrVersion = 3) {
         this.db
-            .prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ? WHERE id = ?")
-            .run(planJson, planHash, runId);
+            .prepare("UPDATE workflow_runs SET plan_json = ?, plan_hash = ?, plan_ir_version = ? WHERE id = ?")
+            .run(planJson, planHash, planIrVersion, runId);
     }
     // ── engine run lease (migration 006 columns, R2 enforcement) ──────────────
     //
@@ -238,15 +238,16 @@ export class WorkflowRunsRepository {
     insertUnit(input) {
         this.db
             .prepare(`INSERT INTO workflow_run_units (
-          run_id, unit_id, step_id, node_id, parent_unit_id, phase, runner, model,
+          run_id, unit_id, step_id, node_id, parent_unit_id, phase, runner, engine, model,
           status, input_hash, worktree_path, started_at, claim_holder, claim_expires_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?, ?)
         ON CONFLICT(run_id, unit_id) DO UPDATE SET
           step_id          = excluded.step_id,
           node_id          = excluded.node_id,
           parent_unit_id   = excluded.parent_unit_id,
-          phase            = excluded.phase,
-          runner           = excluded.runner,
+           phase            = excluded.phase,
+           runner           = excluded.runner,
+           engine           = excluded.engine,
           model            = excluded.model,
           status           = excluded.status,
           input_hash       = excluded.input_hash,
@@ -261,7 +262,7 @@ export class WorkflowRunsRepository {
           finished_at      = NULL,
           last_checkin_at  = NULL,
           attempts         = workflow_run_units.attempts + 1`)
-            .run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId, input.phase, input.runner, input.model, input.inputHash, input.worktreePath ?? null, input.startedAt, input.claimHolder ?? null, input.claimExpiresAt ?? null);
+            .run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId, input.phase, input.runner, input.engine ?? null, input.model, input.inputHash, input.worktreePath ?? null, input.startedAt, input.claimHolder ?? null, input.claimExpiresAt ?? null);
     }
     /**
      * Stamp a `--status running` claim + heartbeat on a unit row (migration 009,