@juspay/neurolink 10.3.0 → 10.4.0

package/dist/knowledge/normalize.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deterministic text normalization for knowledge grounding.
+ *
+ * The SAME normalizer runs at index-build time and query time so that a
+ * configuration key, a technical identifier, and a user's phrasing all
+ * collapse to the same comparable token stream:
+ *
+ *   "Multi-Step Flow"        -> "multi step flow"
+ *   "enableMultiStepFlow"    -> "enable multi step flow"
+ *   "ACCOUNT_STATUS"         -> "account status"
+ *   "  Access   Policy  "    -> "access policy"
+ *
+ * The pipeline is intentionally conservative: it splits identifiers and
+ * separators and folds case/diacritics, but it NEVER invents synonyms.
+ * Reviewed acronym and spelling expansions belong in an entry's `aliases`,
+ * not in this function.
+ */
+/**
+ * Normalize an arbitrary string into a single space-delimited lowercase
+ * phrase. Idempotent: `normalizeText(normalizeText(x)) === normalizeText(x)`.
+ */
+export declare const normalizeText: (input: string) => string;
+/**
+ * Normalize then split into tokens. Empty input yields an empty array.
+ * Numbers and alphanumeric identifiers are preserved as their own tokens.
+ */
+export declare const tokenize: (input: string) => string[];
+/**
+ * Normalize each candidate phrase and drop blanks/duplicates while preserving
+ * first-seen order. Used to build the exact-key and alias key sets.
+ */
+export declare const normalizePhrases: (phrases: string[]) => string[];

package/dist/knowledge/normalize.js

@@ -0,0 +1,74 @@
+/**
+ * Deterministic text normalization for knowledge grounding.
+ *
+ * The SAME normalizer runs at index-build time and query time so that a
+ * configuration key, a technical identifier, and a user's phrasing all
+ * collapse to the same comparable token stream:
+ *
+ *   "Multi-Step Flow"        -> "multi step flow"
+ *   "enableMultiStepFlow"    -> "enable multi step flow"
+ *   "ACCOUNT_STATUS"         -> "account status"
+ *   "  Access   Policy  "    -> "access policy"
+ *
+ * The pipeline is intentionally conservative: it splits identifiers and
+ * separators and folds case/diacritics, but it NEVER invents synonyms.
+ * Reviewed acronym and spelling expansions belong in an entry's `aliases`,
+ * not in this function.
+ */
+/**
+ * Insert spaces at camelCase / PascalCase / acronym boundaries. Must run
+ * BEFORE lowercasing because it relies on case information.
+ *
+ *   "enableURLReading"            -> "enable URL Reading"
+ *   "customAccessOptionsV2"       -> "custom Access Options V2"
+ */
+const splitIdentifierBoundaries = (input) => input
+    // lower/number followed by an uppercase: "enableTwo" -> "enable Two"
+    .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
+    // acronym run followed by a Word: "URLReading" -> "URL Reading"
+    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, "$1 $2");
+/**
+ * Normalize an arbitrary string into a single space-delimited lowercase
+ * phrase. Idempotent: `normalizeText(normalizeText(x)) === normalizeText(x)`.
+ */
+export const normalizeText = (input) => {
+    if (!input) {
+        return "";
+    }
+    const boundaries = splitIdentifierBoundaries(
+    // NFKC folds compatibility forms; NFD + mark-strip removes diacritics.
+    input
+        .normalize("NFKC")
+        .normalize("NFD")
+        .replace(/\p{M}+/gu, ""));
+    return (boundaries
+        // any run of non-letter/non-number (snake_case, kebab-case, dots, slashes,
+        // punctuation, and existing whitespace) collapses to a single space.
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim()
+        .toLowerCase());
+};
+/**
+ * Normalize then split into tokens. Empty input yields an empty array.
+ * Numbers and alphanumeric identifiers are preserved as their own tokens.
+ */
+export const tokenize = (input) => {
+    const normalized = normalizeText(input);
+    return normalized ? normalized.split(" ") : [];
+};
+/**
+ * Normalize each candidate phrase and drop blanks/duplicates while preserving
+ * first-seen order. Used to build the exact-key and alias key sets.
+ */
+export const normalizePhrases = (phrases) => {
+    const seen = new Set();
+    const out = [];
+    for (const phrase of phrases) {
+        const normalized = normalizeText(phrase);
+        if (normalized && !seen.has(normalized)) {
+            seen.add(normalized);
+            out.push(normalized);
+        }
+    }
+    return out;
+};

