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

package/dist/llm/embedders/remote.js

@@ -7,7 +7,7 @@
  * Calls the configured `/embeddings` endpoint and L2-normalizes the returned
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
-import { fetchWithTimeout, isHttpUrl } from "../../core/common.js";
+import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/common.js";
 import { resolveSecret } from "../../core/config/config.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
@@ -39,17 +39,24 @@ export class RemoteEmbedder {
         if (ollamaOpts) {
             body.options = ollamaOpts;
         }
+        // `signal` MUST go through fetchWithTimeout's dedicated 4th parameter, not
+        // the RequestInit: fetchWithTimeout replaces `opts.signal` with its own
+        // controller (`{ ...opts, signal: controller.signal }`), so a signal passed
+        // inside `opts` is silently dropped and caller cancellation never fires.
         const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.endpoint), {
             method: "POST",
             headers,
             body: JSON.stringify(body),
-            signal,
-        });
+        }, 30_000, signal);
         if (!response.ok) {
-            const errBody = await response.text().catch(() => "");
+            const errBody = await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }).catch((err) => {
+                if (signal?.aborted)
+                    throw err;
+                return "";
+            });
             throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
         }
-        const json = (await response.json());
+        const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
         if (!json.data?.[0]?.embedding) {
             throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(this.endpoint)}`);
         }
@@ -74,17 +81,22 @@ export class RemoteEmbedder {
             if (ollamaOpts) {
                 body.options = ollamaOpts;
             }
+            // See embed(): `signal` goes through the 4th parameter, not the
+            // RequestInit, or fetchWithTimeout drops it.
             const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.endpoint), {
                 method: "POST",
                 headers,
                 body: JSON.stringify(body),
-                signal,
-            });
+            }, 30_000, signal);
             if (!response.ok) {
-                const respBody = await response.text().catch(() => "");
+                const respBody = await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }).catch((err) => {
+                    if (signal?.aborted)
+                        throw err;
+                    return "";
+                });
                 throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
             }
-            const json = (await response.json());
+            const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
             if (!json.data || json.data.length !== batch.length) {
                 throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(this.endpoint)}`);
             }

package/dist/llm/feature-gate.js

@@ -3,54 +3,33 @@
 // 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 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,
-    // Legacy default: true
-    graph_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.graphExtraction?.enabled ?? true,
-    // Legacy default: false
+    memory_inference: (cfg) => cfg.index?.memory?.enabled ?? true,
+    graph_extraction: (cfg) => cfg.index?.graph?.enabled ?? true,
     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
- * `LlmFeatureFlags` docstring defaults.
+ * Reads from the unified 0.9.0 config shape.
  */
-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 +46,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);
@@ -86,17 +65,15 @@ export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     }
 }
 /**
- * Section-agnostic process gate. After the 0.8.0 migration, the canonical
- * accessor is the `FEATURE_LOCATION` map above; this helper exists so older
- * call sites that knew the (section, processName) pair don't all need to
- * relearn the new mapping.
+ * Section-agnostic process gate that maps process identifiers to their current
+ * config locations.
  *
  * For unknown (section, processName) pairs the result is `false`.
  */
 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 +85,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

@@ -7,7 +7,7 @@
  * Given a single asset body (typically a `memory:` or `knowledge:` file),
  * asks the configured LLM to surface the entities mentioned in it and the
  * relations between them. The pass itself
- * (`src/indexer/graph-extraction.ts`) is responsible for deciding which
+ * (`src/indexer/graph/graph-extraction.ts`) is responsible for deciding which
  * files to extract, persisting the resulting nodes/edges to the index DB,
  * and feeding the graph data into the FTS5+boosts
  * search pipeline as a single boost component.
