akm-cli 0.9.1 → 0.9.2-alpha.1

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

@@ -1,67 +1,59 @@
 // 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/.
-/**
- * `akm agent [--engine <name>] [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]`
- *
- * Dispatch an agent by named engine, optionally injecting a prompt from
- * inline text, a stash command: asset, or a stash workflow: asset.
- *
- * When none of --prompt, --command, or --workflow are given, the agent is
- * launched interactively (no injected prompt).
- *
- * Template placeholders (`{{0}}`, `{{1}}`, ...) in the loaded asset body are
- * filled from the extra positional args in order.
- */
-import fs from "node:fs";
-import { parseRefInput } from "../../core/asset/resolve-ref.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
+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 { resolveEngine } from "../../integrations/agent/engine-resolution.js";
-import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
-/**
- * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
- * corresponding entries in `args`. Any placeholder index that exceeds the
- * args array is left as-is.
- */
-function fillPlaceholders(template, args) {
-    return template.replace(/\{\{(\d+)\}\}/g, (match, idx) => {
-        const i = Number.parseInt(idx, 10);
-        return i < args.length ? args[i] : match;
-    });
+import { executeInteractiveAgentInvocation } from "../../integrations/agent/execution-lowering.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?.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)
+        current.workspace = options.cwd;
+    return current;
 }
