akm-cli 0.9.31 → 0.10.261002-beta

package/dist/llm/client.js

@@ -49,10 +49,14 @@ function htmlExcerpt(body) {
 export class LlmCallError extends Error {
     code;
     statusCode;
-    constructor(message, code, statusCode) {
+    namesResponseFormat;
+    constructor(message, code, statusCode, 
+    /** A 5xx whose body names the response format; set from the whole body, since the message keeps only its first 200 characters. */
+    namesResponseFormat = false) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
+        this.namesResponseFormat = namesResponseFormat;
         this.name = "LlmCallError";
     }
 }
@@ -275,6 +279,8 @@ const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
 const TEMPERATURE_NAMED = /'temperature'/;
 /** `Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.` */
 const MAX_TOKENS_REPLACED = /max_completion_tokens/;
+/** A gateway that cannot honour the schema may answer 5xx: `502 {"error":{"code":"format_ignored"}}` (#1150). */
+const RESPONSE_FORMAT_NAMED = /format_ignored|response_format|json_schema/;
 /**
  * A single chat-completion attempt: one HTTP request/response cycle, with an
  * inline fallback-once when a schema was requested and the provider 4xx's
@@ -295,24 +301,41 @@ const MAX_TOKENS_REPLACED = /max_completion_tokens/;
 async function chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking = (options?.enableThinking ?? config.enableThinking) !== undefined &&
     !isThinkingControlKnownRejected(config)) {
     const wantsSchema = Boolean(options?.responseSchema) && config.supportsJsonSchema !== false && !isJsonSchemaKnownUnsupported(config);
+    // The schema attempt's error record is held, not emitted: when the retry without the schema
+    // recovers the call, that call is ONE success, not a failure plus a success. Every other exit
+    // flushes the held record, so a failed call is still recorded once.
+    const held = wantsSchema ? {} : undefined;
+    const flushHeld = () => {
+        if (held?.record)
+            emitLlmUsage(held.record);
+    };
     try {
-        return await chatCompletionAttemptOnce(config, messages, options, timeoutMs, wantsSchema, includeThinking);
+        return await chatCompletionAttemptOnce(config, messages, options, timeoutMs, wantsSchema, includeThinking, held);
     }
     catch (err) {
-        if (!isRejectedRequest(err))
+        // A 5xx that names the response format is answered like the 4xx rejection below (#1150).
+        if (wantsSchema && err instanceof LlmCallError && err.namesResponseFormat) {
+            return retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err);
+        }
+        if (!isRejectedRequest(err)) {
+            flushHeld();
             throw err;
+        }
         const key = connectionKey(config);
         if (TEMPERATURE_NAMED.test(err.message) && !temperatureRejectedConnections.has(key)) {
+            flushHeld();
             warnVerbose(`[akm] LLM rejected temperature (${err.statusCode}); retrying once without it: ${err.message}`);
             temperatureRejectedConnections.add(key);
             return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
         }
         if (MAX_TOKENS_REPLACED.test(err.message) && !maxCompletionTokensConnections.has(key)) {
+            flushHeld();
             warnVerbose(`[akm] LLM rejected max_tokens (${err.statusCode}); retrying once with max_completion_tokens: ${err.message}`);
             maxCompletionTokensConnections.add(key);
             return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
         }
         if (includeThinking && THINKING_FIELD_NAMED.test(err.message)) {
+            flushHeld();
             warnVerbose(`[akm] LLM rejected chat_template_kwargs/enable_thinking (${err.statusCode}); retrying once without them: ${err.message}`);
             const fallback = await chatCompletionAttempt(config, messages, options, timeoutMs, false);
             thinkingControlRejectedConnections.add(connectionKey(config));
@@ -320,13 +343,16 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs, inclu
         }
         if (!wantsSchema)
             throw err;
-        warnVerbose(`[akm] LLM rejected response_format:json_schema (${err.statusCode}); retrying once without it: ${err.message}`);
-        const fallback = await chatCompletionAttemptOnce(config, messages, options, timeoutMs, false, includeThinking);
-        jsonSchemaUnsupportedConnections.add(connectionKey(config));
-        return fallback;
+        return retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err);
     }
 }
-async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, includeSchema, includeThinking) {
+async function retryWithoutSchema(config, messages, options, timeoutMs, includeThinking, err) {
+    warnVerbose(`[akm] LLM rejected response_format:json_schema (${err.statusCode}); retrying once without it: ${err.message}`);
+    const fallback = await chatCompletionAttemptOnce(config, messages, options, timeoutMs, false, includeThinking);
+    jsonSchemaUnsupportedConnections.add(connectionKey(config));
+    return fallback;
+}
+async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, includeSchema, includeThinking, held) {
     if (config.extraParams !== undefined) {
         const issue = validateExtraParams(config.extraParams)[0];
         if (issue)
@@ -440,7 +466,7 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
                 throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", status);
             }
             if (status >= 500) {
-                throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
+                throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status, RESPONSE_FORMAT_NAMED.test(rawBody));
             }
             throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
         }
@@ -499,12 +525,16 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
         return result;
     }
     catch (err) {
-        emitLlmUsage({
+        const errorRecord = {
             ...terminalFields,
             outcome: "error",
             durationMs: Date.now() - requestStartedAt,
             errorCode: err instanceof LlmCallError ? err.code : "unknown_error",
-        });
+        };
+        if (held)
+            held.record = errorRecord;
+        else
+            emitLlmUsage(errorRecord);
         throw err;
     }
 }

package/dist/output/cli-hints.js

@@ -2,7 +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/.
 /**
- * Embedded agent CLI guide rendered by `akm hints` and `akm help agents`.
+ * Embedded agent CLI guide rendered by `akm hints`.
  *
  * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
  * docs/CI tooling can re-use the same constants. Two flavors:

package/dist/output/context.js

@@ -4,7 +4,8 @@
 /**
  * Process-level output mode singleton.
  *
- * Output mode (format + detail + shape) is parsed once at startup from
+ * Output mode (format + detail, and the agent projection `--detail agent`
+ * selects) is parsed once at startup from
  * `process.argv` and the persisted user config. All subsequent `output()`
  * calls read from this in-memory singleton instead of re-scanning argv and
  * re-loading config on every call.
@@ -15,8 +16,7 @@
  */
 import { UsageError } from "../core/errors.js";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
-const DETAIL_LEVELS = ["brief", "normal", "full"];
-const SHAPE_MODES = ["human", "agent", "summary"];
+const DETAIL_VALUES = ["brief", "normal", "full", "agent"];
 function parseOutputFormat(value) {
     if (!value)
         return undefined;
@@ -27,16 +27,9 @@ function parseOutputFormat(value) {
 export function parseDetailLevel(value) {
     if (!value)
         return undefined;
-    if (DETAIL_LEVELS.includes(value))
+    if (DETAIL_VALUES.includes(value))
         return value;
-    throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`, "INVALID_DETAIL_VALUE");
-}
-function parseShapeMode(value) {
-    if (!value)
-        return undefined;
-    if (SHAPE_MODES.includes(value))
-        return value;
-    throw new UsageError(`Invalid value for --shape: ${value}. Expected one of: ${SHAPE_MODES.join("|")}`, "INVALID_SHAPE_VALUE");
+    throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_VALUES.join("|")}`, "INVALID_DETAIL_VALUE");
 }
 export function parseFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
@@ -88,13 +81,11 @@ export function getHyphenatedBoolean(args, key) {
  */
 export function resolveOutputMode(argv, defaults = {}) {
     const format = parseOutputFormat(parseFlagValue(argv, "--format")) ?? defaults?.format ?? "json";
-    const rawDetail = parseFlagValue(argv, "--detail");
-    const rawShape = parseFlagValue(argv, "--shape");
-    // `--detail` is verbosity only (brief|normal|full); the projection presets
-    // (`summary`/`agent`) and the `--for-agent` boolean were removed in 0.9.0 —
-    // use `--shape`. Unknown `--detail` values fall through to the default.
-    const detail = parseDetailLevel(rawDetail) ?? defaults?.detail ?? "brief";
-    const shape = parseShapeMode(rawShape) ?? "human";
+    // `--detail agent` selects the agent projection; the verbosity then stays at
+    // the configured default (the projection ignores it).
+    const parsedDetail = parseDetailLevel(parseFlagValue(argv, "--detail"));
+    const shape = parsedDetail === "agent" ? "agent" : "human";
+    const detail = (parsedDetail === "agent" ? undefined : parsedDetail) ?? defaults?.detail ?? "brief";
     const outputPath = parseFlagValue(argv, "--output");
     return { format, detail, shape, ...(outputPath ? { outputPath } : {}) };
 }

package/dist/output/format-exempt.js

@@ -35,12 +35,11 @@ const EXEMPT_COMMANDS = new Set([
     // progress-event lines the child prints during a real `apply` still print
     // verbatim ahead of the formatted result — those are operational logging,
     // not part of the result envelope, the same way a progress spinner would be.
-    // Document payload group: bare `help` prints the sectioned overview,
-    // `help migrate <version>` prints release notes, and `help agents` prints
-    // the embedded CLI-reference guide (`src/output/cli-hints.ts`) — none of
-    // the three render a result envelope.
+    // Document payload group: bare `help` prints the sectioned overview and
+    // `help migrate <version>` prints release notes — neither renders a result
+    // envelope.
     "help",
-    // Embedded agent guide document.
+    // Embedded agent guide document (`src/output/cli-hints.ts`).
     "hints",
 ]);
 /**
@@ -57,9 +56,7 @@ const EXEMPT_SUBCOMMANDS = new Set([
     // envelope. Wrapping it broke every existing substitution silently: the
     // CLI's default format is `json`, so an un-flagged `akm env path <ref>`
     // (exactly how the substitution is always written) started emitting
-    // `{"path":"..."}` instead of the raw path. Unlike `config path`, this
-    // command has no `--all`-style multi-field variant, so the whole surface
-    // can be exempt without wrongly warning on a real envelope case.
+    // `{"path":"..."}` instead of the raw path.
     "env path",
 ]);
 /**

package/dist/output/shapes/helpers.js

@@ -310,7 +310,7 @@ export function shapeSearchHit(hit, detail) {
     }
     // Stash hit (local or remote)
     // `ref` is included at `brief` so agents can run `akm show <ref>` without
-    // needing --detail full or --shape agent (REC-03).
+    // needing --detail full or --detail agent (REC-03).
     if (detail === "brief") {
         return pickFields(hit, ["type", "name", "ref", "action", "estimatedTokens", "keys"]);
     }
@@ -393,27 +393,6 @@ export function shapeShowOutput(result, detail, shape = "human") {
             delete shaped.editHint;
         return shaped;
     }
-    if (shape === "summary") {
-        return pickFields(result, [
-            "type",
-            "name",
-            // ref is present on every show shape (human/summary/agent) — it is the
-            // canonical identity of the asset, not an agent-only convenience field
-            // (R-020).
-            "ref",
-            "description",
-            "tags",
-            "parameters",
-            "workflowTitle",
-            "action",
-            "run",
-            "origin",
-            "keys",
-            "links",
-            ...FRAGMENT_PROVENANCE_FIELDS,
-            ...FRAGMENT_CONTEXT_FIELDS,
-        ]);
-    }
     const base = pickFields(result, [
         "type",
         "name",

package/dist/output/shapes/passthrough.js

@@ -75,7 +75,6 @@ const PASSTHROUGH_COMMANDS = [
     "task-run",
     "task-sync",
     "task-sync-dry-run",
-    "task-validate",
     "update",
     "upgrade",
     "workflow-abandon",

package/dist/output/shapes.js

@@ -1,23 +1,6 @@
 // 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/.
-/**
- * Pure shaping functions that select and trim fields from command result
- * objects according to the active detail level / agent mode.
- *
- * Every function in this module is side-effect free and operates on plain
- * `Record<string, unknown>` shapes, which makes them trivial to unit test.
- *
- * Output shapes are assembled EXPLICITLY here: each per-command module under
- * `src/output/shapes/` EXPORTS a pure `OutputShapeEntry[]` (no top-level
- * side effect), and this barrel imports those exports and registers them in a
- * single deterministic, order-independent pass (`BUILT_IN_OUTPUT_SHAPES`).
- * Dropping a module from the assembly array is a COMPILE error, not a silent
- * runtime gap. The central `shapeForCommand` dispatcher looks up the registry
- * and throws for unknown commands (v1 spec §9 — exhaustive registry, no silent
- * fallback).
- */
-import { warnOnce } from "../core/warn.js";
 import { curateShapes } from "./shapes/curate.js";
 import { envListShapes } from "./shapes/env-list.js";
 import { eventsShapes } from "./shapes/events.js";
@@ -64,12 +47,6 @@ const BUILT_IN_OUTPUT_SHAPES = [
     ...passthroughShapes,
 ];
 registerOutputShapes(BUILT_IN_OUTPUT_SHAPES);
-/**
- * Commands whose shape handler implements the `summary` projection. For every
- * other command, `--shape summary` is a usage error (v1 §5 — honest rejection
- * for a soon-frozen contract, not a silent fallback to `human`).
- */
-const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
 // ── `results` collection alias ──────────────────────────────────────────────
 //
 // Every list-returning command names its collection differently (`hits`,
@@ -80,8 +57,8 @@ const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
 //
 // This maps each list-returning command to the field already holding its
 // collection, and `withResultsAlias` below adds a `results` key pointing at
-// that SAME array (not a copy) to the shaped output — in every `--shape` /
-// `--detail` combination, `human` included, so `--shape agent` needs no
+// that SAME array (not a copy) to the shaped output — in every
+// `--detail` combination, `agent` included, so `--detail agent` needs no
 // separate handling to "guarantee" it. A new list-returning command MUST add
 // an entry here; there is no way to detect a missed one automatically, so the
 // survey deliberately lives in this one place rather than scattered per
@@ -118,14 +95,9 @@ function withResultsAlias(command, shaped) {
     return { ...obj, results: collection };
 }
 export function shapeForCommand(command, result, detail, shape = "human") {
-    let effectiveShape = shape;
-    if (shape === "summary" && !SHAPE_SUMMARY_COMMANDS.has(command)) {
-        warnOnce(`shape-summary-unsupported:${command}`, `[output] '--shape summary' is not supported for 'akm ${command}' (only 'akm show' has a summary projection); falling back to 'agent'.`);
-        effectiveShape = "agent";
-    }
     const handler = getOutputShapeHandler(command);
     if (handler) {
-        return withResultsAlias(command, handler(result, detail, effectiveShape));
+        return withResultsAlias(command, handler(result, detail, shape));
     }
     // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
     // fallback. A missing case here is a registration bug — fail loudly so

package/dist/output/stdout.js

@@ -20,5 +20,9 @@
  * `tests/integration/output-baseline.test.ts` pins the bytes either way.
  */
 export function writeStdout(document) {
-    process.stdout.write(`${document}\n`);
+    process.stdout.write(stdoutText(document));
+}
+/** The exact bytes {@link writeStdout} writes for `document`; in-process callers return this instead of writing. */
+export function stdoutText(document) {
+    return `${document}\n`;
 }

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

@@ -662,7 +662,12 @@ export function formatUpdatePlain(r) {
     }
     return lines.length > 0 ? lines.join("\n") : `update: nothing to update`;
 }
-const HARNESS_LABELS = { "claude-code": "Claude Code", codex: "Codex", opencode: "OpenCode" };
+const HARNESS_LABELS = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    opencode: "OpenCode",
+    "opencode-v2": "OpenCode 2",
+};
 /** The plugin lines worth printing: nothing for a plugin that is current or has no plugin to update. */
 function formatUpgradePluginLines(r) {
     const lines = [];

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

@@ -235,8 +235,7 @@ function formatInputBindingsList(bindings) {
  * expansion's own steps, recursively, indented one level per composition
  * boundary. A child step also carries the child's `planHash` on the step
  * line itself, and (when present) a `with:` line for the step's own
- * `inputBindings[]` and an `exports:` line for the child's declared output
- * names — §4.6's worked example.
+ * `inputBindings[]` — §4.6's worked example.
  */
 function renderPlanStepLines(step, ordinal, lines, prefix = "  ") {
     const stepId = typeof step.stepId === "string" ? step.stepId : "unknown";
@@ -244,11 +243,9 @@ function renderPlanStepLines(step, ordinal, lines, prefix = "  ") {
     const expansion = typeof step.expansion === "object" && step.expansion !== null ? step.expansion : {};
     const via = typeof expansion.via === "string" ? expansion.via : "direct";
     const childPlanHash = typeof expansion.childPlanHash === "string" ? expansion.childPlanHash : undefined;
-    const viaText = via === "task"
-        ? `via ${String(expansion.taskRef ?? "")}`
-        : via === "child"
-            ? `-> ${String(expansion.childRef ?? "")}${childPlanHash ? ` (plan ${childPlanHash})` : ""}`
-            : "direct";
+    const viaText = via === "child"
+        ? `-> ${String(expansion.childRef ?? "")}${childPlanHash ? ` (plan ${childPlanHash})` : ""}`
+        : "direct";
     lines.push(`${prefix}${ordinal}. ${stepId} ${targetKind} ${viaText}`.replace(/ +/g, " ").trimEnd());
     const detailPrefix = `${prefix}  `;
     const inputBindings = Array.isArray(step.inputBindings) ? step.inputBindings : [];
@@ -256,10 +253,6 @@ function renderPlanStepLines(step, ordinal, lines, prefix = "  ") {
         lines.push(`${detailPrefix}with: ${formatInputBindingsList(inputBindings)}`);
     }
     if (via === "child") {
-        const childOutputs = Array.isArray(expansion.childOutputs) ? expansion.childOutputs : [];
-        if (childOutputs.length > 0) {
-            lines.push(`${detailPrefix}exports: ${childOutputs.map(String).join(", ")}`);
-        }
         const childSteps = Array.isArray(expansion.steps) ? expansion.steps : [];
         for (const [index, childStep] of childSteps.entries()) {
             renderPlanStepLines(childStep, index + 1, lines, `${prefix}  ${ordinal}.`);
@@ -304,17 +297,6 @@ export function formatWorkflowPlanPlain(result) {
     const params = Array.isArray(result.params) ? result.params : undefined;
     if (params && params.length > 0)
         lines.push(`params:   ${params.join(", ")}`);
-    const outputs = typeof result.outputs === "object" && result.outputs !== null
-        ? result.outputs
-        : undefined;
-    if (outputs) {
-        for (const [name, declaration] of Object.entries(outputs)) {
-            const from = typeof declaration === "object" && declaration !== null
-                ? String(declaration.from ?? "")
-                : "";
-            lines.push(`outputs:  ${name} <- ${from}`);
-        }
-    }
     const steps = Array.isArray(result.steps) ? result.steps : [];
     lines.push("steps:");
     for (const [index, step] of steps.entries()) {