@@ -15,16 +15,15 @@
  * This module is intentionally tiny and stateless so tests can stub it via
  * `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
- * the connection via `resolveIndexPassLLM("graph", config)` and pass it
- * straight through.
+ * The LLM connection comes from the selected named engine. Callers obtain it
+ * via `resolveIndexPassLLM("graph", config)` and pass it 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 { parseEmbeddedJsonResponse } from "../core/parse.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, isContextSizeError, parseEmbeddedJsonResponse } from "./client.js";
+import { chatCompletion, isContextSizeError } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 import { callStructured } from "./structured-call.js";
 /**
@@ -47,11 +46,6 @@ const SYSTEM_PROMPT = systemPromptTemplate;
 const USER_PROMPT_PREFIX = userPromptTemplate
     .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
     .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));
-// `isContextSizeError` is defined in `./client` and re-exported here so the
-// graph extractor and the retry classifier (`isRetryable`) share one
-// definition (#496). Re-exported (not just imported) to preserve existing
-// importers of this module — including its unit test.
-export { isContextSizeError } from "./client.js";
 const GENERIC_ENTITIES = new Set([
     "agent",
     "application",
@@ -749,5 +743,10 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
         onFallback,
     });
 }
-// deduplicateGraph moved to src/indexer/graph-dedup.ts (pure utility, no LLM calls).
-export { deduplicateGraph } from "../indexer/graph/graph-dedup.js";
+// deduplicateGraph lives in src/indexer/graph/graph-dedup.ts (pure utility, no
+// LLM calls) — import it from there directly. The re-export that used to live
+// here created a value edge back to graph-dedup.ts, which (via its type-only
+// import of GraphExtraction/GraphRelation below) formed a 2-file import cycle
+// (chunk 9 WI-9.8 KILL 4 sever). No src or test consumer used this re-export
+// (graph-extraction.ts and the test suite already import graph-dedup.ts
+// directly), so it is deleted outright rather than repointed.

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.js

@@ -1,4 +1,147 @@
 // 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/.
-export { compressMemoryToDerivedMemory, } from "./memory-infer-impl.js";
+/**
+ * LLM helper for the `akm index` memory-inference pass (#201).
+ *
+ * Compresses a single memory body into one higher-signal derived memory. The
+ * pass itself (in `src/indexer/passes/memory-inference.ts`) is responsible for
+ * deciding which memories are pending, persisting the derived memory with the
+ * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
+ * the parent as processed for idempotency.
+ *
+ * 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.
+ */
+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 { parseEmbeddedJsonResponse } from "../core/parse.js";
+import { warn } from "../core/warn.js";
+import { callStructured } from "./structured-call.js";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
+const PROMPT_PLACEHOLDERS = new Set([
+    "short title string",
+    "one sentence summary string",
+    "tag1",
+    "tag2",
+    "search phrase 1",
+    "search phrase 2",
+    "2-3 sentence compressed body preserving key facts verbatim",
+]);
+/**
+ * Strict JSON Schema for the derived-memory payload. Sent to providers that
+ * opt in via `ChatCompletionConfig.supportsJsonSchema = true`; the client
+ * silently drops the schema for providers that don't.
+ *
+ * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
+ * the memory-inference path. Mirrors the validation gate below
+ * (title/description/content + non-empty tags/searchHints) so a
+ * schema-compliant response is guaranteed to pass the downstream check
+ * — no more "incomplete derived memory payload from LLM; skipping memory"
+ * for shape-only failures.
+ */
+const DERIVED_MEMORY_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        content: { type: "string", minLength: 1 },
+        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+    },
+    required: ["title", "description", "content", "tags", "searchHints"],
+    additionalProperties: false,
+};
+/**
+ * Compress a single memory body into one derived memory via the configured LLM.
+ *
+ * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
+ * 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).
+ */
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return undefined;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    // 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,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            onRetryAttempt,
+        },
+        parse: (raw) => {
+            if (!raw)
+                return undefined;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("memory inference: invalid JSON response from LLM; skipping memory.");
+                return undefined;
+            }
+            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,
+    });
+}

package/dist/llm/metadata-enhance.js

@@ -4,12 +4,11 @@
 /**
  * LLM-driven metadata enhancement for stash entries.
  *
- * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
- * improve descriptions/tags/searchHints) lives separately from the low-level
- * transport client in `client.ts`.
+ * Keeps the higher-level workflow for improving descriptions, tags, and search
+ * hints separate from the low-level transport client.
  */
 import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
-import { parseJsonResponse } from "./client.js";
+import { parseJsonResponse } from "../core/parse.js";
 import { callStructured } from "./structured-call.js";
 const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
@@ -17,10 +16,11 @@ const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
  * generate searchHints, and suggest tags.
  *
  * When `akmConfig` is provided, routes through
- * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured and
- * errors are swallowed to `{}`. When `akmConfig` is `undefined` the gate is
- * bypassed entirely — the LLM call runs unconditionally and errors propagate to
- * the caller (pre-gate behaviour, used by direct callers such as tests).
+ * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured: a
+ * closed gate yields `{ status: "skipped" }` and a thrown/timed-out call yields
+ * `{ status: "failed" }` — neither is reported as an enrichment. When
+ * `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) {
     const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
@@ -41,12 +41,14 @@ Generate improved metadata for this ${entry.type}. Return JSON with these fields
 - "tags": an array of 3-8 relevant keyword tags
 
 Return ONLY the JSON object, no explanation.`;
-    // `parse` owns the raw response: the `!raw`/unparseable case ⇒ `{}`, plus the
-    // description/searchHints/tags shaping. `enhanceMetadata` never warns and
-    // never bumps telemetry, so `onError` (gated path only) just swallows to `{}`
-    // — identical to the surrounding control flow's pre-migration behaviour. The
-    // ungated path (akmConfig === undefined) propagates errors via callStructured.
-    return callStructured({
+    // `parse` owns the raw response: the `!raw`/unparseable case ⇒ empty metadata
+    // (still a genuine success), plus the description/searchHints/tags shaping.
+    // `enhanceMetadata` never warns and never bumps telemetry — `onError` (gated
+    // path only) reports `failed` WITHOUT warning, carrying the message so the
+    // caller can surface it. The ungated path (akmConfig === undefined) propagates
+    // errors via callStructured.
+    let timedOut = false;
+    const outcome = await callStructured({
         feature: "metadata_enhance",
         akmConfig,
         config,
@@ -57,23 +59,36 @@ Return ONLY the JSON object, no explanation.`;
         request: { signal, timeoutMs: config.timeoutMs },
         parse: (raw) => {
             const parsed = raw ? parseJsonResponse(raw) : undefined;
-            if (!parsed)
-                return {};
-            const result = {};
-            if (typeof parsed.description === "string" && parsed.description) {
-                result.description = parsed.description;
+            const metadata = {};
+            if (parsed) {
+                if (typeof parsed.description === "string" && parsed.description) {
+                    metadata.description = parsed.description;
+                }
+                if (Array.isArray(parsed.searchHints)) {
+                    metadata.searchHints = parsed.searchHints
+                        .filter((s) => typeof s === "string" && s.trim().length > 0)
+                        .slice(0, 8);
+                }
+                if (Array.isArray(parsed.tags)) {
+                    metadata.tags = parsed.tags
+                        .filter((s) => typeof s === "string" && s.trim().length > 0)
+                        .slice(0, 10);
+                }
             }
-            if (Array.isArray(parsed.searchHints)) {
-                result.searchHints = parsed.searchHints
-                    .filter((s) => typeof s === "string" && s.trim().length > 0)
-                    .slice(0, 8);
-            }
-            if (Array.isArray(parsed.tags)) {
-                result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
-            }
-            return result;
+            return { status: "enriched", metadata };
+        },
+        onError: (_cls, err) => ({ status: "failed", error: err instanceof Error ? err.message : String(err) }),
+        fallback: { status: "skipped" },
+        // The seam returns the `skipped` fallback for a closed gate AND for a
+        // wrapper-level timeout. Record the timeout so we can reclassify it below —
+        // a timed-out call is a failure, not a silent skip.
+        onFallback: (event) => {
+            if (event.reason === "timeout")
+                timedOut = true;
         },
-        onError: () => ({}),
-        fallback: {},
     });
