@code-yeongyu/senpi 2026.7.20 → 2026.7.22

package/dist/core/retry-fallback/chains.js

@@ -0,0 +1,109 @@
+import { isValidThinkingLevel } from "../../cli/args.js";
+import { findExactModelReferenceMatch, parseModelPattern } from "../model-resolver.js";
+function availableModels(lookup) {
+    return "getAll" in lookup ? lookup.getAll() : [...lookup];
+}
+function selectorReference(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.includes("/") || trimmed.includes("*"))
+        return undefined;
+    const lastColon = trimmed.lastIndexOf(":");
+    if (lastColon === -1)
+        return { reference: trimmed };
+    const prefix = trimmed.slice(0, lastColon);
+    const suffix = trimmed.slice(lastColon + 1).toLowerCase();
+    if (!isValidThinkingLevel(suffix))
+        return { reference: trimmed };
+    return { reference: prefix, thinkingLevel: suffix };
+}
+/**
+ * Resolves only complete provider/model selectors. The full input is resolved first
+ * so colons belonging to a model id remain part of that id; aliases then resolve
+ * against the model-id portion while retaining the explicitly selected provider.
+ */
+export function parseFallbackSelector(raw, lookup) {
+    const models = availableModels(lookup);
+    const trimmed = raw.trim();
+    const parsedReference = selectorReference(trimmed);
+    if (!parsedReference)
+        return undefined;
+    const fullMatch = findExactModelReferenceMatch(trimmed, models);
+    if (fullMatch) {
+        return { raw: trimmed, provider: fullMatch.provider, id: fullMatch.id };
+    }
+    const slashIndex = parsedReference.reference.indexOf("/");
+    const provider = parsedReference.reference.slice(0, slashIndex).trim();
+    const modelPattern = parsedReference.reference.slice(slashIndex + 1).trim();
+    if (!provider || !modelPattern)
+        return undefined;
+    const parsed = parseModelPattern(parsedReference.thinkingLevel ? `${modelPattern}:${parsedReference.thinkingLevel}` : modelPattern, models, { allowInvalidThinkingLevelFallback: false });
+    if (!parsed.model || parsed.warning || parsed.model.provider.toLowerCase() !== provider.toLowerCase())
+        return undefined;
+    if (parsedReference.thinkingLevel && !parsed.thinkingLevel)
+        return undefined;
+    return {
+        raw: trimmed,
+        provider: parsed.model.provider,
+        id: parsed.model.id,
+        thinkingLevel: parsed.thinkingLevel,
+    };
+}
+export function formatSelector(model, thinkingLevel) {
+    const base = `${model.provider}/${model.id}`;
+    return thinkingLevel ? `${base}:${thinkingLevel}` : base;
+}
+export function baseSelector(selector) {
+    return `${selector.provider}/${selector.id}`;
+}
+/** Converts validated configuration to canonical selector strings for runtime lookup. */
+export function canonicalizeFallbackChains(chains, lookup) {
+    const canonical = {};
+    for (const [key, entries] of Object.entries(chains)) {
+        const parsedKey = parseFallbackSelector(key, lookup);
+        if (!parsedKey || !Array.isArray(entries))
+            continue;
+        const canonicalEntries = entries.flatMap((entry) => {
+            const parsedEntry = parseFallbackSelector(entry, lookup);
+            return parsedEntry ? [formatParsedSelector(parsedEntry)] : [];
+        });
+        canonical[formatParsedSelector(parsedKey)] = canonicalEntries;
+    }
+    return canonical;
+}
+export function resolveChainKey(currentModel, currentThinking, chains) {
+    const base = formatSelector(currentModel);
+    const exact = currentThinking ? `${base}:${currentThinking}` : base;
+    if (Object.hasOwn(chains, exact))
+        return exact;
+    return Object.hasOwn(chains, base) ? base : undefined;
+}
+function formatParsedSelector(selector) {
+    const base = baseSelector(selector);
+    return selector.thinkingLevel ? `${base}:${selector.thinkingLevel}` : base;
+}
+function normalizedBase(selector) {
+    if (typeof selector !== "string")
+        return baseSelector(selector).toLowerCase();
+    const normalized = selector.trim().toLowerCase();
+    const lastColon = normalized.lastIndexOf(":");
+    if (lastColon === -1 || !isValidThinkingLevel(normalized.slice(lastColon + 1)))
+        return normalized;
+    return normalized.slice(0, lastColon);
+}
+function normalizedExact(selector) {
+    return typeof selector === "string" ? selector.trim().toLowerCase() : formatParsedSelector(selector).toLowerCase();
+}
+/**
+ * Returns entries after the current fallback. A primary or unknown selector starts
+ * from the beginning, which also makes re-entry after stale runtime state safe.
+ */
+export function candidatesAfter(chainEntries, currentSelector) {
+    const exact = normalizedExact(currentSelector);
+    const exactIndex = chainEntries.findIndex((entry) => entry.toLowerCase() === exact);
+    if (exactIndex !== -1)
+        return chainEntries.slice(exactIndex + 1);
+    const base = normalizedBase(currentSelector);
+    const baseIndex = chainEntries.findIndex((entry) => normalizedBase(entry) === base);
+    return baseIndex === -1 ? chainEntries : chainEntries.slice(baseIndex + 1);
+}
+//# sourceMappingURL=chains.js.map

package/dist/core/retry-fallback/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../../../src/core/retry-fallback/chains.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAavF,SAAS,eAAe,CAAC,MAA2B;IACnD,OAAO,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEtE,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,SAAS,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1D,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACjE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,MAA2B;IAC7E,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,eAAe,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnD,IAAI,CAAC,eAAe;QAAE,OAAO,SAAS,CAAC;IAEvC,MAAM,SAAS,GAAG,4BAA4B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChE,IAAI,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,UAAU,GAAG,eAAe,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IACvE,MAAM,YAAY,GAAG,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,IAAI,CAAC,QAAQ,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAC;IAEjD,MAAM,MAAM,GAAG,iBAAiB,CAC/B,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,YAAY,IAAI,eAAe,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,YAAY,EACjG,MAAM,EACN,EAAE,iCAAiC,EAAE,KAAK,EAAE,CAC5C,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE;QACpG,OAAO,SAAS,CAAC;IAClB,IAAI,eAAe,CAAC,aAAa,IAAI,CAAC,MAAM,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IAE7E,OAAO;QACN,GAAG,EAAE,OAAO;QACZ,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;QAC/B,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;QACnB,aAAa,EAAE,MAAM,CAAC,aAAa;KACnC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAiB,EAAE,aAA6B;IAC9E,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;IAC7C,OAAO,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAmD;IAC/E,OAAO,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,0BAA0B,CAAC,MAAsB,EAAE,MAA2B;IAC7F,MAAM,SAAS,GAAsC,EAAE,CAAC;IAExD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,MAAM,SAAS,GAAG,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,SAAS;QAEpD,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACzD,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,GAAG,gBAAgB,CAAC;IAC/D,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,eAAe,CAC9B,YAAwB,EACxB,eAA0C,EAC1C,MAAsB;IAEtB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,oBAAoB,CAAC,QAA0B;IACvD,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED,SAAS,cAAc,CAAC,QAAmC;IAC1D,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAE9E,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,SAAS,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,UAAU,CAAC;IAClG,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,eAAe,CAAC,QAAmC;IAC3D,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;AACpH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,YAA+B,EAC/B,eAA0C;IAE1C,MAAM,KAAK,GAAG,eAAe,CAAC,eAAe,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAC;IACpF,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IAEjE,MAAM,IAAI,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IACpF,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;AAC5E,CAAC","sourcesContent":["import type { ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { Api, Model } from \"@earendil-works/pi-ai\";\nimport { isValidThinkingLevel } from \"../../cli/args.ts\";\nimport { findExactModelReferenceMatch, parseModelPattern } from \"../model-resolver.ts\";\n\nexport interface FallbackSelector {\n\traw: string;\n\tprovider: string;\n\tid: string;\n\tthinkingLevel?: ThinkingLevel;\n}\n\nexport type FallbackChains = Readonly<Record<string, readonly string[]>>;\n\nexport type FallbackModelLookup = readonly Model<Api>[] | { getAll(): Model<Api>[] };\n\nfunction availableModels(lookup: FallbackModelLookup): Model<Api>[] {\n\treturn \"getAll\" in lookup ? lookup.getAll() : [...lookup];\n}\n\nfunction selectorReference(raw: string): { reference: string; thinkingLevel?: ThinkingLevel } | undefined {\n\tconst trimmed = raw.trim();\n\tif (!trimmed.includes(\"/\") || trimmed.includes(\"*\")) return undefined;\n\n\tconst lastColon = trimmed.lastIndexOf(\":\");\n\tif (lastColon === -1) return { reference: trimmed };\n\n\tconst prefix = trimmed.slice(0, lastColon);\n\tconst suffix = trimmed.slice(lastColon + 1).toLowerCase();\n\tif (!isValidThinkingLevel(suffix)) return { reference: trimmed };\n\treturn { reference: prefix, thinkingLevel: suffix };\n}\n\n/**\n * Resolves only complete provider/model selectors. The full input is resolved first\n * so colons belonging to a model id remain part of that id; aliases then resolve\n * against the model-id portion while retaining the explicitly selected provider.\n */\nexport function parseFallbackSelector(raw: string, lookup: FallbackModelLookup): FallbackSelector | undefined {\n\tconst models = availableModels(lookup);\n\tconst trimmed = raw.trim();\n\tconst parsedReference = selectorReference(trimmed);\n\tif (!parsedReference) return undefined;\n\n\tconst fullMatch = findExactModelReferenceMatch(trimmed, models);\n\tif (fullMatch) {\n\t\treturn { raw: trimmed, provider: fullMatch.provider, id: fullMatch.id };\n\t}\n\n\tconst slashIndex = parsedReference.reference.indexOf(\"/\");\n\tconst provider = parsedReference.reference.slice(0, slashIndex).trim();\n\tconst modelPattern = parsedReference.reference.slice(slashIndex + 1).trim();\n\tif (!provider || !modelPattern) return undefined;\n\n\tconst parsed = parseModelPattern(\n\t\tparsedReference.thinkingLevel ? `${modelPattern}:${parsedReference.thinkingLevel}` : modelPattern,\n\t\tmodels,\n\t\t{ allowInvalidThinkingLevelFallback: false },\n\t);\n\tif (!parsed.model || parsed.warning || parsed.model.provider.toLowerCase() !== provider.toLowerCase())\n\t\treturn undefined;\n\tif (parsedReference.thinkingLevel && !parsed.thinkingLevel) return undefined;\n\n\treturn {\n\t\traw: trimmed,\n\t\tprovider: parsed.model.provider,\n\t\tid: parsed.model.id,\n\t\tthinkingLevel: parsed.thinkingLevel,\n\t};\n}\n\nexport function formatSelector(model: Model<Api>, thinkingLevel?: ThinkingLevel): string {\n\tconst base = `${model.provider}/${model.id}`;\n\treturn thinkingLevel ? `${base}:${thinkingLevel}` : base;\n}\n\nexport function baseSelector(selector: Pick<FallbackSelector, \"provider\" | \"id\">): string {\n\treturn `${selector.provider}/${selector.id}`;\n}\n\n/** Converts validated configuration to canonical selector strings for runtime lookup. */\nexport function canonicalizeFallbackChains(chains: FallbackChains, lookup: FallbackModelLookup): FallbackChains {\n\tconst canonical: Record<string, readonly string[]> = {};\n\n\tfor (const [key, entries] of Object.entries(chains)) {\n\t\tconst parsedKey = parseFallbackSelector(key, lookup);\n\t\tif (!parsedKey || !Array.isArray(entries)) continue;\n\n\t\tconst canonicalEntries = entries.flatMap((entry) => {\n\t\t\tconst parsedEntry = parseFallbackSelector(entry, lookup);\n\t\t\treturn parsedEntry ? [formatParsedSelector(parsedEntry)] : [];\n\t\t});\n\t\tcanonical[formatParsedSelector(parsedKey)] = canonicalEntries;\n\t}\n\n\treturn canonical;\n}\n\nexport function resolveChainKey(\n\tcurrentModel: Model<Api>,\n\tcurrentThinking: ThinkingLevel | undefined,\n\tchains: FallbackChains,\n): string | undefined {\n\tconst base = formatSelector(currentModel);\n\tconst exact = currentThinking ? `${base}:${currentThinking}` : base;\n\tif (Object.hasOwn(chains, exact)) return exact;\n\treturn Object.hasOwn(chains, base) ? base : undefined;\n}\n\nfunction formatParsedSelector(selector: FallbackSelector): string {\n\tconst base = baseSelector(selector);\n\treturn selector.thinkingLevel ? `${base}:${selector.thinkingLevel}` : base;\n}\n\nfunction normalizedBase(selector: FallbackSelector | string): string {\n\tif (typeof selector !== \"string\") return baseSelector(selector).toLowerCase();\n\n\tconst normalized = selector.trim().toLowerCase();\n\tconst lastColon = normalized.lastIndexOf(\":\");\n\tif (lastColon === -1 || !isValidThinkingLevel(normalized.slice(lastColon + 1))) return normalized;\n\treturn normalized.slice(0, lastColon);\n}\n\nfunction normalizedExact(selector: FallbackSelector | string): string {\n\treturn typeof selector === \"string\" ? selector.trim().toLowerCase() : formatParsedSelector(selector).toLowerCase();\n}\n\n/**\n * Returns entries after the current fallback. A primary or unknown selector starts\n * from the beginning, which also makes re-entry after stale runtime state safe.\n */\nexport function candidatesAfter(\n\tchainEntries: readonly string[],\n\tcurrentSelector: FallbackSelector | string,\n): readonly string[] {\n\tconst exact = normalizedExact(currentSelector);\n\tconst exactIndex = chainEntries.findIndex((entry) => entry.toLowerCase() === exact);\n\tif (exactIndex !== -1) return chainEntries.slice(exactIndex + 1);\n\n\tconst base = normalizedBase(currentSelector);\n\tconst baseIndex = chainEntries.findIndex((entry) => normalizedBase(entry) === base);\n\treturn baseIndex === -1 ? chainEntries : chainEntries.slice(baseIndex + 1);\n}\n"]}

package/dist/core/retry-fallback/controller.d.ts

@@ -0,0 +1,77 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { SelectorCooldowns } from "./cooldown.ts";
+import type { FallbackLogger } from "./log.ts";
+export interface ActiveFallbackState {
+    chainKey: string;
+    originalSelector: string;
+    originalThinkingLevel?: ThinkingLevel;
+    lastAppliedThinkingLevel?: ThinkingLevel;
+    pinned: boolean;
+}
+type FallbackReason = "transient" | "refusal" | "hard-error";
+interface FallbackSettings {
+    modelFallback: boolean;
+    chains: Readonly<Record<string, readonly string[]>>;
+}
+export interface RetryFallbackControllerDeps {
+    getSettings(): FallbackSettings;
+    registry: {
+        find(provider: string, id: string): Model<Api> | undefined;
+        getAll(): Model<Api>[];
+    };
+    cooldowns: SelectorCooldowns;
+    logger: FallbackLogger;
+    switchModel(model: Model<Api>, thinking: ThinkingLevel, reason: "fallback" | "fallback-revert"): Promise<void>;
+    emit(event: {
+        type: "retry_fallback_applied";
+        from: string;
+        to: string;
+        chainKey: string;
+        reason: FallbackReason;
+    } | {
+        type: "retry_fallback_reverted";
+        from: string;
+        to: string;
+    }): void;
+    getCurrentSelector(): {
+        model: Model<Api>;
+        thinkingLevel?: ThinkingLevel;
+    } | undefined;
+    isAuthAvailable(provider: string): boolean;
+}
+export declare class RetryFallbackController {
+    private readonly deps;
+    private readonly triedSelectors;
+    private state;
+    private lastExhaustedChainKey;
+    constructor(deps: RetryFallbackControllerDeps);
+    get activeState(): Readonly<ActiveFallbackState> | undefined;
+    get exhaustedChainKey(): string | undefined;
+    resetTurn(): void;
+    clear(): void;
+    canTryFallback(): boolean;
+    /**
+     * Revert to the chain's original model at a turn boundary. Only fires for
+     * unpinned state under the cooldown-expiry policy once the original selector
+     * is no longer suppressed and is still usable; pinned (refusal) state and the
+     * "never" policy always hold the fallback model.
+     */
+    maybeRestorePrimary(revertPolicy: "cooldown-expiry" | "never"): Promise<boolean>;
+    /**
+     * A user-driven setThinkingLevel makes the current level a deliberate choice,
+     * so the revert restore-rule must no longer treat it as fallback-applied.
+     */
+    noteManualThinkingLevel(): void;
+    /** A user-driven model change abandons the fallback window entirely. */
+    clearForManualModelChange(model: Model<Api>): void;
+    tryFallback(reason: FallbackReason, failure: {
+        errorMessage?: string;
+        retryAfterMs?: number;
+    }): Promise<boolean>;
+    private nextCandidate;
+    private selectThinking;
+    private skip;
+}
+export {};
+//# sourceMappingURL=controller.d.ts.map

package/dist/core/retry-fallback/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/core/retry-fallback/controller.ts"],"names":[],"mappings":"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"}

package/dist/core/retry-fallback/controller.js

@@ -0,0 +1,157 @@
+import { getSupportedThinkingLevels } from "../thinking-levels.js";
+import { baseSelector, candidatesAfter, canonicalizeFallbackChains, formatSelector, parseFallbackSelector, resolveChainKey, } from "./chains.js";
+export class RetryFallbackController {
+    constructor(deps) {
+        this.triedSelectors = new Set();
+        this.deps = deps;
+    }
+    get activeState() {
+        return this.state;
+    }
+    get exhaustedChainKey() {
+        return this.lastExhaustedChainKey;
+    }
+    resetTurn() {
+        this.triedSelectors.clear();
+        this.lastExhaustedChainKey = undefined;
+    }
+    clear() {
+        this.state = undefined;
+        this.resetTurn();
+    }
+    canTryFallback() {
+        return this.nextCandidate(false) !== undefined;
+    }
+    /**
+     * Revert to the chain's original model at a turn boundary. Only fires for
+     * unpinned state under the cooldown-expiry policy once the original selector
+     * is no longer suppressed and is still usable; pinned (refusal) state and the
+     * "never" policy always hold the fallback model.
+     */
+    async maybeRestorePrimary(revertPolicy) {
+        const state = this.state;
+        if (!state || state.pinned || revertPolicy !== "cooldown-expiry")
+            return false;
+        if (this.deps.cooldowns.isSuppressed(state.originalSelector))
+            return false;
+        const selector = parseFallbackSelector(state.originalSelector, this.deps.registry);
+        if (!selector || !this.deps.isAuthAvailable(selector.provider))
+            return false;
+        const model = this.deps.registry.find(selector.provider, selector.id);
+        const current = this.deps.getCurrentSelector();
+        if (!model || !current)
+            return false;
+        // User override wins: only restore the original thinking level when the
+        // current level still equals the level the fallback switch applied. A manual
+        // setThinkingLevel clears lastAppliedThinkingLevel (see noteManualThinkingLevel).
+        const thinking = current.thinkingLevel === state.lastAppliedThinkingLevel
+            ? (state.originalThinkingLevel ?? current.thinkingLevel ?? "off")
+            : (current.thinkingLevel ?? "off");
+        await this.deps.switchModel(model, thinking, "fallback-revert");
+        const from = formatSelector(current.model);
+        this.state = undefined;
+        this.deps.logger.info("fallback_reverted", { from, to: state.originalSelector });
+        this.deps.emit({ type: "retry_fallback_reverted", from, to: state.originalSelector });
+        return true;
+    }
+    /**
+     * A user-driven setThinkingLevel makes the current level a deliberate choice,
+     * so the revert restore-rule must no longer treat it as fallback-applied.
+     */
+    noteManualThinkingLevel() {
+        if (this.state)
+            this.state.lastAppliedThinkingLevel = undefined;
+    }
+    /** A user-driven model change abandons the fallback window entirely. */
+    clearForManualModelChange(model) {
+        if (this.state) {
+            this.deps.logger.info("fallback_cleared_manual", { selector: formatSelector(model) });
+        }
+        this.state = undefined;
+        this.deps.cooldowns.clear(formatSelector(model));
+    }
+    async tryFallback(reason, failure) {
+        const current = this.deps.getCurrentSelector();
+        const candidate = this.nextCandidate();
+        if (!current || !candidate)
+            return false;
+        const currentBase = formatSelector(current.model);
+        if (reason === "transient" || reason === "hard-error") {
+            this.deps.cooldowns.note(currentBase, failure);
+            this.deps.logger.info("cooldown_noted", { selector: currentBase, errorMessage: failure.errorMessage });
+        }
+        const thinking = this.selectThinking(candidate.selector, candidate.model, current.thinkingLevel);
+        await this.deps.switchModel(candidate.model, thinking, "fallback");
+        const from = formatSelector(current.model);
+        const to = formatSelector(candidate.model);
+        this.state = {
+            chainKey: candidate.chainKey,
+            originalSelector: this.state?.originalSelector ?? from,
+            originalThinkingLevel: this.state?.originalThinkingLevel ?? current.thinkingLevel,
+            lastAppliedThinkingLevel: thinking,
+            pinned: this.state?.pinned === true || reason === "refusal",
+        };
+        this.deps.logger.info("fallback_applied", { from, to, chainKey: candidate.chainKey, reason });
+        this.deps.emit({ type: "retry_fallback_applied", from, to, chainKey: candidate.chainKey, reason });
+        return true;
+    }
+    nextCandidate(reserve = true) {
+        const settings = this.deps.getSettings();
+        const current = this.deps.getCurrentSelector();
+        if (!settings.modelFallback || !current)
+            return undefined;
+        const chains = canonicalizeFallbackChains(settings.chains, this.deps.registry);
+        const chainKey = resolveChainKey(current.model, current.thinkingLevel, chains) ?? this.state?.chainKey;
+        const entries = chainKey ? chains[chainKey] : undefined;
+        if (!chainKey || !entries) {
+            if (reserve)
+                this.deps.logger.debug("no_chain", { selector: formatSelector(current.model) });
+            return undefined;
+        }
+        for (const raw of candidatesAfter(entries, formatSelector(current.model, current.thinkingLevel))) {
+            const selector = parseFallbackSelector(raw, this.deps.registry);
+            if (!selector) {
+                this.skip(raw, "unknown");
+                continue;
+            }
+            if (selector.provider === current.model.provider && selector.id === current.model.id) {
+                this.skip(raw, "self");
+                continue;
+            }
+            const base = baseSelector(selector);
+            if (this.triedSelectors.has(base)) {
+                this.skip(raw, "tried");
+                continue;
+            }
+            if (this.deps.cooldowns.isSuppressed(base)) {
+                this.skip(raw, "suppressed");
+                continue;
+            }
+            if (!this.deps.isAuthAvailable(selector.provider)) {
+                this.skip(raw, "unauthenticated");
+                continue;
+            }
+            const model = this.deps.registry.find(selector.provider, selector.id);
+            if (!model) {
+                this.skip(raw, "unknown");
+                continue;
+            }
+            if (reserve)
+                this.triedSelectors.add(base);
+            return { chainKey, selector, model };
+        }
+        this.lastExhaustedChainKey = chainKey;
+        if (reserve)
+            this.deps.logger.info("candidates_exhausted", { chainKey });
+        return undefined;
+    }
+    selectThinking(selector, model, inherited) {
+        const requested = selector.thinkingLevel ?? inherited ?? "off";
+        const supported = getSupportedThinkingLevels(model);
+        return supported.includes(requested) ? requested : (supported[supported.length - 1] ?? "off");
+    }
+    skip(candidate, skipReason) {
+        this.deps.logger.debug("candidate_skipped", { candidate, skipReason });
+    }
+}
+//# sourceMappingURL=controller.js.map

package/dist/core/retry-fallback/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../../src/core/retry-fallback/controller.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { Api, Model } from \"@earendil-works/pi-ai\";\nimport { getSupportedThinkingLevels } from \"../thinking-levels.ts\";\nimport {\n\tbaseSelector,\n\tcandidatesAfter,\n\tcanonicalizeFallbackChains,\n\ttype FallbackSelector,\n\tformatSelector,\n\tparseFallbackSelector,\n\tresolveChainKey,\n} from \"./chains.ts\";\nimport type { SelectorCooldowns } from \"./cooldown.ts\";\nimport type { FallbackLogger } from \"./log.ts\";\n\nexport interface ActiveFallbackState {\n\tchainKey: string;\n\toriginalSelector: string;\n\toriginalThinkingLevel?: ThinkingLevel;\n\tlastAppliedThinkingLevel?: ThinkingLevel;\n\tpinned: boolean;\n}\n\ntype FallbackReason = \"transient\" | \"refusal\" | \"hard-error\";\n\ninterface FallbackSettings {\n\tmodelFallback: boolean;\n\tchains: Readonly<Record<string, readonly string[]>>;\n}\n\nexport interface RetryFallbackControllerDeps {\n\tgetSettings(): FallbackSettings;\n\tregistry: { find(provider: string, id: string): Model<Api> | undefined; getAll(): Model<Api>[] };\n\tcooldowns: SelectorCooldowns;\n\tlogger: FallbackLogger;\n\tswitchModel(model: Model<Api>, thinking: ThinkingLevel, reason: \"fallback\" | \"fallback-revert\"): Promise<void>;\n\temit(\n\t\tevent:\n\t\t\t| {\n\t\t\t\t\ttype: \"retry_fallback_applied\";\n\t\t\t\t\tfrom: string;\n\t\t\t\t\tto: string;\n\t\t\t\t\tchainKey: string;\n\t\t\t\t\treason: FallbackReason;\n\t\t\t  }\n\t\t\t| { type: \"retry_fallback_reverted\"; from: string; to: string },\n\t): void;\n\tgetCurrentSelector(): { model: Model<Api>; thinkingLevel?: ThinkingLevel } | undefined;\n\tisAuthAvailable(provider: string): boolean;\n}\n\nexport class RetryFallbackController {\n\tprivate readonly deps: RetryFallbackControllerDeps;\n\tprivate readonly triedSelectors = new Set<string>();\n\tprivate state: ActiveFallbackState | undefined;\n\tprivate lastExhaustedChainKey: string | undefined;\n\n\tconstructor(deps: RetryFallbackControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\tget activeState(): Readonly<ActiveFallbackState> | undefined {\n\t\treturn this.state;\n\t}\n\n\tget exhaustedChainKey(): string | undefined {\n\t\treturn this.lastExhaustedChainKey;\n\t}\n\n\tresetTurn(): void {\n\t\tthis.triedSelectors.clear();\n\t\tthis.lastExhaustedChainKey = undefined;\n\t}\n\n\tclear(): void {\n\t\tthis.state = undefined;\n\t\tthis.resetTurn();\n\t}\n\n\tcanTryFallback(): boolean {\n\t\treturn this.nextCandidate(false) !== undefined;\n\t}\n\n\t/**\n\t * Revert to the chain's original model at a turn boundary. Only fires for\n\t * unpinned state under the cooldown-expiry policy once the original selector\n\t * is no longer suppressed and is still usable; pinned (refusal) state and the\n\t * \"never\" policy always hold the fallback model.\n\t */\n\tasync maybeRestorePrimary(revertPolicy: \"cooldown-expiry\" | \"never\"): Promise<boolean> {\n\t\tconst state = this.state;\n\t\tif (!state || state.pinned || revertPolicy !== \"cooldown-expiry\") return false;\n\t\tif (this.deps.cooldowns.isSuppressed(state.originalSelector)) return false;\n\t\tconst selector = parseFallbackSelector(state.originalSelector, this.deps.registry);\n\t\tif (!selector || !this.deps.isAuthAvailable(selector.provider)) return false;\n\t\tconst model = this.deps.registry.find(selector.provider, selector.id);\n\t\tconst current = this.deps.getCurrentSelector();\n\t\tif (!model || !current) return false;\n\t\t// User override wins: only restore the original thinking level when the\n\t\t// current level still equals the level the fallback switch applied. A manual\n\t\t// setThinkingLevel clears lastAppliedThinkingLevel (see noteManualThinkingLevel).\n\t\tconst thinking =\n\t\t\tcurrent.thinkingLevel === state.lastAppliedThinkingLevel\n\t\t\t\t? (state.originalThinkingLevel ?? current.thinkingLevel ?? \"off\")\n\t\t\t\t: (current.thinkingLevel ?? \"off\");\n\t\tawait this.deps.switchModel(model, thinking, \"fallback-revert\");\n\t\tconst from = formatSelector(current.model);\n\t\tthis.state = undefined;\n\t\tthis.deps.logger.info(\"fallback_reverted\", { from, to: state.originalSelector });\n\t\tthis.deps.emit({ type: \"retry_fallback_reverted\", from, to: state.originalSelector });\n\t\treturn true;\n\t}\n\n\t/**\n\t * A user-driven setThinkingLevel makes the current level a deliberate choice,\n\t * so the revert restore-rule must no longer treat it as fallback-applied.\n\t */\n\tnoteManualThinkingLevel(): void {\n\t\tif (this.state) this.state.lastAppliedThinkingLevel = undefined;\n\t}\n\n\t/** A user-driven model change abandons the fallback window entirely. */\n\tclearForManualModelChange(model: Model<Api>): void {\n\t\tif (this.state) {\n\t\t\tthis.deps.logger.info(\"fallback_cleared_manual\", { selector: formatSelector(model) });\n\t\t}\n\t\tthis.state = undefined;\n\t\tthis.deps.cooldowns.clear(formatSelector(model));\n\t}\n\n\tasync tryFallback(\n\t\treason: FallbackReason,\n\t\tfailure: { errorMessage?: string; retryAfterMs?: number },\n\t): Promise<boolean> {\n\t\tconst current = this.deps.getCurrentSelector();\n\t\tconst candidate = this.nextCandidate();\n\t\tif (!current || !candidate) return false;\n\t\tconst currentBase = formatSelector(current.model);\n\t\tif (reason === \"transient\" || reason === \"hard-error\") {\n\t\t\tthis.deps.cooldowns.note(currentBase, failure);\n\t\t\tthis.deps.logger.info(\"cooldown_noted\", { selector: currentBase, errorMessage: failure.errorMessage });\n\t\t}\n\n\t\tconst thinking = this.selectThinking(candidate.selector, candidate.model, current.thinkingLevel);\n\t\tawait this.deps.switchModel(candidate.model, thinking, \"fallback\");\n\t\tconst from = formatSelector(current.model);\n\t\tconst to = formatSelector(candidate.model);\n\t\tthis.state = {\n\t\t\tchainKey: candidate.chainKey,\n\t\t\toriginalSelector: this.state?.originalSelector ?? from,\n\t\t\toriginalThinkingLevel: this.state?.originalThinkingLevel ?? current.thinkingLevel,\n\t\t\tlastAppliedThinkingLevel: thinking,\n\t\t\tpinned: this.state?.pinned === true || reason === \"refusal\",\n\t\t};\n\t\tthis.deps.logger.info(\"fallback_applied\", { from, to, chainKey: candidate.chainKey, reason });\n\t\tthis.deps.emit({ type: \"retry_fallback_applied\", from, to, chainKey: candidate.chainKey, reason });\n\t\treturn true;\n\t}\n\n\tprivate nextCandidate(\n\t\treserve = true,\n\t): { chainKey: string; selector: FallbackSelector; model: Model<Api> } | undefined {\n\t\tconst settings = this.deps.getSettings();\n\t\tconst current = this.deps.getCurrentSelector();\n\t\tif (!settings.modelFallback || !current) return undefined;\n\t\tconst chains = canonicalizeFallbackChains(settings.chains, this.deps.registry);\n\t\tconst chainKey = resolveChainKey(current.model, current.thinkingLevel, chains) ?? this.state?.chainKey;\n\t\tconst entries = chainKey ? chains[chainKey] : undefined;\n\t\tif (!chainKey || !entries) {\n\t\t\tif (reserve) this.deps.logger.debug(\"no_chain\", { selector: formatSelector(current.model) });\n\t\t\treturn undefined;\n\t\t}\n\t\tfor (const raw of candidatesAfter(entries, formatSelector(current.model, current.thinkingLevel))) {\n\t\t\tconst selector = parseFallbackSelector(raw, this.deps.registry);\n\t\t\tif (!selector) {\n\t\t\t\tthis.skip(raw, \"unknown\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (selector.provider === current.model.provider && selector.id === current.model.id) {\n\t\t\t\tthis.skip(raw, \"self\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst base = baseSelector(selector);\n\t\t\tif (this.triedSelectors.has(base)) {\n\t\t\t\tthis.skip(raw, \"tried\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (this.deps.cooldowns.isSuppressed(base)) {\n\t\t\t\tthis.skip(raw, \"suppressed\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!this.deps.isAuthAvailable(selector.provider)) {\n\t\t\t\tthis.skip(raw, \"unauthenticated\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst model = this.deps.registry.find(selector.provider, selector.id);\n\t\t\tif (!model) {\n\t\t\t\tthis.skip(raw, \"unknown\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (reserve) this.triedSelectors.add(base);\n\t\t\treturn { chainKey, selector, model };\n\t\t}\n\t\tthis.lastExhaustedChainKey = chainKey;\n\t\tif (reserve) this.deps.logger.info(\"candidates_exhausted\", { chainKey });\n\t\treturn undefined;\n\t}\n\n\tprivate selectThinking(\n\t\tselector: FallbackSelector,\n\t\tmodel: Model<Api>,\n\t\tinherited: ThinkingLevel | undefined,\n\t): ThinkingLevel {\n\t\tconst requested = selector.thinkingLevel ?? inherited ?? \"off\";\n\t\tconst supported = getSupportedThinkingLevels(model);\n\t\treturn supported.includes(requested) ? requested : (supported[supported.length - 1] ?? \"off\");\n\t}\n\n\tprivate skip(candidate: string, skipReason: string): void {\n\t\tthis.deps.logger.debug(\"candidate_skipped\", { candidate, skipReason });\n\t}\n}\n"]}

package/dist/core/retry-fallback/cooldown.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime-only selector suppression. A SelectorCooldowns instance belongs to one
+ * AgentSession and is deliberately never persisted to settings or session files.
+ * Callers provide canonical base selectors without a thinking suffix.
+ */
+export declare class SelectorCooldowns {
+    private readonly expiresAtBySelector;
+    private readonly now;
+    private readonly random;
+    constructor(now: () => number, random?: () => number);
+    note(baseSelector: string, failure: {
+        retryAfterMs?: number;
+        errorMessage?: string;
+    }): void;
+    isSuppressed(baseSelector: string): boolean;
+    clear(baseSelector: string): void;
+    clearAll(): void;
+    private durationFor;
+    private capacityJitterMs;
+}
+//# sourceMappingURL=cooldown.d.ts.map

package/dist/core/retry-fallback/cooldown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.d.ts","sourceRoot":"","sources":["../../../src/core/retry-fallback/cooldown.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,YAAY,GAAG,EAAE,MAAM,MAAM,EAAE,MAAM,GAAE,MAAM,MAAoB,EAGhE;IAED,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAE1F;IAED,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAM1C;IAED,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEhC;IAED,QAAQ,IAAI,IAAI,CAEf;IAED,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,gBAAgB;CAGxB"}