package/dist/knowledge/resolve.d.ts

@@ -0,0 +1,18 @@
+import type { KnowledgeEntryInput, KnowledgeManifest, KnowledgeNormalizeOptions, KnowledgeNormalizeResult, KnowledgeSource, NormalizedKnowledgeEntry } from "../types/index.js";
+/**
+ * Resolve one authored entry into a complete `NormalizedKnowledgeEntry`,
+ * materializing every omitted optional (optional arrays to `[]`, `body` to "",
+ * `kind` to "text", `status` to "active") so downstream code never re-checks
+ * it. Authored arrays are cloned so the normalized snapshot is isolated from
+ * caller-owned references.
+ */
+export declare const resolveEntry: (input: KnowledgeEntryInput, version: string) => NormalizedKnowledgeEntry;
+/** Expand a build manifest into sources — one per catalog. */
+export declare const manifestToSources: (manifest: KnowledgeManifest) => KnowledgeSource[];
+/**
+ * Resolve and validate every source into normalized entries. `validation.ok`
+ * is false when any error-level issue was found; the caller (index builder)
+ * must not swap in an index built from an invalid set. Async so the public
+ * contract is stable if a future source kind needs asynchronous loading.
+ */
+export declare const normalizeAndValidate: (sources: KnowledgeSource[], options: KnowledgeNormalizeOptions) => Promise<KnowledgeNormalizeResult>;

package/dist/knowledge/resolve.js

@@ -0,0 +1,156 @@
+/**
+ * Source loading, default resolution, and generic validation.
+ *
+ * Required fields (id/title/summary/domain/integrations) come straight
+ * from the authored entry; omitted optionals fall back to SDK defaults. This
+ * covers only provider-neutral invariants (ids, required fields, enum values,
+ * relationship integrity). Host-specific rules — configuration-key coverage,
+ * taxonomy conflicts — are enforced by the host build BEFORE the manifest
+ * reaches NeuroLink. Errors block indexing; warnings are surfaced but do not.
+ */
+import { decodeArray, decodeString } from "type-decoder/dist/index.js";
+import { normalizeText } from "./normalize.js";
+const SDK_DEFAULT_KIND = "text";
+const SDK_DEFAULT_STATUS = "active";
+const STATUSES = new Set(["draft", "active", "deprecated"]);
+const KINDS = new Set([
+    "concept",
+    "text",
+    "configuration",
+    "tool",
+    "procedure",
+    "policy",
+    "troubleshooting",
+]);
+/**
+ * Resolve one authored entry into a complete `NormalizedKnowledgeEntry`,
+ * materializing every omitted optional (optional arrays to `[]`, `body` to "",
+ * `kind` to "text", `status` to "active") so downstream code never re-checks
+ * it. Authored arrays are cloned so the normalized snapshot is isolated from
+ * caller-owned references.
+ */
+export const resolveEntry = (input, version) => ({
+    id: input.id,
+    title: input.title,
+    summary: input.summary,
+    domain: input.domain,
+    integrations: decodeArray(input.integrations, decodeString) ?? [],
+    kind: input.kind ?? SDK_DEFAULT_KIND,
+    status: input.status ?? SDK_DEFAULT_STATUS,
+    body: input.body ?? "",
+    aliases: [...(input.aliases ?? [])],
+    keywords: [...(input.keywords ?? [])],
+    relatedEntryIds: [...(input.relatedEntryIds ?? [])],
+    parentEntryId: input.parentEntryId,
+    version,
+});
+/** Expand a build manifest into sources — one per catalog. */
+export const manifestToSources = (manifest) => manifest.catalogs.map((catalog) => ({
+    id: catalog.id,
+    version: manifest.contentVersion,
+    entries: catalog.entries,
+}));
+/** Resolve a source's entries and its effective version. */
+const loadSourceEntries = (source, manifestVersion) => ({
+    id: source.id,
+    version: source.version ?? manifestVersion,
+    entries: source.entries,
+});
+const error = (code, message, extra) => ({ level: "error", code, message, ...extra });
+const warn = (code, message, extra) => ({ level: "warning", code, message, ...extra });
+/**
+ * Resolve and validate every source into normalized entries. `validation.ok`
+ * is false when any error-level issue was found; the caller (index builder)
+ * must not swap in an index built from an invalid set. Async so the public
+ * contract is stable if a future source kind needs asynchronous loading.
+ */
+export const normalizeAndValidate = async (sources, options) => {
+    const issues = [];
+    const entries = [];
+    const seenIds = new Set();
+    const aliasOwner = new Map();
+    for (const source of sources) {
+        const loaded = loadSourceEntries(source, options.manifestVersion);
+        if (!loaded.id) {
+            issues.push(error("missing-source-id", "Source has no id"));
+        }
+        for (const input of loaded.entries) {
+            if (!input.id) {
+                issues.push(error("missing-entry-id", "Entry has no id", { sourceId: loaded.id }));
+                continue;
+            }
+            if (seenIds.has(input.id)) {
+                issues.push(error("duplicate-entry-id", `Duplicate entry id "${input.id}"`, {
+                    entryId: input.id,
+                }));
+                continue;
+            }
+            seenIds.add(input.id);
+            if (!input.title || !input.title.trim()) {
+                issues.push(error("missing-title", "Entry is missing a title", {
+                    entryId: input.id,
+                }));
+            }
+            if (!input.summary || !input.summary.trim()) {
+                issues.push(error("missing-summary", "Entry is missing a summary", {
+                    entryId: input.id,
+                }));
+            }
+            if (!input.domain || !input.domain.trim()) {
+                issues.push(error("missing-domain", "Entry is missing a domain", {
+                    entryId: input.id,
+                }));
+            }
+            if (input.integrations === undefined) {
+                issues.push(error("missing-integrations", "Entry is missing integrations", {
+                    entryId: input.id,
+                }));
+            }
+            else if (decodeArray(input.integrations, decodeString) === null) {
+                issues.push(error("bad-integrations", "Entry integrations must be an array of strings", { entryId: input.id }));
+            }
+            const normalized = resolveEntry(input, loaded.version);
+            if (!KINDS.has(normalized.kind)) {
+                issues.push(error("bad-kind", `Unsupported kind "${normalized.kind}"`, {
+                    entryId: normalized.id,
+                }));
+            }
+            if (!STATUSES.has(normalized.status)) {
+                issues.push(error("bad-status", `Unsupported status "${normalized.status}"`, {
+                    entryId: normalized.id,
+                }));
+            }
+            for (const alias of normalized.aliases) {
+                const key = normalizeText(alias);
+                if (!key) {
+                    issues.push(warn("empty-alias", `Alias "${alias}" is empty after normalization`, { entryId: normalized.id }));
+                    continue;
+                }
+                const owner = aliasOwner.get(key);
+                if (owner && owner !== normalized.id) {
+                    issues.push(warn("duplicate-alias", `Alias "${alias}" also used by "${owner}"`, { entryId: normalized.id }));
+                }
+                else {
+                    aliasOwner.set(key, normalized.id);
+                }
+            }
+            entries.push(normalized);
+        }
+    }
+    // Relationship integrity — resolved after all entries are collected.
+    const idSet = new Set(entries.map((entry) => entry.id));
+    for (const entry of entries) {
+        for (const related of entry.relatedEntryIds) {
+            if (!idSet.has(related)) {
+                issues.push(warn("broken-relation", `relatedEntryId "${related}" not found`, {
+                    entryId: entry.id,
+                }));
+            }
+        }
+        if (entry.parentEntryId && !idSet.has(entry.parentEntryId)) {
+            issues.push(warn("broken-parent", `parentEntryId "${entry.parentEntryId}" not found`, { entryId: entry.id }));
+        }
+    }
+    const ok = !issues.some((issue) => issue.level === "error");
+    return { entries, validation: { ok, issues } };
+};

