akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/llm/graph-extract.js

@@ -15,15 +15,16 @@
  * This module is intentionally tiny and stateless so tests can stub it via
  * `mock.module("../src/llm/graph-extract", ...)` without hitting a network.
  *
- * The LLM connection comes from the selected named engine. Callers obtain it
- * via `resolveIndexPassLLM("graph", config)` and pass it straight through.
+ * The symbolic LLM runner comes from the current index-pass execution
+ * resolution and is passed straight through.
  */
 import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
+import { ConfigError } from "../core/errors.js";
 import { parseEmbeddedJsonResponse } from "../core/parse.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, isContextSizeError } from "./client.js";
+import { isContextSizeError } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 import { callStructured } from "./structured-call.js";
 /**
@@ -447,8 +448,24 @@ function buildBatchUserPrompt(bodies) {
         `- The array MUST have exactly ${count} elements — one placeholder per asset even if empty.\n\n` +
         assetBlocks);
 }
-function formatContextHint(llmConfig) {
-    return llmConfig.contextLength ? `, configured contextLength=${llmConfig.contextLength}` : "";
+function formatContextHint(llmRunner) {
+    return llmRunner.connection.contextLength ? `, configured contextLength=${llmRunner.connection.contextLength}` : "";
+}
+/** Dispatch one raw graph prompt through the common resolved-request adapter. */
+async function callGraphLlm(runner, messages, request, lease, onNotices) {
+    return callStructured({
+        feature: "graph_extraction",
+        runner,
+        ...(lease ? { lease } : {}),
+        messages,
+        request,
+        onNotices,
+        parse: (raw) => raw ?? "",
+        onError: (_cls, error) => {
+            throw error;
+        },
+        fallback: "",
+    });
 }
 /**
  * Parse and validate a single item from the batch response array.
@@ -457,6 +474,21 @@ function formatContextHint(llmConfig) {
 function parseBatchItem(raw) {
     return parseGraphExtraction(raw);
 }
+function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState) {
+    if (batchState)
+        batchState.nonArrayBatchFailures = 0;
+    if (batchResult.length > nonEmptyBodies.length) {
+        warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
+            `ignoring ${batchResult.length - nonEmptyBodies.length} extra item(s).`);
+    }
+    for (let j = 0; j < nonEmptyBodies.length; j++) {
+        const originalIndex = nonEmptyIndices[j];
+        if (originalIndex === undefined)
+            continue;
+        if (j < batchResult.length)
+            results[originalIndex] = parseBatchItem(batchResult[j]);
+    }
+}
 /**
  * Extract entities and relations from multiple asset bodies in a single LLM
  * call (batched graph extraction).
@@ -474,13 +506,13 @@ function parseBatchItem(raw) {
  * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
  * and onFallback hook are honoured uniformly.
  *
- * @param llmConfig - LLM connection configuration.
+ * @param llmRunner - Symbolic LLM runner selected through shared execution lowering.
  * @param bodies    - Asset body strings to process in one batch.
  * @param signal    - Optional AbortSignal for cancellation.
  * @param akmConfig - Full AKM config (for feature-gate checks).
  * @param onFallback - Optional fallback event sink.
  */
-export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfig, onFallback, options = {}) {
+export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfig, onFallback, options = {}) {
     const empty = () => ({ entities: [], relations: [] });
     const batchState = normalizeBatchState(options.batchState);
     // Degenerate case: no bodies → empty array (not an error).
@@ -488,7 +520,7 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
         return [];
     // Single body: delegate to the single-asset path for identical behaviour.
     if (bodies.length === 1) {
-        const result = await extractGraphFromBody(llmConfig, bodies[0] ?? "", signal, akmConfig, onFallback, options);
+        const result = await extractGraphFromBody(llmRunner, bodies[0] ?? "", signal, akmConfig, onFallback, options);
         return [result];
     }
     // Filter out bodies that are empty so we don't waste tokens, but keep
@@ -511,13 +543,13 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
     }
     if (oversizedIndices.length > 0) {
         await Promise.all(oversizedIndices.map(async (index) => {
-            results[index] = await extractGraphFromBody(llmConfig, bodies[index] ?? "", signal, akmConfig, onFallback, options);
+            results[index] = await extractGraphFromBody(llmRunner, bodies[index] ?? "", signal, akmConfig, onFallback, options);
         }));
     }
     if (nonEmptyBodies.length === 0)
         return results;
     if (batchState?.batchingDisabled) {
-        return Promise.all(bodies.map((body) => extractGraphFromBody(llmConfig, body, signal, akmConfig, onFallback, options)));
+        return Promise.all(bodies.map((body) => extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options)));
     }
     const systemPrompt = buildBatchSystemPrompt();
     const userPrompt = buildBatchUserPrompt(nonEmptyBodies);
