@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/session/default-model-selection.ts

@@ -0,0 +1,93 @@
+import type { ResolvedThinkingLevel } from "@gajae-code/agent-core";
+import { isRecord } from "@gajae-code/utils";
+
+export type DefaultModelSelectionRollbackStage = "durable" | "session" | "live";
+
+export const DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE =
+	"Default model selection could not be completed after durable selection.";
+
+export type DefaultModelSelectionRecovery = {
+	readonly message: string;
+	readonly rollback: {
+		readonly disposition: "restored" | "partial" | "unknown";
+		readonly failures: readonly {
+			readonly stage: DefaultModelSelectionRollbackStage;
+			readonly message: string;
+		}[];
+	};
+};
+
+export interface DefaultModelSelectionResult {
+	readonly provider: string;
+	readonly modelId: string;
+	readonly thinkingLevel: ResolvedThinkingLevel;
+}
+
+const recoveryMessages: Readonly<
+	Record<DefaultModelSelectionRollbackStage, { readonly fallback: string; readonly allowed: ReadonlySet<string> }>
+> = {
+	durable: {
+		fallback: "Durable default selection recovery could not be completed.",
+		allowed: new Set([
+			"A newer default selection prevented durable recovery.",
+			"Durable default selection recovery could not be completed.",
+		]),
+	},
+	session: {
+		fallback: "Session replacement recovery could not be completed.",
+		allowed: new Set([
+			"Session replacement recovery could not be completed.",
+			"Session replacement outcome could not be determined.",
+		]),
+	},
+	live: {
+		fallback: "Live model publication could not be completed.",
+		allowed: new Set(["Live model publication could not be completed."]),
+	},
+};
+
+export function parseDefaultModelSelectionRecovery(value: unknown): DefaultModelSelectionRecovery | undefined {
+	if (!isRecord(value)) return undefined;
+	if (typeof value.message !== "string" || !value.message.trim()) return undefined;
+	if (!isRecord(value.rollback)) return undefined;
+	const disposition = value.rollback.disposition;
+	if (disposition !== "restored" && disposition !== "partial" && disposition !== "unknown") return undefined;
+	if (!Array.isArray(value.rollback.failures) || value.rollback.failures.length > 3) return undefined;
+
+	const seenStages = new Set<DefaultModelSelectionRollbackStage>();
+	const failures: DefaultModelSelectionRecovery["rollback"]["failures"][number][] = [];
+	for (const failure of value.rollback.failures) {
+		if (!isRecord(failure)) return undefined;
+		const stage = failure.stage;
+		if (
+			(stage !== "durable" && stage !== "session" && stage !== "live") ||
+			typeof failure.message !== "string" ||
+			!failure.message.trim() ||
+			seenStages.has(stage)
+		)
+			return undefined;
+		seenStages.add(stage);
+		const messages = recoveryMessages[stage];
+		failures.push({
+			stage,
+			message: messages.allowed.has(failure.message) ? failure.message : messages.fallback,
+		});
+	}
+
+	return { message: DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE, rollback: { disposition, failures } };
+}
+
+export class DefaultModelSelectionRecoveryError extends Error {
+	readonly name = "DefaultModelSelectionRecoveryError";
+	readonly code = "default_model_selection_recovery";
+	readonly recovery: DefaultModelSelectionRecovery;
+
+	constructor(_message: string, recovery: DefaultModelSelectionRecovery) {
+		const publicRecovery = parseDefaultModelSelectionRecovery(recovery) ?? {
+			message: DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE,
+			rollback: { disposition: "unknown" as const, failures: [] },
+		};
+		super(publicRecovery.message);
+		this.recovery = publicRecovery;
+	}
+}

package/src/session/fallback-chain-controller.ts

