akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/integrations/harnesses/openhands/agent-builder.js

@@ -68,8 +68,7 @@
  * `pattern: "local-runner"`, `structuredOutput: "native-json"`, and no
  * `resume`). Exported standalone so that task only adds a registry entry.
  */
-import { assertNotFlag } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const OPENHANDS_PLATFORM = "openhands";
 /**
@@ -117,7 +116,7 @@ export const openhandsBuilder = {
         args.push(`--task=${buildTaskPayload(req)}`);
         let env;
         if (req.model) {
-            const resolved = resolveModel(req.model, OPENHANDS_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, OPENHANDS_PLATFORM);
             // Model travels via env, not argv — OpenHands' documented channel.
             env = { [OPENHANDS_MODEL_ENV]: resolved };
         }

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

@@ -24,7 +24,6 @@ function caps(c) {
         detection: false,
         configImport: false,
         runtimeIdentity: false,
-        v1Migration: false,
         ...c,
     };
 }

package/dist/integrations/harnesses/pi/agent-builder.js

@@ -48,8 +48,7 @@
  * are registry-side). Exported standalone so that task only adds a registry
  * entry.
  */
-import { assertNotFlag } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const PI_PLATFORM = "pi";
 /**
@@ -87,7 +86,7 @@ export const piBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, PI_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, PI_PLATFORM);
             args.push("--model", resolved);
         }
         if (req.schema) {

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

@@ -24,7 +24,6 @@ function caps(c) {
         detection: false,
         configImport: false,
         runtimeIdentity: false,
-        v1Migration: false,
         ...c,
     };
 }

package/dist/integrations/harnesses/types.js

@@ -4,11 +4,7 @@
 /**
  * Shared base for harness descriptors (#566).
  *
- * Provides the default v1-profile-name matcher so the inference logic lives in
- * ONE place instead of being duplicated across the old `guessAgentPlatform()`
- * (config-migration) and the `name.includes("claude")` heuristic (setup). A
- * concrete harness sets `id`/`aliases`/`capabilities` and, when its v1 profile
- * names could be decorated (e.g. `"opencode-sdk-fast"`), `v1ProfilePrefixes`.
+ * Provides shared optional descriptor fields for concrete harnesses.
  */
 export class BaseHarness {
     runtimeId;
@@ -21,31 +17,4 @@ export class BaseHarness {
     presenceEnv;
     resultExtractor;
     sessionLogProvider;
-    /**
-     * Lowercase prefixes that a decorated v1 profile name may start with and
-     * still belong to this harness (e.g. `["opencode-sdk"]`). The canonical id
-     * and aliases are always matched in addition to these; an empty list means
-     * only exact id/alias matches.
-     */
-    v1ProfilePrefixes = [];
-    matchesV1ProfileName(name) {
-        // Only harnesses with a v1→v2 mapping participate; others never claim a
-        // legacy profile name (so unknown names are dropped, not misclassified).
-        if (!this.capabilities.v1Migration)
-            return false;
-        const lower = name.trim().toLowerCase();
-        if (!lower)
-            return false;
-        if (lower === this.id.toLowerCase())
-            return true;
-        for (const alias of this.aliases) {
-            if (lower === alias.toLowerCase())
-                return true;
-        }
-        for (const prefix of this.v1ProfilePrefixes) {
-            if (lower.startsWith(prefix.toLowerCase()))
-                return true;
-        }
-        return false;
-    }
 }

package/dist/integrations/lockfile.js

@@ -4,8 +4,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../core/common.js";
-import { rethrowIfTestIsolationError } from "../core/errors.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -15,23 +16,26 @@ async function acquireLockSentinel() {
     // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
-        if (tryAcquireLockSync(sentinelPath, String(process.pid))) {
-            return true; // Sentinel created — we own the lock.
+        const releaseBarrier = acquireMaintenanceBarrier();
+        try {
+            const ownership = tryAcquireLockSync(sentinelPath, createLockPayload());
+            if (ownership) {
+                return () => releaseLock(ownership);
+            }
+            const probe = probeLock(sentinelPath);
+            if (probe.state === "stale" && reclaimStaleLock(sentinelPath, probe)) {
+                continue; // Reclaimed — retry immediately.
+            }
         }
-        if (probeLock(sentinelPath).state === "stale") {
-            releaseLock(sentinelPath);
-            continue; // Reclaimed — retry immediately.
+        finally {
+            releaseBarrier();
         }
         // Another process holds the lock — wait briefly before retrying.
         if (attempt < LOCK_MAX_RETRIES - 1) {
             await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
         }
     }
-    // Best-effort: proceed without the lock rather than failing the install.
-    return false;
-}
-function releaseLockSentinel() {
-    releaseLock(getLockfileLockPath());
+    throw new ConfigError(`Could not acquire lockfile sentinel at ${sentinelPath}; refusing to write without exclusive ownership.`, "INVALID_CONFIG_FILE");
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -50,36 +54,43 @@ export function readLockfile() {
         return [];
     }
 }
-export function writeLockfile(entries) {
+function writeLockfileUnlocked(entries) {
     // Always write to $DATA — never to the legacy $CONFIG location.
     const lockfilePath = getLockfilePath();
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(lockfilePath, `${JSON.stringify(entries, null, 2)}\n`);
 }
+export async function writeLockfile(entries) {
+    const release = await acquireLockSentinel();
+    try {
+        writeLockfileUnlocked(entries);
+    }
+    finally {
+        release();
+    }
+}
 export async function upsertLockEntry(entry) {
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
         const entries = readLockfile();
         const withoutExisting = entries.filter((e) => e.id !== entry.id);
-        writeLockfile([...withoutExisting, entry]);
+        writeLockfileUnlocked([...withoutExisting, entry]);
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
 export async function removeLockEntry(id) {
     if (!fs.existsSync(getDataDir()))
         return;
-    const acquired = await acquireLockSentinel();
+    const release = await acquireLockSentinel();
     try {
         const entries = readLockfile();
-        writeLockfile(entries.filter((e) => e.id !== id));
+        writeLockfileUnlocked(entries.filter((e) => e.id !== id));
     }
     finally {
-        if (acquired)
-            releaseLockSentinel();
+        release();
     }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────

package/dist/llm/client.js

@@ -12,14 +12,19 @@
  */
 import { fetchWithTimeout } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
+import { redactSensitiveText } from "../core/redaction.js";
 import { warnVerbose } from "../core/warn.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
 import { emitLlmUsage, extractUsageTokens } from "./usage-telemetry.js";
 // Re-export shared parse utilities so existing importers of `client.ts` continue
 // to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
 export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
 /** Maximum length of an LLM error response body included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
+/** Stable OpenAI-compatible response-schema name used for every structured call. */
+const JSON_SCHEMA_RESPONSE_NAME = "akm_response";
 /**
  * Redact credential-shaped substrings from an upstream error body before
  * including it in a thrown Error. The body is also trimmed to a fixed length
@@ -178,7 +183,11 @@ export async function chatCompletion(config, messages, options) {
     return chatCompletionReal(config, messages, options);
 }
 async function chatCompletionReal(config, messages, options) {
-    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
+    const effectiveTimeoutMs = options && Object.hasOwn(options, "timeoutMs")
+        ? (options.timeoutMs ?? null)
+        : Object.hasOwn(config, "timeoutMs")
+            ? (config.timeoutMs ?? null)
+            : DEFAULT_LLM_TIMEOUT_MS;
     const started = Date.now();
     try {
         return await chatCompletionAttempt(config, messages, options, effectiveTimeoutMs);
@@ -189,8 +198,9 @@ async function chatCompletionReal(config, messages, options) {
         // Timeout-budget guard: if the first attempt already burned most of the
         // budget, a second attempt cannot complete — skip the retry.
         const elapsed = Date.now() - started;
-        const remaining = effectiveTimeoutMs - elapsed;
-        if (elapsed >= effectiveTimeoutMs * RETRY_BUDGET_FRACTION || remaining <= 0) {
+        const remaining = effectiveTimeoutMs === null ? null : effectiveTimeoutMs - elapsed;
+        if (effectiveTimeoutMs !== null &&
+            (elapsed >= effectiveTimeoutMs * RETRY_BUDGET_FRACTION || (remaining !== null && remaining <= 0))) {
             throw err;
         }
         // Signal the caller so it can bump `retryAttempts` (NOT `failureCount`).
@@ -210,6 +220,11 @@ async function chatCompletionReal(config, messages, options) {
  * transient failures.
  */
 async function chatCompletionAttempt(config, messages, options, timeoutMs) {
+    if (config.extraParams !== undefined) {
+        const issue = validateExtraParams(config.extraParams)[0];
+        if (issue)
+            throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
+    }
     const headers = { "Content-Type": "application/json" };
     const resolvedKey = resolveSecret(config.apiKey);
     if (resolvedKey) {
@@ -220,7 +235,12 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     // guess is wrong. Users who need a cap can set llm.maxTokens in config.
     const resolvedMaxTokens = options?.maxTokens ?? config.maxTokens;
     const responseFormat = options?.responseSchema && config.supportsJsonSchema
-        ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
+        ? {
+            response_format: {
+                type: "json_schema",
+                json_schema: { name: JSON_SCHEMA_RESPONSE_NAME, schema: options.responseSchema, strict: true },
+            },
+        }
         : {};
     // Wall-clock start for per-call usage telemetry (#576). Captured here so the
     // emitted duration covers the full request/response/parse cycle of a single
@@ -252,22 +272,22 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
         // caller-driven cancellations. Map both to typed LlmCallError.
         const msg = err instanceof Error ? err.message : String(err);
         if (err instanceof DOMException && err.name === "AbortError") {
-            throw new LlmCallError(`Request timed out after ${timeoutMs}ms`, "timeout");
+            throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
         }
         if (msg.includes("timed out")) {
-            throw new LlmCallError(`Request timed out after ${timeoutMs}ms`, "timeout");
+            throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
         }
         throw new LlmCallError(`Network error: ${msg}`, "network_error");
     }
     if (!response.ok) {
         const rawBody = await response.text().catch(() => "");
-        const safeBody = redactErrorBody(rawBody);
+        const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
         const status = response.status;
         if (status === 429) {
             throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
         }
         if (status >= 500 && isHtmlResponse(rawBody)) {
-            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${htmlExcerpt(rawBody)}`, "provider_html_error", status);
+            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);
@@ -279,14 +299,14 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     // we can categorize an HTML page distinctly from a malformed-JSON parse_error.
     const rawOkBody = await response.text();
     if (isHtmlResponse(rawOkBody)) {
-        throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${htmlExcerpt(rawOkBody)}`, "provider_html_error", response.status);
+        throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", response.status);
     }
     let json;
     try {
         json = JSON.parse(rawOkBody);
     }
     catch {
-        throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactErrorBody(rawOkBody)}`, "parse_error", response.status);
+        throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
     }
     // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
     // or garbled usage block still records duration + model, and a throwing sink
@@ -300,7 +320,7 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     });
     const content = (json.choices?.[0]?.message?.content ?? "").trim();
     const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
-    return content || reasoning;
+    return redactSensitiveText(content || reasoning, resolvedKey ? [resolvedKey] : []);
 }
 /**
  * Strip `<think>` blocks, code fences, and escape control characters in JSON
@@ -325,6 +345,16 @@ export async function isLlmAvailable(config) {
     }
 }
 // ── Capability probe ────────────────────────────────────────────────────────
+const CAPABILITY_PROBE_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        ok: { type: "boolean", const: true },
+        ingest: { type: "boolean", const: true },
+        lint: { type: "boolean", const: true },
+    },
+    required: ["ok", "ingest", "lint"],
+    additionalProperties: false,
+};
 /**
  * Ask the model to emit a strict JSON object so we know whether the knowledge
  * wiki ingest/lint flows can rely on structured output. Failure is non-fatal —
@@ -332,7 +362,7 @@ export async function isLlmAvailable(config) {
  */
 export async function probeLlmCapabilities(config) {
     try {
-        const raw = await chatCompletion(config, [
+        const raw = await chatCompletion({ ...config, supportsJsonSchema: true }, [
             {
                 role: "system",
                 content: "You return only valid JSON. No prose, no markdown fences.",
@@ -341,13 +371,17 @@ export async function probeLlmCapabilities(config) {
                 role: "user",
                 content: 'Return exactly this JSON object and nothing else: {"ok": true, "ingest": true, "lint": true}',
             },
-        ], { maxTokens: 64, temperature: 0 });
+        ], { maxTokens: 64, temperature: 0, responseSchema: CAPABILITY_PROBE_JSON_SCHEMA });
         if (!raw)
             return { reachable: false, structuredOutput: false, error: "empty response" };
         const parsed = parseJsonResponse(raw);
         return {
             reachable: true,
-            structuredOutput: Boolean(parsed && parsed.ok === true),
+            structuredOutput: Boolean(parsed &&
+                Object.keys(parsed).length === 3 &&
+                parsed.ok === true &&
+                parsed.ingest === true &&
+                parsed.lint === true),
         };
     }
     catch (err) {

package/dist/llm/feature-gate.js

@@ -3,54 +3,39 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * For each feature key, return the effective enabled state by reading the
- * new 0.8.0 config shape. Defaults match the legacy `LlmFeatureFlags` docstrings.
+ * 0.9.0 config shape. Defaults match the legacy `LlmFeatureFlags` docstrings.
  */
 // Defaults below mirror the legacy LlmFeatureFlags docstrings so existing
 // behaviour is preserved when a config is silent on a flag.
 const FEATURE_LOCATION = {
-    // Legacy default: false → memory_consolidation only runs when explicitly enabled
-    // (either via the user's improve profile or the built-in `default` profile).
-    memory_consolidation: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.enabled ?? false,
-    // 0.8.0 unified gate: replaces the legacy `feedback_distillation` key.
-    // The orchestration gate (planner) and the LLM-call gate now share the same
-    // source of truth: `processes.distill.enabled`. Default: true (matches the
-    // built-in `default` profile).
-    distill: (cfg) => cfg.profiles?.improve?.default?.processes?.distill?.enabled ?? true,
     // Legacy default: true
-    memory_inference: (cfg) => cfg.profiles?.improve?.default?.processes?.memoryInference?.enabled ?? true,
+    memory_inference: (cfg) => cfg.index?.memory?.enabled ?? true,
     // Legacy default: true
-    graph_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.graphExtraction?.enabled ?? true,
+    graph_extraction: (cfg) => cfg.index?.graph?.enabled ?? true,
     // Legacy default: false
     metadata_enhance: (cfg) => cfg.index?.metadataEnhance?.enabled ?? false,
-    // Default ON since R3 (docs/design/improve-self-learning-analysis.md G5):
-    // distill is a primary acquisition path, so the gate guards minted content by
-    // default. The judge fails CLOSED (07 P0-2): no LLM / timeout / parse failure
-    // reject the proposal rather than passing it through — an unjudgeable proposal
-    // must not slip into the stash. Opt out via
-    // profiles.improve.default.processes.distill.qualityGate.enabled: false.
-    lesson_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.distill?.qualityGate?.enabled ?? true,
-    // Legacy default: false
-    proposal_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.reflect?.qualityGate?.enabled ?? false,
-    // Legacy default: false
-    memory_contradiction_detection: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.contradictionDetection?.enabled ?? false,
     // Always on at the LLM-wrapper level. Enablement is decided ONCE at the
     // extract entry point (`akmExtract`): the `extract.enabled` process toggle
-    // gates extract as a STAGE of `akm improve` (the active improve profile, per
+    // gates extract as a STAGE of `akm improve` (the active improve strategy, per
     // #593/#594), while an explicit `akm extract` command always runs. Gating the
     // inner LLM calls on `default.processes.extract.enabled` here was a footgun —
-    // dropping extract from the daily improve profile silently disabled the
+    // dropping extract from the daily improve strategy silently disabled the
     // standalone `akm extract` command. (cfg unused — kept for resolver signature.)
     session_extraction: (_cfg) => true,
 };
 /**
  * Pure predicate: is the named feature gate enabled in `config`?
  *
- * Reads from the unified 0.8.0 config shape. Defaults follow the legacy
+ * Reads from the unified 0.9.0 config shape. Defaults follow the legacy
  * `LlmFeatureFlags` docstring defaults.
  */
-export function isLlmFeatureEnabled(config, feature) {
+export function isLlmFeatureEnabled(config, feature, improveEnabled) {
     if (!config)
         return false;
+    // Improve resolves enablement from its selected strategy and passes the
+    // decision in. This module does not own a second improve config lookup.
+    if (improveEnabled !== undefined)
+        return improveEnabled;
     const resolver = FEATURE_LOCATION[feature];
     if (!resolver)
         return false;
@@ -67,13 +52,13 @@ const DEFAULT_TIMEOUT_MS = 600_000;
  */
 export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     const resolveFallback = async () => typeof fallback === "function" ? await fallback() : fallback;
-    if (!isLlmFeatureEnabled(config, feature)) {
+    if (!isLlmFeatureEnabled(config, feature, opts?.enabled)) {
         opts?.onFallback?.({ feature, reason: "disabled" });
         return resolveFallback();
     }
-    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutMs = opts && Object.hasOwn(opts, "timeoutMs") ? (opts.timeoutMs ?? null) : DEFAULT_TIMEOUT_MS;
     try {
-        if (timeoutMs <= 0) {
+        if (timeoutMs === null || timeoutMs <= 0) {
             return await fn();
         }
         return await runWithTimeout(fn, timeoutMs, feature);
@@ -96,7 +81,7 @@ export async function tryLlmFeature(feature, config, fn, fallback, opts) {
 export function isProcessEnabled(section, processName, config) {
     if (!config)
         return false;
-    // index.metadataEnhance is a first-class new-shape entry.
+    // Index passes are first-class 0.9 entries.
     if (section === "index") {
         if (processName === "metadata_enhance" || processName === "metadataEnhance") {
             return config.index?.metadataEnhance?.enabled ?? true;
@@ -108,23 +93,6 @@ export function isProcessEnabled(section, processName, config) {
             return isLlmFeatureEnabled(config, "graph_extraction");
         }
     }
-    if (section === "improve") {
-        const processes = config.profiles?.improve?.default?.processes;
-        const entry = processes?.[processName];
-        if (entry && typeof entry.enabled === "boolean")
-            return entry.enabled;
-        // Fallback to default-enabled state for known processes.
-        switch (processName) {
-            case "reflect":
-            case "distill":
-            case "consolidate":
-            case "memoryInference":
-            case "graphExtraction":
-                return true;
-            default:
-                return false;
-        }
-    }
     return false;
 }
 /** Specific error class so call sites and the wrapper can tell timeouts apart from generic throws. */

package/dist/llm/graph-extract.js

@@ -16,7 +16,7 @@
  * `mock.module("../src/llm/graph-extract", ...)` without hitting a network.
  *
  * Locked v1 contract (#208): the LLM connection always comes from the
- * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * selected named LLM engine. Callers obtain
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */

package/dist/llm/index-passes.js

@@ -1,50 +1,16 @@
 // 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 { getDefaultLlmConfig, getIndexPassConfig } from "../core/config/config.js";
+import { materializeLlmConnection, resolveLlmEngineUse } from "../integrations/agent/engine-resolution.js";
 /**
- * Map a pass name (as used by callers — "memory", "graph", etc.) to the
- * matching key under `profiles.improve.default.processes`. Pass names with
- * no improve-profile counterpart return undefined and resolve via the
- * default LLM only.
+ * Resolve standalone index passes from the index section only. Improve
+ * strategies own improve-triggered calls and are intentionally not consulted.
  */
-function improveProcessKeyForPass(passName) {
-    switch (passName) {
-        case "memory":
-            return "memoryInference";
-        case "graph":
-            return "graphExtraction";
-        default:
-            return undefined;
-    }
-}
 export function resolveIndexPassLLM(passName, config) {
-    // Gate 1 — explicit opt-out via the index-config block stays authoritative.
-    const passConfig = getIndexPassConfig(config.index, passName);
-    if (passConfig?.llm === false)
+    const pass = config.index?.[passName];
+    if (pass?.enabled === false)
         return undefined;
-    // Gate 2 — per-process profile from the improve profile, when present.
-    // This is the path that lets
-    //   profiles.improve.default.processes.graphExtraction.profile = "ministral-3b"
-    // actually take effect on the graph pass instead of being silently
-    // ignored.
-    const processKey = improveProcessKeyForPass(passName);
-    if (processKey) {
-        const processConfig = config.profiles?.improve?.default?.processes?.[processKey];
-        // Honor enabled === false here too — an explicit disable wins.
-        if (processConfig?.enabled === false)
-            return undefined;
-        const profileName = processConfig?.profile;
-        if (profileName) {
-            const profile = config.profiles?.llm?.[profileName];
-            if (profile)
-                return profile;
-            // A named-but-missing profile is a configuration error in spirit, but
-            // we fall through to default rather than throwing — callers gracefully
-            // treat `undefined` as "pass disabled" and emitting a hard throw here
-            // would take the whole improve run down on a typo.
-        }
-    }
-    // Gate 3 — fall back to the default LLM profile.
-    return getDefaultLlmConfig(config);
+    const defaults = config.index?.defaults;
+    const resolved = resolveLlmEngineUse(config, [defaults ?? {}, pass ?? {}], { optional: true });
+    return resolved ? materializeLlmConnection(resolved) : undefined;
 }

package/dist/llm/memory-infer-impl.js

@@ -14,7 +14,7 @@
  * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
  *
  * Locked v1 contract (#208): the LLM connection always comes from the
- * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * selected named LLM engine. Callers obtain
  * the connection via `resolveIndexPassLLM("memory", config)` and pass it
  * straight through.
  */

package/dist/llm/usage-persist.js

@@ -31,6 +31,10 @@ function toEventMetadata(record) {
     const metadata = { durationMs: record.durationMs };
     if (record.stage !== undefined)
         metadata.stage = record.stage;
+    if (record.engine !== undefined)
+        metadata.engine = record.engine;
+    if (record.process !== undefined)
+        metadata.process = record.process;
     if (record.model !== undefined)
         metadata.model = record.model;
     if (record.finishReason !== undefined)

package/dist/llm/usage-telemetry.js

@@ -24,7 +24,7 @@
  * `undefined` outside any `withLlmStage` scope.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-const stageStorage = new AsyncLocalStorage();
+const attributionStorage = new AsyncLocalStorage();
 let usageSink;
 /**
  * Run `fn` with `stage` as the ambient LLM stage. Any `chatCompletion` call
@@ -32,12 +32,12 @@ let usageSink;
  * helpers and nested `withLlmStage` calls — the innermost wins) is attributed
  * to `stage`. Returns whatever `fn` returns; never alters control flow.
  */
-export function withLlmStage(stage, fn) {
-    return stageStorage.run(stage, fn);
+export function withLlmStage(stage, fn, attribution = {}) {
+    return attributionStorage.run({ ...attributionStorage.getStore(), ...attribution, stage }, fn);
 }
 /** The ambient LLM stage for the current async context, or `undefined` outside any {@link withLlmStage} scope. */
 export function currentLlmStage() {
-    return stageStorage.getStore();
+    return attributionStorage.getStore()?.stage;
 }
 /**
  * Install the process-wide usage sink. Replaces any previously installed sink.
@@ -69,7 +69,13 @@ export function emitLlmUsage(record) {
     if (!sink)
         return;
     try {
-        sink({ ...record, stage: record.stage ?? currentLlmStage() });
+        const ambient = attributionStorage.getStore();
+        sink({
+            ...record,
+            stage: record.stage ?? ambient?.stage,
+            engine: record.engine ?? ambient?.engine,
+            process: record.process ?? ambient?.process,
+        });
     }
     catch {
         // Telemetry must never break a real run.
@@ -78,6 +84,30 @@ export function emitLlmUsage(record) {
 function asFiniteNonNegative(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Decode durable event metadata with the same validation used by health aggregation. */
+export function decodeLlmUsageRecord(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    const durationMs = asFiniteNonNegative(raw.durationMs);
+    if (durationMs === undefined)
+        return undefined;
+    const record = { durationMs };
+    for (const key of ["stage", "engine", "process", "model", "finishReason"]) {
+        const decoded = asNonEmptyString(raw[key]);
+        if (decoded !== undefined)
+            record[key] = decoded;
+    }
+    for (const key of ["promptTokens", "completionTokens", "totalTokens", "reasoningTokens"]) {
+        const decoded = asFiniteNonNegative(raw[key]);
+        if (decoded !== undefined)
+            record[key] = decoded;
+    }
+    return record;
+}
 /**
  * Project a provider `usage` block into the token fields of an
  * {@link LlmUsageRecord}. Missing or garbled values are omitted (not zeroed)