akm-cli 0.9.0-rc.13 → 0.9.0-rc.15

package/dist/indexer/walk/matchers.js

@@ -188,7 +188,9 @@ function classifyBySmartMd(ctx) {
         return { type: "workflow", specificity: 19 };
     }
     if (fm) {
-        if ("toolPolicy" in fm || "tools" in fm) {
+        // `tools` is the one authoring key for an agent's tool grant. Recognition
+        // covers only the key the renderer honors.
+        if ("tools" in fm) {
             return { type: "agent", specificity: 20 };
         }
         if ("agent" in fm) {

package/dist/integrations/agent/config.js

@@ -1,7 +1,7 @@
 // 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/.
-/** Default hard timeout for an agent CLI when neither engine nor call overrides it. */
-export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
+/** Default agent CLI timeout; null means agents run until they finish. */
+export const DEFAULT_AGENT_TIMEOUT_MS = null;
 /** Default hard timeout for direct LLM calls when no engine/use override exists. */
 export const DEFAULT_LLM_TIMEOUT_MS = 600_000;

package/dist/integrations/agent/detect.js

@@ -15,26 +15,34 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getBuiltinAgentProfile, listBuiltinAgentProfiles } from "./profiles.js";
+import { getBuiltinAgentProfile, listBuiltinAgentProfiles, OPENCODE_SDK_SERVER_BIN, } from "./profiles.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on
  * PATH or the env is empty.
  *
- * `process.env.PATH` is split on the platform-correct delimiter; on
- * Windows the binary may have an executable extension, but for v1 we
- * keep this Unix-flavoured (Bun's primary target) and look for an exact
- * match.
+ * `process.env.PATH` is split on the platform-correct delimiter. On Windows
+ * agent CLIs install as extension-bearing shims (`claude.cmd`, `q.exe`), so
+ * each PATH entry is probed for the bare name AND for `<bin><ext>` over
+ * PATHEXT — an exact-match-only probe reports every agent CLI as missing
+ * there, which silently hides the "installed CLI agent" option during setup.
  */
 export function defaultWhich(bin, envSource = process.env) {
+    // Computed once per call — not per PATH entry — since it never varies.
+    const suffixes = executableSuffixes(envSource);
     if (!bin || bin.includes("/") || bin.includes("\\")) {
         // Absolute / relative paths: caller already specified location.
-        try {
-            return fs.statSync(bin).isFile() ? bin : undefined;
-        }
-        catch {
-            return undefined;
+        for (const suffix of suffixes) {
+            const candidate = bin + suffix;
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                /* try the next extension */
+            }
         }
+        return undefined;
     }
     const pathVar = envSource.PATH ?? envSource.Path ?? envSource.path ?? "";
     if (!pathVar)
@@ -43,18 +51,40 @@ export function defaultWhich(bin, envSource = process.env) {
     for (const dir of pathVar.split(sep)) {
         if (!dir)
             continue;
-        const candidate = path.join(dir, bin);
-        try {
-            const st = fs.statSync(candidate);
-            if (st.isFile())
-                return candidate;
-        }
-        catch {
-            /* keep walking */
+        const base = path.join(dir, bin);
+        for (const suffix of suffixes) {
+            const candidate = base + suffix;
+            try {
+                const st = fs.statSync(candidate);
+                if (st.isFile())
+                    return candidate;
+            }
+            catch {
+                /* keep walking */
+            }
         }
     }
     return undefined;
 }
+/** Windows PATHEXT default, used when the env carries no explicit list. */
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/**
+ * Executable suffixes to try for each candidate path, bare name (`""`) first
+ * so POSIX resolution is byte-for-byte unchanged. Extensions are appended only
+ * on win32 or when the env supplies PATHEXT (which is also the seam tests use
+ * to cover Windows resolution from a POSIX runner).
+ */
+function executableSuffixes(envSource) {
+    const pathext = envSource.PATHEXT ?? envSource.Pathext ?? envSource.pathext;
+    if (process.platform !== "win32" && !pathext)
+        return [""];
+    const exts = (pathext ?? DEFAULT_PATHEXT)
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean)
+        .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+    return ["", ...exts];
+}
 let detectOverrides;
 /** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */
 export function _setAgentDetectForTests(fakes) {
@@ -79,7 +109,7 @@ export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
         profilesByName.set(name, {
             name,
             platform: engine.platform,
-            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? "opencode" : engine.platform),
+            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? OPENCODE_SDK_SERVER_BIN : engine.platform),
             args: engine.args ?? builtin?.args ?? [],
             stdio: "captured",
             envPassthrough: builtin?.envPassthrough ?? [],

package/dist/integrations/agent/engine-fallback.js

@@ -0,0 +1,76 @@
+// 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 { defaultWhich } from "./detect.js";
+import { OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
+/**
+ * Engine name used for the synthesized entry. Matches the platform id so it
+ * reads correctly in `akm workflow status`, frozen plans, and error messages.
+ * A user-configured engine of the same name is preferred over synthesizing.
+ */
+export const FALLBACK_ENGINE_NAME = "opencode-sdk";
+/** Announcement text, surfaced once per run/dispatch. */
+export const FALLBACK_ANNOUNCEMENT = `No engine is configured; falling back to \`${FALLBACK_ENGINE_NAME}\` via the ` +
+    `\`${OPENCODE_SDK_SERVER_BIN}\` binary on PATH — provider, model, and auth come ` +
+    "from opencode's own configuration. " +
+    "Run `akm setup`, or set `defaults.engine`, to choose explicitly.";
+/**
+ * Failure suffix for every surface that needs an engine and found none.
+ * Owned HERE, beside the probe whose outcome it describes: the probe follows a
+ * configured `bin` when one is pinned, so a consumer restating "not on PATH"
+ * would misdescribe a missing absolute path.
+ */
+export const NO_ENGINE_MESSAGE_SUFFIX = `has no selected engine, and no usable \`${OPENCODE_SDK_SERVER_BIN}\` binary was found to fall back to.`;
+/**
+ * Guidance used when the fallback itself is unavailable.
+ *
+ * The opencode route names a BINARY install, not `npm i @opencode-ai/sdk`:
+ * that package is an HTTP client with no dependencies and cannot serve
+ * anything on its own (see the module doc).
+ */
+export const NO_ENGINE_REMEDY = "Run `akm setup` to detect an installed agent, or set one explicitly: " +
+    '`akm config set engines.claude \'{"kind":"agent","platform":"claude"}\'` ' +
+    "then `akm config set defaults.engine claude`. " +
+    `Installing the \`${OPENCODE_SDK_SERVER_BIN}\` binary also works ` +
+    "(`npm i -g opencode-ai`) — akm falls back to it automatically.";
+/**
+ * Return a config whose `defaults.engine` resolves, applying the implicit
+ * `opencode-sdk` fallback when it does not and an opencode binary is present.
+ *
+ * Pure with respect to the input: never mutates `config`. Returns the input
+ * object identity unchanged when no fallback is needed, so callers can cheaply
+ * detect the common case.
+ */
+export function withEngineFallback(config, whichFn = defaultWhich) {
+    if (config.defaults?.engine)
+        return { config };
+    // An operator-configured engine of this name wins over a synthesized one —
+    // theirs may carry a model, an llmEngine fallback, or a pinned bin. Probe
+    // THAT bin rather than the bare command: a configured absolute path outside
+    // PATH is still a usable engine, and reporting it as missing would contradict
+    // the operator-configured-wins rule.
+    const existing = config.engines?.[FALLBACK_ENGINE_NAME];
+    if (!whichFn(existing?.bin ?? OPENCODE_SDK_SERVER_BIN))
+        return { config };
+    const engines = existing
+        ? config.engines
+        : { ...(config.engines ?? {}), [FALLBACK_ENGINE_NAME]: { kind: "agent", platform: "opencode-sdk" } };
+    return {
+        config: {
+            ...config,
+            engines,
+            defaults: { ...(config.defaults ?? {}), engine: FALLBACK_ENGINE_NAME },
+        },
+        fallbackEngineName: FALLBACK_ENGINE_NAME,
+    };
+}
+/**
+ * The announcement, but only when the fallback candidate is the engine that
+ * actually won selection. Returns `undefined` otherwise, so an explicitly
+ * selected engine never triggers a claim that opencode supplied the model.
+ */
+export function fallbackAnnouncement(fallbackEngineName, selectedEngineName) {
+    if (!fallbackEngineName || selectedEngineName !== fallbackEngineName)
+        return undefined;
+    return FALLBACK_ANNOUNCEMENT;
+}

package/dist/integrations/agent/profiles.js

@@ -91,6 +91,20 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
+/**
+ * Binary the `opencode-sdk` harness needs on PATH.
+ *
+ * The embedded SDK is not self-contained, and that is the SDK's own design
+ * rather than a consequence of how akm drives it: `@opencode-ai/sdk` ships
+ * with `"dependencies": {}` and its `createOpencodeServer` is itself a
+ * `spawn("opencode", ["serve", ...])`. akm's runner spawns the same binary
+ * directly and talks HTTP to it (see `harnesses/opencode-sdk/sdk-runner.ts`),
+ * so the `opencode` binary gates the SDK path exactly as it gates the CLI
+ * path — a host with the npm package but no binary can dispatch neither.
+ * `opencode-sdk` deliberately has no {@link BUILTINS} entry — it dispatches
+ * without argv construction — so this is the one place that pairing lives.
+ */
+export const OPENCODE_SDK_SERVER_BIN = "opencode";
 /** Names of the canonical built-in harness descriptors. Stable, sorted. */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
 /** Returns the built-in descriptor for a canonical harness id. */

package/dist/integrations/agent/spawn.js

@@ -21,7 +21,6 @@ import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { runManagedSubprocess, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
 /**
  * Supplement `existingPath` with well-known user binary directories when
  * running in a scheduler context (cron/launchd) where PATH is stripped.
@@ -144,7 +143,7 @@ function streamFailureMessage(profileName, stdout, stderr) {
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
     // null = explicitly disabled (no kill timer). undefined = runtime default.
-    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;

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

@@ -4,9 +4,13 @@
 /**
  * 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 the selected fallback LLM engine) for the SDK.
+ * Uses the embedded `@opencode-ai/sdk` instead of `Bun.spawn` for dispatch, so
+ * no agent CLI argv is ever constructed — but the SDK is not self-contained:
+ * {@link createManagedOpencode} spawns `opencode serve` and talks HTTP to it,
+ * so the `opencode` binary must be on PATH (which is why setup's
+ * `detectHarness` gates this harness on that probe). The user provides an
+ * OpenAI-compatible endpoint (or inherits from the selected fallback LLM
+ * engine) for the SDK.
  *
  * This is the runtime surface of the {@link OpencodeSdkHarness} (`id =
  * 'opencode-sdk'`). It is the dispatch path for SDK runner specs; it exposes
@@ -70,7 +74,12 @@
  * until the child ACTUALLY exits — and a real `opencode serve` (a live HTTP
  * server with provider children) can outlive SIGTERM long enough to hang the
  * caller indefinitely. {@link createManagedOpencode} therefore owns the spawn
- * (the SDK package is used only for `createOpencodeClient`):
+ * (the SDK package is used only for `createOpencodeClient`).
+ *
+ * Owning the spawn changes the LIFECYCLE, not the REQUIREMENT: the SDK's
+ * `createOpencodeServer` is itself a `spawn("opencode", ["serve", ...])`, and
+ * the package declares `"dependencies": {}`, so `opencode` must be on PATH
+ * either way. akm's version differs only in how it supervises the child:
  *
  *   - after the URL handshake, the child and its stdio are `unref()`ed /
  *     destroyed, so the handle can never hold akm open;

package/dist/integrations/lockfile.js

@@ -169,9 +169,7 @@ export async function upsertLockEntry(entry) {
  * migrate-apply's config lock + maintenance barrier) whose synchronous body
  * cannot await the sentinel's retry loop. No-op for an empty list.
  */
-export function mergeLockEntriesSync(entries) {
-    if (entries.length === 0)
-        return;
+function readLockEntriesForMigration() {
     let existing = [];
     const lockfilePath = getLockfilePath();
     if (fs.existsSync(lockfilePath)) {
@@ -187,6 +185,16 @@ export function mergeLockEntriesSync(entries) {
         }
         existing = raw;
     }
+    return existing;
+}
+/** Validate the current lockfile before migrate-apply creates its backup or sentinel. */
+export function assertMigrationLockfileReadable() {
+    readLockEntriesForMigration();
+}
+export function mergeLockEntriesSync(entries) {
+    const existing = readLockEntriesForMigration();
+    if (entries.length === 0)
+        return;
     // MERGE per id, never replace: the migrator's entries are sparse (id/source/
     // ref/localRoot), while an existing row may carry `resolvedVersion`,
     // `resolvedRevision`, `integrity`, `installedAt`, … from a real install.
@@ -202,59 +210,6 @@ export function mergeLockEntriesSync(entries) {
     const incomingIds = new Set(entries.map((e) => e.id));
     writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
 }
-/** Freeze exact old/desired lockfile bytes while the migration lifecycle lock is held. */
-export function planLockMergeSync(entries) {
-    const lockfilePath = getLockfilePath();
-    let oldBytes = null;
-    let existing = [];
-    try {
-        oldBytes = fs.readFileSync(lockfilePath, "utf8");
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    if (oldBytes !== null) {
-        let parsed;
-        try {
-            parsed = JSON.parse(oldBytes);
-        }
-        catch (error) {
-            throw new ConfigError(`Cannot plan migration lock entries from unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
-        }
-        if (!Array.isArray(parsed) || !parsed.every(isValidLockfileEntry)) {
-            throw new ConfigError(`Cannot plan migration lock entries from malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
-        }
-        existing = parsed;
-    }
-    if (entries.length === 0)
-        return { oldBytes, desiredBytes: oldBytes };
-    const byId = new Map(existing.map((entry) => [entry.id, entry]));
-    for (const entry of entries)
-        byId.set(entry.id, { ...byId.get(entry.id), ...entry });
-    return { oldBytes, desiredBytes: `${JSON.stringify([...byId.values()], null, 2)}\n` };
-}
-/** Publish a frozen migration lock generation, accepting only exact old or exact desired bytes. */
-export function publishPlannedLockMergeSync(plan) {
-    const lockfilePath = getLockfilePath();
-    let current = null;
-    try {
-        current = fs.readFileSync(lockfilePath, "utf8");
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    if (current === plan.desiredBytes)
-        return;
-    if (current !== plan.oldBytes) {
-        throw new ConfigError(`Refusing migration lockfile publication because ${lockfilePath} is a third generation, neither the journaled old nor desired bytes.`, "INVALID_CONFIG_FILE");
-    }
-    if (plan.desiredBytes === null)
-        return;
-    fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
-    writeFileAtomic(lockfilePath, plan.desiredBytes, 0o600);
-}
 export async function removeLockEntry(id) {
     if (!fs.existsSync(getDataDir()))
         return;

package/dist/output/shapes/passthrough.js

@@ -57,16 +57,10 @@ const PASSTHROUGH_COMMANDS = [
     "update",
     "upgrade",
     "workflow-abandon",
-    "workflow-brief",
-    "workflow-complete",
-    "workflow-complete-rejected",
     "workflow-create",
     "workflow-list",
-    "workflow-next",
-    "workflow-report",
     "workflow-resume",
     "workflow-run",
-    "workflow-start",
     "workflow-status",
 ];
 export const passthroughShapes = PASSTHROUGH_COMMANDS.map((command) => ({

package/dist/output/text/command-format.js

@@ -289,12 +289,12 @@ export function formatSearchPlain(r, detail) {
             if (hasWorkflowHit) {
                 const workflowRef = hits.find((h) => h.type === "workflow");
                 const wfRef = workflowRef && typeof workflowRef.ref === "string" ? workflowRef.ref : topRef;
-                lines.push(`Next: akm show '${topRef}'  |  To start a workflow: akm workflow next '${wfRef}'`);
-                lines.push("After running workflow next: follow each step and run `akm workflow complete <run-id> --step <step-id>` when done.");
+                lines.push(`Next: akm show '${topRef}'  |  To execute a workflow: akm workflow run '${wfRef}'`);
+                lines.push("Inspect the workflow before running it; `workflow run` executes and verifies its steps automatically.");
             }
             else {
                 lines.push(`Next: akm show '${topRef}'`);
-                lines.push("After reading the asset: check whether a workflow applies before editing — if so, use `akm workflow next` instead.");
+                lines.push("After reading the asset: check whether a workflow applies before editing — if so, inspect it and use `akm workflow run`.");
             }
         }
     }

package/dist/output/text/helpers.js

@@ -18,4 +18,4 @@
 export { formatAddPlain, formatBundleShowPlain, formatClonePlain, formatConfigPlain, formatCuratePlain, formatEnvCreatePlain, formatEnvExportPlain, formatEnvListPlain, formatEnvRemovePlain, formatEventLine, formatEventsPlain, formatFeedbackPlain, formatImportPlain, formatIndexPlain, formatInfoPlain, formatInitPlain, formatListPlain, formatRegistryAddPlain, formatRegistryListPlain, formatRegistryRemovePlain, formatRegistrySearchPlain, formatRememberPlain, formatRemovePlain, formatSearchPlain, formatSyncPlain, formatUpdatePlain, formatUpgradePlain, } from "./command-format.js";
 export { formatGateDecisionSummary, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalShowPlain, } from "./proposal-format.js";
 export { formatShowPlain } from "./show-format.js";
-export { formatWorkflowBriefPlain, formatWorkflowCompleteRejectedPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";
+export { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";

package/dist/output/text/show-directives.js

@@ -45,9 +45,7 @@ export function appendShowDirectives(lines, r) {
     if (assetType === "skill" || assetType === "knowledge") {
         const activeRun = r.activeRun;
         if (activeRun) {
-            // Active workflow: redirect agent to workflow commands instead of direct apply
-            lines.unshift(`  akm workflow complete '${activeRun.runId}'${activeRun.stepId ? ` --step '${activeRun.stepId}'` : ""}`);
-            lines.unshift("Read this schema, then follow your workflow step's instructions to edit the workspace file. When done, mark the step complete:");
+            lines.unshift("Read this reference, follow the active unit's instructions, and return the result to the workflow runner. Step completion is automatic.");
             lines.unshift(`WORKFLOW ACTIVE — schema shown as reference (run: ${activeRun.runId})`);
             lines.unshift("---");
             lines.unshift("");
@@ -88,14 +86,14 @@ export function appendShowDirectives(lines, r) {
         const insertIdx = separatorIdx >= 0 ? separatorIdx + 1 : r.type || r.name ? 1 : 0;
         const actionDirective = [
             `ACTION REQUIRED: Do not execute steps manually from this output.`,
-            `Run \`akm workflow next '${workflowRef}'\` to get your current step with exact instructions.`,
+            `Run \`akm workflow run '${workflowRef}'\` to execute the workflow through its declared gates.`,
             "---",
         ];
         lines.splice(insertIdx, 0, "", ...actionDirective);
         lines.push("");
         lines.push("---");
-        lines.push(`NEXT STEP: Run \`akm workflow next '${workflowRef}'\` to see the current workflow step.`);
-        lines.push("Do not edit workspace files before completing each step with `akm workflow complete`.");
+        lines.push(`NEXT STEP: Run \`akm workflow run '${workflowRef}'\` to execute the workflow.`);
+        lines.push("Inspect the workflow first; the runner dispatches and completes each step automatically.");
     }
 }
 /**