-/**
- * Resolve the body of an asset by ref string. The ref must parse as a
- * valid asset ref (e.g. `command:my-cmd`, `workflow:my-flow`). The file
- * must exist on disk (the index provides the file path).
- *
- * Throws `NotFoundError` when the ref cannot be resolved.
- */
-async function resolveAssetBody(ref) {
-    let parsed;
-    try {
-        parsed = parseRefInput(ref);
-    }
-    catch (err) {
-        throw new UsageError(`Invalid asset ref "${ref}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");
-    }
-    // Lazy import to avoid pulling the full indexer at startup.
-    const { lookup } = await import("../../indexer/indexer.js");
-    const entry = await lookup(parsed);
-    if (!entry) {
-        throw new NotFoundError(`Asset "${ref}" not found in the index. Run \`akm index\` to rebuild the index.`);
-    }
-    try {
-        return fs.readFileSync(entry.filePath, "utf8");
-    }
-    catch (err) {
-        throw new NotFoundError(`Asset "${ref}" is indexed but the file could not be read (${entry.filePath}): ${err instanceof Error ? err.message : String(err)}`);
-    }
+function rejectInvalidAgentRef(agentRef) {
+    if (agentRef === undefined || isPortableExecutionAgentSelector(agentRef))
+        return;
+    throw new UsageError(`agent expects an agent asset ref under agents/...; received ${JSON.stringify(agentRef)}.`, "INVALID_FLAG_VALUE");
+}
+async function delegateCanonicalCommand(options, seams, action) {
+    const execute = seams.executeCommand ?? executeCommandInvocation;
+    const result = await execute({
+        action,
+        config: options.agentConfig,
+        current: canonicalCurrent(options),
+    });
+    for (const message of result.warnings ?? [])
+        warn(message);
+    return result;
 }
-export async function akmAgentDispatch(options) {
+export async function akmAgentDispatch(options, seams = {}) {
     if (!options.agentConfig)
         throw new UsageError("agent requires a valid config with an agent engine.", "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");
+        }
+        return delegateCanonicalCommand(options, seams, { content: options.prompt });
+    }
     // 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);
@@ -73,45 +65,19 @@ export async function akmAgentDispatch(options) {
         warn(engineAnnouncement);
     if (!engineName)
         throw new UsageError(`agent ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "MISSING_REQUIRED_ARGUMENT");
-    const runner = resolveEngine(engineName, agentConfig);
-    if (runner.kind === "llm") {
-        throw new UsageError(`Engine "${engineName}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
-    }
-    const profile = runner.profile;
-    // Resolve the prompt text from whichever source was provided.
-    let prompt;
-    if (options.commandRef) {
-        const body = await resolveAssetBody(options.commandRef);
-        prompt = options.args?.length ? fillPlaceholders(body, options.args) : body;
-    }
-    else if (options.workflowRef) {
-        const body = await resolveAssetBody(options.workflowRef);
-        prompt = options.args?.length ? fillPlaceholders(body, options.args) : body;
-    }
-    else if (options.prompt !== undefined) {
-        prompt = options.prompt;
-    }
-    // When prompt is undefined, the agent is launched interactively.
-    const stdio = prompt === undefined && runner.kind !== "sdk" ? "interactive" : profile.stdio;
-    // Build the final dispatch request: merge the caller-supplied dispatch with
-    // the resolved prompt so the builder has all context in one place.
-    const dispatchRequest = options.dispatch
-        ? { ...options.dispatch, prompt: prompt ?? options.dispatch.prompt }
-        : undefined;
-    const runOptions = {
-        stdio,
-        parseOutput: "text",
-        ...(options.args?.length && !options.commandRef && !options.workflowRef ? { args: options.args } : {}),
+    const executeInteractive = seams.executeInteractive ?? executeInteractiveAgentInvocation;
+    const execution = await executeInteractive({
+        config: agentConfig,
+        engine: engineName,
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-        ...(options.cwd ? { cwd: options.cwd } : {}),
-        ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
-    };
-    const result = await executeRunner(runner, prompt ?? "", runOptions);
+        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    });
+    const result = execution.result;
     return {
         schemaVersion: 2,
         ok: result.ok,
         shape: "agent-result",
-        engine: engineName,
+        engine: execution.engine,
         exitCode: result.exitCode,
         stdout: result.stdout ?? "",
         stderr: result.stderr ?? "",

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

@@ -26,7 +26,6 @@ import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.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";
-import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
 import { getHyphenatedBoolean } from "../../output/context.js";
 import { akmLint } from "../lint/index.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
@@ -37,24 +36,22 @@ 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 asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a bundle agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
+        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.",
     },
     args: {
         ...GLOBAL_OUTPUT_ARGS,
         "agent-ref": {
             type: "positional",
-            description: "Optional agent asset ref (e.g. agents/code-reviewer). Loads system prompt, model, and tool policy from the bundle asset.",
+            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.",
             required: false,
         },
         prompt: { type: "string", description: "Task prompt to pass to the agent" },
         "prompt-stdin": {
             type: "boolean",
-            description: "Read the task prompt from stdin (mutually exclusive with --prompt, --command, and --workflow)",
+            description: "Read the task prompt from stdin (mutually exclusive with --prompt)",
             default: false,
         },
         engine: { type: "string", description: "Agent engine to use (default: defaults.engine)" },
-        command: { type: "string", description: "Load prompt from a command asset" },
-        workflow: { type: "string", description: "Load prompt from a workflow asset" },
         model: {
             type: "string",
             description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
@@ -70,54 +67,24 @@ export const agentCommand = defineCommand({
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const config = loadConfig();
             const agentConfig = config;
-            // Resolve agent asset ref → extract system prompt, model, and tool policy.
+            // Preserve the selector; the common execution-source adapter resolves it.
             const agentRef = getStringArg(args, "agent-ref");
-            let systemPrompt;
-            let assetModel;
-            let assetTools;
-            if (agentRef) {
-                const { akmShowUnified } = await import("../read/show.js");
-                const asset = await akmShowUnified({ ref: agentRef, detail: "full", eventSource: resolveUsageEventSource() });
-                if (asset.type !== "agent") {
-                    throw new UsageError(`Asset ref "${agentRef}" resolves to type "${asset.type}", expected "agent".`, "INVALID_FLAG_VALUE");
-                }
-                systemPrompt = typeof asset.prompt === "string" ? asset.prompt : undefined;
-                assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
-                assetTools = asset.toolPolicy;
-            }
-            // --model flag wins over the asset's modelHint.
-            const model = getStringArg(args, "model") ?? assetModel;
             const promptText = getStringArg(args, "prompt");
-            const commandRef = getStringArg(args, "command");
-            const workflowRef = getStringArg(args, "workflow");
             const promptStdin = args["prompt-stdin"] === true;
-            if (promptStdin && (promptText !== undefined || commandRef !== undefined || workflowRef !== undefined)) {
-                throw new UsageError("--prompt-stdin cannot be combined with --prompt, --command, or --workflow.", "INVALID_FLAG_VALUE");
+            if (promptStdin && promptText !== undefined) {
+                throw new UsageError("--prompt-stdin cannot be combined with --prompt.", "INVALID_FLAG_VALUE");
             }
-            const stdinPrompt = promptStdin ? readPromptStdin() : undefined;
             const cwd = getStringArg(args, "cwd");
-            // Only build a dispatch request when there is something to dispatch — a
-            // prompt, an agent asset, or a model override. When none of these are
-            // present the agent is launched interactively (no injected prompt, no
-            // platform-specific flags beyond the profile's base args).
-            const hasDispatchContent = stdinPrompt !== undefined || !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
+            // 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 stdinPrompt = promptStdin ? readPromptStdin() : undefined;
             const result = await akmAgentDispatch({
                 engine: getStringArg(args, "engine"),
                 prompt: stdinPrompt ?? promptText,
-                commandRef,
-                workflowRef,
+                ...(agentRef === undefined ? {} : { agentRef }),
                 agentConfig,
-                ...(hasDispatchContent
-                    ? {
-                        dispatch: {
-                            prompt: stdinPrompt ?? promptText ?? "",
-                            systemPrompt,
-                            model,
-                            tools: assetTools,
-                            ...(cwd ? { cwd } : {}),
-                        },
-                    }
-                    : {}),
+                ...(model === undefined ? {} : { selection: { model } }),
                 ...(cwd ? { cwd } : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });

package/dist/commands/command/builtin-action.js

@@ -0,0 +1,32 @@
+// 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 { assertSnapshotKeys, snapshotStrictRecord } from "../../execution/record.js";
+/**
+ * Parse the `with:` payload of AKM's built-in command action. The executable
+ * selector is a strict XOR: exactly one of `ref` or `content`.
+ */
+export function parseBuiltinCommandAction(value) {
+    const input = snapshotStrictRecord(value, "built-in command action with");
+    assertSnapshotKeys(input, ["ref", "content", "arguments"], "built-in command action with");
+    const hasRef = Object.hasOwn(input, "ref");
+    const hasContent = Object.hasOwn(input, "content");
+    if (hasRef === hasContent) {
+        throw new UsageError("Built-in command action with requires exactly one of ref or content.", "INVALID_FLAG_VALUE");
+    }
+    if (Object.hasOwn(input, "arguments") && typeof input.arguments !== "string") {
+        throw new UsageError("Built-in command action with.arguments must be a string.", "INVALID_FLAG_VALUE");
+    }
+    const exactArguments = Object.hasOwn(input, "arguments") ? { arguments: input.arguments } : {};
+    if (hasRef) {
+        if (typeof input.ref !== "string" || input.ref.length === 0) {
+            throw new UsageError("Built-in command action with.ref must be a non-empty string.", "INVALID_FLAG_VALUE");
+        }
+        return Object.freeze({ kind: "stored", ref: input.ref, ...exactArguments });
+    }
+    if (typeof input.content !== "string") {
+        throw new UsageError("Built-in command action with.content must be a string.", "INVALID_FLAG_VALUE");
+    }
+    return Object.freeze({ kind: "inline", content: input.content, ...exactArguments });
+}

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

@@ -0,0 +1,99 @@
+// 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 { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.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";
+import { lookupBundleRefReadonly } from "../../indexer/indexer.js";
+import { dispatchPreparedCommandInvocation, inspectPreparedCommandInvocation, prepareCommandInvocation, } from "./command-execution.js";
+function exactStringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+export const commandRunCommand = defineJsonCommand({
+    meta: {
+        name: "run",
+        description: "Resolve a stored command through its bundle adapter, apply portable arguments, and execute one fresh session",
+    },
+    args: {
+        ref: {
+            type: "positional",
+            description: "Command asset ref (for example commands/review or team//commands/review)",
+            required: true,
+        },
+        arguments: {
+            type: "string",
+            description: "Exact string substituted for each literal $ARGUMENTS occurrence (no tokenization or trimming)",
+        },
+        agent: {
+            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" },
+        "timeout-ms": { type: "string", description: "Override the execution timeout in milliseconds" },
+        cwd: { type: "string", description: "Override the execution workspace/current working directory" },
+        "dry-run": {
+            type: "boolean",
+            default: false,
+            description: "Authorize and lower the command, then print safe diagnostics without dispatching or writing state",
+        },
+    },
+    async run({ args }) {
+        if (args.verbose === true)
+            setVerbose(true);
+        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;
+        if (timeoutMs !== undefined)
+            current.timeout = timeoutMs;
+        if (workspace !== undefined)
+            current.workspace = workspace;
+        const argumentInput = exactStringArg(args, "arguments");
+        const dryRun = args["dry-run"] === true;
+        const prepared = await prepareCommandInvocation({
+            action: {
+                ref: args.ref,
+                ...(argumentInput === undefined ? {} : { arguments: argumentInput }),
+            },
+            config: loadConfig(),
+            current: current,
+            ...(dryRun ? { sourceLookup: lookupBundleRefReadonly } : {}),
+        });
+        const diagnostics = dryRun || isVerbose() ? inspectPreparedCommandInvocation(prepared) : undefined;
+        if (dryRun) {
+            output("command-dry-run", diagnostics);
+            return;
+        }
+        if (diagnostics) {
+            warnVerbose(`[akm:command] diagnostics ${JSON.stringify({
+                engine: diagnostics.engine,
+                provenance: diagnostics.provenance,
+                notices: diagnostics.notices,
+            })}`);
+        }
+        const result = await dispatchPreparedCommandInvocation(prepared);
+        for (const message of result.warnings ?? [])
+            warn(message);
+        output("agent-result", result);
+        if (!result.ok)
+            process.exitCode = EXIT_CODES.GENERAL;
+    },
+});
+export const commandCommand = defineGroupCommand({
+    meta: {
+        name: "command",
+        description: "Run reusable agent prompt templates through AKM's common execution resolver",
+    },
+    subCommands: { run: commandRunCommand },
+});