package/dist/knowledge/retrieval.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lexical-first retrieval pipeline.
+ *
+ * For one turn: authorize/filter BEFORE ranking, resolve exact identifiers and
+ * reviewed aliases via query n-gram lookup, add field-aware BM25 over a bounded
+ * query+history window, combine the deterministic signals, take the top
+ * candidates, expand a bounded set of directly-related entries, and classify
+ * confidence. No LLM, no embeddings, no vector store.
+ */
+import type { KnowledgeIndexSnapshot, KnowledgeResolvedRetrieval, KnowledgeRetrievalRequest, KnowledgeSelection } from "../types/index.js";
+/**
+ * Run retrieval against a ready snapshot. Returns the primary selection, a
+ * bounded relationship expansion, the scored candidate list (diagnostics), and
+ * a confidence class. Context assembly is a separate, later step.
+ */
+export declare const retrieve: (snapshot: KnowledgeIndexSnapshot, request: KnowledgeRetrievalRequest, config: KnowledgeResolvedRetrieval, blockedDomains?: string[]) => KnowledgeSelection;

package/dist/knowledge/retrieval.js

@@ -0,0 +1,221 @@
+/**
+ * Lexical-first retrieval pipeline.
+ *
+ * For one turn: authorize/filter BEFORE ranking, resolve exact identifiers and
+ * reviewed aliases via query n-gram lookup, add field-aware BM25 over a bounded
+ * query+history window, combine the deterministic signals, take the top
+ * candidates, expand a bounded set of directly-related entries, and classify
+ * confidence. No LLM, no embeddings, no vector store.
+ */
+import { tokenize } from "./normalize.js";
+/** Per-turn history text cap so a long prior turn cannot dominate the query. */
+const HISTORY_TURN_CHARS = 400;
+/** All contiguous token n-grams (length 1..maxLen), de-duplicated. */
+const generateNGrams = (tokens, maxLen) => {
+    const grams = [];
+    const seen = new Set();
+    const limit = Math.min(maxLen, tokens.length);
+    for (let size = 1; size <= limit; size += 1) {
+        for (let start = 0; start + size <= tokens.length; start += 1) {
+            const gram = tokens.slice(start, start + size).join(" ");
+            if (!seen.has(gram)) {
+                seen.add(gram);
+                grams.push(gram);
+            }
+        }
+    }
+    return grams;
+};
+/** Longest indexed exact/alias phrase length, derived from the active snapshot. */
+const getMaxIndexedPhraseLen = (...indexes) => {
+    let maxLen = 0;
+    for (const index of indexes) {
+        for (const phrase of index.keys()) {
+            const length = phrase === "" ? 0 : phrase.split(" ").length;
+            maxLen = Math.max(maxLen, length);
+        }
+    }
+    return maxLen;
+};
+/** Look each n-gram up in a phrase index; returns entry id -> matched phrases. */
+const lookupPhrases = (grams, index) => {
+    const hits = new Map();
+    for (const gram of grams) {
+        const ids = index.get(gram);
+        if (!ids) {
+            continue;
+        }
+        for (const id of ids) {
+            const matched = hits.get(id) ?? [];
+            matched.push(gram);
+            hits.set(id, matched);
+        }
+    }
+    return hits;
+};
+/** Tokens fed to BM25: the current query plus a bounded recent-turn window. */
+const buildLexicalTokens = (request) => {
+    const parts = [request.query];
+    for (const turn of request.recentTurns) {
+        parts.push(turn.text.slice(0, HISTORY_TURN_CHARS));
+    }
+    return parts.flatMap((part) => tokenize(part));
+};
+/**
+ * Authorization + metadata filter. Applied BEFORE ranking so restricted or
+ * disabled-integration content never enters candidates, traces, or model context.
+ */
+const isAuthorized = (entry, request, blockedDomains) => {
+    if (entry.status !== "active") {
+        return false;
+    }
+    if (blockedDomains && blockedDomains.includes(entry.domain)) {
+        return false;
+    }
+    if (entry.integrations.length > 0) {
+        const active = new Set();
+        for (const integration of request.enabledIntegrations) {
+            active.add(integration.toLowerCase());
+        }
+        if (!entry.integrations.some((integration) => active.has(integration.toLowerCase()))) {
+            return false;
+        }
+    }
+    return true;
+};
+const compareCandidates = (left, right) => {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    if (left.id < right.id) {
+        return -1;
+    }
+    if (left.id > right.id) {
+        return 1;
+    }
+    return 0;
+};
+/**
+ * Confidence class. `high` requires an exact/alias hit at the top; otherwise a
+ * multi-field or dominant lexical top is `medium`, a single weak signal is
+ * `low`, and no candidates is `none`. Thresholds are pre-tuning heuristics.
+ */
+const classifyConfidence = (candidates) => {
+    if (candidates.length === 0) {
+        return "none";
+    }
+    const [top, second] = candidates;
+    if (top.exact || top.alias) {
+        return "high";
+    }
+    const fieldsMatched = Object.keys(top.fieldScores).length;
+    const dominant = second ? top.score >= 1.5 * second.score : false;
+    if (fieldsMatched >= 2 || dominant) {
+        return "medium";
+    }
+    return "low";
+};
+/**
+ * Run retrieval against a ready snapshot. Returns the primary selection, a
+ * bounded relationship expansion, the scored candidate list (diagnostics), and
+ * a confidence class. Context assembly is a separate, later step.
+ */
+export const retrieve = (snapshot, request, config, blockedDomains) => {
+    const queryTokens = tokenize(request.query);
+    const maxPhraseLen = getMaxIndexedPhraseLen(snapshot.exactIndex, snapshot.aliasIndex);
+    const grams = generateNGrams(queryTokens, maxPhraseLen);
+    const exactHits = lookupPhrases(grams, snapshot.exactIndex);
+    const aliasHits = lookupPhrases(grams, snapshot.aliasIndex);
+    const eligibleEntryIds = new Set();
+    for (const [id, entry] of snapshot.entriesById) {
+        if (isAuthorized(entry, request, blockedDomains)) {
+            eligibleEntryIds.add(id);
+        }
+    }
+    const lexicalTokens = buildLexicalTokens(request);
+    const lexicalMatches = snapshot.lexical.search(lexicalTokens, config.candidateLimit * 2, eligibleEntryIds);
+    const lexicalById = new Map(lexicalMatches.map((match) => [match.id, match]));
+    const candidateIds = new Set();
+    for (const id of exactHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const id of aliasHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const match of lexicalMatches) {
+        candidateIds.add(match.id);
+    }
+    const candidates = [];
+    for (const id of candidateIds) {
+        const entry = snapshot.entriesById.get(id);
+        if (!entry) {
+            continue;
+        }
+        const exact = exactHits.has(id);
+        const alias = aliasHits.has(id);
+        const lexicalMatch = lexicalById.get(id);
+        const lexical = lexicalMatch?.score ?? 0;
+        let score = lexical;
+        if (exact) {
+            score += config.exactBoost;
+        }
+        if (alias) {
+            score += config.aliasBoost;
+        }
+        candidates.push({
+            id,
+            score,
+            exact,
+            alias,
+            lexical,
+            fieldScores: lexicalMatch?.fieldScores ?? {},
+            matchedPhrases: [
+                ...(exactHits.get(id) ?? []),
+                ...(aliasHits.get(id) ?? []),
+            ],
+        });
+    }
+    candidates.sort(compareCandidates);
+    const trimmed = candidates.slice(0, config.candidateLimit);
+    const primary = [];
+    for (const candidate of trimmed.slice(0, config.resultLimit)) {
+        const entry = snapshot.entriesById.get(candidate.id);
+        if (entry) {
+            primary.push(entry);
+        }
+    }
+    const selectedIds = new Set(primary.map((entry) => entry.id));
+    const expanded = [];
+    for (const entry of primary) {
+        if (expanded.length >= config.relationLimit) {
+            break;
+        }
+        const relations = snapshot.relationIndex.get(entry.id) ?? [];
+        for (const relatedId of relations) {
+            if (expanded.length >= config.relationLimit) {
+                break;
+            }
+            if (selectedIds.has(relatedId)) {
+                continue;
+            }
+            const relatedEntry = snapshot.entriesById.get(relatedId);
+            if (!relatedEntry ||
+                !isAuthorized(relatedEntry, request, blockedDomains)) {
+                continue;
+            }
+            selectedIds.add(relatedId);
+            expanded.push(relatedEntry);
+        }
+    }
+    return {
+        primary,
+        expanded,
+        candidates: trimmed,
+        confidence: classifyConfidence(trimmed),
+        candidateCount: candidates.length,
+    };
+};

