akm-cli 0.9.31 → 0.10.26101002-alpha

package/dist/integrations/harnesses/opencode-sdk/v1-adapter.js

@@ -0,0 +1,199 @@
+// 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/.
+/**
+ * OpenCode 1 wire adapter, on `@opencode-ai/sdk` 1.2.20.
+ *
+ * Everything here is the V1 protocol and nothing else: the readiness line
+ * (`opencode server listening on <url>`), the SDK client, `session.create` /
+ * `session.prompt` / `session.abort` with the per-call `query.directory`, the
+ * `/event` stream, and `postSessionIdPermissionsPermissionId`. `agent`,
+ * `system` and `tools` ride on the prompt body. The shared server lifecycle
+ * lives in `sdk-runner.ts`.
+ */
+import { isRecord } from "../../../core/common.js";
+import { decodeRetryStatus, } from "./wire.js";
+const queryOf = (spec) => spec.directory ? { query: { directory: spec.directory } } : {};
+/**
+ * Best-effort token usage from a prompt response. Only numeric fields the
+ * server actually reported are copied; undefined when nothing usable is
+ * present (older servers, test fakes).
+ */
+function extractUsage(info) {
+    const tokens = info?.tokens;
+    if (!tokens)
+        return undefined;
+    const usage = {};
+    if (typeof tokens.input === "number" && Number.isFinite(tokens.input))
+        usage.inputTokens = tokens.input;
+    if (typeof tokens.output === "number" && Number.isFinite(tokens.output))
+        usage.outputTokens = tokens.output;
+    if (typeof tokens.reasoning === "number" && Number.isFinite(tokens.reasoning)) {
+        usage.reasoningTokens = tokens.reasoning;
+    }
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+/**
+ * Map an SDK `{ error }` result or a reply's `info.error` onto a failure
+ * (#1015). Both are opencode NamedErrors, `{ name, data: { message } }`. An
+ * aborted message is `aborted`, a reply cut off at the output limit is
+ * `parse_error`, and every other error (auth, API, unknown, an HTTP error
+ * body) is `non_zero_exit`.
+ */
+function v1ErrorFailure(error) {
+    if (!isRecord(error) || typeof error.name !== "string") {
+        return { reason: "non_zero_exit", message: typeof error === "string" ? error : JSON.stringify(error) };
+    }
+    const detail = isRecord(error.data) ? error.data.message : undefined;
+    const message = typeof detail === "string" ? `${error.name}: ${detail}` : error.name;
+    if (error.name === "MessageAbortedError")
+        return { reason: "aborted", message };
+    if (error.name === "MessageOutputLengthError")
+        return { reason: "parse_error", message };
+    return { reason: "non_zero_exit", message };
+}
+/**
+ * Subscribe to the server's event stream. The SDK's own `event.subscribe`
+ * cannot be closed safely: aborting it leaves an unhandled `AbortError`
+ * rejection (from its un-awaited `reader.cancel()`), which akm's global
+ * handler turns into a process exit. This reader ends quietly on abort.
+ */
+async function subscribeEvents(baseUrl, args) {
+    const eventUrl = new URL("/event", baseUrl);
+    if (args.query?.directory)
+        eventUrl.searchParams.set("directory", args.query.directory);
+    const response = await fetch(eventUrl, { signal: args.signal, headers: { accept: "text/event-stream" } });
+    if (!response.ok || !response.body)
+        throw new Error(`OpenCode event stream failed: HTTP ${response.status}`);
+    const reader = response.body.getReader();
+    async function* stream() {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                const frames = buffer.split("\n\n");
+                buffer = frames.pop() ?? "";
+                for (const frame of frames) {
+                    const data = frame
+                        .split("\n")
+                        .filter((line) => line.startsWith("data:"))
+                        .map((line) => line.replace(/^data:\s*/, ""))
+                        .join("\n");
+                    if (!data)
+                        continue;
+                    try {
+                        yield JSON.parse(data);
+                    }
+                    catch {
+                        /* not JSON: not an event we act on */
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (!args.signal.aborted)
+                throw err;
+        }
+    }
+    return { stream: stream() };
+}
+/** The SDK `createOpencodeClient`, with the quiet event reader swapped in. */
+async function connectV1(baseUrl) {
+    const { createOpencodeClient } = (await import("@opencode-ai/sdk").catch(() => {
+        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
+    }));
+    const client = createOpencodeClient({ baseUrl });
+    client.event = { subscribe: (args) => subscribeEvents(baseUrl, args) };
+    return client;
+}
+export const V1_ADAPTER = {
+    major: 1,
+    serveArgv: (bin, port) => [bin, "serve", "--hostname=127.0.0.1", `--port=${port}`],
+    // OpenCode 1 serves unauthenticated on loopback.
+    authorize: () => ({ env: {} }),
+    connect: (baseUrl) => connectV1(baseUrl),
+    async createSession(client, spec) {
+        const created = await client.session.create({ body: { title: "akm" }, ...queryOf(spec) });
+        return created.data?.id;
+    },
+    async prompt(client, sessionId, text, spec) {
+        // Forward the exact native agent selector, system prompt and tools from the
+        // abstract dispatch request (#564).
+        const body = { parts: [{ type: "text", text }] };
+        if (spec.agent)
+            body.agent = spec.agent;
+        if (spec.system)
+            body.system = spec.system;
+        if (spec.tools)
+            body.tools = spec.tools;
+        const prompted = await client.session.prompt({ path: { id: sessionId }, body, ...queryOf(spec) });
+        const parts = prompted.data?.parts ?? [];
+        // The last text part is the answer; earlier ones narrate the steps before it.
+        const textOut = parts.filter((p) => p.type === "text").at(-1)?.text ?? "";
+        const usage = extractUsage(prompted.data?.info);
+        const sdkError = prompted.error ?? prompted.data?.info?.error;
+        return {
+            text: textOut,
+            ...(usage ? { usage } : {}),
+            ...(sdkError ? { failure: v1ErrorFailure(sdkError) } : {}),
+        };
+    },
+    abort(client, sessionId, spec) {
+        void client.session.abort?.({ path: { id: sessionId }, ...queryOf(spec) }).catch(() => { });
+    },
+    canWatch(client) {
+        const c = client;
+        return Boolean(c.event?.subscribe && c.postSessionIdPermissionsPermissionId);
+    },
+    async subscribe(client, spec, signal) {
+        const events = client.event;
+        if (!events)
+            throw new Error("the client has no event surface");
+        const { stream } = await events.subscribe.call(events, { ...queryOf(spec), signal });
+        return stream;
+    },
+    decodeEvent(raw) {
+        if (!isRecord(raw) || !isRecord(raw.properties))
+            return undefined;
+        const props = raw.properties;
+        if (raw.type === "session.created" && isRecord(props.info)) {
+            const { id, parentID } = props.info;
+            if (typeof id !== "string")
+                return undefined;
+            return { kind: "session", id, ...(typeof parentID === "string" ? { parentId: parentID } : {}) };
+        }
+        // `action` is not in the SDK's retry type yet, but current servers send it for provider/account limits.
+        if (raw.type === "session.status")
+            return decodeRetryStatus(props.sessionID, props.status);
+        // `permission.asked` (OpenCode >= 1.3) / `permission.updated` (older).
+        if (raw.type !== "permission.asked" && raw.type !== "permission.updated")
+            return undefined;
+        const { id, sessionID } = props;
+        if (typeof id !== "string" || typeof sessionID !== "string")
+            return undefined;
+        const patterns = Array.isArray(props.patterns) ? props.patterns : props.pattern ? [props.pattern] : [];
+        return {
+            kind: "permission",
+            requestId: id,
+            sessionId: sessionID,
+            description: `${String(props.permission ?? props.type ?? "unknown")} (${patterns.join(", ")})`,
+        };
+    },
+    async rejectPermission(client, event, spec) {
+        const c = client;
+        const reply = c.postSessionIdPermissionsPermissionId;
+        if (!reply)
+            throw new Error("the client cannot answer permission requests");
+        const r = await reply.call(c, {
+            path: { id: event.sessionId, permissionID: event.requestId },
+            body: { response: "reject" },
+            ...queryOf(spec),
+        });
+        if (r.error)
+            throw new Error(JSON.stringify(r.error));
+    },
+};

package/dist/integrations/harnesses/opencode-sdk/v2-adapter.js

@@ -0,0 +1,228 @@
+// 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/.
+/**
+ * OpenCode 2 wire adapter, on
+ * `@opencode/client` 2.0.26 (the promise client, generated types).
+ *
+ * akm owns a private `opencode serve` child (never the v2 background
+ * `service`). What differs from OpenCode 1, verified against the 2.0.26
+ * binary:
+ *
+ *   - Readiness is `server listening on <url>` (no `opencode` prefix).
+ *   - The server is basic-auth protected. akm chooses the password and hands it
+ *     to the child as `OPENCODE_SERVER_PASSWORD` (and `OPENCODE_PASSWORD`,
+ *     which wins when set), so nothing is scraped from stdout; the username is
+ *     the server's default, `opencode`.
+ *   - The working directory is the session's `location.directory`, set once at
+ *     `session.create`. Later calls address the session by id.
+ *   - The agent, the tool permissions (`permissions`: action/resource/effect
+ *     rules) and the title are `session.create` fields. The prompt carries only
+ *     text, so the system text is a session instruction entry.
+ *   - `session.prompt` only enqueues. `session.wait` blocks until the session is
+ *     idle, and `session.context` then holds the turn: our user message, the
+ *     assistant messages and a closing `idle` message with the outcome.
+ *   - Cancellation is `session.interrupt`; permission requests are answered with
+ *     `permission.reply`; the event stream is global, so events are matched to
+ *     the dispatch's sessions by id.
+ *
+ * Config (`OPENCODE_CONFIG_CONTENT`, built by the runner) keeps the V1 shape,
+ * which the 2.0.26 server translates (`model`, `provider`, `agent`, `permission`).
+ */
+import { randomBytes } from "node:crypto";
+import { OpenCode } from "@opencode/client";
+import { isRecord, toErrorMessage } from "../../../core/common.js";
+import { sleep } from "../../../runtime.js";
+import { parseOpencodeMajor } from "../opencode/version.js";
+import { decodeRetryStatus, OTHER_MAJOR_REMEDY, } from "./wire.js";
+/** Key of the session instruction entry carrying the dispatch's system text (`^[a-z0-9][a-z0-9._-]*$`). */
+const SYSTEM_INSTRUCTION_KEY = "akm.system";
+/** The server's default basic-auth username. */
+const SERVER_USERNAME = "opencode";
+const POLL_INTERVAL_MS = 100;
+/**
+ * The turn that began with the user message `userId`, once its closing `idle`
+ * message exists; undefined while the turn is still running.
+ */
+export function v2Turn(messages, userId) {
+    const start = messages.findIndex((m) => m.id === userId);
+    if (start < 0)
+        return undefined;
+    const assistants = [];
+    for (const message of messages.slice(start + 1)) {
+        if (message.type === "assistant")
+            assistants.push(message);
+        else if (message.type === "idle")
+            return { outcome: message.outcome, assistants };
+    }
+    return undefined;
+}
+/** Decode a finished turn into the answer, the usage of every step and the failure, if any. */
+function v2PromptResult(turn) {
+    const text = turn.assistants
+        .flatMap((a) => a.content)
+        .filter((c) => c.type === "text")
+        .at(-1)?.text ?? "";
+    const usage = {};
+    const add = (key, value) => {
+        if (typeof value === "number" && Number.isFinite(value))
+            usage[key] = (usage[key] ?? 0) + value;
+    };
+    for (const a of turn.assistants) {
+        add("inputTokens", a.tokens?.input);
+        add("outputTokens", a.tokens?.output);
+        add("reasoningTokens", a.tokens?.reasoning);
+    }
+    const failure = v2Failure(turn);
+    return {
+        text,
+        ...(Object.keys(usage).length > 0 ? { usage } : {}),
+        ...(failure ? { failure } : {}),
+    };
+}
+function v2Failure(turn) {
+    if (turn.outcome === "interrupted") {
+        return { reason: "aborted", message: "OpenCode session was interrupted" };
+    }
+    const last = turn.assistants.at(-1);
+    if (turn.outcome === "failed") {
+        const error = [...turn.assistants].reverse().find((a) => a.error)?.error;
+        return {
+            reason: "non_zero_exit",
+            message: error ? `${error.type}: ${error.message}` : "OpenCode session failed",
+        };
+    }
+    // A reply cut off at the output limit has no error of its own.
+    if (last?.finish === "length") {
+        return { reason: "parse_error", message: "OpenCode reply was cut off at the output limit" };
+    }
+    return undefined;
+}
+/** Tool enable/disable map -> session permission rules. */
+function toolPermissions(tools) {
+    return Object.entries(tools ?? {}).map(([action, enabled]) => ({
+        action,
+        resource: "*",
+        effect: enabled ? "allow" : "deny",
+    }));
+}
+export const V2_ADAPTER = {
+    major: 2,
+    serveArgv: (bin, port) => [bin, "serve", "--hostname", "127.0.0.1", "--port", String(port)],
+    authorize() {
+        const password = randomBytes(24).toString("base64url");
+        return { env: { OPENCODE_SERVER_PASSWORD: password, OPENCODE_PASSWORD: password }, credentials: password };
+    },
+    async connect(baseUrl, credentials) {
+        const client = OpenCode.make({
+            baseUrl,
+            headers: { authorization: `Basic ${Buffer.from(`${SERVER_USERNAME}:${credentials ?? ""}`).toString("base64")}` },
+        });
+        let version;
+        try {
+            version = (await client.server.info()).version;
+        }
+        catch (err) {
+            throw new Error(`Could not read the OpenCode 2 server info at ${baseUrl}: ${toErrorMessage(err)}. ${OTHER_MAJOR_REMEDY}`);
+        }
+        // Only OpenCode 1 is refused: a newer major than akm knows runs on these adapters (`../opencode/version.ts`).
+        if (parseOpencodeMajor(version) === 1) {
+            throw new Error(`The server is OpenCode ${version}, not OpenCode 2. ${OTHER_MAJOR_REMEDY}`);
+        }
+        return client;
+    },
+    async createSession(client, spec) {
+        const c = client;
+        const permissions = toolPermissions(spec.tools);
+        const session = await c.session.create({
+            title: "akm",
+            ...(spec.agent ? { agent: spec.agent } : {}),
+            ...(spec.directory ? { location: { directory: spec.directory } } : {}),
+            ...(permissions.length > 0 ? { permissions } : {}),
+        });
+        if (spec.system) {
+            await c.session.instructions.entry.put({
+                sessionID: session.id,
+                key: SYSTEM_INSTRUCTION_KEY,
+                value: spec.system,
+            });
+        }
+        return session.id;
+    },
+    async prompt(client, sessionId, text, _spec, signal) {
+        const c = client;
+        const user = await c.session.prompt({ sessionID: sessionId, text }, { signal });
+        for (;;) {
+            await c.session.wait({ sessionID: sessionId }, { signal });
+            const turn = v2Turn(await c.session.context({ sessionID: sessionId }, { signal }), user.id);
+            if (turn)
+                return v2PromptResult(turn);
+            // `wait` can return before the queued prompt starts; look again.
+            await sleep(POLL_INTERVAL_MS);
+            if (signal.aborted)
+                throw new Error("OpenCode prompt cancelled");
+        }
+    },
+    abort(client, sessionId) {
+        void client.session.interrupt({ sessionID: sessionId }).catch(() => { });
+    },
+    async subscribe(client, _spec, signal) {
+        const source = client.event.subscribe({ signal })[Symbol.asyncIterator]();
+        // The stream's first event is `server.connected`: reading it proves the subscription is open.
+        const first = await source.next();
+        async function* stream() {
+            try {
+                if (!first.done)
+                    yield first.value;
+                while (true) {
+                    const next = await source.next();
+                    if (next.done)
+                        return;
+                    yield next.value;
+                }
+            }
+            catch (err) {
+                if (!signal.aborted)
+                    throw err;
+            }
+        }
+        return stream();
+    },
+    decodeEvent(raw) {
+        if (!isRecord(raw) || typeof raw.type !== "string" || !isRecord(raw.data))
+            return undefined;
+        // Shape-checked below, field by field; the generated `V2Event` union documents what each carries.
+        const data = raw.data;
+        if (raw.type === "session.created") {
+            if (typeof data.sessionID !== "string")
+                return undefined;
+            return {
+                kind: "session",
+                id: data.sessionID,
+                ...(typeof data.parentID === "string" ? { parentId: data.parentID } : {}),
+            };
+        }
+        if (raw.type === "session.status")
+            return decodeRetryStatus(data.sessionID, data.status);
+        if (raw.type === "permission.asked") {
+            const { id, sessionID, action, resources } = data;
+            if (typeof id !== "string" || typeof sessionID !== "string")
+                return undefined;
+            const patterns = Array.isArray(resources) ? resources : [];
+            return {
+                kind: "permission",
+                requestId: id,
+                sessionId: sessionID,
+                description: `${String(action ?? "unknown")} (${patterns.join(", ")})`,
+            };
+        }
+        return undefined;
+    },
+    async rejectPermission(client, event) {
+        await client.permission.reply({
+            sessionID: event.sessionId,
+            requestID: event.requestId,
+            decision: "reject",
+        });
+    },
+};

package/dist/integrations/harnesses/opencode-sdk/wire.js

@@ -0,0 +1,66 @@
+// 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/.
+/**
+ * The seam between the OpenCode SDK runner and one OpenCode major's wire
+ * protocol (#1049).
+ *
+ * `sdk-runner.ts` owns everything the two majors share: the managed
+ * `opencode serve` child (spawn, port, registry, cleanup), the child
+ * environment, deadlines, abort handling and result shaping. A
+ * {@link OpencodeWireAdapter} owns what differs: how to ask the binary to
+ * serve, how to read its readiness line, how to authenticate, and how to
+ * create a session, prompt it, abort it, watch its events and answer its
+ * permission requests. `v1-adapter.ts` speaks OpenCode 1 through
+ * `@opencode-ai/sdk`; `v2-adapter.ts` speaks OpenCode 2 through
+ * `@opencode/client`.
+ *
+ * Selection is by detection (`../opencode/version.ts` runs `<bin> --version`
+ * once per binary). An adapter that meets a server of the other major fails and
+ * names the remedy ({@link otherMajorRemedy}); it never falls back to the other
+ * protocol.
+ */
+import { isRecord } from "../../../core/common.js";
+/** The npm client package each major's adapter imports. Setup and health check the one the engine selects. */
+export const OPENCODE_CLIENT_PACKAGE = {
+    1: "@opencode-ai/sdk",
+    2: "@opencode/client",
+};
+/** The sentence every wrong-major failure ends with. */
+export const OTHER_MAJOR_REMEDY = `Upgrade to OpenCode 2, or set this engine's "bin" to the OpenCode binary you want to run.`;
+/** What each major's `serve` prints once it listens; the other major's line names a wrong binary. */
+const READINESS_PREFIX = {
+    1: "opencode server listening",
+    2: "server listening on",
+};
+/** Judge one output line of a server started for `own`: its readiness line, the other major's, or neither. */
+export function parseReadiness(line, own) {
+    const other = own === 1 ? 2 : 1;
+    if (line.startsWith(READINESS_PREFIX[own])) {
+        const match = line.match(/on\s+(https?:\/\/\S+)/);
+        return match?.[1] ? { url: match[1] } : { error: `Failed to parse the OpenCode server url from: ${line}` };
+    }
+    if (line.startsWith(READINESS_PREFIX[other])) {
+        return { error: `The binary is OpenCode ${other} (${line.trim()}). ${OTHER_MAJOR_REMEDY}` };
+    }
+    return undefined;
+}
+/**
+ * A `session.status` payload as the runner's retry event, or undefined for any
+ * other status. Both majors carry the same fields; `action` names the provider
+ * and, for an account usage limit, `reason: "account_rate_limit"` (#1108).
+ */
+export function decodeRetryStatus(sessionID, status) {
+    if (typeof sessionID !== "string" || !isRecord(status) || status.type !== "retry")
+        return undefined;
+    const action = isRecord(status.action) ? status.action : undefined;
+    return {
+        kind: "retry",
+        sessionId: sessionID,
+        ...(typeof status.attempt === "number" ? { attempt: status.attempt } : {}),
+        message: typeof status.message === "string" ? status.message : "OpenCode is retrying",
+        ...(typeof status.next === "number" ? { next: status.next } : {}),
+        ...(typeof action?.provider === "string" ? { provider: action.provider } : {}),
+        accountLimit: action?.reason === "account_rate_limit",
+    };
+}

package/dist/integrations/harnesses/openhands/index.js

@@ -27,6 +27,7 @@ export class OpenhandsHarness extends BaseHarness {
     id = "openhands";
     displayName = "OpenHands";
     agentBuilder = openhandsBuilder;
+    profile = { bin: "openhands", args: [], envPassthrough: ["LLM_MODEL", "LLM_API_KEY", "LLM_BASE_URL"] };
     resultExtractor = openhandsResultExtractor;
     // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
     // No flag-shaped resume: per the matrix OpenHands resumes from workspace state, not a

package/dist/integrations/harnesses/pi/index.js

@@ -27,6 +27,7 @@ export class PiHarness extends BaseHarness {
     id = "pi";
     displayName = "Pi";
     agentBuilder = piBuilder;
+    profile = { bin: "pi", args: [], envPassthrough: ["PI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"] };
     resultExtractor = piResultExtractor;
     // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
     // Session-id env marker only — the matrix's bare PI_* presence vars must

package/dist/integrations/harnesses/shared.js

@@ -7,6 +7,8 @@ export function caps(c) {
         agentDispatch: false,
         detection: false,
         configImport: false,
+        modelWork: false,
+        nativeAgent: false,
         ...c,
     };
 }

package/dist/integrations/harnesses/types.js

@@ -46,6 +46,8 @@ export function isSessionLogHarness(h) {
 export class BaseHarness {
     setupDetectionDir;
     agentBuilder;
+    profile;
+    configImporter;
     executionLowerer;
     identityEnv;
     presenceEnv;

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: