akm-cli 0.10.261013-beta → 0.10.261015-beta

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, on the platforms that have it; its runtime and model are downloaded now), 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: nothing is contacted or downloaded. The endpoint's models are not listed, so a connection added this way has no model until one is named with `akm models set` (the picks it already has are kept), and the local embedder's runtime and model are fetched by the first `akm index`.",
         },
     },
     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 } : {}),
             });

package/dist/commands/command/command-cli.js

@@ -2,6 +2,7 @@
 // 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 { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { RETIRED_ENGINE_ARG, SELECTION_ARGS, selectionFromArgs } from "../../cli/selection.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { isVerbose, setVerbose, warn, warnVerbose } from "../../core/warn.js";
@@ -30,8 +31,8 @@ export const commandRunCommand = defineJsonCommand({
             type: "string",
             description: "Override the command's agent selector with a portable agent ref or native harness selector",
         },
-        engine: { type: "string", description: "Override the selected execution engine" },
-        model: { type: "string", description: "Override the selected model alias or exact model identifier" },
+        ...SELECTION_ARGS,
+        ...RETIRED_ENGINE_ARG,
         "timeout-ms": { type: "string", description: "Override the execution timeout in milliseconds" },
         cwd: { type: "string", description: "Override the execution workspace/current working directory" },
         "dry-run": {
@@ -46,15 +47,10 @@ export const commandRunCommand = defineJsonCommand({
         const timeoutMs = parsePositiveIntFlag(exactStringArg(args, "timeout-ms"), "--timeout-ms");
         const current = {};
         const agent = getStringArg(args, "agent");
-        const engine = getStringArg(args, "engine");
-        const model = getStringArg(args, "model");
         const workspace = getStringArg(args, "cwd");
         if (agent !== undefined)
             current.agent = agent;
-        if (engine !== undefined)
-            current.engine = engine;
-        if (model !== undefined)
-            current.model = model;
+        Object.assign(current, selectionFromArgs(args));
         if (timeoutMs !== undefined)
             current.timeout = timeoutMs;
         if (workspace !== undefined)