@@ -527,19 +559,19 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
     }
     let batchContextError = false;
     let nonArrayResponse = false;
-    const batchResult = await tryLlmFeature("graph_extraction", akmConfig, async () => {
+    const batchOutcome = await tryLlmFeature("graph_extraction", akmConfig, async () => {
         try {
-            const raw = await chatCompletion(llmConfig, [
+            const raw = await callGraphLlm(llmRunner, [
                 { role: "system", content: systemPrompt },
                 { role: "user", content: userPrompt },
             ], {
                 temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
+                timeoutMs: llmRunner.timeoutMs,
                 signal,
                 onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-            });
+            }, options.lease, options.onNotices);
             if (!raw)
-                return null;
+                return { kind: "value", value: null };
             // Array-preferring salvage (#635): the batch contract is a top-level
             // JSON array. A leading/example `{…}` object in the response must not
             // mask a valid `[…]` array as a false "non-array" failure.
@@ -549,10 +581,10 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
                 // (#635). Many genuine non-array responses recover when the model is
                 // told explicitly to emit only the raw array.
                 bumpTelemetry(options.telemetry, "retryAttempts");
-                const retryRaw = await chatCompletion(llmConfig, [
+                const retryRaw = await callGraphLlm(llmRunner, [
                     { role: "system", content: buildBatchRetrySystemPrompt() },
                     { role: "user", content: userPrompt },
-                ], { temperature: 0, timeoutMs: llmConfig.timeoutMs, signal });
+                ], { temperature: 0, timeoutMs: llmRunner.timeoutMs, signal }, options.lease, options.onNotices);
                 parsed = retryRaw ? parseEmbeddedJsonResponse(retryRaw, { expect: "array" }) : undefined;
             }
             if (!Array.isArray(parsed)) {
@@ -566,51 +598,42 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
                 }
                 warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s) ` +
                     `even after a stricter retry; will fall back per-asset. ` +
-                    `promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
-                return null;
+                    `promptChars=${userPrompt.length}${formatContextHint(llmRunner)}`);
+                return { kind: "value", value: null };
             }
-            return parsed;
+            return { kind: "value", value: parsed };
         }
         catch (err) {
+            if (err instanceof ConfigError)
+                return { kind: "config-error", error: err };
             const errMsg = toErrorMessage(err);
             if (isContextSizeError(errMsg)) {
                 batchContextError = true;
                 bumpTelemetry(options.telemetry, "contextBatchRetries");
                 warn(`graph extraction (batch): context size exceeded for ${nonEmptyBodies.length} asset(s); ` +
-                    `skipping batch. promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
+                    `skipping batch. promptChars=${userPrompt.length}${formatContextHint(llmRunner)}`);
             }
             else {
                 warn(`graph extraction (batch) failed for ${nonEmptyBodies.length} asset(s); ` +
-                    `promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
+                    `promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
             }
-            return null;
+            return { kind: "value", value: null };
         }
-    }, null, {
-        timeoutMs: llmConfig.timeoutMs,
+    }, { kind: "value", value: null }, {
+        timeoutMs: llmRunner.timeoutMs,
         onFallback,
     });
+    if (batchOutcome.kind === "config-error")
+        throw batchOutcome.error;
+    const batchResult = batchOutcome.value;
     // Map successful batch results back to their original indices.
     if (batchResult !== null) {
-        if (batchState)
-            batchState.nonArrayBatchFailures = 0;
-        if (batchResult.length > nonEmptyBodies.length) {
-            warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
-                `ignoring ${batchResult.length - nonEmptyBodies.length} extra item(s).`);
-        }
-        for (let j = 0; j < nonEmptyBodies.length; j++) {
-            const originalIndex = nonEmptyIndices[j];
-            if (originalIndex === undefined)
-                continue;
-            if (j < batchResult.length) {
-                results[originalIndex] = parseBatchItem(batchResult[j]);
-            }
-            // j >= batchResult.length → partial failure; handled below.
-        }
+        applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState);
     }
     if (batchContextError && nonEmptyBodies.length > 1) {
         const splitAt = Math.ceil(nonEmptyBodies.length / 2);
-        const left = await extractGraphFromBodies(llmConfig, nonEmptyBodies.slice(0, splitAt), signal, akmConfig, onFallback, options);
-        const right = await extractGraphFromBodies(llmConfig, nonEmptyBodies.slice(splitAt), signal, akmConfig, onFallback, options);
+        const left = await extractGraphFromBodies(llmRunner, nonEmptyBodies.slice(0, splitAt), signal, akmConfig, onFallback, options);
+        const right = await extractGraphFromBodies(llmRunner, nonEmptyBodies.slice(splitAt), signal, akmConfig, onFallback, options);
         const combined = [...left, ...right];
         for (let j = 0; j < nonEmptyIndices.length; j++) {
             const origIdx = nonEmptyIndices[j];
@@ -642,7 +665,7 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
         }
         await Promise.all(fallbackIndices.map(async (origIdx) => {
             const body = bodies[origIdx] ?? "";
-            results[origIdx] = await extractGraphFromBody(llmConfig, body, signal, akmConfig, onFallback, options);
+            results[origIdx] = await extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options);
         }));
     }
     else if (batchContextError) {
@@ -664,7 +687,7 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
  * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
  * and onFallback hook are honoured uniformly (Fix C5).
  */
-export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, onFallback, options = {}) {
+export async function extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options = {}) {
     const empty = (reason, status) => ({
         entities: [],
         relations: [],
@@ -682,7 +705,7 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
     if (chunked.chunks.length > 1) {
         const chunkResults = [];
         for (const chunk of chunked.chunks) {
-            chunkResults.push(await extractGraphFromBody(llmConfig, chunk, signal, akmConfig, onFallback, options));
+            chunkResults.push(await extractGraphFromBody(llmRunner, chunk, signal, akmConfig, onFallback, options));
         }
         const merged = mergeGraphExtractions(chunkResults);
         merged.truncationCount = (merged.truncationCount ?? 0) + chunked.truncationCount;
@@ -692,17 +715,19 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
     return callStructured({
         feature: "graph_extraction",
         akmConfig,
-        config: llmConfig,
+        runner: llmRunner,
+        ...(options.lease ? { lease: options.lease } : {}),
         messages: [
             { role: "system", content: SYSTEM_PROMPT },
             { role: "user", content: userPrompt },
         ],
         request: {
             temperature: 0.1,
-            timeoutMs: llmConfig.timeoutMs,
+            timeoutMs: llmRunner.timeoutMs,
             signal,
             onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
         },
+        onNotices: options.onNotices,
         parse: (raw) => {
             if (!raw)
                 return empty();
@@ -724,18 +749,18 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
             const errMsg = toErrorMessage(err);
             if (cls === "context_limit") {
                 bumpTelemetry(options.telemetry, "failureCount");
-                warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}. ` +
+                warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}. ` +
                     `Consider increasing llm.contextLength in config.json.`);
                 return empty("context_limit", "failed");
             }
             else if (cls === "html") {
                 bumpTelemetry(options.telemetry, "htmlErrorCount");
-                warn(`graph extraction: provider returned HTML instead of JSON for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
+                warn(`graph extraction: provider returned HTML instead of JSON for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
                 return empty("llm_error", "failed");
             }
             else {
                 bumpTelemetry(options.telemetry, "failureCount");
-                warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
+                warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmRunner)}: ${errMsg}`);
                 return empty("llm_error", "failed");
             }
         },