package/dist/core/retry-fallback/cooldown.js

@@ -0,0 +1,49 @@
+/**
+ * Runtime-only selector suppression. A SelectorCooldowns instance belongs to one
+ * AgentSession and is deliberately never persisted to settings or session files.
+ * Callers provide canonical base selectors without a thinking suffix.
+ */
+export class SelectorCooldowns {
+    constructor(now, random = Math.random) {
+        this.expiresAtBySelector = new Map();
+        this.now = now;
+        this.random = random;
+    }
+    note(baseSelector, failure) {
+        this.expiresAtBySelector.set(baseSelector, this.now() + this.durationFor(failure));
+    }
+    isSuppressed(baseSelector) {
+        const expiresAt = this.expiresAtBySelector.get(baseSelector);
+        if (expiresAt === undefined)
+            return false;
+        if (this.now() < expiresAt)
+            return true;
+        this.expiresAtBySelector.delete(baseSelector);
+        return false;
+    }
+    clear(baseSelector) {
+        this.expiresAtBySelector.delete(baseSelector);
+    }
+    clearAll() {
+        this.expiresAtBySelector.clear();
+    }
+    durationFor({ retryAfterMs, errorMessage }) {
+        if (retryAfterMs !== undefined && Number.isFinite(retryAfterMs) && retryAfterMs > 0) {
+            return retryAfterMs;
+        }
+        const message = errorMessage?.toLowerCase() ?? "";
+        if (/usage[- ]limit|quota|insufficient_quota|billing/.test(message))
+            return 30 * 60_000;
+        if (/rate[ -]?limit|429|too many requests/.test(message))
+            return 30_000;
+        if (/overloaded|capacity/.test(message))
+            return 45_000 + this.capacityJitterMs();
+        if (/5xx|\b5\d\d\b|server|internal error/.test(message))
+            return 20_000;
+        return 5 * 60_000;
+    }
+    capacityJitterMs() {
+        return Math.round(Math.min(1, Math.max(0, this.random())) * 30_000);
+    }
+}
+//# sourceMappingURL=cooldown.js.map

package/dist/core/retry-fallback/cooldown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.js","sourceRoot":"","sources":["../../../src/core/retry-fallback/cooldown.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAK7B,YAAY,GAAiB,EAAE,MAAM,GAAiB,IAAI,CAAC,MAAM;QAJhD,wBAAmB,GAAG,IAAI,GAAG,EAAkB,CAAC;QAKhE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,YAAoB,EAAE,OAAyD;QACnF,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,YAAY,CAAC,YAAoB;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC7D,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAAE,OAAO,IAAI,CAAC;QACxC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC;IACd,CAAC;IAED,KAAK,CAAC,YAAoB;QACzB,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED,QAAQ;QACP,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;IAEO,WAAW,CAAC,EAAE,YAAY,EAAE,YAAY,EAAoD;QACnG,IAAI,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrF,OAAO,YAAY,CAAC;QACrB,CAAC;QAED,MAAM,OAAO,GAAG,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAClD,IAAI,iDAAiD,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACxF,IAAI,sCAAsC,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,MAAM,CAAC;QACxE,IAAI,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACjF,IAAI,qCAAqC,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,MAAM,CAAC;QACvE,OAAO,CAAC,GAAG,MAAM,CAAC;IACnB,CAAC;IAEO,gBAAgB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IACrE,CAAC;CACD","sourcesContent":["/**\n * Runtime-only selector suppression. A SelectorCooldowns instance belongs to one\n * AgentSession and is deliberately never persisted to settings or session files.\n * Callers provide canonical base selectors without a thinking suffix.\n */\nexport class SelectorCooldowns {\n\tprivate readonly expiresAtBySelector = new Map<string, number>();\n\tprivate readonly now: () => number;\n\tprivate readonly random: () => number;\n\n\tconstructor(now: () => number, random: () => number = Math.random) {\n\t\tthis.now = now;\n\t\tthis.random = random;\n\t}\n\n\tnote(baseSelector: string, failure: { retryAfterMs?: number; errorMessage?: string }): void {\n\t\tthis.expiresAtBySelector.set(baseSelector, this.now() + this.durationFor(failure));\n\t}\n\n\tisSuppressed(baseSelector: string): boolean {\n\t\tconst expiresAt = this.expiresAtBySelector.get(baseSelector);\n\t\tif (expiresAt === undefined) return false;\n\t\tif (this.now() < expiresAt) return true;\n\t\tthis.expiresAtBySelector.delete(baseSelector);\n\t\treturn false;\n\t}\n\n\tclear(baseSelector: string): void {\n\t\tthis.expiresAtBySelector.delete(baseSelector);\n\t}\n\n\tclearAll(): void {\n\t\tthis.expiresAtBySelector.clear();\n\t}\n\n\tprivate durationFor({ retryAfterMs, errorMessage }: { retryAfterMs?: number; errorMessage?: string }): number {\n\t\tif (retryAfterMs !== undefined && Number.isFinite(retryAfterMs) && retryAfterMs > 0) {\n\t\t\treturn retryAfterMs;\n\t\t}\n\n\t\tconst message = errorMessage?.toLowerCase() ?? \"\";\n\t\tif (/usage[- ]limit|quota|insufficient_quota|billing/.test(message)) return 30 * 60_000;\n\t\tif (/rate[ -]?limit|429|too many requests/.test(message)) return 30_000;\n\t\tif (/overloaded|capacity/.test(message)) return 45_000 + this.capacityJitterMs();\n\t\tif (/5xx|\\b5\\d\\d\\b|server|internal error/.test(message)) return 20_000;\n\t\treturn 5 * 60_000;\n\t}\n\n\tprivate capacityJitterMs(): number {\n\t\treturn Math.round(Math.min(1, Math.max(0, this.random())) * 30_000);\n\t}\n}\n"]}

package/dist/core/retry-fallback/log.d.ts

@@ -0,0 +1,10 @@
+export interface FallbackLogger {
+    debug(event: string, data?: Record<string, unknown>): void;
+    info(event: string, data?: Record<string, unknown>): void;
+    warn(event: string, data?: Record<string, unknown>): void;
+}
+export interface FallbackLoggerOptions {
+    maxBytes?: number;
+}
+export declare function createFallbackLogger(agentDir: string, options?: FallbackLoggerOptions): FallbackLogger;
+//# sourceMappingURL=log.d.ts.map

package/dist/core/retry-fallback/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/core/retry-fallback/log.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,cAAc;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAsB1G"}

package/dist/core/retry-fallback/log.js

@@ -0,0 +1,128 @@
+import { chmodSync, closeSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const MAX_STRING_LENGTH = 200;
+const BLOCKED_KEY = /^(?:__proto__|constructor|prototype|headers?|env(?:ironment)?|authorization|credential(?:s)?|password|secret|token|api_?key|client_?secret)$/i;
+const ALLOWED_DATA_KEY = /^(?:selector|candidate|currentSelector|originalSelector|from|to|model|chainKey|reason|skipReason|classification|thinkingLevel|durationMs|retryAfterMs|error|errorMessage|warning)$/;
+const SENSITIVE_TEXT = /((?:authorization\s*[:=]\s*(?:bearer|basic)\s+)|(?:bearer\s+)|(?:[?&](?:api[_-]?key|token|secret|password|auth(?:orization)?)=))[^\s&,"'}\]]+/gi;
+export function createFallbackLogger(agentDir, options = {}) {
+    const filePath = join(agentDir, "logs", "fallback.log");
+    const maxBytes = validMaxBytes(options.maxBytes);
+    let reportedWriteFailure = false;
+    function log(level, event, data) {
+        try {
+            const line = formatLine(level, event, data);
+            writeLine(filePath, line, maxBytes);
+        }
+        catch (error) {
+            if (!reportedWriteFailure) {
+                reportedWriteFailure = true;
+                console.error("Unable to write retry fallback debug log", error);
+            }
+        }
+    }
+    return {
+        debug: (event, data) => log("debug", event, data),
+        info: (event, data) => log("info", event, data),
+        warn: (event, data) => log("warn", event, data),
+    };
+}
+function validMaxBytes(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : DEFAULT_MAX_BYTES;
+}
+function formatLine(level, event, data) {
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+        event: safeText(event),
+    };
+    if (data !== undefined) {
+        for (const [key, value] of safeEntries(data)) {
+            if (ALLOWED_DATA_KEY.test(key) && !BLOCKED_KEY.test(key)) {
+                const safeValue = serializeValue(value, new WeakSet());
+                if (safeValue !== undefined)
+                    entry[key] = safeValue;
+            }
+        }
+    }
+    return JSON.stringify(entry);
+}
+function writeLine(filePath, line, maxBytes) {
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const text = `${line}\n`;
+    if (fileExceedsCap(filePath, Buffer.byteLength(text), maxBytes)) {
+        rmSync(`${filePath}.1`, { force: true });
+        renameSync(filePath, `${filePath}.1`);
+        chmodSync(`${filePath}.1`, 0o600);
+    }
+    const descriptor = openSync(filePath, "a", 0o600);
+    try {
+        writeSync(descriptor, text);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    chmodSync(filePath, 0o600);
+}
+function fileExceedsCap(filePath, incomingBytes, maxBytes) {
+    try {
+        return statSync(filePath).size + incomingBytes > maxBytes;
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return false;
+        throw error;
+    }
+}
+function isMissingFileError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function serializeValue(value, seen) {
+    if (typeof value === "string")
+        return safeText(value);
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" || typeof value === "boolean" || value === null)
+        return value;
+    if (typeof value === "undefined")
+        return undefined;
+    if (typeof value === "function" || typeof value === "symbol")
+        return String(value);
+    if (seen.has(value))
+        return "[Circular]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => serializeValue(item, seen) ?? null);
+    const result = {};
+    for (const [key, item] of safeEntries(value)) {
+        if (!BLOCKED_KEY.test(key)) {
+            const safeValue = serializeValue(item, seen);
+            if (safeValue !== undefined)
+                result[key] = safeValue;
+        }
+    }
+    return result;
+}
+function safeEntries(value) {
+    try {
+        const entries = [];
+        for (const key of Object.keys(value)) {
+            try {
+                const item = Reflect.get(value, key);
+                entries.push([key, item]);
+            }
+            catch {
+                entries.push([key, "[Unreadable]"]);
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [["unserializable", "[Unreadable]"]];
+    }
+}
+function safeText(value) {
+    const redacted = value.replace(SENSITIVE_TEXT, "$1[redacted]");
+    return redacted.length <= MAX_STRING_LENGTH ? redacted : `${redacted.slice(0, MAX_STRING_LENGTH - 3)}...`;
+}
+//# sourceMappingURL=log.js.map