+    if (outcome.status === "skipped" && timedOut) {
+        return { status: "failed", error: "metadata_enhance timed out" };
+    }
+    return outcome;
 }

package/dist/llm/structured-call.js

@@ -1,7 +1,7 @@
 // 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 { chatCompletion, isContextSizeError, LlmCallError, } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 /**
  * Classify a thrown LLM error into one of the three buckets. This is the single
@@ -17,14 +17,21 @@ export function classifyLlmError(err) {
     return "other";
 }
 export async function callStructured(opts) {
-    const { feature, akmConfig, config, messages, request, parse, onError, fallback, onFallback } = 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 = {
-        temperature: request?.temperature,
-        timeoutMs: request?.timeoutMs,
-        signal: request?.signal,
-        responseSchema: request?.responseSchema,
-        onRetryAttempt: request?.onRetryAttempt,
+        ...(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 } : {}),
     };
     // UNGATED: run the chat+parse directly. Errors propagate — no `onError`
     // funnel — matching the pre-gate behaviour of direct callers.
@@ -43,7 +50,8 @@ export async function callStructured(opts) {
             return onError(classifyLlmError(err), err);
         }
     }, fallback, {
-        timeoutMs: request?.timeoutMs,
+        ...(has("timeoutMs") ? { timeoutMs: request?.timeoutMs } : {}),
+        ...(enabled !== undefined ? { enabled } : {}),
         onFallback,
     });
 }