@mastra/code-sdk 1.7.3-alpha.0 → 1.8.0-alpha.10

package/dist/auth/account-rotation-processor.js

@@ -0,0 +1,669 @@
+import { getOAuthProviders } from "./storage.js";
+import { ProviderAuthRequiredError } from "./provider-auth-error.js";
+import { resolveModePackFallbackChain } from "../onboarding/packs.js";
+import { findModePackForModel, loadSettings, resolveModePackModels } from "../onboarding/settings.js";
+import { resolveCredentialStore } from "../agents/credential-resolver.js";
+import { getRequestAccountSelection, markRequestAccountRoutingExhausted, setRequestAccountSelection } from "./account-routing-context.js";
+import { listResolvableModePacks, resolveModel, resolveRequestThinkingLevel } from "../agents/model.js";
+import { TripWire } from "@mastra/core/agent";
+//#region src/auth/account-rotation-processor.ts
+/**
+* Error-driven rotation across a provider's OAuth account registry.
+*
+* When the active account cannot serve a request (rate limit, quota
+* exhaustion, dead token, persistent outage), the next account in insertion
+* order is selected for the request and the request retried. OAuth fetch
+* wrappers read that request-scoped selection on every HTTP attempt, so
+* concurrent runs can't swap each other's credentials. Every switch is
+* persisted as a non-transient `data-mastracode-account-switch` part so it
+* shows in the transcript and survives history reload.
+*
+* Two classes, two lanes — the split is load-bearing. The processor runner
+* walks `[...inputProcessors, ...outputProcessors, ...errorProcessors]` when
+* running `processAPIError`, so a processor registered in the input lane that
+* also implemented `processAPIError` would run BEFORE
+* `StreamErrorRetryProcessor` and hop on 5xx errors before transient retries
+* had a chance. `AccountRotationProcessor` therefore implements
+* `processAPIError` only and is registered in `errorProcessors` after
+* `StreamErrorRetryProcessor`; `AccountStartNoticeProcessor` implements
+* `processInput` only and is registered in `inputProcessors`.
+*/
+const ACCOUNT_SWITCH_PART_TYPE = "data-mastracode-account-switch";
+/** Rotatable providers = the OAuth provider registry; API-key-only providers never rotate. */
+const KNOWN_PROVIDER_IDS = new Set(getOAuthProviders().map((provider) => provider.id));
+/** Hostname suffixes → provider ids, for `APICallError.url`. */
+const PROVIDER_HOST_PATTERNS = [
+	[/(^|\.)api\.anthropic\.com$/i, "anthropic"],
+	[/(^|\.)api\.kimi\.com$/i, "kimi-for-coding"],
+	[/(^|\.)api\.x\.ai$/i, "xai"],
+	[/(^|\.)chatgpt\.com$/i, "openai-codex"],
+	[/(^|\.)backend-api\.codex\.ai$/i, "openai-codex"],
+	[/(^|\.)githubcopilot\.com$/i, "github-copilot"],
+	[/(^|\.)api\.github\.com$/i, "github-copilot"]
+];
+/**
+* Provider usage/quota-limit wording (locked Q7 bucket 1). Statuses 429/402
+* are matched before this; some providers deliver quota errors as plain 400s,
+* which only the message reveals. Deliberately restricted to unambiguous
+* quota phrases — a generic "exceeded your … limit" can appear on non-quota
+* client errors (request size, context length) that must never rotate.
+*/
+const USAGE_LIMIT_MESSAGE_PATTERN = /usage (?:limit|cap)|insufficient[_ ]quota|quota (?:exceeded|exhausted|reached)|exceeded (?:your )?current quota|insufficient (?:balance|credits?)|credits? exhausted|rate limit (?:exceeded|reached)|weekly limit|monthly limit/i;
+const NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"EPIPE",
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"ETIMEDOUT",
+	"EAI_AGAIN",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_SOCKET"
+]);
+const NETWORK_MESSAGE_PATTERN = /fetch failed|network error|socket hang up|getaddrinfo|econnrefused|enotfound|etimedout|connection (?:refused|reset|closed|timed out)|other side closed|write epipe/i;
+const MAX_CAUSE_DEPTH = 4;
+/** Persisted data-part type for a fallback-pack hop. */
+const PACK_FALLBACK_PART_TYPE = "data-mastracode-pack-fallback";
+/**
+* Session-state key the processor sets when a pack hop happens. The TUI
+* listens for it on the typed `state_changed` controller event (data parts
+* never ride controller message events) and applies thread stickiness.
+*/
+const PACK_FALLBACK_STATE_KEY = "mastracodePendingPackFallback";
+function isErrorWithCode(error) {
+	return typeof error === "object" && error !== null && "code" in error;
+}
+function readErrorStatus(error) {
+	let current = error;
+	for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) {
+		if (typeof current !== "object") break;
+		const { statusCode, status } = current;
+		if (typeof statusCode === "number") return statusCode;
+		if (typeof status === "number") return status;
+		current = current.cause;
+	}
+}
+function isProviderAuthRequiredError(error) {
+	let current = error;
+	for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) {
+		if (current instanceof ProviderAuthRequiredError || current instanceof Error && current.name === "ProviderAuthRequiredError") return true;
+		if (typeof current !== "object") break;
+		current = current.cause;
+	}
+	return false;
+}
+/** Concatenate the error's message with its cause chain (bounded). */
+function collectErrorText(error) {
+	const parts = [];
+	let current = error;
+	for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) if (current instanceof Error) {
+		parts.push(current.message);
+		current = current.cause;
+	} else if (typeof current === "object" && "message" in current) {
+		const message = current.message;
+		if (typeof message === "string") parts.push(message);
+		current = current.cause;
+	} else break;
+	return parts.join(" | ");
+}
+function isNetworkErrorLike(error) {
+	let current = error;
+	for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) {
+		if (isErrorWithCode(current) && typeof current.code === "string" && NETWORK_ERROR_CODES.has(current.code.toUpperCase())) return true;
+		if (current instanceof Error) {
+			if (NETWORK_MESSAGE_PATTERN.test(current.message)) return true;
+			current = current.cause;
+		} else if (typeof current === "object") current = current.cause;
+		else break;
+	}
+	return false;
+}
+/**
+* The locked Q7 taxonomy. 429/402/usage-limit rotate immediately (429 is not
+* covered by any transient matcher, so it arrives here on first occurrence);
+* 401/403 and `ProviderAuthRequiredError` rotate after one forced refresh;
+* 5xx/network hop only when the transient retry budget is already spent (they
+* reach this processor because `StreamErrorRetryProcessor` declined); 400 and
+* everything unknown never touch the registry.
+*/
+function classifyRotationError(error) {
+	if (isProviderAuthRequiredError(error)) return {
+		kind: "rotate",
+		reason: "auth-failed"
+	};
+	const status = readErrorStatus(error);
+	if (status === 429) return {
+		kind: "rotate",
+		reason: "rate-limit"
+	};
+	if (status === 402) return {
+		kind: "rotate",
+		reason: "quota-exhausted"
+	};
+	if (status === 401 || status === 403) return {
+		kind: "rotate",
+		reason: "auth-failed"
+	};
+	if (status !== void 0 && status >= 500 && status < 600) return { kind: "hop" };
+	if (status === void 0 || status === 400) {
+		if (USAGE_LIMIT_MESSAGE_PATTERN.test(collectErrorText(error))) return {
+			kind: "rotate",
+			reason: "quota-exhausted"
+		};
+	}
+	if (isNetworkErrorLike(error)) return { kind: "hop" };
+	return { kind: "never" };
+}
+/** Provider id off a router model id: `mastracode/<provider>/<model>` or `<provider>/<model>`. */
+function providerFromModelId(modelId) {
+	const providerId = modelId.replace(/^mastracode\//, "").split("/")[0];
+	if (providerId === "openai") return "openai-codex";
+	return providerId && KNOWN_PROVIDER_IDS.has(providerId) ? providerId : void 0;
+}
+function providerFromHost(hostname) {
+	for (const [pattern, providerId] of PROVIDER_HOST_PATTERNS) if (pattern.test(hostname)) return providerId;
+}
+/**
+* Identify the provider an error came from: the request URL's hostname
+* (`APICallError.url`, cause chain included), falling back to the router
+* model id. Unknown → undefined (caller treats as never-rotate).
+*/
+function providerFromError(error) {
+	const causeChain = [];
+	let current = error;
+	for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth++) {
+		if (typeof current !== "object") break;
+		causeChain.push(current);
+		current = current.cause;
+	}
+	for (const item of causeChain) {
+		const urls = [
+			item.url,
+			item.requestURL,
+			item.requestUrl
+		];
+		for (const url of urls) {
+			if (typeof url !== "string") continue;
+			try {
+				const providerId = providerFromHost(new URL(url).hostname);
+				if (providerId) return providerId;
+			} catch {}
+		}
+	}
+	for (const item of causeChain) {
+		const modelId = item.modelId;
+		if (typeof modelId !== "string") continue;
+		const providerId = providerFromModelId(modelId);
+		if (providerId) return providerId;
+	}
+}
+function getTriedInstances(state) {
+	const existing = state.triedInstances;
+	if (existing instanceof Set) return existing;
+	const created = /* @__PURE__ */ new Set();
+	state.triedInstances = created;
+	return created;
+}
+function getForcedRefreshInstances(state) {
+	const existing = state.forcedAuthRefresh;
+	if (existing instanceof Set) return existing;
+	const created = /* @__PURE__ */ new Set();
+	state.forcedAuthRefresh = created;
+	return created;
+}
+/** Friendly names for the part/notice copy (display only — never auth data). */
+const PROVIDER_DISPLAY_NAMES = {
+	anthropic: "Anthropic",
+	"kimi-for-coding": "Kimi",
+	"openai-codex": "Codex",
+	"github-copilot": "GitHub Copilot",
+	xai: "xAI"
+};
+const REASON_TEXT = {
+	"rate-limit": "rate limit",
+	"quota-exhausted": "quota exhausted",
+	"auth-failed": "auth failed",
+	"pool-exhausted": "pool exhausted",
+	"persistent-outage": "persistent outage",
+	"preferred-routing": "subscription routing"
+};
+/** Validates untrusted `reason` values (e.g. persisted message parts). */
+function isAccountSwitchReason(value) {
+	return value === "starting-on-account" || typeof value === "string" && Object.prototype.hasOwnProperty.call(REASON_TEXT, value);
+}
+/**
+* One-line transcript copy for a switch part. Shared by the live `info`
+* controller event (the TUI shows controller `info` events as transcript
+* lines, and no message event carries data parts mid-run) and by the TUI's
+* history rendering of the persisted part — one formatter, identical text.
+*/
+function accountSwitchNoticeText(data) {
+	const provider = PROVIDER_DISPLAY_NAMES[data.provider] ?? data.provider;
+	if (data.reason === "starting-on-account" && data.to) return `Starting on ${provider} account: ${data.to.label}`;
+	const reason = data.reason === "starting-on-account" ? data.reason : REASON_TEXT[data.reason];
+	if (data.to === null) {
+		if (data.exclusive) return `Pinned ${provider} account unavailable (${reason})`;
+		return `All ${provider} accounts unavailable (${reason})`;
+	}
+	return `Switched ${provider} account: ${data.from?.label ?? "unknown"} → ${data.to.label} (${reason})`;
+}
+/** Transcript line for a pack-fallback hop; shared by the live info event and the TUI's history render. */
+function packFallbackNoticeText(data) {
+	const reason = REASON_TEXT[data.reason] ?? data.reason;
+	return `Switched model pack: ${data.from.label} → ${data.to.label} (${reason})`;
+}
+/**
+* Whether a persisted pack-fallback reason is one this build understands.
+* `REASON_TEXT` also covers the account-switch reasons, so the notice text
+* alone would happily render a foreign value such as `rate-limit` as a
+* pack-fallback reason; history parsed from another build's part must be
+* rejected instead.
+*/
+function isPackFallbackReason(value) {
+	return value === "pool-exhausted" || value === "persistent-outage";
+}
+async function emitAccountSwitchPart(args, data) {
+	await args.writer?.custom({
+		type: ACCOUNT_SWITCH_PART_TYPE,
+		data
+	});
+	(args.requestContext?.get("controller"))?.emitEvent?.({
+		type: "info",
+		message: accountSwitchNoticeText(data)
+	});
+}
+/**
+* Provider of the model the controller session is currently running — the
+* fallback identification path for errors that carry neither a request URL
+* nor a model id (e.g. `ProviderAuthRequiredError` thrown by a fetch wrapper
+* before any HTTP request exists).
+*/
+function providerFromSession(args) {
+	const modelId = (args.requestContext?.get("controller"))?.session?.modelId;
+	return typeof modelId === "string" ? providerFromModelId(modelId) : void 0;
+}
+function getRoutingController(args) {
+	return args.requestContext?.get("controller");
+}
+/**
+* A12: the account a pack/model route targets, or `undefined` when the route
+* is `Automatic` (no entry — insertion order, full pool rotation).
+*
+* A targeted route is *exclusive*: only that account may serve the route, so
+* rotation must never spill the request onto a sibling subscription's quota.
+* A heavy model on one subscription can burn that subscription's quota in
+* hours; spilling it into a second subscription defeats the point of having
+* one.
+*/
+function getRouteTargetAccountId(settingsPath, route) {
+	if (!route) return void 0;
+	return loadSettings(settingsPath).models.packAccountPreferences?.[route.packId]?.[route.modelId];
+}
+function getRequestActiveAccount(args, store, providerId) {
+	const selectedId = getRequestAccountSelection(args.requestContext, providerId);
+	return (selectedId ? store.listAccounts?.(providerId).find((account) => account.id === selectedId) : void 0) ?? store.getActiveAccount?.(providerId) ?? store.listAccounts?.(providerId).find((account) => account.active);
+}
+function resolveAccountRoute(args, settingsPath, explicit) {
+	const controller = getRoutingController(args);
+	const state = controller?.getState?.();
+	const pending = state?.mastracodePendingPackFallback;
+	const pendingMatchesThread = pending && typeof pending.toPackId === "string" && typeof pending.toModelId === "string" && (pending.threadId === void 0 || pending.threadId === controller?.threadId);
+	const resolvedModelId = explicit?.modelId ?? (pendingMatchesThread ? pending.toModelId : void 0) ?? (typeof controller?.session?.modelId === "string" ? controller.session.modelId : void 0);
+	if (typeof resolvedModelId !== "string" || resolvedModelId.length === 0) return null;
+	const modelId = resolvedModelId;
+	const settings = loadSettings(settingsPath);
+	const packs = listResolvableModePacks(settings);
+	const modeId = typeof controller?.session?.modeId === "string" && controller.session.modeId.length > 0 ? controller.session.modeId : "build";
+	const explicitPackId = explicit?.packId ?? (pendingMatchesThread ? pending.toPackId : void 0) ?? (typeof state?.activeModelPackId === "string" ? state.activeModelPackId : settings.models.activeModelPackId);
+	const pack = explicitPackId ? packs.find((candidate) => candidate.id === explicitPackId) : findModePackForModel(settings, packs, modelId, modeId, void 0);
+	if (!pack || resolveModePackModels(settings, pack)[modeId] !== modelId) return null;
+	const providerId = providerFromModelId(modelId);
+	return providerId ? {
+		packId: pack.id,
+		modelId,
+		providerId
+	} : null;
+}
+/**
+* A14: `Automatic` rotation starts *at* the persisted active account and walks
+* insertion order from there, wrapping once. The active account is the cursor
+* rotation last left at, so a turn that starts at index 0 regardless would
+* re-activate and re-try an account the previous turn already moved past —
+* which is the whole job the removed sticky-exclusion set was doing badly.
+* With no persisted active account the order is plain insertion order.
+*/
+function orderAccountsFromActive(accounts, activeId) {
+	const index = activeId === void 0 ? -1 : accounts.findIndex((account) => account.id === activeId);
+	if (index <= 0) return accounts;
+	return [...accounts.slice(index), ...accounts.slice(0, index)];
+}
+async function applyPreferredAccountRoute(args, store, settingsPath, route) {
+	const preferredId = getRouteTargetAccountId(settingsPath, route);
+	const accounts = store.listAccounts?.(route.providerId) ?? [];
+	if (accounts.length === 0) return false;
+	const tried = getTriedInstances(args.state);
+	const unavailable = new Set(accounts.filter((account) => tried.has(account.id)).map((account) => account.id));
+	const active = getRequestActiveAccount(args, store, route.providerId);
+	const selected = (preferredId ? accounts.filter((account) => account.id === preferredId) : orderAccountsFromActive(accounts, active?.id)).find((account) => !unavailable.has(account.id));
+	for (const accountId of unavailable) tried.add(accountId);
+	if (!selected) {
+		markRequestAccountRoutingExhausted(args.requestContext, route.providerId);
+		return false;
+	}
+	if (active?.id === selected.id) {
+		setRequestAccountSelection(args.requestContext, route.providerId, selected.id);
+		return false;
+	}
+	const activated = store.activateAccount?.(route.providerId, selected.id) ?? selected;
+	setRequestAccountSelection(args.requestContext, route.providerId, activated.id);
+	await emitAccountSwitchPart(args, {
+		provider: route.providerId,
+		from: active ? {
+			id: active.id,
+			label: active.label
+		} : null,
+		to: {
+			id: activated.id,
+			label: activated.label
+		},
+		reason: "preferred-routing",
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	return true;
+}
+var AccountRotationProcessor = class {
+	options;
+	id = "mastracode-account-rotation";
+	constructor(options) {
+		this.options = options;
+	}
+	async processAPIError(args) {
+		const { error, state } = args;
+		if (args.retryCount >= this.options.maxProcessorRetries) {
+			await this.gateChainHop(args, error);
+			return { retry: false };
+		}
+		const classification = classifyRotationError(error);
+		if (classification.kind === "never") {
+			await this.gateChainHop(args, error);
+			return { retry: false };
+		}
+		const cascade = await this.getPackCascade(args);
+		const currentPack = cascade?.packs[cascade.position];
+		const cascadeModelId = currentPack ? cascade.models[currentPack.packId]?.[cascade.modeId] : void 0;
+		const providerId = providerFromError(error) ?? (typeof cascadeModelId === "string" ? providerFromModelId(cascadeModelId) : void 0) ?? (cascade ? void 0 : providerFromSession(args));
+		if (!providerId) {
+			await this.emitPackFallbackPart(args, classification.kind === "hop" ? "persistent-outage" : "pool-exhausted");
+			return { retry: false };
+		}
+		const store = resolveCredentialStore(args.requestContext) ?? this.options.credentialStore;
+		const accounts = store.listAccounts?.(providerId) ?? [];
+		const active = getRequestActiveAccount(args, store, providerId);
+		const route = currentPack && typeof cascadeModelId === "string" ? resolveAccountRoute(args, this.options.settingsPath, {
+			packId: currentPack.packId,
+			modelId: cascadeModelId
+		}) : resolveAccountRoute(args, this.options.settingsPath);
+		if (classification.kind === "rotate" && classification.reason === "auth-failed" && active) {
+			const forced = getForcedRefreshInstances(state);
+			const refreshKey = `${providerId}:${active?.id ?? "active"}`;
+			if (!forced.has(refreshKey) && typeof store.forceRefreshActiveAccount === "function") {
+				forced.add(refreshKey);
+				if (await store.forceRefreshActiveAccount(providerId, active?.id) !== void 0) return { retry: true };
+			}
+		}
+		const targetAccountId = route?.providerId === providerId ? getRouteTargetAccountId(this.options.settingsPath, route) : void 0;
+		if (classification.kind === "hop") return this.declarePoolUnavailable(args, providerId, "persistent-outage", targetAccountId !== void 0);
+		if (targetAccountId !== void 0) return this.declarePoolUnavailable(args, providerId, "pool-exhausted", true);
+		if (accounts.length < 2) return this.declarePoolUnavailable(args, providerId, "pool-exhausted");
+		const tried = getTriedInstances(state);
+		if (active) tried.add(active.id);
+		if (accounts.filter((account) => tried.has(account.id)).length >= accounts.length) return this.declarePoolUnavailable(args, providerId, "pool-exhausted");
+		const nextCandidate = accounts.find((account) => !tried.has(account.id));
+		const next = nextCandidate ? store.activateAccount?.(providerId, nextCandidate.id) : void 0;
+		if (!next) return this.declarePoolUnavailable(args, providerId, "pool-exhausted");
+		setRequestAccountSelection(args.requestContext, providerId, next.id);
+		tried.add(next.id);
+		args.rotateResponseMessageId?.();
+		await emitAccountSwitchPart(args, {
+			provider: providerId,
+			from: active ? {
+				id: active.id,
+				label: active.label
+			} : null,
+			to: {
+				id: next.id,
+				label: next.label
+			},
+			reason: classification.reason,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return { retry: true };
+	}
+	/**
+	* The request's pack cascade, computed once from the session's pack and
+	* cached in processor state. Truncated at the first pack that lacks the
+	* session mode's model — mirroring getDynamicModel's truncation — so the
+	* cascade never promises a hop core's fallback array cannot make. The
+	* position advances per hop, so a second hop in the same turn reports B→C
+	* even though the session modelId still points at pack A (stickiness lands
+	* TUI-side only after the part renders). Returns null when the session has
+	* no active pack or the pack has no fallback chain.
+	*/
+	async getPackCascade(args) {
+		if (args.state.packCascade !== void 0) return args.state.packCascade ?? null;
+		const controller = args.requestContext?.get("controller");
+		const modelId = controller?.session?.modelId;
+		if (typeof modelId !== "string" || modelId.length === 0) {
+			args.state.packCascade = null;
+			return null;
+		}
+		const modeId = typeof controller?.session?.modeId === "string" && controller.session.modeId.length > 0 ? controller.session.modeId : "build";
+		const settings = loadSettings(this.options.settingsPath);
+		const packs = listResolvableModePacks(settings);
+		const controllerState = controller?.getState?.();
+		const statePackId = controllerState?.activeModelPackId ?? settings.models.activeModelPackId;
+		const activePack = findModePackForModel(settings, packs, modelId, modeId, typeof statePackId === "string" ? statePackId : void 0);
+		const chain = activePack ? resolveModePackFallbackChain(settings.models.packFallbacks ?? {}, activePack.id, settings.customModelPacks) : [];
+		if (chain.length < 2) {
+			args.state.packCascade = null;
+			return null;
+		}
+		const resolvedPacks = [];
+		const models = {};
+		for (const packId of chain) {
+			const pack = packs.find((candidate) => candidate.id === packId);
+			const packModels = pack ? resolveModePackModels(settings, pack) : {};
+			if (resolvedPacks.length > 0) {
+				const entryModelId = packModels[modeId];
+				if (!entryModelId) break;
+				try {
+					resolveModel(entryModelId, {
+						thinkingLevel: resolveRequestThinkingLevel({
+							state: { thinkingLevel: controllerState?.thinkingLevel },
+							session: { modeId }
+						}, this.options.settingsPath),
+						remapForCodexOAuth: true,
+						requestContext: args.requestContext
+					});
+				} catch {
+					break;
+				}
+			}
+			resolvedPacks.push({
+				packId,
+				label: pack?.name ?? packId
+			});
+			models[packId] = packModels;
+		}
+		if (resolvedPacks.length < 2) {
+			args.state.packCascade = null;
+			return null;
+		}
+		const cascade = {
+			packs: resolvedPacks,
+			models,
+			modeId,
+			position: 0
+		};
+		args.state.packCascade = cascade;
+		return cascade;
+	}
+	/**
+	* Q14 gate: 400/unknown/unattributable errors never hop packs. Core's
+	* fallback array advances on ANY thrown error except TripWire
+	* (llm-execution-step.ts), so when the session's pack has a chain and the
+	* current entry is non-last, a bare `retry: false` would silently hop on an
+	* error class the user excluded from hop triggers. TripWire is the only
+	* no-advance escape: the runner rethrows it and the fallback loop declines
+	* to advance. No chain (or already on the last entry) → return and let the
+	* plain `retry: false` surface the error exactly as before.
+	*/
+	async gateChainHop(args, error) {
+		const cascade = await this.getPackCascade(args);
+		if (!cascade) return;
+		if (cascade.position >= cascade.packs.length - 1) return;
+		throw new TripWire(error instanceof Error ? error.message : String(error), {}, this.id);
+	}
+	/**
+	* Emit the pack-fallback part when a configured chain has a next pack and
+	* queue the thread stickiness trigger. Core's fallback array does the hop
+	* itself on `retry: false`; this only announces it. The cascade is
+	* truncated exactly like getDynamicModel's chain (missing mode model or
+	* unresolvable model), so an announced hop is always one core can make;
+	* the toModelId guard stays as defense against a stale cache.
+	*/
+	async emitPackFallbackPart(args, reason) {
+		const cascade = await this.getPackCascade(args);
+		if (!cascade) return;
+		const from = cascade.packs[cascade.position];
+		const to = cascade.packs[cascade.position + 1];
+		if (!from || !to) return;
+		const toModelId = cascade.models[to.packId]?.[cascade.modeId];
+		if (!toModelId) return;
+		const controller = args.requestContext?.get("controller");
+		const at = (/* @__PURE__ */ new Date()).toISOString();
+		const threadId = typeof controller?.threadId === "string" ? controller.threadId : void 0;
+		const pending = {
+			fromPackId: from.packId,
+			toPackId: to.packId,
+			toModelId,
+			...threadId ? { threadId } : {},
+			reason,
+			at
+		};
+		await controller?.setThreadSetting?.({
+			key: PACK_FALLBACK_STATE_KEY,
+			value: pending
+		});
+		const data = {
+			from,
+			to,
+			reason,
+			at
+		};
+		try {
+			await args.writer?.custom({
+				type: PACK_FALLBACK_PART_TYPE,
+				data
+			});
+		} catch (error) {
+			await controller?.setThreadSetting?.({
+				key: PACK_FALLBACK_STATE_KEY,
+				value: void 0
+			});
+			throw error;
+		}
+		await controller?.setState?.({ [PACK_FALLBACK_STATE_KEY]: pending });
+		args.state.startNoticeEmitted = false;
+		const targetRoute = resolveAccountRoute(args, this.options.settingsPath, {
+			packId: to.packId,
+			modelId: toModelId
+		});
+		if (targetRoute) await applyPreferredAccountRoute(args, resolveCredentialStore(args.requestContext) ?? this.options.credentialStore, this.options.settingsPath, targetRoute).catch(() => void 0);
+		controller?.emitEvent?.({
+			type: "info",
+			message: packFallbackNoticeText(data)
+		});
+		cascade.position++;
+	}
+	/**
+	* Pool done for this request: every instance recorded in the tried-set and
+	* a `to: null` part emitted. Returns `retry: false` so core's fallback
+	* array can hop to the next pack (announced by `emitPackFallbackPart`).
+	* Silent on the account part when the provider has no registry at all —
+	* there are no accounts to declare unavailable, but the hop still applies.
+	*/
+	async declarePoolUnavailable(args, providerId, reason, exclusive = false) {
+		const store = resolveCredentialStore(args.requestContext) ?? this.options.credentialStore;
+		const accounts = store.listAccounts?.(providerId) ?? [];
+		if (accounts.length === 0) {
+			await this.emitPackFallbackPart(args, reason);
+			return { retry: false };
+		}
+		const tried = getTriedInstances(args.state);
+		for (const account of accounts) tried.add(account.id);
+		const active = getRequestActiveAccount(args, store, providerId);
+		await emitAccountSwitchPart(args, {
+			provider: providerId,
+			from: active ? {
+				id: active.id,
+				label: active.label
+			} : null,
+			to: null,
+			reason,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			...exclusive ? { exclusive: true } : {}
+		});
+		await this.emitPackFallbackPart(args, reason);
+		return { retry: false };
+	}
+};
+/**
+* Emits the "starting on a non-default account" notice (Q19) once per
+* request when the active registry account is not the first entry.
+*
+* TYPE CONSTRAINT: this class must NEVER implement `processAPIError`. It
+* lives in `inputProcessors`; the runner walks input processors first when
+* running `processAPIError`, so adding the method here would classify and
+* rotate errors BEFORE `StreamErrorRetryProcessor`'s transient retries run.
+*/
+var AccountStartNoticeProcessor = class {
+	options;
+	id = "mastracode-account-start-notice";
+	constructor(options) {
+		this.options = options;
+	}
+	async processInput(args) {
+		if (args.state.startNoticeEmitted) return args.messageList;
+		const store = resolveCredentialStore(args.requestContext) ?? this.options.credentialStore;
+		const route = resolveAccountRoute(args, this.options.settingsPath);
+		if (route) {
+			if (await applyPreferredAccountRoute(args, store, this.options.settingsPath, route)) {
+				args.state.startNoticeEmitted = true;
+				return args.messageList;
+			}
+		}
+		const providerId = route?.providerId ?? providerFromSession(args);
+		if (!providerId) return args.messageList;
+		const accounts = store.listAccounts?.(providerId) ?? [];
+		if (accounts.length < 2) return args.messageList;
+		const active = store.getActiveAccount?.(providerId);
+		const first = accounts[0];
+		if (!active || !first || active.id === first.id) return args.messageList;
+		args.state.startNoticeEmitted = true;
+		await emitAccountSwitchPart(args, {
+			provider: providerId,
+			from: null,
+			to: {
+				id: active.id,
+				label: active.label
+			},
+			reason: "starting-on-account",
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return args.messageList;
+	}
+};
+//#endregion
+export { ACCOUNT_SWITCH_PART_TYPE, AccountRotationProcessor, AccountStartNoticeProcessor, PACK_FALLBACK_PART_TYPE, PACK_FALLBACK_STATE_KEY, PROVIDER_DISPLAY_NAMES, accountSwitchNoticeText, classifyRotationError, isAccountSwitchReason, isPackFallbackReason, packFallbackNoticeText, providerFromError, providerFromModelId };
+
+//# sourceMappingURL=account-rotation-processor.js.map