akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/llm/memory-infer.js

@@ -18,10 +18,9 @@
  */
 import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
 import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
-import { toErrorMessage } from "../core/common.js";
+import { effectiveRequestFields } from "../core/llm-inference.js";
 import { parseEmbeddedJsonResponse } from "../core/parse.js";
 import { warn } from "../core/warn.js";
-import { runnerLlmConnection } from "../integrations/agent/runner.js";
 import { callStructured } from "./structured-call.js";
 const SYSTEM_PROMPT = memoryInferSystemPrompt;
 const USER_PROMPT_PREFIX = memoryInferUserPrompt;
@@ -40,8 +39,7 @@ export function isMemoryInferNoChange(value) {
 }
 /**
  * Strict JSON Schema for the derived-memory payload. Sent as `response_format`
- * unless the engine sets `supportsJsonSchema: false`; the client drops it once
- * for a provider that rejects it.
+ * and the client drops it once for a provider that rejects it.
  *
  * Every property is required (a strict provider refuses otherwise), so the
  * explicit no-change decision is `noChange: true` with the other fields empty.
@@ -61,6 +59,51 @@ export const DERIVED_MEMORY_JSON_SCHEMA = {
     required: ["noChange", "title", "description", "content", "tags", "searchHints"],
     additionalProperties: false,
 };
+/** The temperature a connection's request fields set, if any. */
+function configuredTemperature(runner) {
+    const temperature = runner.kind === "connection" ? effectiveRequestFields(runner.request, runner.inference).temperature : undefined;
+    return typeof temperature === "number" ? temperature : undefined;
+}
+/** Read the model's reply: a draft, an explicit no-change decision, or `undefined` for one that is unusable. */
+function parseDerivedMemory(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = parseEmbeddedJsonResponse(raw);
+    if (!parsed) {
+        warn("memory inference: invalid JSON response from LLM; skipping memory.");
+        return undefined;
+    }
+    // Only a literal boolean `true` is a decision; anything else falls through
+    // to the complete-payload checks, so a malformed reply is never restraint.
+    if (parsed.noChange === true)
+        return MEMORY_INFER_NO_CHANGE;
+    const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+    const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+    const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
+    const tags = Array.isArray(parsed.tags)
+        ? parsed.tags
+            .filter((t) => typeof t === "string")
+            .map((t) => t.trim())
+            .filter(Boolean)
+            .slice(0, 8)
+        : [];
+    const searchHints = Array.isArray(parsed.searchHints)
+        ? parsed.searchHints
+            .filter((h) => typeof h === "string")
+            .map((h) => h.trim())
+            .filter(Boolean)
+            .slice(0, 6)
+        : [];
+    if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
+        warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+        return undefined;
+    }
+    if ([title, description, content, ...tags, ...searchHints].some((value) => PROMPT_PLACEHOLDERS.has(value.toLowerCase()))) {
+        warn("memory inference: prompt placeholder response from LLM; skipping memory.");
+        return undefined;
+    }
+    return { title, description, tags, searchHints, content };
+}
 /**
  * Compress a single memory into one derived memory via the configured LLM.
  * `body` is the pass's effective input (a `Source context:` section, then the
@@ -68,92 +111,39 @@ export const DERIVED_MEMORY_JSON_SCHEMA = {
  *
  * Returns the draft, or {@link MEMORY_INFER_NO_CHANGE} when the model explicitly
  * decides the memory needs no derived memory. Returns `undefined` on any failure
- * (timeout, invalid JSON, empty or incomplete response, HTML, abort, disabled
- * pass), which is never the same thing as no-change. Errors are logged via `warn()` but never thrown — a failed split for one memory
- * must not abort the rest of the index pass.
- *
- * Routes through `callStructured({ feature: "memory_inference", ... })` so the
- * feature gate, error classification, and onFallback hook are honoured uniformly
- * (Fix C5).
+ * (timeout, invalid JSON, empty or incomplete response, HTML, abort), which is
+ * never the same thing as no-change. Failures are logged via `warn()` but never
+ * thrown — a failed split for one memory must not abort the rest of the index
+ * pass. Whether the pass runs at all is the pass's decision, not this helper's.
  */
-export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt, onNotices) {
+export async function compressMemoryToDerivedMemory(llmRunner, body, signal, telemetry, onRetryAttempt, onNotices) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
-    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody}`;
-    // Memory inference is always gated: no config closes the gate instead of
-    // taking callStructured's ungated path for direct callers.
-    if (!akmConfig) {
-        onFallback?.({ feature: "memory_inference", reason: "disabled" });
-        return undefined;
-    }
-    return callStructured({
-        feature: "memory_inference",
-        akmConfig,
+    const outcome = await callStructured({
         runner: llmRunner,
         messages: [
             { role: "system", content: SYSTEM_PROMPT },
-            { role: "user", content: userPrompt },
+            { role: "user", content: `${USER_PROMPT_PREFIX}${trimmedBody}` },
         ],
         request: {
-            // The engine's or the process's configured temperature; 0.1 only when neither sets one.
-            temperature: runnerLlmConnection(llmRunner)?.temperature ?? 0.1,
-            ...(Object.hasOwn(llmRunner, "timeoutMs") ? { timeoutMs: llmRunner.timeoutMs } : {}),
+            // The connection's or the process's configured temperature; 0.1 only when neither sets one.
+            temperature: configuredTemperature(llmRunner) ?? 0.1,
             signal,
             responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
             onRetryAttempt,
         },
         onNotices,
-        parse: (raw) => {
-            if (!raw)
-                return undefined;
-            const parsed = parseEmbeddedJsonResponse(raw);
-            if (!parsed) {
-                warn("memory inference: invalid JSON response from LLM; skipping memory.");
-                return undefined;
-            }
-            // Only a literal boolean `true` is a decision; anything else falls through
-            // to the complete-payload checks, so a malformed reply is never restraint.
-            if (parsed.noChange === true)
-                return MEMORY_INFER_NO_CHANGE;
-            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
-            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
-            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
-            const tags = Array.isArray(parsed.tags)
-                ? parsed.tags
-                    .filter((t) => typeof t === "string")
-                    .map((t) => t.trim())
-                    .filter(Boolean)
-                    .slice(0, 8)
-                : [];
-            const searchHints = Array.isArray(parsed.searchHints)
-                ? parsed.searchHints
-                    .filter((h) => typeof h === "string")
-                    .map((h) => h.trim())
-                    .filter(Boolean)
-                    .slice(0, 6)
-                : [];
-            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
-                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
-                return undefined;
-            }
-            if ([title, description, content, ...tags, ...searchHints].some((value) => PROMPT_PLACEHOLDERS.has(value.toLowerCase()))) {
-                warn("memory inference: prompt placeholder response from LLM; skipping memory.");
-                return undefined;
-            }
-            return { title, description, tags, searchHints, content };
-        },
-        onError: (cls, err) => {
-            if (cls === "html") {
-                if (telemetry)
-                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
-                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
-                return undefined;
-            }
-            warn(`memory inference failed: ${toErrorMessage(err)}`);
-            return undefined;
-        },
-        fallback: undefined,
-        onFallback,
     });
+    if (outcome.ok)
+        return parseDerivedMemory(outcome.raw);
+    if (outcome.result?.llmErrorCode === "provider_html_error") {
+        if (telemetry)
+            telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
+        warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${outcome.error}`);
+    }
+    else {
+        warn(`memory inference failed: ${outcome.error}`);
+    }
+    return undefined;
 }

package/dist/llm/model-list.js

@@ -0,0 +1,35 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The models an OpenAI-compatible endpoint serves: one `GET <base>/models`, with
+ * the connection's key when it has one. `akm setup` (the connection, its local-server
+ * detection and an embedding endpoint) and `akm models` list models this way, so
+ * what they show agrees. `akm health` asks only whether the endpoint answers, with
+ * its own request (`probeLlmEndpoint` in `client.ts`), and reads no list.
+ */
+import { openAiOperationUrl } from "../core/endpoint-url.js";
+const LIST_TIMEOUT_MS = 3_000;
+/** The model ids the endpoint lists, in the order it lists them. Never throws; a failure says why. */
+export async function listEndpointModels(connection, timeoutMs = LIST_TIMEOUT_MS) {
+    try {
+        const response = await fetch(openAiOperationUrl(connection.endpoint, "models"), {
+            headers: connection.apiKey ? { authorization: `Bearer ${connection.apiKey}` } : {},
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return { ok: false, error: `HTTP ${response.status}` };
+        const body = (await response.json());
+        if (!Array.isArray(body.data))
+            return { ok: false, error: "the response has no model list" };
+        const ids = body.data.flatMap((entry) => typeof entry?.id === "string" && entry.id ? [entry.id] : []);
+        return { ok: true, models: [...new Set(ids)] };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Whether a model id names an embedding model rather than a chat model. */
+export function isEmbeddingModel(id) {
+    return /embed|nomic|minilm|bge/i.test(id);
+}

package/dist/llm/rerank-client.js

@@ -25,10 +25,8 @@
  * `core/config/schema/search.ts` for why.
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
-import { resolveSecret } from "../core/config/config.js";
-import { isApiKeyReference } from "../core/config/schema/primitives.js";
-import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
-import { resolveSecretFromStore } from "../sources/snapshot-fetchers/secret-seam.js";
+import { resolveApiKey } from "../core/config/credentials.js";
+import { redactErrorBody, redactSensitiveText, redactUrlCredentials } from "../core/redaction.js";
 const DEFAULT_RERANK_TIMEOUT_MS = 10_000;
 export class RerankCallError extends Error {
     code;
@@ -44,10 +42,8 @@ export class RerankCallError extends Error {
  * didn't return a score for keeps its original relative order, appended
  * after every scored document (never dropped).
  *
- * Throws {@link RerankCallError} on any transport/parse failure — callers
- * that want a graceful fallback should use `tryLlmFeature("curate_rerank", ...)`
- * (`llm/feature-gate.ts`), matching every other bounded in-tree LLM/rerank
- * call site.
+ * Throws {@link RerankCallError} on any transport/parse failure — a caller
+ * that wants a graceful fallback catches it.
  */
 export async function rerankDocuments(config, query, documents) {
     if (!config.endpoint) {
@@ -55,9 +51,7 @@ export async function rerankDocuments(config, query, documents) {
     }
     if (documents.length === 0)
         return [];
-    const resolvedKey = config.apiKey && isApiKeyReference(config.apiKey)
-        ? resolveSecret(config.apiKey, resolveSecretFromStore)
-        : config.apiKey;
+    const resolvedKey = resolveApiKey(config.apiKey, { service: "curateRerank" }, config.endpoint);
     const headers = { "Content-Type": "application/json" };
     if (resolvedKey)
         headers.Authorization = `Bearer ${resolvedKey}`;
@@ -81,7 +75,7 @@ export async function rerankDocuments(config, query, documents) {
     if (!response.ok) {
         const rawBody = await readBodyWithByteCap(response).catch(() => "");
         const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
-        throw new RerankCallError(`Rerank request failed (${response.status}) ${config.endpoint}: ${safeBody}`, "provider_error");
+        throw new RerankCallError(`Rerank request failed (${response.status}) ${redactUrlCredentials(config.endpoint)}: ${safeBody}`, "provider_error");
     }
     const rawBody = await readBodyWithByteCap(response);
     let json;
@@ -89,10 +83,10 @@ export async function rerankDocuments(config, query, documents) {
         json = JSON.parse(rawBody);
     }
     catch {
-        throw new RerankCallError(`Rerank response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error");
+        throw new RerankCallError(`Rerank response was not valid JSON ${redactUrlCredentials(config.endpoint)}: ${redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error");
     }
     if (!Array.isArray(json.results)) {
-        throw new RerankCallError(`Rerank response from ${config.endpoint} has no "results" array.`, "parse_error");
+        throw new RerankCallError(`Rerank response from ${redactUrlCredentials(config.endpoint)} has no "results" array.`, "parse_error");
     }
     const scored = new Map();
     for (const entry of json.results) {

package/dist/llm/structured-call.js

@@ -1,34 +1,29 @@
 // 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 { ConfigError } from "../core/errors.js";
-import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
-import { buildExecution, resolveExecution } from "../integrations/agent/execution.js";
-import { runExecution } from "../integrations/agent/runner-dispatch.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
- * inlined at every call site.
+ * `callStructured()` — one model call on any runner kind.
+ *
+ * It resolves the call once (the runner's target, model and timeout, the call's
+ * own settings), lowers it for the runner's transport, dispatches it, and
+ * returns the reply text or the failure. A provider's failure (transport error,
+ * timeout, abort, a harness that exits non-zero) is a failed outcome, the same
+ * for every caller; only a configuration failure throws, because it is not the
+ * provider's and no fallback can repair it.
+ *
+ * What stays per-caller: reading the reply (the structured loop, `llm/structured.ts`),
+ * and what a failed outcome means for that caller.
  */
-export function classifyLlmError(err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (isContextSizeError(message))
-        return "context_limit";
-    if (err instanceof LlmCallError && err.code === "provider_html_error")
-        return "html";
-    return "other";
-}
+import { ConfigError } from "../core/errors.js";
+import { buildExecution, currentLayer, resolveExecution } from "../integrations/agent/execution.js";
+import { runExecution } from "../integrations/agent/runner-dispatch.js";
 function own(value, key) {
     return value !== undefined && Object.hasOwn(value, key);
 }
 /**
  * @internal Exact request-to-cascade projection, exported for presence-semantics contracts.
- * Model work is bounded: with no timeout from the request or the runner, it
- * gets {@link DEFAULT_LLM_TIMEOUT_MS} on every runner kind.
  */
-export function resolveStructuredCurrent(current, request, runner) {
+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)
@@ -51,9 +46,6 @@ export function resolveStructuredCurrent(current, request, runner) {
     }
     if (own(request, "timeoutMs"))
         out.timeout = request?.timeoutMs ?? null;
-    else if (runner && !Object.hasOwn(runner, "timeoutMs") && !own(current, "timeout")) {
-        out.timeout = DEFAULT_LLM_TIMEOUT_MS;
-    }
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function requireTerminalUserMessage(messages) {
@@ -66,92 +58,46 @@ function requireTerminalUserMessage(messages) {
         conversation: messages.slice(0, -1).map((message) => ({ role: message.role, content: message.content })),
     };
 }
-function dispatchFailure(result) {
-    const message = result.error ?? result.stderr ?? result.reason ?? "dispatch failed";
-    const error = result.llmErrorCode ? new LlmCallError(message, result.llmErrorCode) : new Error(message);
-    return Object.assign(error, { reason: result.reason, result });
-}
-/** The runner's failure reason (`timeout`, `aborted`, …) a failed dispatch threw with, whatever its kind. */
-export function dispatchFailureReason(err) {
-    return err instanceof Error ? err.reason : undefined;
+/** Timeout and abort come from the dispatch's own reason, whatever the runner's kind. */
+function failed(error, result) {
+    const reason = result?.reason;
+    return {
+        ok: false,
+        reason: reason === "timeout" || reason === "aborted" ? reason : "error",
+        error,
+        ...(result ? { result } : {}),
+    };
 }
-/** The failed dispatch's own result (an agent's exit code and stderr, say), whatever its kind. */
-export function dispatchFailureResult(err) {
-    return err instanceof Error ? err.result : undefined;
+/** A dispatch's result as the reply it produced or the failure it reports. */
+export function outcomeOf(result) {
+    return result.ok
+        ? { ok: true, raw: result.stdout }
+        : failed(result.error ?? result.stderr ?? result.reason ?? "dispatch failed", result);
 }
 export async function callStructured(opts) {
-    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 runner");
-    const terminal = requireTerminalUserMessage(messages);
-    // `gateSignal` aborts when the feature gate's timeout fires, so the dispatch stops with it.
-    // Every structured call is unattended model work, so it runs under the model-work tool policy.
-    const prepareInvocation = () => {
+    const { runner, messages, request } = opts;
+    try {
+        const terminal = requireTerminalUserMessage(messages);
+        // Every structured call is unattended model work, so it runs under the model-work tool policy.
         const prepared = resolveExecution({
             content: terminal.content,
             conversation: terminal.conversation,
             runner,
-            current: resolveStructuredCurrent(opts.current, request, runner),
+            layers: [currentLayer(resolveStructuredCurrent(opts.current, request) ?? {})],
             modelWork: true,
         });
         const lowered = buildExecution(prepared.request, prepared.runner);
         opts.onNotices?.(lowered.notices);
-        return async (gateSignal) => {
-            const signal = request?.signal && gateSignal ? AbortSignal.any([request.signal, gateSignal]) : (request?.signal ?? gateSignal);
-            const runOptions = { ...request?.runOptions, ...(signal ? { signal } : {}) };
-            const result = await runExecution(lowered, {
-                ...(request?.chat ? { chat: request.chat } : {}),
-                ...(request?.runSdk ? { runSdk: request.runSdk } : {}),
-                ...(request?.onRetryAttempt ? { onRetryAttempt: request.onRetryAttempt } : {}),
-                ...(Object.keys(runOptions).length > 0 ? { runOptions } : {}),
-            });
-            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) {
-        return prepareInvocation()();
+        const result = await runExecution(lowered, {
+            ...(request?.chat ? { chat: request.chat } : {}),
+            ...(request?.onRetryAttempt ? { onRetryAttempt: request.onRetryAttempt } : {}),
+            ...(request?.signal ? { signal: request.signal } : {}),
+        });
+        return outcomeOf(result);
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        return failed(err instanceof Error ? err.message : String(err));
     }
-    // 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.
-    const outcome = await tryLlmFeature(feature, akmConfig, async (gateSignal) => {
-        try {
-            return { kind: "value", value: await invoke(gateSignal) };
-        }
-        catch (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) };
-        }
-    }, { 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/llm/structured.js

@@ -0,0 +1,60 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The one corrective loop for a model call whose reply must have a shape:
+ * dispatch, parse, and, when the parser refuses the reply, one more dispatch that
+ * carries what was wrong. Whoever dispatches decides how the correction reaches
+ * the model (appended to the prompt, or as the next turns of the conversation);
+ * whoever parses decides what a good reply is.
+ *
+ * Only a refused reply is corrected. A dispatch that fails, in transport or by
+ * timeout, ends the loop with that failure as the dispatch reported it: the
+ * transports own their retries, and a command is never run twice to fix its
+ * output (`attempts: 1`).
+ */
+import { parseEmbeddedJsonResponse } from "../core/parse.js";
+/** The reply was refused by the parser, as against the dispatch failing. */
+export function isRefused(result) {
+    return !result.ok && "errors" in result;
+}
+/** The default instruction for a refused reply. */
+export function correctionText(refusal) {
+    if ((refusal.reason ?? "parse_error") === "parse_error") {
+        return "Your previous response contained no parseable JSON. Respond with ONLY a JSON value that matches the requested schema — no prose, no code fences.";
+    }
+    return `Your previous JSON response failed validation:\n- ${refusal.errors.join("\n- ")}\nRespond again with ONLY a corrected JSON value.`;
+}
+export async function structuredLoop(options) {
+    const attempts = Math.max(1, options.attempts ?? 2);
+    const correct = options.correct ?? correctionText;
+    let correction;
+    for (let attempt = 1;; attempt += 1) {
+        const dispatched = await options.dispatch(correction);
+        if (!dispatched.ok)
+            return { ...dispatched, attempts: attempt };
+        const raw = dispatched.raw;
+        const parsed = options.parse(raw);
+        if (parsed.ok)
+            return { ok: true, value: parsed.value, raw, attempts: attempt };
+        if (attempt >= attempts) {
+            return { ok: false, reason: parsed.reason ?? "parse_error", errors: parsed.errors, raw, attempts: attempt };
+        }
+        correction = { text: correct(parsed), reply: raw };
+    }
+}
+/**
+ * A parser for a reply that is JSON, perhaps in prose or code fences: the JSON
+ * found in it, held to `validate`. A reply with no JSON in it is a `parse_error`;
+ * JSON that fails `validate` is a `validation_error`.
+ */
+export function jsonParser(validate) {
+    return (raw) => {
+        const candidate = parseEmbeddedJsonResponse(raw);
+        if (candidate === undefined) {
+            return { ok: false, errors: ["no JSON structure found in response"], reason: "parse_error" };
+        }
+        const verdict = validate(candidate);
+        return verdict.ok ? verdict : { ...verdict, reason: verdict.reason ?? "validation_error" };
+    };
+}

package/dist/output/renderers.js

@@ -204,20 +204,14 @@ const agentMdRenderer = {
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
         const parsedMd = parseFrontmatter(ctx.content());
-        const toolPolicy = parsedMd.data.tools;
         const modelHint = typeof parsedMd.data.model === "string" ? parsedMd.data.model : undefined;
         return {
             type: "agent",
             name,
             path: ctx.absPath,
-            action: "Dispatch using the prompt below verbatim. Use modelHint and toolPolicy if present.",
+            action: "Dispatch using the prompt below verbatim. Use modelHint if present.",
             description: asNonEmptyString(parsedMd.data.description),
             prompt: parsedMd.content,
-            // `tools` is self-declared frontmatter. The provenance CEILING that decides
-            // whether this self-declared policy is honoured is applied at the show
-            // layer (`akmShowUnified`), which knows whether the source is the operator's
-            // own writable stash vs a read-only third-party source (07 P1-D).
-            ...(toolPolicy !== undefined ? { toolPolicy } : {}),
             ...(modelHint !== undefined ? { modelHint } : {}),
         };
     },
@@ -240,7 +234,7 @@ const knowledgeMdRenderer = {
 };
 // ── 4c. lesson-md ────────────────────────────────────────────────────────────
 /**
- * Renderer for the `lesson` asset type (v1 spec §13).
+ * Renderer for the `lesson` asset type.
  *
  * Lessons are markdown files with required `description` and `when_to_use`
  * frontmatter. The renderer projects both fields explicitly so consumers can