@@ -0,0 +1,136 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+
+/** Immutable configured fallback intent. Transient attempt state never belongs here. */
+export interface ConfiguredFallbackChain {
+	role: string;
+	entries: readonly string[];
+	origin: string;
+	identity?: string;
+	explicitHead: boolean;
+}
+
+export interface FallbackFailure {
+	selector: string;
+	triggerClass: FallbackTriggerClass;
+	reason: string;
+}
+
+export type FallbackFailureResult = "retry" | "advance" | "exhausted";
+
+/**
+ * In-memory policy state for one fallback-chain scope. A controller is deliberately
+ * not serializable: configured chain intent is durable, current position is not.
+ */
+export class FallbackChainController {
+	readonly chain: ConfiguredFallbackChain;
+	readonly maxAttempts: number;
+	activeIndex = 0;
+	attemptsUsed = 0;
+	tried: FallbackFailure[] = [];
+	#attemptStarted = false;
+	skips: Array<{ selector: string; reason: string }> = [];
+	exhaustedForTurn = false;
+
+	constructor(chain: ConfiguredFallbackChain, maxAttempts: number) {
+		if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+			throw new Error("fallback.maxAttempts must be a positive integer");
+		}
+		this.chain = { ...chain, entries: [...chain.entries] };
+		this.maxAttempts = maxAttempts;
+		if (this.chain.entries.length === 0) this.exhaustedForTurn = true;
+	}
+
+	currentSelector(): string | undefined {
+		return this.chain.entries[this.activeIndex];
+	}
+
+	onResolutionSkip(reason: string): boolean {
+		const selector = this.currentSelector();
+		if (selector) this.skips.push({ selector, reason });
+		return this.advance();
+	}
+
+	/** Charge an upstream request at its concrete transport boundary. */
+	onAttemptStarted(): void {
+		if (!this.currentSelector() || this.exhaustedForTurn) return;
+		this.attemptsUsed += 1;
+		this.#attemptStarted = true;
+	}
+
+	/** Start a logically new request without losing its sticky selected entry. */
+	resetAttemptBudget(): void {
+		this.attemptsUsed = 0;
+		this.tried = [];
+		this.#attemptStarted = false;
+	}
+
+	/** Seed a controller from auth-aware resolution without charging requests. */
+	seedResolution(activeIndex: number, skips: Array<{ selector: string; reason: string }>): void {
+		this.activeIndex = Math.min(Math.max(0, activeIndex), this.chain.entries.length);
+		this.skips = [...skips];
+		this.attemptsUsed = 0;
+		this.#attemptStarted = false;
+		this.exhaustedForTurn = this.activeIndex >= this.chain.entries.length;
+	}
+
+	onAttemptFailure(triggerClass: FallbackTriggerClass, reason: string): FallbackFailureResult {
+		const selector = this.currentSelector();
+		if (!selector || this.exhaustedForTurn) return "exhausted";
+		if (!this.#attemptStarted) this.attemptsUsed += 1;
+		this.#attemptStarted = false;
+		this.tried.push({ selector, triggerClass, reason });
+		if (this.attemptsUsed < this.maxAttempts) return "retry";
+		return this.advance() ? "advance" : "exhausted";
+	}
+
+	advance(): boolean {
+		if (this.exhaustedForTurn) return false;
+		this.activeIndex += 1;
+		this.attemptsUsed = 0;
+		this.#attemptStarted = false;
+		if (this.activeIndex >= this.chain.entries.length) {
+			this.exhaustedForTurn = true;
+			return false;
+		}
+		return true;
+	}
+
+	isExhausted(): boolean {
+		return this.exhaustedForTurn;
+	}
+
+	resetForNewTurn(): void {
+		this.resetSticky();
+	}
+
+	resetSticky(): void {
+		this.activeIndex = 0;
+		this.attemptsUsed = 0;
+		this.tried = [];
+		this.skips = [];
+		this.exhaustedForTurn = this.chain.entries.length === 0;
+		this.#attemptStarted = false;
+	}
+}
+
+export function cappedExponentialWithFullJitter(
+	baseDelayMs: number,
+	maxDelayMs: number,
+	attemptK: number,
+	random: () => number = Math.random,
+): number {
+	const exponential = baseDelayMs * 2 ** Math.max(0, attemptK - 1);
+	const cap = maxDelayMs > 0 ? Math.min(exponential, maxDelayMs) : exponential;
+	return Math.floor(Math.max(0, cap) * Math.max(0, Math.min(1, random())));
+}
+
+/** Retry-After is intentionally uncapped. */
+export function effectiveFallbackDelay(
+	baseDelayMs: number,
+	maxDelayMs: number,
+	attemptK: number,
+	retryAfterMs: number | undefined,
+	random: () => number = Math.random,
+): number {
+	return Math.max(cappedExponentialWithFullJitter(baseDelayMs, maxDelayMs, attemptK, random), retryAfterMs ?? 0);
+}