package/dist/lib/constants/contextWindows.d.ts

@@ -30,6 +30,30 @@ export declare const MODEL_CONTEXT_WINDOWS: Record<string, Record<string, number
 export declare function registerRuntimeContextWindow(provider: string, model: string, contextWindow: number): void;
 /** Test hook: clear runtime-discovered windows (state is module-global). */
 export declare function clearRuntimeContextWindows(): void;
+/**
+ * Runtime-discovered window for an exact provider/model pair, or undefined.
+ *
+ * Unlike {@link getContextWindowSize} this NEVER falls back to static table
+ * values. Callers use it to distinguish "the serving infrastructure told us
+ * the real window" (safe to hard-enforce: clamp max_tokens, fail fast) from
+ * "static guess" (advisory only — hard-enforcing a guessed window would
+ * falsely reject requests that the real deployment accepts).
+ */
+export declare function getRuntimeContextWindow(provider: string, model?: string): number | undefined;
+/**
+ * Register a runtime-discovered output-token ceiling for a provider/model
+ * pair. Later registrations overwrite earlier ones (rediscovery refreshes
+ * values). Non-positive/non-finite ceilings are ignored so a malformed
+ * discovery source can never shrink an output budget to zero.
+ */
+export declare function registerRuntimeOutputCeiling(provider: string, model: string, maxOutputTokens: number): void;
+/**
+ * Runtime-discovered output ceiling for an exact provider/model pair, or
+ * undefined when the serving infrastructure has not advertised one.
+ */
+export declare function getRuntimeOutputCeiling(provider: string, model?: string): number | undefined;
+/** Test hook: clear runtime-discovered output ceilings (state is module-global). */
+export declare function clearRuntimeOutputCeilings(): void;
 /**
  * Resolve context window size for a provider/model combination.
  *

package/dist/lib/constants/contextWindows.js

@@ -420,6 +420,56 @@ export function registerRuntimeContextWindow(provider, model, contextWindow) {
 export function clearRuntimeContextWindows() {
     RUNTIME_CONTEXT_WINDOWS.clear();
 }
+/**
+ * Runtime-discovered window for an exact provider/model pair, or undefined.
+ *
+ * Unlike {@link getContextWindowSize} this NEVER falls back to static table
+ * values. Callers use it to distinguish "the serving infrastructure told us
+ * the real window" (safe to hard-enforce: clamp max_tokens, fail fast) from
+ * "static guess" (advisory only — hard-enforcing a guessed window would
+ * falsely reject requests that the real deployment accepts).
+ */
+export function getRuntimeContextWindow(provider, model) {
+    if (!model) {
+        return undefined;
+    }
+    return RUNTIME_CONTEXT_WINDOWS.get(`${provider}:${model}`);
+}
+/**
+ * Runtime-discovered output-token ceilings, keyed `${provider}:${model}` —
+ * the `max_output_tokens` the serving infrastructure advertises for a model
+ * (e.g. LiteLLM `/model/info`). Same async-populate/sync-read contract as
+ * {@link registerRuntimeContextWindow}. Consumed by `getSafeMaxTokens` so
+ * requested maxTokens is clamped to the deployed model's real cap instead of
+ * a static per-provider table value.
+ */
+const RUNTIME_OUTPUT_CEILINGS = new Map();
+/**
+ * Register a runtime-discovered output-token ceiling for a provider/model
+ * pair. Later registrations overwrite earlier ones (rediscovery refreshes
+ * values). Non-positive/non-finite ceilings are ignored so a malformed
+ * discovery source can never shrink an output budget to zero.
+ */
+export function registerRuntimeOutputCeiling(provider, model, maxOutputTokens) {
+    if (!Number.isFinite(maxOutputTokens) || maxOutputTokens <= 0) {
+        return;
+    }
+    RUNTIME_OUTPUT_CEILINGS.set(`${provider}:${model}`, maxOutputTokens);
+}
+/**
+ * Runtime-discovered output ceiling for an exact provider/model pair, or
+ * undefined when the serving infrastructure has not advertised one.
+ */
+export function getRuntimeOutputCeiling(provider, model) {
+    if (!model) {
+        return undefined;
+    }
+    return RUNTIME_OUTPUT_CEILINGS.get(`${provider}:${model}`);
+}
+/** Test hook: clear runtime-discovered output ceilings (state is module-global). */
+export function clearRuntimeOutputCeilings() {
+    RUNTIME_OUTPUT_CEILINGS.clear();
+}
 /**
  * Resolve context window size for a provider/model combination.
  *

package/dist/lib/context/errorDetection.d.ts

@@ -23,6 +23,12 @@ export declare function getContextOverflowProvider(error: unknown): string | nul
 export declare function parseProviderOverflowDetails(error: unknown): {
     actualTokens: number;
     budgetTokens: number;
+    /**
+     * Output tokens the rejected request asked for, when the message states
+     * them separately (vllm/LiteLLM phrasing). Lets recovery re-fit
+     * max_tokens instead of shrinking the input.
+     */
+    requestedOutputTokens?: number;
 } | null;
 /**
  * Extract error message from various error formats.

package/dist/lib/context/errorDetection.js

@@ -113,6 +113,24 @@ export function parseProviderOverflowDetails(error) {
             budgetTokens: parseInt(openaiMax[1].replace(/,/g, ""), 10),
         };
     }
+    // vllm / LiteLLM-proxied backends: "This model's maximum context length is
+    // N tokens. However, you requested X output tokens and your prompt contains
+    // at least Y input tokens..." — input and requested-output are stated
+    // separately (no "resulted in"), so recovery can re-fit max_tokens to
+    // N − Y instead of shrinking the input.
+    const vllmInput = message.match(/prompt\s+contains\s+at\s+least\s+(\d[\d,]{0,19})\s+input\s+tokens/i);
+    if (vllmInput && openaiMax) {
+        const requestedOutput = message.match(/requested\s+(\d[\d,]{0,19})\s+output\s+tokens/i);
+        return {
+            actualTokens: parseInt(vllmInput[1].replace(/,/g, ""), 10),
+            budgetTokens: parseInt(openaiMax[1].replace(/,/g, ""), 10),
+            ...(requestedOutput
+                ? {
+                    requestedOutputTokens: parseInt(requestedOutput[1].replace(/,/g, ""), 10),
+                }
+                : {}),
+        };
+    }
     // Anthropic pattern: "X tokens > Y token limit" or "X tokens, limit Y"
     // Use single character-class number groups to prevent ReDoS (CodeQL: js/polynomial-redos)
     const anthropicMatch = message.match(/(\d[\d,]{0,19})\s*tokens?\s*[>:]\s*(\d[\d,]{0,19})/i);

package/dist/lib/context/stepBudgetGuard.d.ts

@@ -41,7 +41,21 @@ export declare function estimateStepMessagesTokens(messages: readonly ModelMessa
 export declare function estimateFixedOverheadTokens(system: unknown, tools: Record<string, unknown> | undefined, provider?: string): number;
 /**
  * Create a per-step budget guard. Returns a function that, given the step's
- * messages, returns a compacted replacement array when the projected request
- * exceeds the threshold — or `undefined` when no change is needed.
+ * messages (and optionally the REAL input-token count the provider reported
+ * for the previous step), returns a compacted replacement array when the
+ * projected request exceeds the threshold — or `undefined` when no change is
+ * needed.
+ *
+ * Two dynamic behaviours:
+ *  - the available-input budget is re-resolved on EVERY invocation, so
+ *    runtime window discovery (`/model/info`, overflow self-healing) that
+ *    lands mid-loop takes effect immediately instead of the guard staying
+ *    frozen on the value captured at loop start;
+ *  - usage feedback calibrates the estimator: the ratio between the real
+ *    prompt tokens of the previous step and this guard's own estimate for
+ *    what that step sent scales later estimates (only UP — underestimates
+ *    overflow, overestimates merely compact earlier), eliminating the
+ *    char-based estimator's drift on dense code/diff content without
+ *    shipping a tokenizer.
  */
-export declare function createStepBudgetGuard(config: StepBudgetGuardConfig): (messages: readonly ModelMessage[]) => ModelMessage[] | undefined;
+export declare function createStepBudgetGuard(config: StepBudgetGuardConfig): (messages: readonly ModelMessage[], observedInputTokensLastStep?: number) => ModelMessage[] | undefined;