akm-cli 0.7.4 → 0.8.0-rc1

package/dist/commands/agent-dispatch.js

@@ -0,0 +1,102 @@
+/**
+ * `akm agent <profile> [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]`
+ *
+ * Dispatch an agent by named profile, 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 { parseAssetRef } from "../core/asset-ref";
+import { NotFoundError, UsageError } from "../core/errors";
+import { requireAgentProfile } from "../integrations/agent/config";
+import { runWithAgentRunner } from "../integrations/agent/runners";
+/**
+ * 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;
+    });
+}
+/**
+ * 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 = parseAssetRef(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)}`);
+    }
+}
+export async function akmAgentDispatch(options) {
+    if (!options.profileName?.trim()) {
+        throw new UsageError("agent: <profile> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    // Resolve the profile — throws ConfigError with an actionable hint when
+    // agent config is absent or the profile is not found.
+    const profile = requireAgentProfile(options.agentConfig, options.profileName.trim());
+    // 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 && profile.sdkMode !== true ? "interactive" : profile.stdio;
+    const result = await runWithAgentRunner({
+        profile,
+        prompt,
+        llmConfig: options.llmConfig,
+        runOptions: {
+            stdio,
+            parseOutput: "text",
+            ...(options.args?.length && !options.commandRef && !options.workflowRef ? { args: options.args } : {}),
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: result.ok,
+        shape: "agent-result",
+        profileName: profile.name,
+        exitCode: result.exitCode,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        durationMs: result.durationMs,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+    };
+}

package/dist/commands/agent-support.js

@@ -0,0 +1,62 @@
+/**
+ * Shared helpers for agent-based commands (reflect, propose, etc.).
+ *
+ * Consolidates utility functions that were duplicated byte-for-byte across
+ * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
+ * profile can import from here rather than copy-pasting.
+ */
+import { loadConfig } from "../core/config";
+import { parseAgentConfig, requireAgentProfile, } from "../integrations/agent";
+// ── Config helpers ───────────────────────────────────────────────────────────
+/**
+ * Load the agent config block from the on-disk config file.
+ * Returns `undefined` when no agent block is present.
+ */
+export function loadAgentConfigFromDisk() {
+    const config = loadConfig();
+    return parseAgentConfig(config.agent);
+}
+/**
+ * Resolve the agent profile for a command's options.
+ * Prefers an injected `agentProfile` (test seam) over the on-disk config.
+ */
+export function resolveAgentProfile(options) {
+    if (options.agentProfile)
+        return options.agentProfile;
+    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+    return requireAgentProfile(agent, options.profile);
+}
+// ── Failure helpers ──────────────────────────────────────────────────────────
+/**
+ * Base failure envelope shared by all agent command failures.
+ * Each command returns its own typed failure shape — this helper builds the
+ * common fields so per-command wrappers only need to add their own fields.
+ */
+export function baseFailureFields(result, fallbackReason = "non_zero_exit") {
+    const reason = result.reason ?? fallbackReason;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        reason,
+        error: result.error ?? `agent failure (${reason})`,
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+// ── ENOENT hint ──────────────────────────────────────────────────────────────
+/**
+ * Return `true` when a failed agent result looks like the binary was not found
+ * on PATH. Used to surface a better error message pointing the user at
+ * `akm setup`.
+ */
+export function isEnoentFailure(result) {
+    return (result.reason === "spawn_failed" &&
+        (!!result.error?.includes("ENOENT") || !!result.error?.toLowerCase().includes("not found")));
+}
+/**
+ * Build an actionable error message for a spawn-ENOENT failure.
+ */
+export function enoentHintMessage(binName) {
+    return `The agent binary '${binName}' was not found on PATH. Run \`akm setup\` to configure an agent CLI, or install ${binName} and retry.`;
+}

package/dist/commands/config-cli.js

@@ -1,5 +1,6 @@
-import { DEFAULT_CONFIG, } from "../core/config";
+import { DEFAULT_CONFIG, getSources, } from "../core/config";
 import { UsageError } from "../core/errors";
+import { assertWritableAllowedForKind } from "../core/write-source";
 // ── Merge helpers for LLM/embedding subkey set ───────────────────────────────
 function mergeLlmLike(base, patch) {
     return { endpoint: "", model: "", ...(base ?? {}), ...patch };
@@ -7,6 +8,14 @@ function mergeLlmLike(base, patch) {
 function mergeLlmLikeEmbedding(base, patch) {
     return { endpoint: "", model: "", ...(base ?? {}), ...patch };
 }
+function validateSources(entries) {
+    if (!entries)
+        return undefined;
+    for (const entry of entries) {
+        assertWritableAllowedForKind(entry);
+    }
+    return entries;
+}
 export function parseConfigValue(key, value) {
     switch (key) {
         case "stashDir":
@@ -45,12 +54,14 @@ export function parseConfigValue(key, value) {
             return { llm: mergeLlmLike(undefined, { model: requireNonEmptyString(value, key) }) };
         case "llm.apiKey":
             return { llm: mergeLlmLike(undefined, { apiKey: requireNonEmptyString(value, key) }) };
+        case "llm.contextLength":
+            return { llm: mergeLlmLike(undefined, { contextLength: parsePositiveInteger(value, key) }) };
         case "registries":
             return { registries: parseRegistriesValue(value) };
         case "sources":
         case "stashes":
             // "stashes" is kept as an alias for backwards-compat; both write to `sources`.
-            return { sources: parseStashesValue(value) };
+            return { sources: validateSources(parseStashesValue(value)) };
         case "output.format":
             return { output: { format: parseOutputFormat(value) } };
         case "output.detail":
@@ -100,12 +111,14 @@ export function getConfigValue(config, key) {
             return config.llm?.model ?? null;
         case "llm.apiKey":
             return config.llm?.apiKey ?? null;
+        case "llm.contextLength":
+            return config.llm?.contextLength ?? null;
         case "registries":
             return config.registries ?? DEFAULT_CONFIG.registries ?? [];
         case "sources":
         case "stashes":
             // "stashes" is an alias for "sources" for backwards-compat.
-            return config.sources ?? config.stashes ?? [];
+            return getSources(config);
         case "output.format":
             return config.output?.format ?? null;
         case "output.detail":
@@ -180,9 +193,11 @@ export function setConfigValue(config, key, rawValue) {
             return { ...config, llm: mergeLlmLike(config.llm, { model: requireNonEmptyString(rawValue, key) }) };
         case "llm.apiKey":
             return { ...config, llm: mergeLlmLike(config.llm, { apiKey: requireNonEmptyString(rawValue, key) }) };
+        case "llm.contextLength":
+            return { ...config, llm: mergeLlmLike(config.llm, { contextLength: parsePositiveInteger(rawValue, key) }) };
         case "defaultWriteTarget": {
             const name = requireNonEmptyString(rawValue, key);
-            const knownNames = (config.sources ?? config.stashes ?? [])
+            const knownNames = getSources(config)
                 .map((s) => s.name)
                 .filter((n) => typeof n === "string");
             if (knownNames.length > 0 && !knownNames.includes(name)) {
@@ -237,12 +252,18 @@ export function unsetConfigValue(config, key) {
             const { apiKey: _b, ...restLlm } = config.llm;
             return { ...config, llm: restLlm };
         }
+        case "llm.contextLength": {
+            if (!config.llm)
+                return config;
+            const { contextLength: _lctx, ...restLlm2 } = config.llm;
+            return { ...config, llm: restLlm2 };
+        }
         case "registries":
             return { ...config, registries: undefined };
         case "sources":
         case "stashes":
             // "stashes" is kept as an alias for backwards-compat; both clear `sources`.
-            return { ...config, sources: undefined, stashes: undefined };
+            return { ...config, sources: undefined };
         case "output.format":
             return { ...config, output: mergeOutputConfig(config.output, { format: undefined }) };
         case "output.detail":
@@ -287,7 +308,7 @@ export function listConfig(config) {
         output: mergeOutputConfig(DEFAULT_CONFIG.output, config.output) ?? null,
         stashDir: config.stashDir ?? null,
         installed: config.installed ?? [],
-        sources: config.sources ?? config.stashes ?? [],
+        sources: getSources(config),
     };
     if (config.defaultWriteTarget)
         result.defaultWriteTarget = config.defaultWriteTarget;
@@ -410,17 +431,8 @@ function parseRegistriesValue(value) {
         if (typeof obj.url !== "string" || !obj.url) {
             throw new UsageError(`Invalid value for registries[${i}]: "url" is required`);
         }
-        const result = { url: obj.url };
-        if (typeof obj.name === "string" && obj.name)
-            result.name = obj.name;
-        if (typeof obj.enabled === "boolean")
-            result.enabled = obj.enabled;
-        if (typeof obj.provider === "string" && obj.provider)
-            result.provider = obj.provider;
-        if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
-            result.options = obj.options;
-        }
-        return result;
+        // Spread the full entry so unknown/future fields round-trip intact.
+        return { ...obj };
     });
 }
 function parseEmbeddingConnectionValue(value) {
@@ -430,30 +442,25 @@ function parseEmbeddingConnectionValue(value) {
         endpoint: "http://localhost:11434/v1/embeddings",
         model: "nomic-embed-text",
     });
-    const localModel = typeof parsed.localModel === "string" && parsed.localModel ? parsed.localModel : undefined;
-    const endpoint = typeof parsed.endpoint === "string" ? parsed.endpoint : "";
-    if (!endpoint) {
-        if (!localModel) {
-            throw new UsageError(`Invalid value for embedding: endpoint/model are required for remote embeddings, or provide localModel`);
-        }
-        const localOnly = { endpoint: "", model: "", localModel };
-        if (typeof parsed.provider === "string" && parsed.provider)
-            localOnly.provider = parsed.provider;
-        return localOnly;
+    // Require either a non-empty endpoint (remote) or a localModel (local-only).
+    const hasEndpoint = typeof parsed.endpoint === "string" && parsed.endpoint !== "";
+    const hasLocalModel = typeof parsed.localModel === "string" && parsed.localModel !== "";
+    if (!hasEndpoint && !hasLocalModel) {
+        throw new UsageError(`Invalid value for embedding: "endpoint" is required for remote embeddings, or provide "localModel" for local-only`);
     }
-    const result = {
-        endpoint: asRequiredString(parsed.endpoint, "embedding", "endpoint"),
-        model: asRequiredString(parsed.model, "embedding", "model"),
-    };
-    if (typeof parsed.provider === "string" && parsed.provider)
-        result.provider = parsed.provider;
-    if (parsed.dimension !== undefined)
-        result.dimension = parseUnknownPositiveInteger(parsed.dimension, "embedding.dimension");
-    if (typeof parsed.apiKey === "string" && parsed.apiKey)
-        result.apiKey = parsed.apiKey;
-    if (localModel)
-        result.localModel = localModel;
-    return result;
+    // Validate the types of the required/structural fields that the runtime
+    // depends on, but do not reconstruct the object — pass everything through.
+    if (parsed.endpoint !== undefined && typeof parsed.endpoint !== "string") {
+        throw new UsageError(`Invalid value for embedding: "endpoint" must be a string`);
+    }
+    if (parsed.model !== undefined && typeof parsed.model !== "string") {
+        throw new UsageError(`Invalid value for embedding: "model" must be a string`);
+    }
+    if (parsed.dimension !== undefined && !Number.isInteger(parsed.dimension)) {
+        throw new UsageError(`embedding.dimension: expected a positive integer, got ${parsed.dimension}`, "INVALID_FLAG_VALUE");
+    }
+    // Spread the full parsed object so unknown/future fields round-trip intact.
+    return { endpoint: "", model: "", ...parsed };
 }
 function parseLlmConnectionValue(value) {
     if (value === "null" || value === "")
@@ -462,19 +469,25 @@ function parseLlmConnectionValue(value) {
         endpoint: "http://localhost:11434/v1/chat/completions",
         model: "llama3.2",
     });
-    const result = {
-        endpoint: asRequiredString(parsed.endpoint, "llm", "endpoint"),
-        model: asRequiredString(parsed.model, "llm", "model"),
-    };
-    if (typeof parsed.provider === "string" && parsed.provider)
-        result.provider = parsed.provider;
-    if (parsed.temperature !== undefined)
-        result.temperature = parseUnknownNumber(parsed.temperature, "llm.temperature");
-    if (parsed.maxTokens !== undefined)
-        result.maxTokens = parseUnknownPositiveInteger(parsed.maxTokens, "llm.maxTokens");
-    if (typeof parsed.apiKey === "string" && parsed.apiKey)
-        result.apiKey = parsed.apiKey;
-    return result;
+    if (parsed.endpoint !== undefined && typeof parsed.endpoint !== "string") {
+        throw new UsageError(`Invalid value for llm: "endpoint" is a required string field`);
+    }
+    if (parsed.model !== undefined && typeof parsed.model !== "string") {
+        throw new UsageError(`Invalid value for llm: "model" is a required string field`);
+    }
+    if (typeof parsed.endpoint !== "string" || !parsed.endpoint) {
+        throw new UsageError(`Invalid value for llm: "endpoint" is a required string field`);
+    }
+    if (parsed.model === undefined) {
+        return { endpoint: parsed.endpoint, model: "", ...parsed };
+    }
+    if (!parsed.model) {
+        throw new UsageError(`Invalid value for llm: "model" must be a non-empty string when provided`);
+    }
+    // Spread the full parsed object so unknown/future fields round-trip intact.
+    // The config loader (config.ts) handles warn-and-ignore for unknown sub-keys
+    // at read time, so we do not need to whitelist here.
+    return { ...parsed };
 }
 function parseJsonObject(value, key, example) {
     let parsed;
@@ -490,30 +503,12 @@ function parseJsonObject(value, key, example) {
     }
     return parsed;
 }
-function asRequiredString(value, key, field) {
-    if (typeof value !== "string" || !value) {
-        throw new UsageError(`Invalid value for ${key}: "${field}" is a required string field`);
-    }
-    return value;
-}
 function requireNonEmptyString(value, key) {
     if (!value) {
         throw new UsageError(`Invalid value for ${key}: expected a non-empty string`);
     }
     return value;
 }
-function parseUnknownNumber(value, key) {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new UsageError(`Invalid value for ${key}: expected a number`);
-    }
-    return value;
-}
-function parseUnknownPositiveInteger(value, key) {
-    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
-        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
-    }
-    return value;
-}
 function parsePositiveInteger(value, key) {
     const n = Number(value);
     if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
@@ -542,18 +537,7 @@ function parseStashesValue(value) {
         if (typeof obj.type !== "string" || !obj.type) {
             throw new UsageError(`Invalid value for sources[${i}]: "type" is required`);
         }
-        const result = { type: obj.type };
-        if (typeof obj.path === "string" && obj.path)
-            result.path = obj.path;
-        if (typeof obj.url === "string" && obj.url)
-            result.url = obj.url;
-        if (typeof obj.name === "string" && obj.name)
-            result.name = obj.name;
-        if (typeof obj.enabled === "boolean")
-            result.enabled = obj.enabled;
-        if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
-            result.options = obj.options;
-        }
-        return result;
+        // Spread the full entry so unknown/future fields round-trip intact.
+        return { ...obj };
     });
 }