akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/commands/improve/retrieval-scope.js

@@ -43,7 +43,7 @@ export function loadRetrievalScope(access, stashDir) {
             }
             if (!stashDir)
                 return;
-            // Blocker 1 (second review round): a pair-pass ledger row must NOT mark
+            // A pair-pass ledger row must NOT mark
             // an asset "processed" — unlike every other stage, the pair pass judges
             // material against its NEIGHBOURS, not on its own merits, so its own
             // attempt is not usage evidence the proactive lane

package/dist/commands/improve/session-asset.js

@@ -112,8 +112,9 @@ export function buildSessionAccessInstructions(harness, logPath, sessionId) {
     if (harness === "opencode") {
         return [
             `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,
-            "Query: SELECT m.data, p.data FROM message AS m JOIN part AS p ON p.message_id = m.id WHERE m.session_id = ? AND p.session_id = ? ORDER BY m.time_created, p.time_created;",
-            `Bind both parameters to ${JSON.stringify(sessionId)}.`,
+            "If it has a session_v2 table (OpenCode 2), query: SELECT type, data FROM session_message WHERE session_id = ? ORDER BY seq;",
+            "otherwise (OpenCode 1), query: SELECT m.data, p.data FROM message AS m JOIN part AS p ON p.message_id = m.id WHERE m.session_id = ? AND p.session_id = ? ORDER BY m.time_created, p.time_created;",
+            `Bind the session parameters (one in the first query, both in the second) to ${JSON.stringify(sessionId)}.`,
         ].join("\n");
     }
     return `Read with: cat ${logPath}`;

package/dist/commands/improve/stage.js

@@ -1,13 +1,13 @@
 // 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 { getImproveProcessConfig } from "../../core/config/config.js";
+import { SHIPPED_ALIAS } from "../../core/config/model-aliases.js";
 import { ConfigError } from "../../core/errors.js";
+import { effectiveRequestFields, thinkingSetting } from "../../core/llm-inference.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { defaultFeedback } from "../../core/structured.js";
 import { warn } from "../../core/warn.js";
-import { runnerLlmConnection } from "../../integrations/agent/runner.js";
-import { callStructured, dispatchFailureReason, dispatchFailureResult, } from "../../llm/structured-call.js";
+import { isRefused, structuredLoop } from "../../llm/structured.js";
+import { callStructured } from "../../llm/structured-call.js";
 import { currentLlmStage, withLlmStage } from "../../llm/usage-telemetry.js";
 import { isProceduralRejection } from "../proposal/proposal-types.js";
 import { createProposal, listProposalsReadOnly, proposalContentHash, recordGateDecision, } from "../proposal/repository.js";
@@ -16,65 +16,47 @@ import { resolveImproveExecution } from "./execution.js";
 export function errMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
-/** The lowering notices a stage's dispatches emitted, each once. */
-export function noticeSet(forward) {
-    const byKey = new Map();
-    const add = (notices) => {
-        for (const notice of notices)
-            byKey.set(JSON.stringify(notice), notice);
-        forward?.(notices);
-    };
-    const list = () => Object.freeze([...byKey.values()]);
-    return { add, list, fields: () => (byKey.size > 0 ? { notices: list() } : {}) };
-}
 /**
  * A stage's runner: the one the improve plan froze for it (an own
- * `llmRunner` key, `null` meaning "none"), else the process engine cascade.
+ * `llmRunner` key, `null` meaning "none"), else the one the process resolves to now.
  */
-export function stageRunner(frozen, config, profile, processName, onNotices) {
+export function stageRunner(frozen, config, processName, onNotices) {
     if (Object.hasOwn(frozen, "llmRunner"))
         return frozen.llmRunner ?? undefined;
-    const resolved = resolveImproveExecution({
-        config,
-        profile,
-        process: getImproveProcessConfig(processName, profile),
-        processName,
-    });
+    const resolved = resolveImproveExecution({ config, processName, alias: SHIPPED_ALIAS.improve });
     if (resolved)
         onNotices?.(resolved.notices);
     return resolved?.runner;
 }
 /**
- * One model call. Provider trouble (transport error, timeout, abort, a
- * disabled feature) comes back as `{ ok: false }`; only a configuration
- * failure throws. A reply to a call with `request.responseSchema` that the
- * stage's own `parse` rejects gets one corrective retry; the last reply comes
- * back either way, and the caller parses it again.
+ * The stage's call under the structured loop: each dispatch is one
+ * {@link callStageOnce}, and the correction a refused reply earns is appended
+ * to the prompt. The loop's own result comes back, so a caller that must tell a
+ * refused reply (and read what the parser said) from a failed call can.
  */
-export async function callStage(call) {
-    const reply = await callStageOnce(call);
-    if (!reply.ok || !call.request?.responseSchema)
-        return reply;
-    if ((call.parse ?? parseEmbeddedJsonResponse)(reply.raw) !== undefined)
-        return reply;
-    const feedback = defaultFeedback({ reason: "parse_error", errors: [] });
-    const retry = await callStageOnce({ ...call, prompt: `${call.prompt}\n\n${feedback}` });
-    // A retry that fails in transport keeps the first reply, which the caller may still accept.
-    return retry.ok ? retry : reply;
-}
-/** Timeout and abort come from the dispatch's own reason, whatever the runner's kind. */
-function failureReason(err) {
-    const reason = dispatchFailureReason(err);
-    return reason === "timeout" || reason === "aborted" ? reason : "error";
+export function callStageLoop(call, parse, correct) {
+    return structuredLoop({
+        dispatch: (correction) => callStageOnce(correction ? { ...call, prompt: `${call.prompt}\n\n${correction.text}` } : call),
+        parse,
+        ...(correct ? { correct } : {}),
+    });
 }
-/** A failed call: its reason and message, and the dispatch's own result when it reached a transport. */
-function failedCall(err) {
-    const result = dispatchFailureResult(err);
-    return { ok: false, reason: failureReason(err), error: errMessage(err), ...(result ? { result } : {}) };
+/**
+ * One model call. Provider trouble (transport error, timeout, abort) comes back
+ * as `{ ok: false }`; only a configuration failure throws. A reply to a call with `request.responseSchema` that the
+ * stage's own `parse` rejects gets one corrective retry (the structured loop);
+ * the last reply comes back either way, and the caller parses it again.
+ */
+export async function callStage(call) {
+    if (!call.request?.responseSchema)
+        return callStageOnce(call);
+    const parse = call.parse ?? parseEmbeddedJsonResponse;
+    const loop = await callStageLoop(call, (raw) => parse(raw) === undefined ? { ok: false, errors: ["no parseable JSON"] } : { ok: true, value: raw });
+    return loop.ok || isRefused(loop) ? { ok: true, raw: loop.raw } : loop;
 }
 /**
- * One dispatch with no validation, for a caller that parses and repairs the
- * reply itself (reflect's repair turn, extract's own structured loop).
+ * One dispatch with no validation: the loop's dispatch ({@link callStageLoop}),
+ * and a caller's own (reflect's repair turn carries a conversation).
  */
 export async function callStageOnce(call) {
     const messages = [
@@ -82,43 +64,19 @@ export async function callStageOnce(call) {
         ...(call.history ?? []),
         { role: "user", content: call.prompt },
     ];
-    let failure;
-    try {
-        const dispatch = () => callStructured({
-            feature: call.feature,
-            ...(call.gate
-                ? { akmConfig: call.gate.config, ...(call.gate.enabled !== undefined ? { enabled: call.gate.enabled } : {}) }
-                : {}),
-            runner: call.runner,
-            messages,
-            ...(call.request ? { request: call.request } : {}),
-            ...(call.current ? { current: call.current } : {}),
-            ...(call.onNotices ? { onNotices: call.onNotices } : {}),
-            parse: (r) => r ?? "",
-            onError: (_cls, err) => {
-                failure = failedCall(err);
-                return undefined;
-            },
-            fallback: undefined,
-            onFallback: (event) => {
-                failure ??= { ok: false, reason: event.reason, ...(event.error ? { error: event.error.message } : {}) };
-            },
-        });
-        // Usage is credited to the engine that serves the call, which for a gate's own judge
-        // (#1011) is not the stage's planned engine.
-        const stage = currentLlmStage();
-        const raw = await (stage === undefined
-            ? dispatch()
-            : withLlmStage(stage, dispatch, { engine: call.runner.engine }));
-        return raw === undefined ? (failure ?? { ok: false, reason: "error" }) : { ok: true, raw };
-    }
-    catch (err) {
-        if (err instanceof ConfigError)
-            throw err;
-        return failedCall(err);
-    }
+    const dispatch = () => callStructured({
+        runner: call.runner,
+        messages,
+        ...(call.request ? { request: call.request } : {}),
+        ...(call.current ? { current: call.current } : {}),
+        ...(call.onNotices ? { onNotices: call.onNotices } : {}),
+    });
+    // Usage is credited to the connection or harness that serves the call, which for a gate's own judge
+    // (#1011) is not the one the stage planned.
+    const stage = currentLlmStage();
+    return stage === undefined ? dispatch() : withLlmStage(stage, dispatch, { engine: call.runner.name });
 }
-/** Attribute a stage's LLM calls to its process and planned engine (the usage report). */
+/** Attribute a stage's LLM calls to its process and planned connection or harness (the usage report). */
 const STAGE_LABELS = {
     reflect: "reflect",
     distill: "distill",
@@ -128,7 +86,7 @@ const STAGE_LABELS = {
     validation: "validation",
 };
 export function attributeStage(plan, process, fn) {
-    return withLlmStage(STAGE_LABELS[process], fn, { engine: plan?.processes[process].runner?.engine, process });
+    return withLlmStage(STAGE_LABELS[process], fn, { engine: plan?.processes[process].runner?.name, process });
 }
 /** How many prior rejected proposals are shown to the model as "don't repeat this". */
 export const MAX_REJECTED_PROPOSALS = 3;
@@ -187,31 +145,41 @@ export function stageJudgedProposal(stash, proposal, judged, proposalsCtx) {
         return proposal;
     }
 }
+/** Whether `improve.qualityGate` sets where the judge runs, or only how. */
+function gateNamesAJudge(gate) {
+    return ["connection", "harness", "model", "timeoutMs", "llm"].some((key) => Object.hasOwn(gate, key));
+}
 /**
- * The judge a quality gate names for itself (#1011): the gate's `engine`,
- * `model`, `timeoutMs` and `llm` over the process's own settings, as
- * `processes.triage.judgment` resolves over triage. `undefined` when the gate
- * is off or sets none of them, so the caller keeps its own judge. The engine
- * may be of any kind; config validation has required one that confines the
- * model-work tool policy. Throws when they resolve to no engine at all,
- * before anything is generated: the gate never falls back to another judge.
+ * The judge of a process's quality gate (#1011). Its layers are the improve-wide
+ * `improve.connection` / `improve.harness`, then `improve.qualityGate`'s
+ * connection or harness, model, timeout and inference, asking for the `judge`
+ * alias when neither names a model. What the run selected (`--connection`,
+ * `--harness`, `--model`) is nearer than all of these. The process's own `improve.processes.<name>`
+ * settings (its `model`, `llm`, connection) are the generation call's and do not
+ * reach the judge, so a `reasoning` model chosen for the writer is not the one
+ * that judges it. `undefined` when the strategy turns the gate off or no
+ * connection or harness is configured, so the caller keeps its own. The judge
+ * may be a connection or a harness; a harness that cannot confine the
+ * model-work tool policy runs unrestricted, with a notice. Throws when
+ * `improve.qualityGate` names a judge that resolves to nothing, before anything
+ * is generated: the gate never falls back to another judge.
  */
-export function resolveQualityGateJudge(config, profile, processName, onNotices) {
-    const process = profile?.processes?.[processName];
-    const gate = process?.qualityGate;
-    if (!gate || gate.enabled === false)
-        return undefined;
-    if (!["engine", "model", "timeoutMs", "llm"].some((key) => Object.hasOwn(gate, key)))
+export function resolveQualityGateJudge(config, profile, processName, onNotices, run) {
+    if (profile?.processes?.[processName]?.qualityGate?.enabled === false)
         return undefined;
+    const gate = config.improve?.qualityGate;
     const resolved = resolveImproveExecution({
         config,
         processName: `${processName}-quality-judge`,
-        ...(profile ? { profile } : {}),
-        ...(process ? { process } : {}),
-        current: gate,
+        alias: SHIPPED_ALIAS.judge,
+        ...(gate ? { current: gate } : {}),
+        ...(run ? { run } : {}),
     });
     if (!resolved) {
-        throw new ConfigError(`The ${processName} quality gate's judge has no engine. Set processes.${processName}.qualityGate.engine.`, "INVALID_CONFIG_FILE");
+        if (gate && gateNamesAJudge(gate)) {
+            throw new ConfigError("The quality gate's judge has no connection or harness. Set improve.qualityGate.connection.", "INVALID_CONFIG_FILE");
+        }
+        return undefined;
     }
     onNotices?.(resolved.notices);
     return resolved.runner;
@@ -275,12 +243,13 @@ function buildChangedRegion(sourceContent, candidateContent) {
     return boundedDocument(`Removed or replaced:\n${removed || "(none)"}\n\nAdded or replacement:\n${added || "(none)"}`);
 }
 /**
- * What the judge may do with tools when it runs on an agent engine: verify a
+ * What the judge may do with tools when it runs on a harness: verify a
  * fact the revision adds or alters, and nothing else. The plain judge's prompt
  * is unchanged (its rubric is tuned and measured without this paragraph).
  */
-function reflectJudgeToolRules(ref) {
-    const asset = ref ? `The asset is \`${ref}\`: read it with akm_show, ` : "Read an asset with akm_show ";
+function reflectJudgeToolRules(ref, tool) {
+    const read = tool === "akm_show" ? "akm_show" : `\`akm show ${ref ?? "<ref>"}\``;
+    const asset = ref ? `The asset is \`${ref}\`: read it with ${read}, ` : `Read an asset with ${read} `;
     return `Tools: ${asset}or an asset the changed region names, only to verify a fact the revision adds or alters; the text above already shows every change. Do not search, do not read anything else, and do not use a tool to judge structure or wording. One or two reads at most. Before scoring, check two lists: (1) every statement the revision adds: find each in the asset, or as a fact the feedback states about the subject, and score QUALITY 1-2 if any is in neither; a statement is found only when the asset or the feedback says it, in any words: a new step, cause, consequence or detail that merely seems to follow is not found; feedback says what to fix and is not content, so an added statement about how the asset was used, found or verified is unsupported; (2) every fact, caveat and field of the source: find each in the revision, and score PRESERVATION 1-3 if any is missing. A read that finds nothing wrong raises no score above what these lists support. Then reply with the JSON.`;
 }
 /**
@@ -291,7 +260,7 @@ function reflectJudgeToolRules(ref) {
 const REFLECT_JUDGE_INTRO = "You are evaluating a proposed revision of an existing akm asset's frontmatter. The revision may change only the `description`, the `when_to_use` and the title (a level-1 heading added when the body has none); the body is unchanged.";
 const REFLECT_JUDGE_NEGATIVE = "This revision answers negative feedback. It cannot change the body, so it need not resolve the feedback: judge only the fields it changes, and never fault it for a field it leaves as it was. Most negative feedback says the asset did not help with a task it was retrieved for: a retrieval miss, not a defect. It justifies changing a field only when the field claims more than the body covers (narrow it to what the body covers), or when the feedback calls the asset stale, outdated, superseded or historical (a new `when_to_use` must then name the version or date the body records). Feedback about a task the asset never claims to cover justifies no change. Repairing a missing or broken field is always needed, whatever the feedback says.";
 const REFLECT_JUDGE_MAINTENANCE = "This revision is maintenance: there is no negative feedback. Only a missing or broken field needs a change; rewording a sound `description` or `when_to_use` is churn, however accurate.";
-/** Judge prompt for an in-place revision. `tools` is set when the judge runs on an agent engine. */
+/** Judge prompt for an in-place revision. `tools` is set when the judge runs on a harness. */
 export function buildReflectJudgePrompt(candidateContent, sourceContent, feedback, tools) {
     return [
         REFLECT_JUDGE_INTRO,
@@ -323,7 +292,7 @@ export function buildReflectJudgePrompt(candidateContent, sourceContent, feedbac
         buildChangedRegion(sourceContent, candidateContent),
         "```",
         "",
-        ...(tools ? [reflectJudgeToolRules(tools.ref), ""] : []),
+        ...(tools ? [reflectJudgeToolRules(tools.ref, tools.tool), ""] : []),
         'Return ONLY valid JSON, no prose: {"scores": {"need": <1-5 integer>, "preservation": <1-5 integer>, "quality": <1-5 integer>}, "reason": "<one sentence>"}',
     ].join("\n");
 }
@@ -405,7 +374,7 @@ export function judgeResponseSchema(keys) {
  */
 async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     const resolved = !options.runnerSelectionFrozen && !options.llmRunner
-        ? resolveImproveExecution({ config, processName: `${feature}-judge` })
+        ? resolveImproveExecution({ config, processName: `${feature}-judge`, alias: SHIPPED_ALIAS.judge })
         : null;
     if (resolved)
         options.onNotices?.(resolved.notices);
@@ -414,17 +383,17 @@ async function runQualityJudge(feature, config, prompt, keys, chat, options) {
         return {
             pass: false,
             score: -1,
-            reason: "no engine configured — cannot judge, routed to review",
+            reason: "no connection or harness configured — cannot judge, routed to review",
             reviewNeeded: true,
         };
     const outcome = await callStage({
-        feature,
         runner,
         system: "Return only valid JSON. No prose.",
         prompt,
         request: {
-            // Off unless the judge's own engine enables thinking (a slower, separate judge engine, #1011).
-            enableThinking: runnerLlmConnection(runner)?.enableThinking === true,
+            // Off unless the judge's own connection enables thinking (a slower, separate judge, #1011).
+            enableThinking: runner.kind === "connection" &&
+                thinkingSetting(effectiveRequestFields(runner.request, runner.inference)) === true,
             temperature: 0,
             responseSchema: judgeResponseSchema(keys),
             ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
@@ -457,8 +426,11 @@ export function runLessonQualityJudge(config, lessonContent, sourceContent, chat
 }
 /** Judge an in-place reflect revision without new-lesson novelty criteria. */
 export function runReflectQualityJudge(config, candidateContent, sourceContent, feedback, chat, options = {}) {
-    // A judge on an agent engine gets the tool rules; the runner is the frozen one or none.
-    const tools = options.llmRunner && options.llmRunner.kind !== "llm" ? { ref: options.ref } : undefined;
+    // A judge on a harness gets the tool rules, in the spelling its harness has; the runner is the frozen one or none.
+    const judge = options.llmRunner;
+    const tools = judge && judge.kind !== "connection"
+        ? { ref: options.ref, tool: judge.platform === "opencode" ? "akm_show" : "akm show" }
+        : undefined;
     const prompt = buildReflectJudgePrompt(candidateContent, sourceContent, feedback, tools);
     return runQualityJudge("proposal_quality_gate", config, prompt, REFLECT_JUDGE_CRITERIA, chat, options);
 }

package/dist/commands/lint/base-linter.js

@@ -318,9 +318,9 @@ function localRefMissingRelPath(refType, refName, allRoots) {
 }
 /**
  * 0.9.0 grammar recognition: fully-qualified `bundle//conceptId` body-refs
- * (`BUNDLE_REF_RE`, the anchored prose form — spec §11.1 / ref-grammar decision
- * D-R3). The conceptId is reverse-translated to its legacy `type`/`name` via the
- * D-R2 static table (`typeNameFromConceptId`) so the SAME on-disk existence
+ * (`BUNDLE_REF_RE`, the anchored prose form). The conceptId is
+ * reverse-translated to its legacy `type`/`name` via the static table
+ * (`typeNameFromConceptId`) so the SAME on-disk existence
  * check applies; a conceptId whose leading segment names no known stash-subdir
  * is not a local asset ref and is skipped (foreign-adapter / cross-bundle prose).
  */

package/dist/commands/lint/env-key-rules.js

@@ -11,18 +11,19 @@
  *
  * Enforcement scope:
  *   - `akm lint` reports findings as `dangerous-env-key` (non-blocking warn).
- *   - `akm bundle add` BLOCKS install unless `--allow-dangerous-env-keys` is set (or, on TTY,
- *     the user explicitly confirms at the prompt).
+ *   - Nothing else consults this list. Installing a bundle is the trust
+ *     decision, so `akm bundle add` and `akm bundle update` do not scan env
+ *     files, and `akm env run` does not refuse a key. The
+ *     `--allow-dangerous-env-keys` flag is a deprecated no-op.
  *   - Local env writes do NOT consult this list — by design, the operator may
- *     legitimately store any key locally. The gate exists only for third-party
- *     stash installation.
+ *     legitimately store any key locally.
  *
  * False-positive tradeoff:
  *   A handful of keys (EDITOR, VISUAL, PAGER) are included because they are
  *   invoked by many interactive tools and are a documented RCE vector when
  *   sourced from untrusted environments. They will also flag on benign files
- *   where the operator legitimately wants to set their editor — accept the
- *   FP and bypass with `--allow-dangerous-env-keys` after review.
+ *   where the operator legitimately wants to set their editor — the warning is
+ *   advisory, so ignore it after review.
  */
 import fs from "node:fs";
 import { listKeys } from "../env/env.js";

package/dist/commands/lint/index.js

@@ -237,7 +237,7 @@ export function diagnosticToLintIssue(diag) {
     };
 }
 /**
- * Lint a bundle through its OWN adapter's `validate()` (spec §12.1): the
+ * Lint a bundle through its OWN adapter's `validate()`: the
  * adapter never writes, so every finding lands in `flagged` — `fixed` is
  * always `false`/`"failed"` for a non-akm bundle regardless of `--fix`
  * (the CLI option is silently a no-op here, exactly as it already was for
@@ -497,7 +497,7 @@ export function lintAssetFile(ctx, subdir) {
             issues.push(...factDiagnostics(ctx.relPath, ctx.data));
             break;
         case "tasks":
-            issues.push(...taskDiagnostics(ctx.relPath, ctx.raw, ctx.stashRoot));
+            issues.push(...taskDiagnostics(ctx.relPath, ctx.raw));
             break;
         case "memories":
             appendMemoryStubIssue(ctx, issues);
@@ -725,7 +725,7 @@ export async function akmLint(options = {}) {
     // cross-stash refs (e.g. referencing assets in dimm-city/agent-stash) are
     // not falsely flagged as missing-ref.
     const cfg = options.config ?? loadConfig();
-    // 0.9.0 (spec §10.1): the primary stash is the defaultBundle's path.
+    // The primary stash is the defaultBundle's path.
     const stashRoot = options.dir ?? primaryBundlePath(cfg) ?? resolveStashDir();
     const sources = resolveSourceEntries(stashRoot, cfg);
     const configuredAdapter = sources.find((source) => path.resolve(source.path) === path.resolve(stashRoot))?.adapterId;

package/dist/commands/models-cli.js

@@ -1,80 +1,120 @@
 // 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 { isDeepStrictEqual } from "node:util";
-import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
-import { loadConfig } from "../core/config/config.js";
-import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, WILDCARD_ENGINE_KEY, } from "../integrations/agent/model-map.js";
 /**
- * Compute the effective alias table (#946): every (alias, column) pair from
- * the fully resolved map, labeled with where its value came from.
+ * `akm models` — the one place to see and change which model answers each alias
+ * (`fast`, `balanced`, `reasoning`, and any the user adds) on a connection.
  *
- * `source` compares the installed-only merge against the full (installed +
- * user) merge for the same pair — identical means the user file never
- * touched it. `via`/`engine` come from the raw overlaid-but-unresolved
- * profile (before `engine` indirection is expanded), so a column that
- * resolves through `{ engine: "local-fast" }` reports which engine it
- * borrowed its model from.
+ *   akm models [--connection NAME]                      the picks, then what the endpoint lists
+ *   akm models set <alias> <model> [--connection NAME]  change one
+ *
+ * Connections only: a harness's alias map is `harnesses.<name>.models`, edited
+ * with `akm config set`.
  */
-function modelsListRows() {
-    const config = loadConfig();
-    const layers = loadModelMapLayers();
-    const rawProfiles = mergedModelMapProfiles(layers.installed, layers.user);
-    const defaultsOnly = mergeModelMapLayers(layers.installed, undefined, config.engines);
-    const resolved = mergeModelMapLayers(layers.installed, layers.user, config.engines);
-    const rows = [];
-    for (const [alias, columns] of Object.entries(resolved.aliases)) {
-        for (const [column, profile] of Object.entries(columns)) {
-            // The wildcard default (#946) is an alias-wide fallback, not a real
-            // platform column an operator would dispatch to; report it folded into
-            // the real per-platform rows above instead of as its own row.
-            if (column === WILDCARD_ENGINE_KEY)
-                continue;
-            const raw = rawProfiles[alias]?.[column];
-            const via = raw?.engine !== undefined ? "engine" : "literal";
-            const defaultProfile = defaultsOnly.aliases[alias]?.[column];
-            const source = defaultProfile !== undefined && isDeepStrictEqual(defaultProfile, profile) ? "default" : "user";
-            rows.push({
-                alias,
-                column,
-                model: profile.model,
-                ...(Object.hasOwn(profile, "inference") ? { inference: profile.inference } : {}),
-                source,
-                via,
-                ...(via === "engine" && raw?.engine !== undefined ? { engine: raw.engine } : {}),
-            });
-        }
+import { defineGroupCommand, defineJsonCommand, GLOBAL_OUTPUT_ARGS, output } from "../cli/shared.js";
+import { defaultConnection, loadConfig, mutateConfig, } from "../core/config/config.js";
+import { resolveApiKey } from "../core/config/credentials.js";
+import { entryModel, entryWithModel } from "../core/config/model-aliases.js";
+import { ConfigError, UsageError } from "../core/errors.js";
+import { redactUrlCredentials } from "../core/redaction.js";
+import { warn } from "../core/warn.js";
+import { selectionNotConfigured } from "../integrations/agent/resolution.js";
+import { listEndpointModels } from "../llm/model-list.js";
+const CONNECTION_ARG = {
+    connection: {
+        type: "string",
+        description: "The connection to show or change (default: the default connection)",
+    },
+};
+/** The connection to show or change: the one named, else the default. */
+function targetConnection(config, name) {
+    if (name !== undefined) {
+        const connection = config.connections?.[name];
+        if (connection)
+            return { name, connection };
+        throw selectionNotConfigured(config, "connection", name);
     }
-    rows.sort((left, right) => left.alias === right.alias ? left.column.localeCompare(right.column) : left.alias.localeCompare(right.alias));
-    return rows;
+    const found = defaultConnection(config);
+    if (found)
+        return found;
+    throw new ConfigError("No connection is configured, so there are no model aliases to show or change. Run `akm setup` to add one.", "LLM_NOT_CONFIGURED");
+}
+/** The models the connection's endpoint lists, or none when it cannot say. */
+async function availableModels(name, connection, probe) {
+    if (!probe)
+        return [];
+    const apiKey = resolveApiKey(connection.apiKey, { connection: name }, connection.endpoint);
+    const listed = await listEndpointModels({ endpoint: connection.endpoint, ...(apiKey ? { apiKey } : {}) });
+    if (listed.ok)
+        return listed.models;
+    warn(`Could not list models from ${redactUrlCredentials(connection.endpoint)} (${listed.error}).`);
+    return [];
 }
-/** Operator-owned model-map lifecycle commands. Alias expansion is consumed through the runtime API. */
+/** Probing is the default, so only the opt-out is declared; citty parses `--no-probe` as `probe: false` (see `setup`'s flag in `cli.ts`). */
+const PROBE_ARG = {
+    "no-probe": {
+        type: "boolean",
+        description: "Do not ask the endpoint which models it lists.",
+    },
+};
+const probes = (args) => args.probe !== false;
 export const modelsCommand = defineGroupCommand({
-    meta: { name: "models", description: "Inspect and customize model intent alias defaults" },
+    meta: {
+        name: "models",
+        description: "Show which model answers each alias on a connection, then the models its endpoint lists; `models set` changes one",
+    },
+    // The group runs the list itself, so it declares the output flags a leaf command would get from `defineJsonCommand`.
+    args: { ...GLOBAL_OUTPUT_ARGS, ...CONNECTION_ARG, ...PROBE_ARG },
+    // `akm models` is itself the list, so the bare group is not a usage error here.
+    async defaultRun({ args }) {
+        const { name, connection } = targetConnection(loadConfig(), args.connection);
+        const aliases = Object.fromEntries(Object.entries(connection.models ?? {}).map(([alias, entry]) => [alias, entryModel(entry)]));
+        output("models", { connection: name, aliases, available: await availableModels(name, connection, probes(args)) });
+    },
     subCommands: {
-        "copy-defaults": defineJsonCommand({
+        set: defineJsonCommand({
             meta: {
-                name: "copy-defaults",
-                description: "Copy AKM's installed models.json into the user configuration directory",
+                name: "set",
+                description: "Make a model answer an alias on a connection, e.g. `akm models set reasoning glm-5`; an alias with request fields keeps them",
             },
             args: {
-                overwrite: {
-                    type: "boolean",
-                    default: false,
-                    description: "Confirm replacing an existing regular user models.json file",
-                },
-            },
-            run({ args }) {
-                output("models", copyDefaultModelMap({ overwrite: args.overwrite === true }));
-            },
-        }),
-        list: defineJsonCommand({
-            meta: {
-                name: "list",
-                description: "Show the effective model intent alias table and where each mapping resolved from",
+                alias: { type: "positional", required: true, description: "Alias: fast, balanced, reasoning, or your own" },
+                model: { type: "positional", required: true, description: "The model's name on the endpoint" },
+                ...CONNECTION_ARG,
+                ...PROBE_ARG,
             },
-            run() {
-                output("models-list", { rows: modelsListRows() });
+            async run({ args }) {
+                const alias = args.alias.trim();
+                const model = args.model.trim();
+                if (!alias || !model) {
+                    throw new UsageError("Name an alias and a model: `akm models set <alias> <model>`.", "MISSING_REQUIRED_ARGUMENT");
+                }
+                const { name, connection } = targetConnection(loadConfig(), args.connection);
+                const available = await availableModels(name, connection, probes(args));
+                if (available.length > 0 && !available.includes(model)) {
+                    warn(`"${model}" is not among the models ${name} lists; setting it anyway.`);
+                }
+                const before = connection.models?.[alias];
+                mutateConfig((current) => {
+                    const target = targetConnection(current, name);
+                    const held = target.connection.models?.[alias];
+                    return {
+                        ...current,
+                        connections: {
+                            ...current.connections,
+                            [name]: {
+                                ...target.connection,
+                                models: { ...target.connection.models, [alias]: entryWithModel(held, model) },
+                            },
+                        },
+                    };
+                });
+                output("models-set", {
+                    connection: name,
+                    alias,
+                    model,
+                    previous: before === undefined ? null : entryModel(before),
+                });
             },
         }),
     },