nodedex 0.1.0

package/dist/engine/providers/anthropic.js

@@ -0,0 +1,125 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { EmptyResponseError, classifyGenError, llmTimeoutMs, decideEmptyOrTimeoutAction, isInsufficientCreditError } from "./failure-policy.js";
+export class AnthropicProvider {
+    client;
+    model;
+    fallbackModel;
+    constructor(apiKey) {
+        this.client = apiKey ? new Anthropic({ apiKey }) : null;
+        this.model = process.env.AI_MODEL ?? "claude-opus-4-6";
+        const fb = process.env.NODEDEX_FALLBACK_MODEL ?? "";
+        this.fallbackModel = fb && fb !== this.model ? fb : null;
+    }
+    isAvailable() { return this.client !== null; }
+    getName() { return "anthropic"; }
+    async generateStructured(systemPrompt, userInput, schema, options) {
+        if (!this.client)
+            return { result: null, rateLimited: false };
+        const modelsToTry = options?.modelOverride
+            ? [options.modelOverride]
+            : this.fallbackModel ? [this.model, this.fallbackModel] : [this.model];
+        const attempts = [];
+        for (let i = 0; i < modelsToTry.length; i++) {
+            const modelName = modelsToTry[i];
+            const isFallback = i > 0;
+            let emptyRetried = false;
+            while (true) {
+                try {
+                    const response = await this.client.messages.create({
+                        model: modelName,
+                        max_tokens: options?.maxOutputTokens ?? 8192,
+                        system: systemPrompt,
+                        messages: [{ role: "user", content: userInput }],
+                        tools: [{
+                                name: "save_result",
+                                description: "Save the structured extraction result",
+                                input_schema: schema,
+                            }],
+                        tool_choice: { type: "tool", name: "save_result" },
+                    }, { timeout: llmTimeoutMs() });
+                    const toolUse = response.content.find((c) => c.type === "tool_use");
+                    // No tool_use block = the model produced no structured content = EMPTY/hung
+                    // (see ./failure-policy). Raise it so the catch retries/escalates rather than
+                    // failing the pass outright (the old behavior — no retry, no fallback).
+                    if (!toolUse)
+                        throw new EmptyResponseError(modelName);
+                    if (isFallback)
+                        console.log(`[anthropic] escalated to fallback model ${modelName}`);
+                    attempts.push({ model: modelName, outcome: "ok" });
+                    return {
+                        result: toolUse.input,
+                        rateLimited: false,
+                        usage: { input: response.usage.input_tokens, thinking: 0, output: response.usage.output_tokens },
+                        model: modelName,
+                        attempts,
+                    };
+                }
+                catch (e) {
+                    // Out-of-credit (402) — surface DEFINITIVELY (see openai.ts): the reflect queue
+                    // pauses-the-spend + requeues instead of swallowing it into a generic null.
+                    if (isInsufficientCreditError(e)) {
+                        attempts.push({ model: modelName, outcome: "error" });
+                        console.error(`[anthropic] ${modelName} insufficient credit (status=${e?.status ?? "?"}) — credit exhausted; not retrying/escalating (account unfunded)`);
+                        return { result: null, rateLimited: false, creditExhausted: true, model: modelName, attempts };
+                    }
+                    const kind = classifyGenError(e);
+                    const rateLimited = kind === "rate_limited";
+                    const hasNextModel = i + 1 < modelsToTry.length;
+                    // EMPTY/TIMEOUT → shared escalate-first policy (./failure-policy): a fallback model
+                    // is the likeliest recovery for an input-specific empty (and skips the slow same-
+                    // model draw); only a single-key setup retries the SAME model once.
+                    if (kind === "empty" || kind === "timeout") {
+                        const action = decideEmptyOrTimeoutAction({ kind, hasNextModel, emptyRetried });
+                        attempts.push({ model: modelName, outcome: kind === "timeout" ? "timeout" : "empty" });
+                        if (action === "escalate") {
+                            console.log(`[anthropic] ${modelName} ${kind} — escalating to fallback ${modelsToTry[i + 1]}`);
+                            break; // exit while; outer for tries the next model
+                        }
+                        if (action === "retry_same") {
+                            console.warn(`[anthropic] ${modelName} returned no structured content — no fallback; retrying same model once`);
+                            emptyRetried = true;
+                            continue; // retry same model
+                        }
+                        if (kind === "timeout") {
+                            console.error(`[anthropic] generateStructured TIMEOUT (${modelName}): ${llmTimeoutMs()}ms — pipeline continues`);
+                        }
+                        return { result: null, rateLimited: false, model: modelName, attempts };
+                    }
+                    // RATE-LIMIT / other → escalate to the next model if one remains, else degrade.
+                    // (No same-model bump: anthropic returns structured tool input directly, not
+                    // parsed JSON, so there is no truncation-retry rung.)
+                    attempts.push({ model: modelName, outcome: rateLimited ? "rate_limited" : "error" });
+                    if (rateLimited && hasNextModel) {
+                        console.log(`[anthropic] ${modelName} rate-limited — escalating to fallback ${modelsToTry[i + 1]}`);
+                        break; // exit while; outer for tries the next model
+                    }
+                    if (!rateLimited) {
+                        console.error(`[anthropic] generateStructured error (${modelName}): status=${e?.status} msg=${String(e?.message ?? e).slice(0, 200)}`);
+                    }
+                    return { result: null, rateLimited, model: modelName, attempts };
+                }
+            }
+        }
+        return { result: null, rateLimited: true, attempts };
+    }
+    async generate(prompt) {
+        if (!this.client)
+            return null;
+        try {
+            const response = await this.client.messages.create({
+                model: this.model,
+                max_tokens: 2048,
+                messages: [{ role: "user", content: prompt }],
+            });
+            const textBlock = response.content.find((c) => c.type === "text");
+            return textBlock?.text ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async ping() {
+        return (await this.generate("Say OK")) !== null;
+    }
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/engine/providers/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/engine/providers/anthropic.ts"],"names":[],"mappings":"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"}

package/dist/engine/providers/failure-policy.d.ts

@@ -0,0 +1,56 @@
+/** Empty/hung response: the model returned NO content (text="" / 0 tokens, often
+ *  after a long hang). DISTINCT from truncation — there is no partial classification,
+ *  so a max_tokens bump is a no-op and escalating to a fallback model is SAFE (the
+ *  determinism trap does not apply when there was no classification at all). */
+export declare class EmptyResponseError extends Error {
+    readonly model: string;
+    constructor(model: string);
+}
+/** True when an extracted completion body has no usable content. */
+export declare function isEmptyResult(text: string | null | undefined): boolean;
+/** Bound an LLM call so a hung provider can't stall the pipeline indefinitely.
+ *  Promise.race — the underlying request continues in the background on timeout but
+ *  the pipeline unblocks. Providers whose SDK has a native per-request timeout
+ *  (openai, anthropic) use that instead; gemini's SDK does not, so it wraps with this.
+ *  (debt-4 Stage A, promoted from gemini.ts so the bound is shared.) */
+export declare function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T>;
+/** The shared call-timeout bound (ms). 180s is generous: a healthy Pass 3 (~60-80s)
+ *  and Pass 2c (~100-150s) fit; it caps the worst case (~3min) AND the ~200s empty-
+ *  hang we observed (Run 12, 2026-06-06). Configurable via NODEDEX_LLM_TIMEOUT_MS;
+ *  <=0 disables the bound. */
+export declare function llmTimeoutMs(): number;
+export type GenFailureKind = "empty" | "timeout" | "rate_limited" | "truncated" | "mechanism_or_other";
+/** Classify a generateStructured() failure so every provider's retry policy branches
+ *  identically. Order matters: the explicit EmptyResponseError must win over the
+ *  SyntaxError that an empty body would otherwise produce. */
+export declare function classifyGenError(e: unknown): GenFailureKind;
+/** Out-of-credit / billing failure — DISTINCT from a transient rate-limit. The account
+ *  can't pay for the call (HTTP 402, or an "insufficient credit/funds/balance/quota" body),
+ *  so retrying the same model OR escalating to a fallback is pointless — every model on the
+ *  account is equally unfunded. The pipeline treats this as a PAUSE-the-spend trigger
+ *  (preserve + requeue the turn, auto-resume on top-up), NOT a per-turn failure that counts
+ *  toward the drop cap. Accepts an Error, an OpenRouter/OpenAI SDK error ({status,code,message}),
+ *  or a plain reason string (so the reflect queue can classify a swallowed-null reason too).
+ *  Checked separately from classifyGenError so a billing-out never masquerades as a
+ *  rate-limit (which would wastefully escalate to an equally-unfunded fallback model). */
+export declare function isInsufficientCreditError(e: unknown): boolean;
+export type RetryAction = "escalate" | "retry_same" | "degrade";
+/** Decide what to do with an EMPTY or TIMEOUT failure, given the retry state. This is
+ *  the "escalate-first-when-a-fallback-exists" policy (2026-06-06, Run 14 finding):
+ *  - escalate    : a fallback model remains → try it. For an empty, a DIFFERENT model is
+ *                  the likeliest recovery (the empty tends to be input-specific to one
+ *                  model) and it skips the slow same-model draw; for a timeout, don't pay
+ *                  the bound twice on the same model.
+ *  - retry_same  : NO fallback remains AND this is an un-retried empty → give the SAME
+ *                  model one more independent draw. This is a single-key user's ONLY
+ *                  recovery path (empties are probabilistic — a 2nd draw sometimes wins).
+ *  - degrade     : nothing left to try (no fallback + already retried, or a timeout with
+ *                  no fallback — we never re-pay a timeout on the same model).
+ *  Neither empty nor timeout ever bumps max_tokens (no partial output to grow) and both
+ *  are SAFE to escalate (no determinism trap — there was no classification to contradict). */
+export declare function decideEmptyOrTimeoutAction(opts: {
+    kind: "empty" | "timeout";
+    hasNextModel: boolean;
+    emptyRetried: boolean;
+}): RetryAction;
+//# sourceMappingURL=failure-policy.d.ts.map

package/dist/engine/providers/failure-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-policy.d.ts","sourceRoot":"","sources":["../../../src/engine/providers/failure-policy.ts"],"names":[],"mappings":"AAoBA;;;gFAGgF;AAChF,qBAAa,kBAAmB,SAAQ,KAAK;aACf,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAI1C;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED;;;;wEAIwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAOnF;AAED;;;8BAG8B;AAC9B,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,oBAAoB,CAAC;AAEvG;;8DAE8D;AAC9D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,cAAc,CAa3D;AAED;;;;;;;;0FAQ0F;AAC1F,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAY7D;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;AAEhE;;;;;;;;;;;;8FAY8F;AAC9F,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB,GAAG,WAAW,CAId"}

package/dist/engine/providers/failure-policy.js

@@ -0,0 +1,120 @@
+// ── Shared LLM-call failure policy (2026-06-06) ──────────────────────────────────
+// The three providers (openai/gemini/anthropic) differ only in SDK CALL MECHANICS.
+// "What to do when a call empties / hangs / truncates / rate-limits" is the SAME
+// policy and must hold on EVERY real-world provider path — a developer may run
+// Nodedex on any provider with their own key, not just our OpenRouter setup. This
+// module owns the provider-agnostic pieces (failure classification, empty-detection,
+// the call timeout); each provider maps its SDK errors into classifyGenError() and
+// applies the one canonical retry policy:
+//
+//   empty        → retry SAME model once (transient glitch; the only recovery a
+//                  single-key user has) → escalate to fallback model if configured
+//                  → else degrade. Never bump max_tokens (no output to grow).
+//   timeout      → escalate to fallback model → else degrade. No same-model retry
+//                  (the call already paid the full timeout; don't pay it twice).
+//   rate_limited → escalate to fallback model → else degrade (capacity problem).
+//   truncated    → retry SAME model once with a bigger budget → else degrade. NEVER
+//                  swap models (a different model yields a different classification =
+//                  the determinism trap).
+//   mechanism_or_other → provider-specific (openai: one prompt-JSON retry; others degrade).
+/** Empty/hung response: the model returned NO content (text="" / 0 tokens, often
+ *  after a long hang). DISTINCT from truncation — there is no partial classification,
+ *  so a max_tokens bump is a no-op and escalating to a fallback model is SAFE (the
+ *  determinism trap does not apply when there was no classification at all). */
+export class EmptyResponseError extends Error {
+    model;
+    constructor(model) {
+        super(`empty/hung response from ${model}`);
+        this.model = model;
+        this.name = "EmptyResponseError";
+    }
+}
+/** True when an extracted completion body has no usable content. */
+export function isEmptyResult(text) {
+    return (text ?? "").trim() === "";
+}
+/** Bound an LLM call so a hung provider can't stall the pipeline indefinitely.
+ *  Promise.race — the underlying request continues in the background on timeout but
+ *  the pipeline unblocks. Providers whose SDK has a native per-request timeout
+ *  (openai, anthropic) use that instead; gemini's SDK does not, so it wraps with this.
+ *  (debt-4 Stage A, promoted from gemini.ts so the bound is shared.) */
+export function withTimeout(p, ms, label) {
+    return Promise.race([
+        p,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms)),
+    ]);
+}
+/** The shared call-timeout bound (ms). 180s is generous: a healthy Pass 3 (~60-80s)
+ *  and Pass 2c (~100-150s) fit; it caps the worst case (~3min) AND the ~200s empty-
+ *  hang we observed (Run 12, 2026-06-06). Configurable via NODEDEX_LLM_TIMEOUT_MS;
+ *  <=0 disables the bound. */
+export function llmTimeoutMs() {
+    const n = Number(process.env.NODEDEX_LLM_TIMEOUT_MS ?? "180000");
+    return Number.isFinite(n) ? n : 180000;
+}
+/** Classify a generateStructured() failure so every provider's retry policy branches
+ *  identically. Order matters: the explicit EmptyResponseError must win over the
+ *  SyntaxError that an empty body would otherwise produce. */
+export function classifyGenError(e) {
+    if (e instanceof EmptyResponseError)
+        return "empty";
+    const msg = String(e?.message ?? "");
+    const status = e?.status;
+    // Capacity / rate-limit: 429, 503 (overloaded), 529 (Anthropic overloaded), quota.
+    if (status === 429 || status === 503 || status === 529 ||
+        /\b429\b|\b503\b|\b529\b|quota|RESOURCE_EXHAUSTED|high demand/i.test(msg))
+        return "rate_limited";
+    const name = String(e?.name ?? "");
+    // Timeout: openai/anthropic SDK throw APIConnectionTimeoutError; withTimeout() throws "... timeout after Nms".
+    if (name === "APIConnectionTimeoutError" || /timeout after|timed?\s?out|timeout/i.test(msg))
+        return "timeout";
+    // Truncation: JSON.parse threw on a NON-empty body (cut mid-structure at max_tokens).
+    if (e instanceof SyntaxError || msg.includes("Unterminated") || msg.includes("position"))
+        return "truncated";
+    return "mechanism_or_other";
+}
+/** Out-of-credit / billing failure — DISTINCT from a transient rate-limit. The account
+ *  can't pay for the call (HTTP 402, or an "insufficient credit/funds/balance/quota" body),
+ *  so retrying the same model OR escalating to a fallback is pointless — every model on the
+ *  account is equally unfunded. The pipeline treats this as a PAUSE-the-spend trigger
+ *  (preserve + requeue the turn, auto-resume on top-up), NOT a per-turn failure that counts
+ *  toward the drop cap. Accepts an Error, an OpenRouter/OpenAI SDK error ({status,code,message}),
+ *  or a plain reason string (so the reflect queue can classify a swallowed-null reason too).
+ *  Checked separately from classifyGenError so a billing-out never masquerades as a
+ *  rate-limit (which would wastefully escalate to an equally-unfunded fallback model). */
+export function isInsufficientCreditError(e) {
+    if (e == null)
+        return false;
+    const status = e?.status ?? e?.code;
+    if (status === 402 || status === "402")
+        return true;
+    const msg = typeof e === "string" ? e : String(e?.message ?? "");
+    // 402 / "insufficient credit" = account out of funds. ALSO treat a provider SPEND-CAP as the
+    // same class so it routes through the pause-spend + TUI alert + auto-resume path instead of a
+    // silent generic-failure fail-clean: OpenRouter returns 403 "Key limit exceeded (total limit)"
+    // when a key's spend ceiling is hit. Deliberately NOT a transient 429 rate-limit (that backs
+    // off + retries — pausing-till-topup would be wrong) and NOT a bare 403 (auth/permission) —
+    // only the limit-exceeded TEXT, which "rate limit exceeded" does not match.
+    return /\b402\b|payment required|insufficient[\s_-]*(credit|fund|balance|quota)|negative\s+(credit|balance)|requires?\s+(more|additional)\s+credit|out of credit|add (more )?credit|key\s+limit\s+exceeded|\btotal\s+limit\b|credit\s+limit\b/i.test(msg);
+}
+/** Decide what to do with an EMPTY or TIMEOUT failure, given the retry state. This is
+ *  the "escalate-first-when-a-fallback-exists" policy (2026-06-06, Run 14 finding):
+ *  - escalate    : a fallback model remains → try it. For an empty, a DIFFERENT model is
+ *                  the likeliest recovery (the empty tends to be input-specific to one
+ *                  model) and it skips the slow same-model draw; for a timeout, don't pay
+ *                  the bound twice on the same model.
+ *  - retry_same  : NO fallback remains AND this is an un-retried empty → give the SAME
+ *                  model one more independent draw. This is a single-key user's ONLY
+ *                  recovery path (empties are probabilistic — a 2nd draw sometimes wins).
+ *  - degrade     : nothing left to try (no fallback + already retried, or a timeout with
+ *                  no fallback — we never re-pay a timeout on the same model).
+ *  Neither empty nor timeout ever bumps max_tokens (no partial output to grow) and both
+ *  are SAFE to escalate (no determinism trap — there was no classification to contradict). */
+export function decideEmptyOrTimeoutAction(opts) {
+    if (opts.hasNextModel)
+        return "escalate";
+    if (opts.kind === "empty" && !opts.emptyRetried)
+        return "retry_same";
+    return "degrade";
+}
+//# sourceMappingURL=failure-policy.js.map

package/dist/engine/providers/failure-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-policy.js","sourceRoot":"","sources":["../../../src/engine/providers/failure-policy.ts"],"names":[],"mappings":"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"}

package/dist/engine/providers/gemini.d.ts

@@ -0,0 +1,22 @@
+import type { LLMProvider, EmbeddingProvider, GenerateResult } from "../ai-provider.js";
+export declare class GeminiProvider implements LLMProvider {
+    private genAI;
+    constructor(apiKey: string);
+    isAvailable(): boolean;
+    getName(): string;
+    generateStructured<T>(systemPrompt: string, userInput: string, schema: object, options?: {
+        thinkingBudget?: number;
+        maxOutputTokens?: number;
+        modelOverride?: string;
+    }): Promise<GenerateResult<T>>;
+    generate(prompt: string): Promise<string | null>;
+    ping(): Promise<boolean>;
+}
+export declare class GeminiEmbeddingProvider implements EmbeddingProvider {
+    private genAI;
+    private readonly embModel;
+    constructor(apiKey: string);
+    isAvailable(): boolean;
+    embed(text: string): Promise<number[] | null>;
+}
+//# sourceMappingURL=gemini.d.ts.map

package/dist/engine/providers/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../../src/engine/providers/gemini.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAkBxF,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,KAAK,CAA4B;gBAE7B,MAAM,EAAE,MAAM;IAI1B,WAAW,IAAI,OAAO;IACtB,OAAO,IAAI,MAAM;IAEX,kBAAkB,CAAC,CAAC,EACxB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACtF,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAmIvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBhD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAG/B;AAED,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiE;gBAE9E,MAAM,EAAE,MAAM;IAI1B,WAAW,IAAI,OAAO;IAEhB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CAiBpD"}

package/dist/engine/providers/gemini.js

@@ -0,0 +1,180 @@
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { EmptyResponseError, classifyGenError, isEmptyResult, withTimeout, llmTimeoutMs, decideEmptyOrTimeoutAction, isInsufficientCreditError } from "./failure-policy.js";
+// Default + fallback model resolved LIVE from env per call. A const frozen at
+// MODULE LOAD would ignore a web-UI / config-endpoint model change until a full
+// restart (resetProviders can't refresh a module-level const) — so these are
+// functions read at call time.
+function primaryModel() {
+    return process.env.AI_MODEL ?? process.env.NODEDEX_PRIMARY_MODEL ?? "gemini-2.5-flash";
+}
+function fallbackModel() {
+    return process.env.NODEDEX_FALLBACK_MODEL ?? "gemini-2.5-pro";
+}
+// Failure handling (timeout bound, empty-detection, failure classification) is now
+// shared across all providers — see ./failure-policy.ts. The 180s call bound
+// (debt-4 Stage A) lives there as llmTimeoutMs() / withTimeout().
+export class GeminiProvider {
+    genAI;
+    constructor(apiKey) {
+        this.genAI = apiKey ? new GoogleGenerativeAI(apiKey) : null;
+    }
+    isAvailable() { return this.genAI !== null; }
+    getName() { return "gemini"; }
+    async generateStructured(systemPrompt, userInput, schema, options) {
+        if (!this.genAI)
+            return { result: null, rateLimited: false };
+        const primary = primaryModel(), fallback = fallbackModel();
+        const modelsToTry = options?.modelOverride
+            ? [options.modelOverride]
+            : primary === fallback ? [primary] : [primary, fallback];
+        const attempts = [];
+        for (let i = 0; i < modelsToTry.length; i++) {
+            const modelName = modelsToTry[i];
+            const isFallback = i > 0;
+            // gemini-2.5-pro requires non-zero thinking budget
+            const budget = isFallback
+                ? Math.max(512, options?.thinkingBudget ?? 0)
+                : (options?.thinkingBudget ?? 0);
+            const genConfig = {
+                thinkingConfig: { thinkingBudget: budget },
+                responseMimeType: "application/json",
+                responseSchema: schema,
+            };
+            if (options?.maxOutputTokens)
+                genConfig.maxOutputTokens = options.maxOutputTokens;
+            // Deterministic extraction → default temperature 0 (cuts run-to-run variance).
+            // Gemini thinking models accept temperature. Configurable via NODEDEX_REFLECT_TEMPERATURE.
+            {
+                const tEnv = process.env.NODEDEX_REFLECT_TEMPERATURE;
+                genConfig.temperature = tEnv !== undefined && tEnv !== "" && Number.isFinite(Number(tEnv)) ? Number(tEnv) : 0;
+            }
+            const model = this.genAI.getGenerativeModel({
+                model: modelName,
+                systemInstruction: systemPrompt,
+                generationConfig: genConfig,
+            });
+            let emptyRetried = false;
+            while (true) {
+                try {
+                    const response = await withTimeout(model.generateContent(userInput), llmTimeoutMs(), `generateStructured(${modelName})`);
+                    const usageMeta = response.response.usageMetadata ?? {};
+                    // Extract non-thinking output parts (pass3 reads thinking separately)
+                    const parts = response.response.candidates?.[0]?.content?.parts ?? [];
+                    const rawText = (parts.length > 0
+                        ? parts.filter((p) => !p.thought).map((p) => p.text ?? "").join("")
+                        : response.response.text()).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+                    const thinking = parts
+                        .filter((p) => p.thought === true)
+                        .map((p) => p.text ?? "")
+                        .join("\n")
+                        .trim();
+                    // EMPTY/HUNG guard BEFORE JSON.parse — a distinct failure (see ./failure-policy):
+                    // JSON.parse("") would look like truncation; raise it explicitly so the catch
+                    // retries/escalates instead of mislabeling it.
+                    if (isEmptyResult(rawText))
+                        throw new EmptyResponseError(modelName);
+                    const result = JSON.parse(rawText);
+                    attempts.push({ model: modelName, outcome: "ok" });
+                    return {
+                        result,
+                        rateLimited: false,
+                        thinking,
+                        usage: {
+                            input: usageMeta.promptTokenCount ?? 0,
+                            thinking: usageMeta.thoughtsTokenCount ?? 0,
+                            output: usageMeta.candidatesTokenCount ?? 0,
+                        },
+                        model: modelName,
+                        attempts,
+                    };
+                }
+                catch (e) {
+                    // Out-of-credit (402) — surface DEFINITIVELY (see openai.ts): the reflect queue
+                    // pauses-the-spend + requeues instead of swallowing it into a generic null.
+                    if (isInsufficientCreditError(e)) {
+                        attempts.push({ model: modelName, outcome: "error" });
+                        console.error(`[gemini] ${modelName} insufficient credit (status=${e?.status ?? "?"}) — credit exhausted; not retrying/escalating (account unfunded)`);
+                        return { result: null, rateLimited: false, creditExhausted: true, model: modelName, attempts };
+                    }
+                    const kind = classifyGenError(e);
+                    const rateLimited = kind === "rate_limited";
+                    const hasNextModel = i + 1 < modelsToTry.length;
+                    // EMPTY/TIMEOUT → shared escalate-first policy (./failure-policy): a fallback
+                    // model is the likeliest recovery for an input-specific empty (and skips the slow
+                    // same-model draw); only a single-key setup retries the SAME model once.
+                    if (kind === "empty" || kind === "timeout") {
+                        const action = decideEmptyOrTimeoutAction({ kind, hasNextModel, emptyRetried });
+                        attempts.push({ model: modelName, outcome: kind === "timeout" ? "timeout" : "empty" });
+                        if (action === "escalate") {
+                            console.warn(`[gemini] ${modelName} ${kind} — escalating to fallback`);
+                            break; // exit while; outer for tries the next model
+                        }
+                        if (action === "retry_same") {
+                            console.warn(`[gemini] ${modelName} returned EMPTY/hung response — no fallback; retrying same model once`);
+                            emptyRetried = true;
+                            continue; // retry same model
+                        }
+                        if (kind === "timeout") {
+                            console.error(`[gemini] generateStructured TIMEOUT (${modelName}): ${llmTimeoutMs()}ms — pipeline continues, request may still be running at provider`);
+                        }
+                        return { result: null, rateLimited: false, model: modelName, attempts };
+                    }
+                    // RATE-LIMIT / TRUNCATED → escalate to the next model if one remains, else degrade.
+                    // (Truncation→fallback preserves gemini's long-standing behavior; openai's stricter
+                    // same-model-only truncation policy is left provider-specific to keep this tight.)
+                    attempts.push({ model: modelName, outcome: kind === "truncated" ? "truncated" :
+                            rateLimited ? "rate_limited" : "error" });
+                    if ((kind === "truncated" || rateLimited) && hasNextModel) {
+                        console.warn(`[gemini] ${modelName} ${kind} — escalating to fallback`);
+                        break; // exit while; outer for tries the next model
+                    }
+                    if (!rateLimited) {
+                        console.error(`[gemini] generateStructured error (${modelName}): ${String(e?.message ?? e).slice(0, 300)}`);
+                    }
+                    return { result: null, rateLimited, model: modelName, attempts };
+                }
+            }
+        }
+        return { result: null, rateLimited: true, attempts };
+    }
+    async generate(prompt) {
+        if (!this.genAI)
+            return null;
+        try {
+            const primary = primaryModel();
+            const model = this.genAI.getGenerativeModel({ model: primary });
+            const result = await withTimeout(model.generateContent(prompt), llmTimeoutMs(), `generate(${primary})`);
+            return result.response.text().trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    async ping() {
+        return (await this.generate("Say OK")) !== null;
+    }
+}
+export class GeminiEmbeddingProvider {
+    genAI;
+    embModel = process.env.NODEDEX_EMBEDDING_MODEL ?? "gemini-embedding-001";
+    constructor(apiKey) {
+        this.genAI = apiKey ? new GoogleGenerativeAI(apiKey) : null;
+    }
+    isAvailable() { return this.genAI !== null; }
+    async embed(text) {
+        if (!this.genAI)
+            return null;
+        try {
+            const model = this.genAI.getGenerativeModel({ model: this.embModel });
+            // Provider-level timeout: belt-and-suspenders with EmbeddingEngine.embed
+            // wrapper (which also times out at 30s + records stats). This catches
+            // direct provider calls if they ever happen without the engine.
+            const result = await withTimeout(model.embedContent(text), 30_000, `embed(${this.embModel})`);
+            return result.embedding.values;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=gemini.js.map

package/dist/engine/providers/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/engine/providers/gemini.ts"],"names":[],"mappings":"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"}

package/dist/engine/providers/index.d.ts

@@ -0,0 +1,8 @@
+import type { LLMProvider, EmbeddingProvider } from "../ai-provider.js";
+/** Returns the singleton LLM provider (lazy-initialized from env vars). */
+export declare function getLLMProvider(): LLMProvider;
+/** Returns the singleton embedding provider (lazy-initialized from env vars). */
+export declare function getEmbeddingProvider(): EmbeddingProvider;
+/** Reset singletons — used in tests after env var changes. */
+export declare function resetProviders(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAUxE,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,WAAW,CAoB5C;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,IAAI,iBAAiB,CAiCxD;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}

package/dist/engine/providers/index.js

@@ -0,0 +1,67 @@
+import { GeminiProvider, GeminiEmbeddingProvider } from "./gemini.js";
+import { OpenAIProvider, OpenAIEmbeddingProvider } from "./openai.js";
+import { AnthropicProvider } from "./anthropic.js";
+import { LocalEmbeddingProvider } from "./local.js";
+import { wrapWithUsageLedger } from "./usage-ledger.js";
+let _llm = null;
+let _embeddings = null;
+/** Returns the singleton LLM provider (lazy-initialized from env vars). */
+export function getLLMProvider() {
+    if (_llm)
+        return _llm;
+    const name = (process.env.AI_PROVIDER ?? "gemini").toLowerCase();
+    if (name === "openai" || name === "openai-compatible") {
+        _llm = new OpenAIProvider(process.env.OPENAI_API_KEY ?? "", process.env.OPENAI_BASE_URL);
+    }
+    else if (name === "anthropic") {
+        _llm = new AnthropicProvider(process.env.ANTHROPIC_API_KEY ?? "");
+    }
+    else {
+        _llm = new GeminiProvider(process.env.GEMINI_API_KEY ?? "");
+    }
+    // Meter every structured key call at the single seam — wrap once so the cached
+    // provider (and all callers) route generateStructured() through the usage ledger.
+    _llm = wrapWithUsageLedger(_llm);
+    return _llm;
+}
+/** Returns the singleton embedding provider (lazy-initialized from env vars). */
+export function getEmbeddingProvider() {
+    if (_embeddings)
+        return _embeddings;
+    // Embeddings default to LOCAL (bundled bge-small, offline, $0, no key) when
+    // EMBEDDING_PROVIDER is unset — the shipped release default. A fresh install gets
+    // working semantic search with zero setup; set EMBEDDING_PROVIDER=gemini|openai|
+    // anthropic for hosted embeddings. (Decoupled from AI_PROVIDER on purpose: a chat
+    // model like owl/openai-compatible is a poor embedder.)
+    const embName = (process.env.EMBEDDING_PROVIDER ?? "local").toLowerCase();
+    if (embName === "local") {
+        // Local, free, offline embeddings (transformers.js) — no API/quota.
+        _embeddings = new LocalEmbeddingProvider();
+    }
+    else if (embName === "openai" || embName === "openai-compatible") {
+        _embeddings = new OpenAIEmbeddingProvider(process.env.OPENAI_API_KEY ?? "", process.env.OPENAI_BASE_URL);
+    }
+    else if (embName === "anthropic") {
+        // Anthropic has no embeddings API — cascade to Gemini, then OpenAI
+        if (process.env.GEMINI_API_KEY) {
+            _embeddings = new GeminiEmbeddingProvider(process.env.GEMINI_API_KEY);
+        }
+        else if (process.env.OPENAI_API_KEY) {
+            _embeddings = new OpenAIEmbeddingProvider(process.env.OPENAI_API_KEY);
+        }
+        else {
+            _embeddings = { embed: async () => null, isAvailable: () => false };
+        }
+    }
+    else {
+        // gemini (default)
+        _embeddings = new GeminiEmbeddingProvider(process.env.GEMINI_API_KEY ?? "");
+    }
+    return _embeddings;
+}
+/** Reset singletons — used in tests after env var changes. */
+export function resetProviders() {
+    _llm = null;
+    _embeddings = null;
+}
+//# sourceMappingURL=index.js.map