package/dist/llm/index-passes.js

@@ -1,16 +1,54 @@
 // 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 { materializeLlmConnection, resolveLlmEngineUse } from "../integrations/agent/engine-resolution.js";
+import { ConfigError } from "../core/errors.js";
+import { cloneExecutionJsonObject } from "../execution/json.js";
+import { lowerResolvedExecutionRequest } from "../integrations/agent/execution-lowering.js";
+import { prepareInlineExecution } from "../integrations/agent/inline-execution.js";
+const NO_LOWERING_NOTICES = Object.freeze([]);
+function own(value, key) {
+    return value !== undefined && Object.hasOwn(value, key);
+}
+/** Adapt one index invocation layer into the shared execution vocabulary. */
+function indexExecutionDefaults(layer) {
+    if (!layer)
+        return {};
+    return {
+        ...(own(layer, "engine") ? { engine: layer.engine } : {}),
+        ...(own(layer, "model") ? { model: layer.model } : {}),
+        ...(own(layer, "timeoutMs") ? { timeout: layer.timeoutMs } : {}),
+        ...(own(layer, "llm") && layer.llm !== undefined
+            ? { inference: cloneExecutionJsonObject(layer.llm, "index pass LLM inference") }
+            : {}),
+    };
+}
 /**
  * Resolve standalone index passes from the index section only. Improve
  * strategies own improve-triggered calls and are intentionally not consulted.
  */
