akm-cli 0.9.0-beta.45 → 0.9.0-beta.46

package/dist/indexer/passes/dir-staleness.js

@@ -0,0 +1,114 @@
+// 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/.
+/**
+ * Incremental dir-staleness engine.
+ *
+ * Decides, per stash directory, whether the directory's indexed rows are still
+ * fresh relative to what is on disk — so an incremental `akm index` run can
+ * skip unchanged directories instead of regenerating their metadata.
+ *
+ * Two persisted signals back the decision:
+ *   1. The `entries` rows already indexed for the directory (`getEntriesByDir`).
+ *   2. The `index_dir_state` fingerprint row (`getIndexDirState`), which caches
+ *      the file-set hash + max mtime for directories that legitimately produced
+ *      zero rows, so they are not rescanned every run.
+ *
+ * `computeDirFingerprint` derives the fingerprint (basename set + max mtime)
+ * that both the freshness check and the persisted `index_dir_state` row use.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getEntriesByDir, getIndexDirState } from "../db/db.js";
+export function getDirIndexState(db, dirPath, files, builtAtMs) {
+    const prevEntries = getEntriesByDir(db, dirPath);
+    const fingerprint = computeDirFingerprint(dirPath, files);
+    if (prevEntries.length > 0) {
+        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
+        if (!staleReason) {
+            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        }
+        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+    }
+    const cachedState = getIndexDirState(db, dirPath);
+    if (cachedState &&
+        cachedState.fileSetHash === fingerprint.fileSetHash &&
+        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+        return {
+            stale: false,
+            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
+            persistedRowCount: 0,
+        };
+    }
+    return {
+        stale: true,
+        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
+        persistedRowCount: 0,
+    };
+}
+export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+    if (state.stale || state.reason.kind !== "cached-zero-row-state")
+        return undefined;
+    if (!canUseIncrementalSkip(state, priorDirsChanged))
+        return undefined;
+    return state;
+}
+export function canUseIncrementalSkip(state, priorDirsChanged) {
+    return !(priorDirsChanged &&
+        state.reason.kind === "cached-zero-row-state" &&
+        state.reason.detail === "deduped-zero-row");
+}
+export function computeDirFingerprint(_dirPath, files) {
+    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    let fileMtimeMaxMs = 0;
+    for (const file of files) {
+        try {
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
+            break;
+        }
+    }
+    return {
+        fileSetHash: normalizedFiles.join("\0"),
+        fileMtimeMaxMs,
+    };
+}
+function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
+    const prevFileNames = new Set(previousEntries
+        .map((ie) => {
+        const fromPath = path.basename(ie.filePath);
+        return fromPath || ie.entry.filename;
+    })
+        .filter((e) => !!e));
+    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size) {
+        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
+    }
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return { kind: "file-set-changed", detail: name };
+    }
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return { kind: "mtime-changed", detail: path.basename(file) };
+        }
+        catch {
+            return { kind: "missing-file", detail: path.basename(file) };
+        }
+    }
+    return undefined;
+}
+export function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
+    if (dedupedRows > 0)
+        return "deduped-zero-row";
+    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
+    if (workflowNoise)
+        return "workflow-noise";
+    if (!stash || stash.entries.length === 0)
+        return "empty-generated-set";
+    return `zero-row:${priorReason?.kind ?? "unknown"}`;
+}

package/dist/indexer/search/search-source.js

@@ -5,13 +5,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
-import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
+import { resolveSourceProviderFactory, resolveSourceProviders } from "../../sources/provider-factory.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
 import { warn } from "../../core/warn.js";
-import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../../sources/providers/git.js";
-import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
 // Legacy "context-hub" / "github" type aliases are normalized to "git" at
 // config-load time (see src/config.ts), so this set only contains the canonical
 // type.
@@ -261,31 +259,19 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    const entries = getSources(cfg);
-    for (const entry of entries) {
-        if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
+    // Polymorphic refresh: walk every enabled source through its registered
+    // provider and call `sync()`. Every cache-backed kind (git, website, npm)
+    // refreshes the same way — a bad source warns and is skipped without
+    // aborting the others. The git content/-subdir layout convention stays in
+    // resolveEntryContentDir.
+    for (const provider of resolveSourceProviders(cfg)) {
+        if (!provider.sync)
             continue;
         try {
-            const repo = parseGitRepoUrl(entry.url);
-            const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, {
-                requireRepoDir: true,
-                writable: entry.writable === true,
-                force,
-            });
-        }
-        catch (err) {
-            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    for (const entry of entries) {
-        if (entry.type !== "website" || !entry.url || entry.enabled === false)
-            continue;
-        try {
-            await ensureWebsiteMirror(entry, { requireStashDir: true, force });
+            await provider.sync({ force });
         }
         catch (err) {
-            warn(`Warning: failed to refresh website stash for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/integrations/agent/runner-dispatch.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * X3 — the ONE dispatch seam for the {@link RunnerSpec} tagged union.
+ *
+ * The improve slice dispatches a `RunnerSpec` (`llm | agent | sdk`) in several
+ * places (`reflect.ts`, `proposal/drain.ts`, …). Before this module each site
+ * re-rolled the identical 3-arm switch and re-declared its own per-kind test
+ * seams (`chat`, `runAgentFn`, `runSdkFn`). `executeRunner` collapses that into
+ * one switch + one {@link RunnerSeams} object.
+ *
+ * Scoping (behavior-preserving):
+ *   - The `agent` and `sdk` arms are byte-identical across call sites: invoke
+ *     the profile runner (`runAgent` / `runOpencodeSdk`) with the per-call
+ *     `RunAgentOptions` the caller passes. Those default runners live here so
+ *     callers stop importing `runAgent` / `runOpencodeSdk` for dispatch. The
+ *     `opts` (incl. any `timeoutMs`) is constructed by the caller and passed
+ *     through unchanged, so each site keeps its exact option set.
+ *   - The `llm` arm is irreducibly caller-specific (reflect wraps
+ *     `runReflectViaLlm`, which returns reflect's iteration shape; drain wraps a
+ *     plain `chatCompletion`). It is therefore a REQUIRED seam — there is no
+ *     default `llm` handler — so neither caller's bespoke behavior is changed.
+ *   - The `assertNever` exhaustiveness arm is kept so a 4th `RunnerSpec` kind is
+ *     a compile error here instead of a silent runtime fall-through.
+ *
+ * The return type is {@link AgentRunResult} so a later `callStructured` layer
+ * (X2) can wrap `executeRunner` without changing this contract.
+ */
+import { assertNever } from "../../core/assert.js";
+import { runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { runAgent } from "./spawn.js";
+/**
+ * Dispatch a {@link RunnerSpec} to its runner and return the raw
+ * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
+ * (`agent` / `sdk`) arms; it is passed through unchanged so each caller keeps
+ * its exact option set (incl. any `timeoutMs` the caller chose to apply).
+ */
+export async function executeRunner(spec, prompt, opts, seams = {}) {
+    switch (spec.kind) {
+        case "llm": {
+            if (!seams.llm) {
+                throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
+            }
+            return seams.llm(spec, prompt);
+        }
+        case "agent": {
+            const run = seams.runAgent ?? runAgent;
+            return run(spec.profile, prompt, opts);
+        }
+        case "sdk": {
+            const run = seams.runSdk ?? runOpencodeSdk;
+            return run(spec.profile, prompt, opts);
+        }
+        default:
+            // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
+            return assertNever(spec);
+    }
+}

package/dist/llm/client.js

@@ -103,18 +103,29 @@ function retryBackoffMs() {
     return RETRY_BACKOFF_MIN_MS + Math.random() * (RETRY_BACKOFF_MAX_MS - RETRY_BACKOFF_MIN_MS);
 }
 /**
- * Detect whether an error message indicates a context-size-exceeded condition.
- * Mirrors the heuristic in `graph-extract.ts` — retrying a context overflow
- * cannot shrink the input, so it must not be retried.
+ * Detect whether an error message indicates a context size exceeded condition.
+ * Covers common patterns from OpenAI-compatible APIs (LM Studio, Ollama, etc).
+ *
+ * Requires BOTH a context keyword AND token-count/overflow evidence so that
+ * model prose merely mentioning "context size" / "context length" (e.g. gemma
+ * narrating about a document) does not get misclassified as a provider
+ * context-limit error (#496).
+ *
+ * Canonical home: `graph-extract.ts` re-exports this so the index-pass
+ * graph extractor and the retry classifier (`isRetryable`) share one
+ * definition — retrying a context overflow cannot shrink the input, so it
+ * must never be retried.
  */
-function looksLikeContextOverflow(message) {
+export function isContextSizeError(message) {
     const lower = message.toLowerCase();
-    return (lower.includes("context") &&
-        (lower.includes("context size") ||
-            lower.includes("context length") ||
-            lower.includes("context_window") ||
-            lower.includes("prompt too long") ||
-            lower.includes("exceeds")));
+    const contextKw = /context (size|length|window)|prompt too long|exceeds.*context/.test(lower);
+    if (!contextKw) {
+        return false;
+    }
+    const evidence = /\b\d+\s*(token|tokens|tk)\b/.test(lower) ||
+        /max(imum)?\s+(context|token|input)/.test(lower) ||
+        /exceeded|over.*limit|too.*long/.test(lower);
+    return evidence;
 }
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
@@ -138,7 +149,7 @@ function looksLikeContextOverflow(message) {
  * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
-    if (looksLikeContextOverflow(err.message))
+    if (isContextSizeError(err.message))
         return false;
     if (err.code === "provider_error") {
         return typeof err.statusCode === "number" && err.statusCode >= 500;

package/dist/llm/graph-extract.js

@@ -24,8 +24,9 @@ import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" wit
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
+import { chatCompletion, isContextSizeError, parseEmbeddedJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
+import { callStructured } from "./structured-call.js";
 /**
  * Separator token used between assets in a batch prompt.
  * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
@@ -46,26 +47,11 @@ 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));
-/**
- * Detect whether an error message indicates a context size exceeded condition.
- * Covers common patterns from OpenAI-compatible APIs (LM Studio, Ollama, etc).
- *
- * Requires BOTH a context keyword AND token-count/overflow evidence so that
- * model prose merely mentioning "context size" / "context length" (e.g. gemma
- * narrating about a document) does not get misclassified as a provider
- * context-limit error (#496).
- */
-export function isContextSizeError(message) {
-    const lower = message.toLowerCase();
-    const contextKw = /context (size|length|window)|prompt too long|exceeds.*context/.test(lower);
-    if (!contextKw) {
-        return false;
-    }
-    const evidence = /\b\d+\s*(token|tokens|tk)\b/.test(lower) ||
-        /max(imum)?\s+(context|token|input)/.test(lower) ||
-        /exceeded|over.*limit|too.*long/.test(lower);
-    return evidence;
-}
+// `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",
@@ -703,17 +689,21 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
         return merged;
     }
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody}`;
-    return tryLlmFeature("graph_extraction", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-            });
+    return callStructured({
+        feature: "graph_extraction",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
+        },
+        parse: (raw) => {
             if (!raw)
                 return empty();
             const parsed = parseEmbeddedJsonResponse(raw);
@@ -729,16 +719,16 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
             if (extraction.status === "failed")
                 bumpTelemetry(options.telemetry, "failureCount");
             return extraction;
-        }
-        catch (err) {
+        },
+        onError: (cls, err) => {
             const errMsg = toErrorMessage(err);
-            if (isContextSizeError(errMsg)) {
+            if (cls === "context_limit") {
                 bumpTelemetry(options.telemetry, "failureCount");
                 warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}. ` +
                     `Consider increasing llm.contextLength in config.json.`);
                 return empty("context_limit", "failed");
             }
-            else if (err instanceof LlmCallError && err.code === "provider_html_error") {
+            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}`);
                 return empty("llm_error", "failed");
@@ -748,9 +738,8 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
                 warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
                 return empty("llm_error", "failed");
             }
-        }
-    }, empty(), {
-        timeoutMs: llmConfig.timeoutMs,
+        },
+        fallback: empty(),
         onFallback,
     });
 }

package/dist/llm/memory-infer.js

@@ -22,8 +22,8 @@ import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" w
 import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
+import { parseEmbeddedJsonResponse } from "./client.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;
@@ -59,26 +59,39 @@ const DERIVED_MEMORY_JSON_SCHEMA = {
  * 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 `tryLlmFeature("memory_inference", ...)` so the feature gate
- * and onFallback hook are honoured uniformly (Fix C5).
+ * 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)}`;
-    return tryLlmFeature("memory_inference", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
-                onRetryAttempt,
-            });
+    // Memory-inference is ALWAYS gated: no `akmConfig` ⇒ gate closed (no chat,
+    // `disabled` fallback), never the seam's ungated/propagate path (which is for
+    // direct callers like `enhanceMetadata`). This is the gate-closed branch
+    // `tryLlmFeature(_, undefined, _)` took before the migration.
+    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);
@@ -108,9 +121,9 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
                 return undefined;
             }
             return { title, description, tags, searchHints, content };
-        }
-        catch (err) {
-            if (err instanceof LlmCallError && err.code === "provider_html_error") {
+        },
+        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)}`);
@@ -118,9 +131,8 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
             }
             warn(`memory inference failed: ${toErrorMessage(err)}`);
             return undefined;
-        }
-    }, undefined, {
-        timeoutMs: llmConfig.timeoutMs,
+        },
+        fallback: undefined,
         onFallback,
     });
 }

package/dist/llm/metadata-enhance.js

@@ -9,8 +9,8 @@
  * transport client in `client.ts`.
  */
 import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
-import { chatCompletion, parseJsonResponse } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
+import { parseJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
 const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
@@ -41,34 +41,39 @@ 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.`;
-    const runLlm = async () => {
-        const raw = await chatCompletion(config, [
+    // `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({
+        feature: "metadata_enhance",
+        akmConfig,
+        config,
+        messages: [
             { role: "system", content: SYSTEM_PROMPT },
             { role: "user", content: userPrompt },
-        ], { signal });
-        const parsed = parseJsonResponse(raw);
-        if (!parsed)
-            return {};
-        const result = {};
-        if (typeof parsed.description === "string" && parsed.description) {
-            result.description = parsed.description;
-        }
-        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;
-    };
-    // When no akmConfig is provided, bypass the feature gate entirely: run the
-    // LLM call directly and let errors propagate to the caller (pre-gate
-    // behaviour). When akmConfig is present, honour the feature flag and swallow
-    // errors to {} via tryLlmFeature.
-    if (akmConfig === undefined) {
-        return runLlm();
-    }
-    return tryLlmFeature("metadata_enhance", akmConfig, runLlm, {}, { timeoutMs: config.timeoutMs });
+        ],
+        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;
+            }
+            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;
+        },
+        onError: () => ({}),
+        fallback: {},
+    });
 }

package/dist/llm/structured-call.js

@@ -0,0 +1,49 @@
+// 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";
+/**
+ * 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.
+ */
+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";
+}
+export async function callStructured(opts) {
+    const { feature, akmConfig, config, messages, request, parse, onError, fallback, onFallback } = opts;
+    const chat = request?.chat ?? chatCompletion;
+    const chatOptions = {
+        temperature: request?.temperature,
+        timeoutMs: request?.timeoutMs,
+        signal: request?.signal,
+        responseSchema: request?.responseSchema,
+        onRetryAttempt: request?.onRetryAttempt,
+    };
+    // 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);
+    }
+    // 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 () => {
+        try {
+            const raw = await chat(config, messages, chatOptions);
+            return parse(raw);
+        }
+        catch (err) {
+            return onError(classifyLlmError(err), err);
+        }
+    }, fallback, {
+        timeoutMs: request?.timeoutMs,
+        onFallback,
+    });
+}

package/dist/output/shapes/passthrough.js

@@ -23,7 +23,6 @@ const PASSTHROUGH_COMMANDS = [
     "agent-result",
     "clone",
     "config",
-    "db-backups",
     "disable",
     "enable",
     "env-create",