@kodrunhq/opencode-autopilot 0.1.0

package/src/orchestrator/fallback/error-classifier.ts

@@ -0,0 +1,148 @@
+import type { ErrorType } from "./types";
+
+export const RETRYABLE_ERROR_PATTERNS: readonly RegExp[] = Object.freeze([
+	/rate.?limit/i,
+	/too.?many.?requests/i,
+	/quota.?exceeded/i,
+	/quota.?protection/i,
+	/key.?limit.?exceeded/i,
+	/usage\s+limit\s+has\s+been\s+reached/i,
+	/service.?unavailable/i,
+	/overloaded/i,
+	/temporarily.?unavailable/i,
+	/try.?again/i,
+	/credit.*balance.*too.*low/i,
+	/insufficient.?(?:credits?|funds?|balance)/i,
+	/(?:^|\s)429(?:\s|$)/,
+	/(?:^|\s)503(?:\s|$)/,
+	/(?:^|\s)529(?:\s|$)/,
+]);
+
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Handles nested error.error.message, error.message, error.error, and string errors.
+ */
+export function getErrorMessage(error: unknown): string {
+	if (error === null || error === undefined) return "";
+	if (typeof error === "string") return error;
+
+	if (typeof error === "object") {
+		const obj = error as Record<string, unknown>;
+
+		// Check nested error.error.message first
+		if (obj.error && typeof obj.error === "object") {
+			const nested = obj.error as Record<string, unknown>;
+			if (typeof nested.message === "string") return nested.message;
+		}
+
+		// Check error.message
+		if (typeof obj.message === "string") return obj.message;
+
+		// Check error.error as string
+		if (typeof obj.error === "string") return obj.error;
+	}
+
+	return "";
+}
+
+/**
+ * Extracts a status code from an error if it matches the retryable set.
+ * Checks error.status, error.statusCode, and message text.
+ */
+export function extractStatusCode(error: unknown, retryOnErrors: readonly number[]): number | null {
+	if (error !== null && typeof error === "object") {
+		const obj = error as Record<string, unknown>;
+
+		if (typeof obj.status === "number" && retryOnErrors.includes(obj.status)) {
+			return obj.status;
+		}
+		if (typeof obj.statusCode === "number" && retryOnErrors.includes(obj.statusCode)) {
+			return obj.statusCode;
+		}
+	}
+
+	// Extract from message text — restrict to 4xx/5xx to avoid false positives
+	const message = getErrorMessage(error);
+	const matches = message.matchAll(/\b([45]\d{2})\b/g);
+	for (const m of matches) {
+		const code = Number.parseInt(m[1], 10);
+		if (retryOnErrors.includes(code)) return code;
+	}
+
+	return null;
+}
+
+/**
+ * Classifies an error into a known ErrorType category based on message patterns and status codes.
+ */
+export function classifyErrorType(error: unknown): ErrorType {
+	const message = getErrorMessage(error);
+	const lowerMessage = message.toLowerCase();
+
+	// Check status code first
+	if (error !== null && typeof error === "object") {
+		const obj = error as Record<string, unknown>;
+		if (obj.status === 429 || obj.statusCode === 429) return "rate_limit";
+	}
+
+	// Check message patterns
+	if (
+		/api.?key/i.test(message) &&
+		/missing|no\s|not\s+(?:provided|found|set|configured)/i.test(message)
+	)
+		return "missing_api_key";
+	if (/model.*not.*(?:found|exist)/i.test(message)) return "model_not_found";
+	if (/content.?filter/i.test(message)) return "content_filter";
+	if (/context.?length/i.test(message)) return "context_length";
+	if (/rate.?limit/i.test(lowerMessage) || /too.?many.?requests/i.test(lowerMessage))
+		return "rate_limit";
+	if (
+		/quota.?exceeded/i.test(lowerMessage) ||
+		/insufficient.?(?:credits?|funds?|balance)/i.test(lowerMessage)
+	)
+		return "quota_exceeded";
+	if (/service.?unavailable/i.test(lowerMessage) || /overloaded/i.test(lowerMessage))
+		return "service_unavailable";
+
+	return "unknown";
+}
+
+/**
+ * Determines whether an error is retryable by another model.
+ * Checks status codes, built-in patterns, error type, and user-provided patterns.
+ */
+export function isRetryableError(
+	error: unknown,
+	retryOnErrors: readonly number[],
+	userPatterns?: readonly string[],
+): boolean {
+	const errorType = classifyErrorType(error);
+
+	// content_filter: same content will fail on any model.
+	// context_length: replay would fail without truncation; caller must truncate first.
+	if (errorType === "content_filter" || errorType === "context_length") return false;
+
+	if (errorType === "missing_api_key" || errorType === "model_not_found") return true;
+
+	const statusCode = extractStatusCode(error, retryOnErrors);
+	if (statusCode !== null && retryOnErrors.includes(statusCode)) return true;
+
+	const message = getErrorMessage(error);
+	if (RETRYABLE_ERROR_PATTERNS.some((pattern) => pattern.test(message))) return true;
+
+	if (userPatterns) {
+		for (const patternStr of userPatterns) {
+			// ReDoS protection: reject patterns with nested quantifiers or backtracking risk
+			if (/(\+|\*|\{)\s*\)(\+|\*|\{|\?)/.test(patternStr)) continue;
+			if (/\(.*\|.*\)(\+|\*|\{)/.test(patternStr)) continue;
+			try {
+				const re = new RegExp(patternStr, "i");
+				if (re.test(message)) return true;
+			} catch {
+				/* Invalid regex -- skip */
+			}
+		}
+	}
+
+	return false;
+}

package/src/orchestrator/fallback/event-handler.ts

@@ -0,0 +1,235 @@
+import type { FallbackConfig } from "./fallback-config";
+import type { FallbackManager } from "./fallback-manager";
+import { replayWithDegradation } from "./message-replay";
+import type { MessagePart } from "./types";
+
+/**
+ * SDK operations interface for dependency injection.
+ * Enables testing without the OpenCode runtime.
+ */
+export interface SdkOperations {
+	readonly abortSession: (sessionID: string) => Promise<void>;
+	readonly getSessionMessages: (sessionID: string) => Promise<readonly MessagePart[]>;
+	readonly promptAsync: (
+		sessionID: string,
+		model: { readonly providerID: string; readonly modelID: string },
+		parts: readonly MessagePart[],
+	) => Promise<void>;
+	readonly showToast: (
+		title: string,
+		message: string,
+		variant: "info" | "warning" | "error",
+	) => Promise<void>;
+}
+
+export interface EventHandlerDeps {
+	readonly manager: FallbackManager;
+	readonly sdk: SdkOperations;
+	readonly config: FallbackConfig;
+}
+
+/**
+ * Parses a "provider/model" string into { providerID, modelID }.
+ * Splits on the first "/" only. Returns null if no "/" found.
+ */
+export function parseModelString(
+	model: string,
+): { readonly providerID: string; readonly modelID: string } | null {
+	const slashIndex = model.indexOf("/");
+	if (slashIndex <= 0) return null;
+	return {
+		providerID: model.slice(0, slashIndex),
+		modelID: model.slice(slashIndex + 1),
+	};
+}
+
+/**
+ * Extracts a session ID from event properties.
+ * Supports both `properties.sessionID` and `properties.info.sessionID`.
+ */
+function extractSessionID(properties: Record<string, unknown>): string | undefined {
+	if (typeof properties.sessionID === "string") return properties.sessionID;
+	if (
+		properties.info !== null &&
+		typeof properties.info === "object" &&
+		typeof (properties.info as Record<string, unknown>).sessionID === "string"
+	) {
+		return (properties.info as Record<string, unknown>).sessionID as string;
+	}
+	return undefined;
+}
+
+/**
+ * Factory that creates an event handler function bound to fallback dependencies.
+ * The returned handler routes OpenCode events to the FallbackManager.
+ */
+export function createEventHandler(deps: EventHandlerDeps) {
+	const { manager, sdk, config } = deps;
+
+	return async (input: {
+		readonly event: { readonly type: string; readonly [key: string]: unknown };
+	}): Promise<void> => {
+		const { event } = input;
+		const properties = (event.properties ?? {}) as Record<string, unknown>;
+
+		switch (event.type) {
+			case "session.created": {
+				const info = properties.info as
+					| { id?: string; model?: string; parentID?: string | null; agent?: string }
+					| undefined;
+				if (!info?.id) return;
+
+				const model = typeof info.model === "string" ? info.model : "";
+				const parentID = info.parentID !== undefined ? info.parentID : undefined;
+				const agentName = typeof info.agent === "string" ? info.agent : undefined;
+				manager.initSession(info.id, model, parentID, agentName);
+
+				// Start TTFT timeout only when fallback is enabled and timeout configured.
+				// Without a fallback chain, a TTFT abort would just fail the session.
+				if (model && config.enabled && config.timeoutSeconds > 0) {
+					manager.startTtftTimeout(info.id, () => {
+						// Guard: skip if session was cleaned up before timer fires
+						if (!manager.getSessionState(info.id as string)) return;
+						// On TTFT timeout, abort session to trigger fallback via session.error
+						sdk.abortSession(info.id as string).catch(() => {
+							// Best-effort abort; session.error will handle the result
+						});
+					});
+				}
+				return;
+			}
+
+			case "session.deleted": {
+				const info = properties.info as { id?: string } | undefined;
+				if (info?.id) {
+					manager.cleanupSession(info.id);
+				}
+				return;
+			}
+
+			case "session.compacted": {
+				const sessionID = extractSessionID(properties);
+				if (sessionID) {
+					manager.clearCompactionInFlight(sessionID);
+				}
+				return;
+			}
+
+			case "message.part.delta":
+			case "session.diff": {
+				const sessionID = extractSessionID(properties);
+				if (sessionID) {
+					manager.recordFirstToken(sessionID);
+					manager.clearAwaitingResult(sessionID);
+				}
+				return;
+			}
+
+			case "session.error": {
+				const sessionID =
+					typeof properties.sessionID === "string" ? properties.sessionID : undefined;
+				if (!sessionID) return;
+
+				const error = properties.error;
+				const modelStr = typeof properties.model === "string" ? properties.model : undefined;
+
+				await handleFallbackError(manager, sdk, config, sessionID, error, modelStr);
+				return;
+			}
+
+			case "message.updated": {
+				const info = properties.info as
+					| { sessionID?: string; error?: unknown; model?: string }
+					| undefined;
+				if (!info?.sessionID || !info.error) return;
+
+				const modelStr = typeof info.model === "string" ? info.model : undefined;
+				await handleFallbackError(manager, sdk, config, info.sessionID, info.error, modelStr);
+				return;
+			}
+
+			default:
+				// Unknown event type -- ignore
+				return;
+		}
+	};
+}
+
+/**
+ * Shared fallback error handling logic used by both session.error and message.updated.
+ */
+async function handleFallbackError(
+	manager: FallbackManager,
+	sdk: SdkOperations,
+	config: FallbackConfig,
+	sessionID: string,
+	error: unknown,
+	modelStr?: string,
+): Promise<void> {
+	// All guards (self-abort, stale, retryable, lock) are inside manager.handleError
+	const plan = manager.handleError(sessionID, error, modelStr);
+	if (!plan) return;
+
+	try {
+		// Record self-abort before aborting (Pitfall 2)
+		manager.recordSelfAbort(sessionID);
+
+		// Abort current request
+		await sdk.abortSession(sessionID);
+
+		// Session may have been cleaned up during await — verify before continuing
+		if (!manager.getSessionState(sessionID)) {
+			manager.releaseRetryLock(sessionID);
+			return;
+		}
+
+		// Get messages for replay
+		const messages = await sdk.getSessionMessages(sessionID);
+
+		// Session existence check after second await
+		if (!manager.getSessionState(sessionID)) {
+			manager.releaseRetryLock(sessionID);
+			return;
+		}
+
+		// Get current state for attempt-based degradation
+		const state = manager.getSessionState(sessionID);
+		const attemptCount = state?.attemptCount ?? 0;
+		const { parts: replayedParts } = replayWithDegradation(messages, attemptCount);
+
+		// Commit fallback state — abort dispatch if commit fails (stale plan)
+		const committed = manager.commitAndUpdateState(sessionID, plan);
+		if (!committed) {
+			manager.releaseRetryLock(sessionID);
+			return;
+		}
+
+		// Parse the new model for the SDK call
+		const parsedModel = parseModelString(plan.newModel);
+		if (parsedModel) {
+			// Notify user if enabled
+			if (config.notifyOnFallback) {
+				await sdk
+					.showToast(
+						"Model Fallback",
+						`Switching from ${plan.failedModel} to ${plan.newModel}: ${plan.reason}`,
+						"warning",
+					)
+					.catch(() => {
+						// Best-effort notification
+					});
+			}
+
+			// Dispatch replay with fallback model
+			await sdk.promptAsync(sessionID, parsedModel, replayedParts);
+			// Mark awaiting result inside dispatch block — only when prompt was sent
+			manager.markAwaitingResult(sessionID);
+		}
+
+		// Release lock after dispatch (or skip if model unparseable)
+		manager.releaseRetryLock(sessionID);
+	} catch {
+		// On failure, release the lock to allow future retries
+		manager.releaseRetryLock(sessionID);
+	}
+}

package/src/orchestrator/fallback/fallback-config.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export const fallbackConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	retryOnErrors: z.array(z.number()).default([401, 402, 429, 500, 502, 503, 504]),
+	retryableErrorPatterns: z.array(z.string().max(256)).max(50).default([]),
+	maxFallbackAttempts: z.number().min(1).max(100).default(10),
+	cooldownSeconds: z.number().min(1).max(3600).default(60),
+	timeoutSeconds: z.number().min(0).max(300).default(30),
+	notifyOnFallback: z.boolean().default(true),
+});
+
+export type FallbackConfig = z.infer<typeof fallbackConfigSchema>;
+
+// Pre-compute defaults for Zod v4 nested default compatibility
+export const fallbackDefaults = fallbackConfigSchema.parse({});