-export function resolveIndexPassLLM(passName, config) {
+export function resolveIndexPassExecution(passName, config) {
     const pass = config.index?.[passName];
     if (pass?.enabled === false)
-        return undefined;
+        return Object.freeze({ runner: undefined, notices: NO_LOWERING_NOTICES });
     const defaults = config.index?.defaults;
-    const resolved = resolveLlmEngineUse(config, [defaults ?? {}, pass ?? {}], { optional: true });
-    return resolved ? materializeLlmConnection(resolved) : undefined;
+    const fallbackLlmEngine = config.defaults?.llmEngine;
+    const selectedEngine = pass?.engine ?? defaults?.engine ?? fallbackLlmEngine;
+    if (!selectedEngine)
+        return Object.freeze({ runner: undefined, notices: NO_LOWERING_NOTICES });
+    const invocationDefaults = {
+        ...indexExecutionDefaults(defaults),
+        ...(!own(defaults, "engine") && fallbackLlmEngine ? { engine: fallbackLlmEngine } : {}),
+    };
+    const prepared = prepareInlineExecution({
+        content: "",
+        config,
+        invocationKind: "direct",
+        invocationDefaults,
+        current: indexExecutionDefaults(pass),
+    });
+    const lowered = lowerResolvedExecutionRequest(prepared.request, prepared.config);
+    if (lowered.runner.kind !== "llm") {
+        throw new ConfigError(`Index pass ${JSON.stringify(passName)} requires an LLM engine; ${JSON.stringify(selectedEngine)} is not one.`, "INVALID_CONFIG_FILE");
+    }
+    return Object.freeze({ runner: lowered.runner, notices: lowered.notices });
 }

package/dist/llm/memory-infer.js

@@ -13,8 +13,8 @@
  * This module is intentionally tiny and stateless so tests can stub it via
  * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
  *
- * The LLM connection comes from the selected named engine. Callers obtain it
- * via `resolveIndexPassLLM("memory", config)` and pass it straight through.
+ * The symbolic LLM runner comes from the current index-pass execution
+ * resolution and is passed straight through.
  */
 import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
 import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
@@ -37,7 +37,7 @@ const PROMPT_PLACEHOLDERS = new Set([
 ]);
 /**
  * Strict JSON Schema for the derived-memory payload. Sent to providers that
- * opt in via `ChatCompletionConfig.supportsJsonSchema = true`; the client
+ * opt in via `runner.connection.supportsJsonSchema = true`; the client
  * silently drops the schema for providers that don't.
  *
  * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
@@ -70,7 +70,7 @@ const DERIVED_MEMORY_JSON_SCHEMA = {
  * feature gate, error classification, and onFallback hook are honoured uniformly
  * (Fix C5).
  */
-export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
+export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt, onNotices, lease) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
@@ -84,18 +84,20 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
     return callStructured({
         feature: "memory_inference",
         akmConfig,
-        config: llmConfig,
+        runner: llmRunner,
+        ...(lease ? { lease } : {}),
         messages: [
             { role: "system", content: SYSTEM_PROMPT },
             { role: "user", content: userPrompt },
         ],
         request: {
             temperature: 0.1,
-            timeoutMs: llmConfig.timeoutMs,
+            timeoutMs: llmRunner.timeoutMs,
             signal,
             responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
             onRetryAttempt,
         },
+        onNotices,
         parse: (raw) => {
             if (!raw)
                 return undefined;

package/dist/llm/metadata-enhance.js

@@ -22,7 +22,7 @@ const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
  * `akmConfig` is `undefined` the gate is bypassed entirely: the LLM call runs
  * unconditionally and errors propagate to direct callers such as tests.
  */
-export async function enhanceMetadata(config, entry, fileContent, signal, akmConfig) {
+export async function enhanceMetadata(runner, entry, fileContent, signal, akmConfig, onNotices, lease) {
     const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
     if (entry.description)
         contextParts.push(`Current description: ${entry.description}`);
@@ -51,12 +51,14 @@ Return ONLY the JSON object, no explanation.`;
     const outcome = await callStructured({
         feature: "metadata_enhance",
         akmConfig,
-        config,
+        runner,
+        ...(lease ? { lease } : {}),
         messages: [
             { role: "system", content: SYSTEM_PROMPT },
             { role: "user", content: userPrompt },
         ],
-        request: { signal, timeoutMs: config.timeoutMs },
+        request: { signal, timeoutMs: runner.timeoutMs },
+        onNotices,
         parse: (raw) => {
             const parsed = raw ? parseJsonResponse(raw) : undefined;
             const metadata = {};

package/dist/llm/structured-call.js

@@ -1,8 +1,11 @@
 // 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 { chatCompletion, isContextSizeError, LlmCallError, } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
+import { ConfigError } from "../core/errors.js";
+import { acquireLoweredExecutionDispatchLease, dispatchLoweredExecutionRequest, lowerResolvedExecutionRequestWithRunner, } from "../integrations/agent/execution-lowering.js";
+import { prepareInlineExecutionWithRunner } from "../integrations/agent/inline-execution.js";
+import { isContextSizeError, LlmCallError } from "./client.js";
+import { isLlmFeatureEnabled, tryLlmFeature, } from "./feature-gate.js";
 /**
  * Classify a thrown LLM error into one of the three buckets. This is the single
  * home for the `isContextSizeError -> html -> other` ladder that was previously
@@ -16,42 +19,136 @@ export function classifyLlmError(err) {
         return "html";
     return "other";
 }
+function own(value, key) {
+    return value !== undefined && Object.hasOwn(value, key);
+}
+/** @internal Exact request-to-cascade projection, exported for presence-semantics contracts. */
+export function resolveStructuredCurrent(current, request) {
+    const out = current ? { ...current } : {};
+    const requestHasInference = own(request, "temperature") || own(request, "maxTokens") || own(request, "enableThinking");
+    const baseInference = current?.inference && typeof current.inference === "object" && !Array.isArray(current.inference)
+        ? { ...current.inference }
+        : {};
+    const inference = { ...baseInference };
+    if (own(request, "temperature") && request?.temperature !== undefined)
+        inference.temperature = request.temperature;
+    if (own(request, "maxTokens") && request?.maxTokens !== undefined)
+        inference.maxTokens = request.maxTokens;
+    if (own(request, "enableThinking") && request?.enableThinking !== undefined) {
+        inference.enableThinking = request.enableThinking;
+    }
+    if (Object.keys(inference).length > 0 || requestHasInference)
+        out.inference = inference;
+    else if (current?.inference === null)
+        out.inference = null;
+    if (own(request, "responseSchema") && request?.responseSchema !== undefined) {
+        out.outputSchema = request.responseSchema;
+    }
+    if (own(request, "timeoutMs"))
+        out.timeout = request?.timeoutMs ?? null;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function requireTerminalUserMessage(messages) {
+    const terminal = messages.at(-1);
+    if (!terminal || terminal.role !== "user") {
+        throw new TypeError("callStructured messages must end with the terminal user command");
+    }
+    return {
+        content: terminal.content,
+        conversation: messages.slice(0, -1).map((message) => ({ role: message.role, content: message.content })),
+    };
+}
+function dispatchFailure(result) {
+    const message = result.error ?? result.stderr ?? result.reason ?? "LLM dispatch failed";
+    return result.llmErrorCode ? new LlmCallError(message, result.llmErrorCode) : new Error(message);
+}
+/**
+ * Validate one already-selected symbolic LLM runner before an operation makes
+ * any durable mutation. Callers must apply their feature/authorization gates
+ * first. Acquisition crosses the canonical prepare -> lower -> lease boundary,
+ * so required credentials are snapshotted by the same central authority as a
+ * real call without contacting the provider.
+ */
+export async function preflightStructuredLlmRunner(runner) {
+    const prepared = prepareInlineExecutionWithRunner({
+        content: "Validate the selected LLM runner before operation dispatch.",
+        runner,
+        invocationKind: "direct",
+    });
+    const lowered = lowerResolvedExecutionRequestWithRunner(prepared.request, prepared.runner);
+    return acquireLoweredExecutionDispatchLease(lowered);
+}
 export async function callStructured(opts) {
-    const { feature, akmConfig, enabled, config, messages, request, parse, onError, fallback, onFallback } = opts;
-    const chat = request?.chat ?? chatCompletion;
-    // Forward each option key ONLY when present on `request` — see the
-    // key-presence semantics note on CallStructuredRequest: for `timeoutMs`,
-    // present-but-undefined means "explicitly disabled" while absent means
-    // "use the default", both in the feature-gate wrapper and the transport.
-    const has = (key) => request !== undefined && Object.hasOwn(request, key);
-    const chatOptions = {
-        ...(has("temperature") ? { temperature: request?.temperature } : {}),
-        ...(has("timeoutMs") ? { timeoutMs: request?.timeoutMs } : {}),
-        ...(has("signal") ? { signal: request?.signal } : {}),
-        ...(has("responseSchema") ? { responseSchema: request?.responseSchema } : {}),
-        ...(has("maxTokens") ? { maxTokens: request?.maxTokens } : {}),
-        ...(has("enableThinking") ? { enableThinking: request?.enableThinking } : {}),
-        ...(has("onRetryAttempt") ? { onRetryAttempt: request?.onRetryAttempt } : {}),
+    const { feature, akmConfig, enabled, messages, request, parse, onError, fallback, onFallback } = opts;
+    // A disabled feature owns a true no-work path: it does not need a runner,
+    // messages, authorization, lowering, or provider state. Some commands keep
+    // their runner optional precisely because a disabled feature must fall back
+    // before execution planning begins.
+    if (akmConfig !== undefined && !isLlmFeatureEnabled(akmConfig, feature, enabled)) {
+        return tryLlmFeature(feature, akmConfig, async () => fallback, fallback, {
+            ...(own(request, "timeoutMs") ? { timeoutMs: request?.timeoutMs } : {}),
+            ...(enabled !== undefined ? { enabled } : {}),
+            onFallback,
+        });
+    }
+    const runner = opts.runner;
+    if (!runner)
+        throw new TypeError("callStructured requires a resolved LLM runner");
+    const terminal = requireTerminalUserMessage(messages);
+    const prepareInvocation = () => {
+        const current = resolveStructuredCurrent(opts.current, request);
+        const prepared = prepareInlineExecutionWithRunner({
+            content: terminal.content,
+            conversation: terminal.conversation,
+            runner,
+            invocationKind: "direct",
+            ...(current ? { current } : {}),
+            ...(opts.authorizeTools ? { authorizeTools: opts.authorizeTools } : {}),
+        });
+        const lowered = lowerResolvedExecutionRequestWithRunner(prepared.request, prepared.runner);
+        opts.onNotices?.(lowered.notices);
+        return async () => {
+            const result = await dispatchLoweredExecutionRequest(lowered, {
+                ...(opts.lease ? { lease: opts.lease } : {}),
+                ...(request?.chat ? { chat: request.chat } : {}),
+                ...(request?.onRetryAttempt ? { onRetryAttempt: request.onRetryAttempt } : {}),
+                ...(own(request, "signal") ? { runOptions: { signal: request?.signal } } : {}),
+            });
+            if (!result.ok)
+                throw dispatchFailure(result);
+            return parse(result.stdout);
+        };
     };
     // UNGATED: run the chat+parse directly. Errors propagate — no `onError`
     // funnel — matching the pre-gate behaviour of direct callers.
     if (akmConfig === undefined) {
-        const raw = await chat(config, messages, chatOptions);
-        return parse(raw);
+        return prepareInvocation()();
     }
+    // On an enabled path, preparation/lowering happen OUTSIDE tryLlmFeature so
+    // authorization and invalid-config failures remain hard failures instead of
+    // being mistaken for provider fallbacks.
+    const invoke = prepareInvocation();
     // GATED: run through `tryLlmFeature`. A throw inside is classified ONCE and
     // routed to `onError`; `tryLlmFeature` returns `fallback` on disablement/timeout.
-    return tryLlmFeature(feature, akmConfig, async () => {
+    const outcome = await tryLlmFeature(feature, akmConfig, async () => {
         try {
-            const raw = await chat(config, messages, chatOptions);
-            return parse(raw);
+            return { kind: "value", value: await invoke() };
         }
         catch (err) {
-            return onError(classifyLlmError(err), err);
+            // Credential materialization remains dispatch-owned, so a missing
+            // required symbolic credential can surface here. Preserve config
+            // failures as hard pre-provider errors instead of sending them through
+            // a leaf's provider/runtime fallback policy.
+            if (err instanceof ConfigError)
+                return { kind: "config-error", error: err };
+            return { kind: "value", value: onError(classifyLlmError(err), err) };
         }
-    }, fallback, {
-        ...(has("timeoutMs") ? { timeoutMs: request?.timeoutMs } : {}),
+    }, { kind: "value", value: fallback }, {
+        ...(own(request, "timeoutMs") ? { timeoutMs: request?.timeoutMs } : {}),
         ...(enabled !== undefined ? { enabled } : {}),
         onFallback,
     });
+    if (outcome.kind === "config-error")
+        throw outcome.error;
+    return outcome.value;
 }

package/dist/output/format-exempt.js

@@ -25,7 +25,7 @@ const EXEMPT_COMMANDS = new Set([
     // Emits shell completion script source for eval.
     "completions",
     // `migrate status`/`apply` used to be exempt here too: `runMigrationTool`
-    // (src/commands/migration-tool.ts) spawns the standalone
+    // (src/commands/migration-tool.ts) spawns the task-only standalone
     // `scripts/akm-migrate.ts` tool, which always emitted its own fixed JSON
     // shape and never consulted `--format`. `src/commands/migrate-cli.ts` now
     // parses that child's final result line and renders it through the normal

package/dist/output/render-registry.js

@@ -27,31 +27,15 @@ const HTML_RENDERER_REGISTRY = createCommandRegistry();
 export function registerMdRenderer(command, handler) {
     MD_RENDERER_REGISTRY.register(command, handler);
 }
-/** Register a batch of Markdown renderers in iteration order. */
-export function registerMdRenderers(entries) {
-    MD_RENDERER_REGISTRY.registerAll(entries);
-}
 /** Look up a registered Markdown renderer, or `undefined` when unregistered. */
 export function getMdRendererHandler(command) {
     return MD_RENDERER_REGISTRY.get(command);
 }
-/** Remove a previously-registered Markdown renderer. Test-only utility. */
-export function deregisterMdRenderer(command) {
-    MD_RENDERER_REGISTRY.deregister(command);
-}
 /** Register an HTML renderer for a command name. */
 export function registerHtmlRenderer(command, handler) {
     HTML_RENDERER_REGISTRY.register(command, handler);
 }
-/** Register a batch of HTML renderers in iteration order. */
-export function registerHtmlRenderers(entries) {
-    HTML_RENDERER_REGISTRY.registerAll(entries);
-}
 /** Look up a registered HTML renderer, or `undefined` when unregistered. */
 export function getHtmlRendererHandler(command) {
     return HTML_RENDERER_REGISTRY.get(command);
 }
-/** Remove a previously-registered HTML renderer. Test-only utility. */
-export function deregisterHtmlRenderer(command) {
-    HTML_RENDERER_REGISTRY.deregister(command);
-}