akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/assets/ui/config.js

@@ -34,16 +34,32 @@ function node(key, value, path, sources, depth) {
   return html`<li class="leaf"><span class="mono key">${key}</span><span class="leaf-value">${leafValue(value)}</span>${sourceBadge(source)}</li>`;
 }
 
-function enginesTable(engines) {
-  if (engines.length === 0) return emptyState("No engines are configured.");
-  const rest = (e) => {
-    const { name, kind, endpoint, model, ...others } = e;
-    return Object.keys(others).length > 0 ? JSON.stringify(others) : "";
-  };
+/** What a table shows of an entry beyond its named columns, as compact JSON. */
+function otherFields(entry, shown) {
+  const rest = Object.fromEntries(Object.entries(entry).filter(([key]) => !shown.includes(key)));
+  return Object.keys(rest).length > 0 ? JSON.stringify(rest) : "";
+}
+
+function connectionsTable(connections) {
+  if (connections.length === 0) return emptyState("No connections are configured.");
+  const aliases = (c) =>
+    Object.entries(c.models ?? {})
+      .map(([alias, entry]) => `${alias}: ${typeof entry === "string" ? entry : entry.model}`)
+      .join(", ");
+  return tableWrap(
+    html`<table><thead><tr><th>Name</th><th>Endpoint</th><th>Models</th><th>Other</th></tr></thead><tbody>${connections.map(
+      (c) =>
+        html`<tr><td class="mono">${c.name}</td><td class="mono wrap">${c.endpoint ?? ""}</td><td class="mono wrap">${aliases(c)}</td><td class="mono small wrap">${otherFields(c, ["name", "endpoint", "models"])}</td></tr>`,
+    )}</tbody></table>`,
+  );
+}
+
+function harnessesTable(harnesses) {
+  if (harnesses.length === 0) return emptyState("No harnesses are configured.");
   return tableWrap(
-    html`<table><thead><tr><th>Name</th><th>Kind</th><th>Endpoint</th><th>Model</th><th>Other</th></tr></thead><tbody>${engines.map(
-      (e) =>
-        html`<tr><td class="mono">${e.name}</td><td>${e.kind}</td><td class="mono wrap">${e.endpoint ?? ""}</td><td class="mono">${e.model ?? ""}</td><td class="mono small wrap">${rest(e)}</td></tr>`,
+    html`<table><thead><tr><th>Name</th><th>Platform</th><th>Other</th></tr></thead><tbody>${harnesses.map(
+      (h) =>
+        html`<tr><td class="mono">${h.name}</td><td class="mono">${h.platform ?? h.name}</td><td class="mono small wrap">${otherFields(h, ["name", "platform"])}</td></tr>`,
     )}</tbody></table>`,
   );
 }
@@ -58,7 +74,8 @@ export async function render() {
     ])}${data.exists ? "" : html`<p class="muted">There is no config file, so everything below is a default.</p>`}</section>
     <section><h2>Effective config</h2><p class="legend-line">Source: ${sourceBadge("default")} built-in ${sourceBadge("file")} this install's config.json ${sourceBadge("extends:ref")} a config it extends</p>
       ${keys.length === 0 ? emptyState("The effective config is empty.") : html`<ul class="tree root">${keys.map((k) => node(k, data.config[k], k, sources, 0))}</ul>`}</section>
-    <section><h2>Engines</h2>${enginesTable(data.engines)}</section>
+    <section><h2>Connections</h2>${connectionsTable(data.connections)}</section>
+    <section><h2>Harnesses</h2>${harnessesTable(data.harnesses)}</section>
     <section><h2>Environment</h2><p class="muted">AKM_* variables set for the server. They override paths and credentials.</p>${
       data.env.length === 0
         ? emptyState("No AKM_* environment variables are set.")

package/dist/assets/workflows/workflow-template.md

@@ -37,8 +37,8 @@ first step's attached artifact."
 
 A `### gate` sub-heading is the step's completion rubric: the judge
 receives this whole section byte-exact. Omit the heading or leave its text
-empty to skip validation. A non-empty rubric requires
-`workflow.judgeEngine`; verifier failures and malformed verdicts reject the
+empty to skip validation. A non-empty rubric needs a connection or a harness
+to judge it; verifier failures and malformed verdicts reject the
 gate rather than silently skipping it.
 
 - Confirm the step accomplished what it set out to do.

package/dist/cli/clack.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/.
-import { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
+import { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, password as realPassword, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
 // ── Test seam ────────────────────────────────────────────────────────────────
 // Swap-and-restore override. Inert in production; only tests call the setter
 // (via tests/_helpers/seams.ts `overrideSeam`, never directly).
@@ -18,6 +18,7 @@ const realFns = {
     select: realSelect,
     multiselect: realMultiselect,
     text: realText,
+    password: realPassword,
     spinner: realSpinner,
     note: realNote,
     isCancel: realIsCancel,
@@ -42,6 +43,7 @@ export const confirm = bind("confirm");
 export const select = bind("select");
 export const multiselect = bind("multiselect");
 export const text = bind("text");
+export const password = bind("password");
 export const spinner = bind("spinner");
 export const note = bind("note");
 export const isCancel = bind("isCancel");

package/dist/cli/selection.js

@@ -0,0 +1,33 @@
+// 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 { UsageError } from "../core/errors.js";
+import { warnOnce } from "../core/warn.js";
+import { getStringArg } from "./parse-args.js";
+export const SELECTION_ARGS = {
+    connection: { type: "string", description: "Run on this connection, by name (default: the default connection)" },
+    harness: { type: "string", description: "Run on this harness, by name or platform (default: the default harness)" },
+    model: { type: "string", description: "Model to run, by alias (fast, balanced, reasoning) or exact name" },
+};
+/** The retired `--engine`: parsed, left out of `--help` (`withoutHiddenArgs`). Spread it where the flag existed. */
+export const RETIRED_ENGINE_ARG = {
+    engine: { type: "string", hidden: true, description: "Retired: use --connection or --harness." },
+};
+export function selectionFromArgs(args) {
+    const connection = getStringArg(args, "connection");
+    const harness = getStringArg(args, "harness");
+    if (connection !== undefined && harness !== undefined) {
+        throw new UsageError("--connection and --harness are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+    }
+    const engine = getStringArg(args, "engine");
+    if (engine !== undefined) {
+        warnOnce("retired-flag:--engine", "--engine is retired: use --connection or --harness. For now it names a connection by that name, else a harness.");
+    }
+    const model = getStringArg(args, "model");
+    return {
+        ...(connection !== undefined ? { connection } : {}),
+        ...(harness !== undefined ? { harness } : {}),
+        ...(engine !== undefined ? { engine } : {}),
+        ...(model !== undefined ? { model } : {}),
+    };
+}

package/dist/cli/shared.js

@@ -92,7 +92,7 @@ function extractHint(error) {
  * R-067: this used to call `process.exit(exitCode)` directly, which
  * terminates the process synchronously and skips every pending `finally`
  * block up the call stack — including `src/cli.ts`'s own
- * `disposeDispatchResources()` cleanup and citty's per-command `cleanup`
+ * `disposeLlmUsageSink()` cleanup and citty's per-command `cleanup`
  * hooks. `process.exitCode = exitCode; return;` is equivalent for every
  * caller here: Node/Bun exits with that code once the event loop drains
  * naturally, but cleanup on the way there still runs.
@@ -183,6 +183,19 @@ export const GLOBAL_OUTPUT_ARGS = {
         default: false,
     },
 };
+/**
+ * A command with the args marked `hidden` left out: what `--help` renders. A
+ * hidden arg parses like any other and is simply not advertised, the way
+ * `meta.hidden` keeps a command out of the COMMANDS list. It is for a retired
+ * spelling that still works, so a scheduled command written for an earlier
+ * release keeps running.
+ */
+export function withoutHiddenArgs(command) {
+    const args = command.args;
+    if (!args)
+        return command;
+    return { ...command, args: Object.fromEntries(Object.entries(args).filter(([, def]) => def.hidden !== true)) };
+}
 /**
  * Define a citty command whose `run` body is automatically wrapped in
  * `runWithJsonErrors`, so the handler emits a byte-identical JSON error

package/dist/cli/unknown-flags.js

@@ -25,6 +25,7 @@
  * by a `meta.name` alias rather than its key takes the stand-down path (no
  * validation) — conservative by design.
  */
+import { closestMatch } from "../core/closest-match.js";
 import { UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
 import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } from "./invocation.js";
@@ -61,7 +62,8 @@ function collectKnownArgs(root, rawArgs) {
             // Shared args (GLOBAL_OUTPUT_ARGS) recur at every level; suggest each once.
             if (!names.has(comparable)) {
                 names.add(comparable);
-                displayNames.push(`--${key}`);
+                if (def.hidden !== true)
+                    displayNames.push(`--${key}`);
             }
             if (def.type === "string" || def.type === "enum")
                 valueFlags.add(comparable);
@@ -100,37 +102,6 @@ function collectKnownArgs(root, rawArgs) {
     }
     return { names, valueFlags, booleanFlags, displayNames, path, resolved: true };
 }
-/** Single-row-at-a-time edit-distance DP (inputs are short flag/command names). */
-function editDistance(a, b) {
-    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
-    for (let i = 1; i <= a.length; i += 1) {
-        const current = [i];
-        for (let j = 1; j <= b.length; j += 1) {
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + cost));
-        }
-        previous = current;
-    }
-    return previous[b.length] ?? 0;
-}
-/**
- * Closest candidate within `threshold` edit distance, or undefined when
- * nothing is close enough to be worth suggesting. Shared by the unknown-flag
- * and unknown-command (src/cli.ts) did-you-mean paths, which pick different
- * thresholds.
- */
-export function closestMatch(attempted, candidates, threshold) {
-    let best;
-    let bestDistance = Number.POSITIVE_INFINITY;
-    for (const candidate of candidates) {
-        const distance = editDistance(attempted, candidate);
-        if (distance < bestDistance) {
-            bestDistance = distance;
-            best = candidate;
-        }
-    }
-    return best !== undefined && bestDistance <= threshold ? best : undefined;
-}
 /**
  * The one unknown-flag rejection, shared by the short- and long-flag scans so
  * the user-facing error contract cannot drift between them. No explicit hint
@@ -164,13 +135,11 @@ export function assertKnownFlags(root, rawArgs) {
     // `workflow run`, `task run`, and `task explain` each own one deliberately
     // dynamic namespace: long options become exact-name parameter/input flags
     // and are checked against the frozen plan / task source's own contract
-    // before this gate would otherwise reject them (spec
-    // docs/plans/specs/p2a-task-source-v4.md §5.1 — task run's
+    // before this gate would otherwise reject them (task run's
     // UNKNOWN_FLAG/INPUT_BINDING_INVALID must be raised from INSIDE the command
     // body, where runWithJsonErrors renders the JSON envelope, not from this
-    // generic pre-dispatch gate; docs/plans/specs/p2b-input-bindings.md §4.5,
-    // B-55 — `task explain` reuses the identical `parseTaskInputFlags`
-    // scanner, so it needs the identical exemption).
+    // generic pre-dispatch gate; `task explain` reuses the identical
+    // `parseTaskInputFlags` scanner, so it needs the identical exemption).
     const dynamicNamedFlagCommands = new Set(["workflow run", "task run", "task explain"]);
     const dynamicWorkflowParams = dynamicNamedFlagCommands.has(known.path.join(" "));
     const tolerant = UNKNOWN_FLAG_TOLERANT_COMMANDS.has(known.path.join(" "));

package/dist/cli.js

@@ -58,8 +58,8 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
 import { findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
-import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
-import { assertKnownFlags, closestMatch } from "./cli/unknown-flags.js";
+import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, withoutHiddenArgs, } from "./cli/shared.js";
+import { assertKnownFlags } from "./cli/unknown-flags.js";
 import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
 import { commandCommand } from "./commands/command/command-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
@@ -68,6 +68,7 @@ import { envCommand } from "./commands/env/env-cli.js";
 import { secretCommand } from "./commands/env/secret-cli.js";
 import { feedbackCommand } from "./commands/feedback-cli.js";
 import { akmHealth } from "./commands/health.js";
+import { closestMatch } from "./core/closest-match.js";
 import "./commands/health/renderers.js";
 import "./commands/metrics/md-report.js";
 import { parseWindowSpec } from "./commands/health/windows.js";
@@ -95,7 +96,6 @@ import { getConfigPath } from "./core/paths.js";
 import { DURATION_UNITS, parseDuration } from "./core/time.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
-import { disposeDispatchResources } from "./integrations/agent/runner-dispatch.js";
 import { installLlmUsagePersistenceIfAbsent } from "./llm/usage-persist.js";
 import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints.js";
 import { getOutputMode, initOutputMode, parseDetailLevel } from "./output/context.js";
@@ -120,8 +120,8 @@ function applyEarlyStderrFlags(argv) {
  * Default --format is `json`, so a CI or piped consumer sees only the JSON on
  * stdout. But an interactive user running `akm setup --yes` would otherwise
  * see only the JSON blob with no obvious next step. When stderr is a TTY and
- * the JSON went to stdout, print a two-line summary to stderr telling the
- * user (a) where the stash landed and (b) what to run next.
+ * the JSON went to stdout, print a short summary to stderr telling the user
+ * (a) where the stash landed, (b) what runs where, and (c) what to run next.
  *
  * Silent when: stderr is not a TTY (CI, pipes), --format=text/yaml (the user
  * already gets readable output), --quiet, or the result is missing fields.
@@ -136,7 +136,10 @@ function printSetupTtyHint(result) {
         return;
     if (!result?.bundleDir)
         return;
-    console.error(plainize(`\n✓ Bundle created at ${result.bundleDir}\n` +
+    const runs = result.runs
+        ? `  Model calls:  ${result.runs.modelCalls}\n  Agent work:   ${result.runs.agentWork}\n  Embeddings:   ${result.runs.embeddings}\n`
+        : "";
+    console.error(plainize(`\n✓ Bundle created at ${result.bundleDir}\n${runs}` +
         '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm hints`'));
 }
 /**
@@ -149,7 +152,7 @@ function printSetupTtyHint(result) {
 const setupCommand = defineCommand({
     meta: {
         name: "setup",
-        description: "Interactive configuration wizard. Configures embeddings/LLM connections (for indexing/enrichment), agent profiles (CLI agent, embedded SDK, or none), sources, and registries. Shows which features are enabled at the end. Use --config <json> or --yes for non-interactive/scripting mode.",
+        description: "Interactive configuration wizard. Enables agent programs (Claude Code, Codex, OpenCode, ...), sets up a model connection and embeddings, and picks bundle sources and registries. Flags answer individual questions; --yes takes the detected default for the rest, for scripting.",
     },
     args: {
         // R-051/S11: `setup` is a raw `defineCommand` (not `defineJsonCommand`),
@@ -157,9 +160,33 @@ const setupCommand = defineCommand({
         // already had. Three of its four run branches call `output()`; spreading
         // this in is a `--help` visibility fix, not a behavior change.
         ...GLOBAL_OUTPUT_ARGS,
-        config: {
+        endpoint: {
             type: "string",
-            description: 'Config JSON to apply non-interactively, e.g. \'{"engines":{"local":{"kind":"llm","endpoint":"...","model":"..."}},"defaults":{"llmEngine":"local"}}\'',
+            description: "OpenAI-compatible endpoint to add or update as a connection (the first is named default), e.g. http://localhost:11434/v1",
+        },
+        "api-key-env": {
+            type: "string",
+            description: "Name of the environment variable holding the connection's API key; the connection gets apiKey: $NAME. Keys are never passed on the command line.",
+        },
+        name: {
+            type: "string",
+            description: "Name for a further connection (with --endpoint); the first connection is named default",
+        },
+        harness: {
+            type: "string",
+            description: "Agent programs to enable, comma-separated (claude,codex,opencode,...); the first is the default",
+        },
+        embedding: {
+            type: "string",
+            description: "Embeddings: a model the connection serves, local (the built-in embedder), or off",
+        },
+        "embedding-endpoint": {
+            type: "string",
+            description: "Another endpoint that serves the --embedding model",
+        },
+        "embedding-api-key-env": {
+            type: "string",
+            description: "Name of the environment variable holding the embedding endpoint's API key",
         },
         from: {
             type: "string",
@@ -168,11 +195,11 @@ const setupCommand = defineCommand({
         yes: {
             type: "boolean",
             default: false,
-            description: "Accept all defaults, skip all prompts. Idempotent — safe to run in CI.",
+            description: "Take the detected default for every question no flag answers; no prompts. Idempotent — safe to run in CI.",
         },
         dir: {
             type: "string",
-            description: "Bundle directory path (overrides defaultBundle in config or --config JSON)",
+            description: "Bundle directory path (overrides defaultBundle in config)",
         },
         // Declared as the POSITIVE name with `default: true` so citty's native
         // `--no-<name>` negation (it strips a leading `--no-` from ANY token and
@@ -186,19 +213,32 @@ const setupCommand = defineCommand({
             default: true,
             description: "Scaffold the bundle directory. Use --no-init to write configuration without scaffolding it.",
         },
-        probe: {
+        // There is no `--probe`: probing is the default, so only the opt-out is declared. citty parses `--no-probe`
+        // as the negation of `probe` whether or not `probe` is declared, so the value is `args.probe === false`;
+        // declaring `no-probe` is what puts the flag in `--help` and keeps the unknown-flag check from refusing it.
+        "no-probe": {
             type: "boolean",
-            default: false,
-            description: "Probe LLM/embedding endpoints before writing config to verify connectivity",
+            description: "Offline run: the endpoint is not contacted and its models are not listed. A connection added this way has no model until one is named with `akm models set`; the picks it already has are kept.",
         },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const noInit = !args.init;
-            if (args.from && args.config) {
-                throw new UsageError("Pass either --from <file> or --config <json>, not both.", "INVALID_FLAG_VALUE");
-            }
+            const noProbe = args.probe === false;
+            const { hasSetupFlags, parseSetupFlags } = await import("./setup/setup-flags.js");
+            const flags = parseSetupFlags({
+                endpoint: args.endpoint,
+                apiKeyEnv: args["api-key-env"],
+                name: args.name,
+                harness: args.harness,
+                embedding: args.embedding,
+                embeddingEndpoint: args["embedding-endpoint"],
+                embeddingApiKeyEnv: args["embedding-api-key-env"],
+            });
             if (args.from) {
+                if (hasSetupFlags(flags) && !args.yes) {
+                    throw new UsageError("--from takes --endpoint, --harness and the other answer flags only with --yes.", "INVALID_FLAG_VALUE");
+                }
                 // File-based bootstrap. `loadSetupConfigFromFile` expands a leading
                 // `~`, resolves relative paths against cwd, picks the YAML or JSON
                 // parser based on the file extension, and surfaces any
@@ -211,21 +251,8 @@ const setupCommand = defineCommand({
                     configJson: loaded.configJson,
                     dir: args.dir,
                     noInit,
-                    probe: args.probe,
-                    applyDefaults: args.yes,
-                });
-                output("setup", result);
-                printSetupTtyHint(result);
-            }
-            else if (args.config) {
-                // Non-interactive config mode. With `--yes`, defaults fill any keys
-                // the JSON blob leaves missing after the deep merge.
-                const { runSetupFromConfig } = await import("./setup/setup.js");
-                const result = await runSetupFromConfig({
-                    configJson: args.config,
-                    dir: args.dir,
-                    noInit,
-                    probe: args.probe,
+                    noProbe,
+                    flags,
                     applyDefaults: args.yes,
                 });
                 output("setup", result);
@@ -234,11 +261,7 @@ const setupCommand = defineCommand({
             else if (args.yes) {
                 // Defaults mode — no prompts
                 const { runSetupWithDefaults } = await import("./setup/setup.js");
-                const result = await runSetupWithDefaults({
-                    dir: args.dir,
-                    noInit,
-                    probe: args.probe,
-                });
+                const result = await runSetupWithDefaults({ dir: args.dir, noInit, noProbe, flags });
                 output("setup", result);
                 printSetupTtyHint(result);
             }
@@ -248,10 +271,10 @@ const setupCommand = defineCommand({
                 // first prompt and then block forever instead of failing — and `akm
                 // setup` is the first command users automate.
                 if (process.stdin.isTTY !== true) {
-                    throw new UsageError("Interactive setup requires a TTY. Pass --yes to accept defaults, or --config <json> / --from <file> to configure non-interactively.", "NON_INTERACTIVE_REQUIRES_YES");
+                    throw new UsageError("Interactive setup requires a TTY. Pass --yes to take the detected defaults (flags such as --endpoint answer questions), or --from <file> to configure from a file.", "NON_INTERACTIVE_REQUIRES_YES");
                 }
                 const { runSetupWizard } = await import("./setup/setup.js");
-                await runSetupWizard({ dir: args.dir, noInit });
+                await runSetupWizard({ dir: args.dir, noInit, noProbe, flags });
             }
         });
     },
@@ -298,8 +321,8 @@ const healthCommand = defineCommand({
         probe: {
             type: "boolean",
             default: true,
-            description: "Probe default-llm-engine / configured-engines reachability, check for a newer akm release, and check the scheduler's recorded akm binary version (on by default).",
-            negativeDescription: "Skip the reachability probes, the update check, and the scheduler-binary version check (for an offline or air-gapped host).",
+            description: "Probe configured connections for reachability and run each harness's `--version`, check for a newer akm release, look up the newest Claude plugin tag, and check the scheduler's recorded akm binary version (on by default).",
+            negativeDescription: "Skip the reachability probes, the harness `--version` runs, the update check, the Claude plugin tag lookup, and the scheduler-binary version check (for an offline or air-gapped host).",
         },
     },
     async run({ args }) {
@@ -464,6 +487,7 @@ const commands = {
     registry: registryCommand,
     migrate: migrateCommand,
     config: configCommand,
+    models: modelsCommand,
     feedback: feedbackCommand,
     log: logCommand,
     agent: agentCommand,
@@ -475,14 +499,13 @@ const commands = {
     env: envCommand,
     secret: secretCommand,
     task: taskCommand,
-    models: modelsCommand,
     hints: hintsCommand,
 };
 function commandHelpTopic(name, command) {
     return defineCommand({
         meta: { name, description: `Print help for akm ${name}` },
         async run() {
-            await showUsage(command, buildUsageParentForPath([name]));
+            await showUsage(withoutHiddenArgs(command), buildUsageParentForPath([name]));
         },
     });
 }
@@ -571,8 +594,7 @@ export const main = defineCommand({
 });
 const MAIN_TOP_LEVEL_ARGS = main.args;
 /**
- * F-5 (spec docs/plans/specs/p2a-task-source-v4.md §6): exported so
- * `akm task run`'s input-flags coverage can pin that an undeclared,
+ * Exported so `akm task run`'s input-flags coverage can pin that an undeclared,
  * per-task dynamic flag (e.g. `--scope all`) does not change this
  * classification — it parses only `args.id` off the declared args and
  * tolerates extra tokens (citty's non-strict `parseArgs`).
@@ -1066,7 +1088,7 @@ export async function runCli() {
             }
             else {
                 const path = resolveCittyCommandPath(main, rawArgs);
-                await showUsage(resolved, buildUsageParentForPath(path));
+                await showUsage(withoutHiddenArgs(resolved), buildUsageParentForPath(path));
             }
             return;
         }
@@ -1099,14 +1121,13 @@ export async function runCli() {
         // could ever reach this boundary. Route it the same way rather than
         // hard-coding GENERAL(1): the CLI contract reserves 1 for general/not-found
         // and requires a non-`AkmError` throw to render the JSON failure envelope
-        // with INTERNAL(70) (AGENTS.md "CLI Contract"), which is what lets
+        // with INTERNAL(70), which is what lets
         // automation tell an internal defect apart from an ordinary failure.
         // `emitJsonError` classifies and sets `process.exitCode` itself.
         emitJsonError(error);
     }
     finally {
         disposeLlmUsageSink();
-        await disposeDispatchResources();
     }
 }
 // Only run the CLI when this module is the direct entry point. When it is

package/dist/commands/agent/agent-dispatch.js

@@ -4,23 +4,24 @@
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { isPortableExecutionAgentSelector } from "../../execution/source.js";
-import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { executeInteractiveAgentInvocation } from "../../integrations/agent/runner-dispatch.js";
 import { executeCommandInvocation } from "../command/command-execution.js";
 function canonicalCurrent(options) {
     const current = {};
     if (options.agentRef !== undefined)
         current.agent = options.agentRef;
-    if (options.engine !== undefined)
-        current.engine = options.engine;
+    if (options.selection?.connection !== undefined)
+        current.connection = options.selection.connection;
+    if (options.selection?.harness !== undefined)
+        current.harness = options.selection.harness;
+    if (options.selection?.engine !== undefined)
+        current.engine = options.selection.engine;
     if (options.selection?.model !== undefined)
         current.model = options.selection.model;
     if (Object.hasOwn(options.selection ?? {}, "inference"))
         current.inference = options.selection?.inference;
     if (options.selection?.outputSchema !== undefined)
         current.outputSchema = options.selection.outputSchema;
-    if (options.selection?.tools !== undefined)
-        current.tools = options.selection.tools;
     if (options.timeoutMs !== undefined)
         current.timeout = options.timeoutMs;
     if (options.cwd !== undefined)
@@ -53,30 +54,22 @@ async function delegateCanonicalCommand(options, seams, action) {
 }
 export async function akmAgentDispatch(options, seams = {}) {
     if (!options.agentConfig)
-        throw new UsageError("agent requires a valid config with an agent engine.", "MISSING_REQUIRED_ARGUMENT");
+        throw new UsageError("agent requires a valid config with a harness or connection.", "MISSING_REQUIRED_ARGUMENT");
     rejectInvalidAgentRef(options.agentRef);
-    const hasResolvedSelection = options.agentRef !== undefined || options.selection !== undefined;
-    if (options.prompt !== undefined || hasResolvedSelection) {
-        if (options.prompt === undefined) {
-            throw new UsageError("Agent persona/model/tool/schema/inference selection requires an explicit task from --prompt or --prompt-stdin; it cannot fabricate an empty command. Omit those selections for a prompt-free interactive launch.", "MISSING_REQUIRED_ARGUMENT");
-        }
+    if (options.prompt !== undefined)
         return delegateCanonicalCommand(options, seams, { content: options.prompt });
+    // No prompt: the harness is started for a person. Only where and which model ride along; the rest needs a task.
+    const { connection, harness, engine, model, ...needsTask } = options.selection ?? {};
+    if (options.agentRef !== undefined || Object.keys(needsTask).length > 0) {
+        throw new UsageError("An agent persona, inference setting or output schema applies to a task: pass --prompt or --prompt-stdin. Without a prompt only the harness (and a model) is started.", "MISSING_REQUIRED_ARGUMENT");
     }
-    // Same implicit opencode-sdk fallback the workflow and task surfaces apply,
-    // so an engine-less install is usable everywhere or nowhere — not a mix.
-    const { config: agentConfig, fallbackEngineName } = withEngineFallback(options.agentConfig);
-    const engineName = options.engine ?? agentConfig.defaults?.engine;
-    // Announced, never silent: `options.engine` outranks the default, so the
-    // fallback is only reportable when it is the engine actually selected.
-    const engineAnnouncement = fallbackAnnouncement(fallbackEngineName, engineName);
-    if (engineAnnouncement)
-        warn(engineAnnouncement);
-    if (!engineName)
-        throw new UsageError(`agent ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "MISSING_REQUIRED_ARGUMENT");
     const executeInteractive = seams.executeInteractive ?? executeInteractiveAgentInvocation;
     const execution = await executeInteractive({
-        config: agentConfig,
-        engine: engineName,
+        config: options.agentConfig,
+        ...(typeof connection === "string" ? { connection } : {}),
+        ...(typeof harness === "string" ? { harness } : {}),
+        ...(typeof engine === "string" ? { engine } : {}),
+        ...(typeof model === "string" ? { model } : {}),
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
         ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
     });
@@ -92,6 +85,5 @@ export async function akmAgentDispatch(options, seams = {}) {
         durationMs: result.durationMs,
         ...(result.error !== undefined ? { error: result.error } : {}),
         ...(result.reason !== undefined ? { reason: result.reason } : {}),
-        ...(engineAnnouncement ? { warnings: [engineAnnouncement] } : {}),
     };
 }

package/dist/commands/agent/contribute-cli.js

@@ -23,6 +23,7 @@
 import fs from "node:fs";
 import { defineCommand } from "citty";
 import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { RETIRED_ENGINE_ARG, SELECTION_ARGS, selectionFromArgs } from "../../cli/selection.js";
 import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
@@ -36,13 +37,13 @@ export function readPromptStdin(read = () => fs.readFileSync(0, "utf8")) {
 export const agentCommand = defineCommand({
     meta: {
         name: "agent",
-        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent persona and model defaults. Use --prompt for work; stored commands run through akm command run. Nonempty tool requests require separate operator authorization and are rejected by the current CLI.",
+        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent persona and model defaults. Use --prompt for work; without one the harness starts interactively. Stored commands run through akm command run.",
     },
     args: {
         ...GLOBAL_OUTPUT_ARGS,
         "agent-ref": {
             type: "positional",
-            description: "Optional agent asset ref (e.g. agents/code-reviewer). Resolves persona and model defaults; the current CLI rejects a nonempty tool request without separate operator authorization.",
+            description: "Optional agent asset ref (e.g. agents/code-reviewer). Resolves persona and model defaults.",
             required: false,
         },
         prompt: { type: "string", description: "Task prompt to pass to the agent" },
@@ -51,10 +52,11 @@ export const agentCommand = defineCommand({
             description: "Read the task prompt from stdin (mutually exclusive with --prompt)",
             default: false,
         },
-        engine: { type: "string", description: "Agent engine to use (default: defaults.engine)" },
+        ...SELECTION_ARGS,
+        ...RETIRED_ENGINE_ARG,
         model: {
-            type: "string",
-            description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
+            ...SELECTION_ARGS.model,
+            description: `${SELECTION_ARGS.model.description}. Overrides the model specified in the agent asset.`,
         },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
         cwd: {
@@ -77,14 +79,13 @@ export const agentCommand = defineCommand({
             const cwd = getStringArg(args, "cwd");
             // The common invocation resolver loads a selected agent through its
             // owning bundle adapter. This CLI never re-reads/show-projects the file.
-            const model = getStringArg(args, "model");
+            const selection = selectionFromArgs(args);
             const stdinPrompt = promptStdin ? readPromptStdin() : undefined;
             const result = await akmAgentDispatch({
-                engine: getStringArg(args, "engine"),
                 prompt: stdinPrompt ?? promptText,
                 ...(agentRef === undefined ? {} : { agentRef }),
                 agentConfig,
-                ...(model === undefined ? {} : { selection: { model } }),
+                ...(Object.keys(selection).length === 0 ? {} : { selection }),
                 ...(cwd ? { cwd } : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });