@kodrunhq/opencode-autopilot 0.1.0

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

@@ -0,0 +1,323 @@
+import { isRetryableError } from "./error-classifier";
+import type { FallbackConfig } from "./fallback-config";
+import {
+	commitFallback,
+	createFallbackState,
+	planFallback,
+	recoverToOriginal,
+} from "./fallback-state";
+import type { FallbackPlan, FallbackState } from "./types";
+
+const SELF_ABORT_WINDOW_MS = 2000;
+
+export interface FallbackManagerOptions {
+	readonly config: FallbackConfig;
+	readonly resolveFallbackChain: (sessionID: string, agentName?: string) => readonly string[];
+}
+
+/**
+ * Encapsulates per-session fallback state and concurrency guards.
+ * Delegates to pure functions from fallback-state/error-classifier modules.
+ * Accepts SDK operations as callbacks to remain testable without the OpenCode runtime.
+ */
+export class FallbackManager {
+	private readonly config: FallbackConfig;
+	private readonly resolveFallbackChain: (
+		sessionID: string,
+		agentName?: string,
+	) => readonly string[];
+
+	// Per-session tracking (all private)
+	private readonly sessionStates: Map<string, FallbackState> = new Map();
+	private readonly sessionRetryInFlight: Set<string> = new Set();
+	private readonly sessionAwaitingFallbackResult: Set<string> = new Set();
+	private readonly sessionSelfAbortTimestamp: Map<string, number> = new Map();
+	private readonly sessionFirstTokenReceived: Map<string, boolean> = new Map();
+	private readonly sessionFallbackTimeouts: Map<string, ReturnType<typeof setTimeout>> = new Map();
+	private readonly sessionParentID: Map<string, string | null> = new Map();
+	private readonly sessionCompactionInFlight: Set<string> = new Set();
+	private readonly sessionAgentName: Map<string, string> = new Map();
+
+	constructor(options: FallbackManagerOptions) {
+		this.config = options.config;
+		this.resolveFallbackChain = options.resolveFallbackChain;
+	}
+
+	/**
+	 * Creates fallback state for a session with the given model.
+	 */
+	initSession(
+		sessionID: string,
+		model: string,
+		parentID?: string | null,
+		agentName?: string,
+	): void {
+		this.sessionStates.set(sessionID, createFallbackState(model));
+		if (parentID !== undefined) {
+			this.sessionParentID.set(sessionID, parentID);
+		}
+		if (agentName) {
+			this.sessionAgentName.set(sessionID, agentName);
+		}
+	}
+
+	/**
+	 * Returns FallbackState for known session, undefined for unknown.
+	 */
+	getSessionState(sessionID: string): FallbackState | undefined {
+		return this.sessionStates.get(sessionID);
+	}
+
+	/**
+	 * Removes all tracking state for a session. Safe to call on unknown sessions.
+	 */
+	cleanupSession(sessionID: string): void {
+		this.sessionStates.delete(sessionID);
+		this.sessionRetryInFlight.delete(sessionID);
+		this.sessionAwaitingFallbackResult.delete(sessionID);
+		this.sessionSelfAbortTimestamp.delete(sessionID);
+		this.sessionFirstTokenReceived.delete(sessionID);
+		this.sessionParentID.delete(sessionID);
+		this.sessionAgentName.delete(sessionID);
+		this.sessionCompactionInFlight.delete(sessionID);
+
+		// Clear TTFT timeout if present
+		const timer = this.sessionFallbackTimeouts.get(sessionID);
+		if (timer !== undefined) {
+			clearTimeout(timer);
+			this.sessionFallbackTimeouts.delete(sessionID);
+		}
+	}
+
+	/**
+	 * Acquires the per-session retry lock. Returns true on first call, false if already held.
+	 * Prevents dual event handler race (Pitfall 1).
+	 */
+	acquireRetryLock(sessionID: string): boolean {
+		if (this.sessionRetryInFlight.has(sessionID)) {
+			return false;
+		}
+		this.sessionRetryInFlight.add(sessionID);
+		return true;
+	}
+
+	/**
+	 * Releases the per-session retry lock.
+	 */
+	releaseRetryLock(sessionID: string): void {
+		this.sessionRetryInFlight.delete(sessionID);
+	}
+
+	/**
+	 * Returns true if a retry dispatch or fallback result is pending for the session.
+	 */
+	isDispatchInFlight(sessionID: string): boolean {
+		return (
+			this.sessionRetryInFlight.has(sessionID) || this.sessionAwaitingFallbackResult.has(sessionID)
+		);
+	}
+
+	/**
+	 * Marks a session as awaiting a fallback result (replay dispatched, not yet complete).
+	 */
+	markAwaitingResult(sessionID: string): void {
+		this.sessionAwaitingFallbackResult.add(sessionID);
+	}
+
+	/**
+	 * Clears the awaiting-result flag for a session.
+	 */
+	clearAwaitingResult(sessionID: string): void {
+		this.sessionAwaitingFallbackResult.delete(sessionID);
+	}
+
+	/**
+	 * Records a self-abort timestamp for self-abort suppression (Pitfall 2).
+	 */
+	recordSelfAbort(sessionID: string): void {
+		this.sessionSelfAbortTimestamp.set(sessionID, Date.now());
+	}
+
+	/**
+	 * Returns true when a MessageAbortedError arrives within 2000ms of recordSelfAbort.
+	 * Suppresses self-inflicted abort errors (Pitfall 2).
+	 */
+	isSelfAbortError(sessionID: string): boolean {
+		const timestamp = this.sessionSelfAbortTimestamp.get(sessionID);
+		if (timestamp === undefined) {
+			return false;
+		}
+		if (Date.now() - timestamp < SELF_ABORT_WINDOW_MS) {
+			// Consume on match — prevents silencing subsequent legitimate errors
+			this.sessionSelfAbortTimestamp.delete(sessionID);
+			return true;
+		}
+		this.sessionSelfAbortTimestamp.delete(sessionID);
+		return false;
+	}
+
+	/**
+	 * Returns true when error model is in failedModels and differs from currentModel.
+	 * Suppresses stale error events from previous models (Pitfall 5).
+	 */
+	isStaleError(sessionID: string, errorModel?: string): boolean {
+		const state = this.sessionStates.get(sessionID);
+		if (!state || !errorModel) {
+			return false;
+		}
+		return errorModel !== state.currentModel && state.failedModels.has(errorModel);
+	}
+
+	/**
+	 * Creates a TTFT timer that calls the provided callback after timeoutSeconds.
+	 * Replaces any existing timeout for the session.
+	 */
+	startTtftTimeout(sessionID: string, onTimeout: () => void): void {
+		// Clear existing timeout if any
+		const existingTimer = this.sessionFallbackTimeouts.get(sessionID);
+		if (existingTimer !== undefined) {
+			clearTimeout(existingTimer);
+		}
+
+		this.sessionFirstTokenReceived.set(sessionID, false);
+
+		const timer = setTimeout(onTimeout, this.config.timeoutSeconds * 1000);
+		this.sessionFallbackTimeouts.set(sessionID, timer);
+	}
+
+	/**
+	 * Records that the first token was received for a session. Cancels the TTFT timer.
+	 */
+	recordFirstToken(sessionID: string): void {
+		if (this.sessionFirstTokenReceived.get(sessionID) === false) {
+			this.sessionFirstTokenReceived.set(sessionID, true);
+			const timer = this.sessionFallbackTimeouts.get(sessionID);
+			if (timer !== undefined) {
+				clearTimeout(timer);
+				this.sessionFallbackTimeouts.delete(sessionID);
+			}
+		}
+	}
+
+	/**
+	 * Handles an error for a session. Orchestrates guard checks and returns a FallbackPlan
+	 * if fallback should proceed, or null if the error should be suppressed/ignored.
+	 *
+	 * Guard order:
+	 * 1. Self-abort suppression (Pitfall 2)
+	 * 2. Stale error suppression (Pitfall 5)
+	 * 3. Retryable error check
+	 * 4. Retry lock (Pitfall 1)
+	 * 5. Session state existence
+	 * 6. Plan fallback via pure function
+	 */
+	handleError(sessionID: string, error: unknown, errorModel?: string): FallbackPlan | null {
+		// Pitfall 2: Suppress self-abort errors
+		if (this.isSelfAbortError(sessionID)) {
+			return null;
+		}
+
+		// Pitfall 5: Suppress stale errors from previous models
+		if (this.isStaleError(sessionID, errorModel)) {
+			return null;
+		}
+
+		// Check if error is retryable
+		if (!isRetryableError(error, this.config.retryOnErrors, this.config.retryableErrorPatterns)) {
+			return null;
+		}
+
+		// Pitfall 1: Only one handler plans+dispatches per session
+		if (!this.acquireRetryLock(sessionID)) {
+			return null;
+		}
+
+		// Check session state
+		const state = this.sessionStates.get(sessionID);
+		if (!state) {
+			this.releaseRetryLock(sessionID);
+			return null;
+		}
+
+		// Plan fallback via pure function — pass agent name for per-agent chain resolution
+		const agentName = this.sessionAgentName.get(sessionID);
+		const chain = this.resolveFallbackChain(sessionID, agentName);
+		const result = planFallback(
+			state,
+			chain,
+			this.config.maxFallbackAttempts,
+			this.config.cooldownSeconds * 1000,
+		);
+
+		if (!result.success) {
+			this.releaseRetryLock(sessionID);
+			return null;
+		}
+
+		// Return plan (caller commits after successful dispatch)
+		return result.plan;
+	}
+
+	/**
+	 * Applies a fallback plan to session state immutably.
+	 * Returns true if the plan was committed, false if stale or session unknown.
+	 */
+	commitAndUpdateState(sessionID: string, plan: FallbackPlan): boolean {
+		const state = this.sessionStates.get(sessionID);
+		if (!state) {
+			return false;
+		}
+
+		const result = commitFallback(state, plan);
+		if (result.committed) {
+			this.sessionStates.set(sessionID, result.state);
+		}
+		return result.committed;
+	}
+
+	/**
+	 * Attempts to recover to the original model after cooldown expires.
+	 * Returns true if recovery succeeded, false otherwise.
+	 */
+	tryRecoverToOriginal(sessionID: string): boolean {
+		const state = this.sessionStates.get(sessionID);
+		if (!state) {
+			return false;
+		}
+
+		const recovered = recoverToOriginal(state, this.config.cooldownSeconds * 1000);
+		if (recovered) {
+			this.sessionStates.set(sessionID, recovered);
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Marks a session as having compaction in flight.
+	 */
+	markCompactionInFlight(sessionID: string): void {
+		this.sessionCompactionInFlight.add(sessionID);
+	}
+
+	/**
+	 * Clears the compaction-in-flight flag for a session.
+	 */
+	clearCompactionInFlight(sessionID: string): void {
+		this.sessionCompactionInFlight.delete(sessionID);
+	}
+
+	/**
+	 * Returns true if compaction is in flight for a session.
+	 */
+	isCompactionInFlight(sessionID: string): boolean {
+		return this.sessionCompactionInFlight.has(sessionID);
+	}
+
+	/**
+	 * Returns the parent session ID for a child session, or undefined if not tracked.
+	 */
+	getParentID(sessionID: string): string | null | undefined {
+		return this.sessionParentID.get(sessionID);
+	}
+}

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

@@ -0,0 +1,120 @@
+import type {
+	CommitResult,
+	FallbackPlan,
+	FallbackPlanFailure,
+	FallbackPlanResult,
+	FallbackState,
+} from "./types";
+
+/**
+ * Creates a new FallbackState for a model. Initial state: on primary model, no failures.
+ */
+export function createFallbackState(model: string): FallbackState {
+	return {
+		originalModel: model,
+		currentModel: model,
+		fallbackIndex: -1,
+		failedModels: new Map(),
+		attemptCount: 0,
+	};
+}
+
+/**
+ * Plans the next fallback action. Pure function: reads state + config, returns plan or failure.
+ * Does NOT mutate state.
+ *
+ * Finds the next model in the fallback chain that is not in cooldown.
+ * Returns failure if max attempts reached or all models exhausted.
+ */
+export function planFallback(
+	state: Readonly<FallbackState>,
+	fallbackChain: readonly string[],
+	maxAttempts: number,
+	cooldownMs: number,
+): FallbackPlanResult | FallbackPlanFailure {
+	if (state.attemptCount >= maxAttempts) {
+		return {
+			success: false as const,
+			reason: `Max fallback attempts reached (${maxAttempts})`,
+		};
+	}
+
+	const now = Date.now();
+
+	// Iterate chain starting from fallbackIndex + 1, wrapping around
+	for (let i = 0; i < fallbackChain.length; i++) {
+		const index = (state.fallbackIndex + 1 + i) % fallbackChain.length;
+		const model = fallbackChain[index];
+
+		// Skip current model — can't fall back to the model that just failed
+		if (model === state.currentModel) continue;
+
+		// Skip models still in cooldown
+		const failedAt = state.failedModels.get(model);
+		if (failedAt !== undefined && now - failedAt < cooldownMs) {
+			continue;
+		}
+
+		return {
+			success: true as const,
+			plan: {
+				failedModel: state.currentModel,
+				newModel: model,
+				newFallbackIndex: index,
+				reason: `Fallback from ${state.currentModel} to ${model}`,
+			},
+		};
+	}
+
+	return {
+		success: false as const,
+		reason: "All fallback models exhausted or in cooldown",
+	};
+}
+
+/**
+ * Commits a fallback plan to produce a new state. Pure function: returns new state, NEVER mutates input.
+ *
+ * Returns committed:false if the plan is stale (currentModel changed since plan was created).
+ */
+export function commitFallback(state: Readonly<FallbackState>, plan: FallbackPlan): CommitResult {
+	if (state.currentModel !== plan.failedModel) {
+		return { committed: false, state: { ...state, failedModels: new Map(state.failedModels) } };
+	}
+
+	return {
+		committed: true,
+		state: {
+			...state,
+			fallbackIndex: plan.newFallbackIndex,
+			failedModels: new Map([...state.failedModels, [plan.failedModel, Date.now()]]),
+			attemptCount: state.attemptCount + 1,
+			currentModel: plan.newModel,
+		},
+	};
+}
+
+/**
+ * Attempts to recover to the original model after cooldown expires.
+ * Pure function: returns new state if recovery is possible, null otherwise.
+ *
+ * Returns null if already on original model or if original is still in cooldown.
+ */
+export function recoverToOriginal(
+	state: Readonly<FallbackState>,
+	cooldownMs: number,
+): FallbackState | null {
+	if (state.currentModel === state.originalModel) return null;
+
+	const failedAt = state.failedModels.get(state.originalModel);
+	if (failedAt !== undefined && Date.now() - failedAt < cooldownMs) {
+		return null;
+	}
+
+	return {
+		...state,
+		currentModel: state.originalModel,
+		fallbackIndex: -1,
+		failedModels: new Map(state.failedModels),
+	};
+}

package/src/orchestrator/fallback/index.ts

@@ -0,0 +1,11 @@
+export { createChatMessageHandler } from "./chat-message-handler";
+export * from "./error-classifier";
+export type { EventHandlerDeps, SdkOperations } from "./event-handler";
+export { createEventHandler } from "./event-handler";
+export * from "./fallback-config";
+export type { FallbackManagerOptions } from "./fallback-manager";
+export { FallbackManager } from "./fallback-manager";
+export * from "./fallback-state";
+export * from "./message-replay";
+export { createToolExecuteAfterHandler } from "./tool-execute-handler";
+export * from "./types";

package/src/orchestrator/fallback/message-replay.ts

@@ -0,0 +1,40 @@
+import type { ContentTier, MessagePart } from "./types";
+
+/**
+ * Filters message parts based on content tier.
+ *
+ * - Tier 1: All parts (full fidelity)
+ * - Tier 2: Text + images (filters out tool_call and tool_result)
+ * - Tier 3: Text only (maximum compatibility)
+ */
+export function filterPartsByTier(
+	parts: readonly MessagePart[],
+	tier: ContentTier,
+): readonly MessagePart[] {
+	if (tier === 1) return parts;
+
+	if (tier === 2) {
+		return parts.filter((part) => part.type !== "tool_call" && part.type !== "tool_result");
+	}
+
+	// Tier 3: text only
+	return parts.filter((part) => part.type === "text");
+}
+
+/**
+ * Returns degraded message parts based on the attempt number.
+ *
+ * - Attempt 0: Tier 1 (all parts)
+ * - Attempt 1: Tier 2 (text + images, no tool parts)
+ * - Attempt 2+: Tier 3 (text only)
+ */
+export function replayWithDegradation(
+	parts: readonly MessagePart[],
+	attempt: number,
+): { readonly parts: readonly MessagePart[]; readonly tier: ContentTier } {
+	const tier: ContentTier = attempt === 0 ? 1 : attempt === 1 ? 2 : 3;
+	return {
+		parts: filterPartsByTier(parts, tier),
+		tier,
+	};
+}

package/src/orchestrator/fallback/resolve-chain.ts

@@ -0,0 +1,34 @@
+/**
+ * Two-tier fallback chain resolution.
+ *
+ * Tier 1: Per-agent fallback_models from opencode.json agent config
+ * Tier 2: Global fallback_models from plugin config
+ *
+ * Normalizes a single string to a single-element array.
+ * Always returns a new array (no shared references).
+ */
+export function resolveChain(
+	agentName: string,
+	agentConfigs: Record<string, Record<string, unknown>> | undefined,
+	globalFallbacks: string | readonly string[] | undefined,
+): string[] {
+	// Tier 1: Per-agent fallback_models
+	if (agentName && agentConfigs?.[agentName]) {
+		const perAgent = agentConfigs[agentName].fallback_models;
+		if (perAgent) {
+			if (typeof perAgent === "string") return [perAgent];
+			if (Array.isArray(perAgent))
+				return perAgent.filter((m): m is string => typeof m === "string" && m.length > 0);
+		}
+		// Non-string/non-array value (e.g. number, object) — skip to Tier 2
+	}
+
+	// Tier 2: Global fallback_models
+	if (globalFallbacks) {
+		if (typeof globalFallbacks === "string") return [globalFallbacks];
+		if (Array.isArray(globalFallbacks))
+			return [...globalFallbacks].filter((m): m is string => typeof m === "string" && m.length > 0);
+	}
+
+	return [];
+}

package/src/orchestrator/fallback/tool-execute-handler.ts

@@ -0,0 +1,44 @@
+import type { FallbackManager } from "./fallback-manager";
+
+/**
+ * Factory that creates a tool.execute.after hook handler for subagent result sync.
+ *
+ * Intercepts "task" tool results (subagent dispatches). When a child session's
+ * fallback is still in progress, the task result may be empty. This handler
+ * marks such results with a `fallbackPending` metadata flag so the orchestrator
+ * knows to retry.
+ */
+export function createToolExecuteAfterHandler(manager: FallbackManager) {
+	return async (
+		input: {
+			readonly tool: string;
+			readonly sessionID: string;
+			readonly callID: string;
+			readonly args: unknown;
+		},
+		output: { title: string; output: string; metadata: unknown },
+	): Promise<void> => {
+		// Only intercept 'task' tool results (subagent dispatch results)
+		if (input.tool !== "task") return;
+
+		// Check if output is empty (indicates subagent failure mid-fallback)
+		if (
+			!output.output ||
+			output.output.trim() === "" ||
+			output.output === "<task_result></task_result>"
+		) {
+			// Check if child session had a parent
+			const parentID = manager.getParentID(input.sessionID);
+			if (parentID != null) {
+				// Mark for the orchestrator to retry -- the child session's fallback
+				// will complete asynchronously. Add metadata flag.
+				output.metadata = {
+					...(typeof output.metadata === "object" && output.metadata !== null
+						? output.metadata
+						: {}),
+					fallbackPending: true,
+				};
+			}
+		}
+	};
+}

package/src/orchestrator/fallback/types.ts

@@ -0,0 +1,46 @@
+export type ErrorType =
+	| "rate_limit"
+	| "quota_exceeded"
+	| "service_unavailable"
+	| "missing_api_key"
+	| "model_not_found"
+	| "content_filter"
+	| "context_length"
+	| "unknown";
+
+export type ContentTier = 1 | 2 | 3;
+
+export interface FallbackState {
+	readonly originalModel: string;
+	readonly currentModel: string;
+	readonly fallbackIndex: number; // -1 = primary
+	readonly failedModels: ReadonlyMap<string, number>; // model -> timestamp
+	readonly attemptCount: number;
+}
+
+export interface FallbackPlan {
+	readonly failedModel: string;
+	readonly newModel: string;
+	readonly newFallbackIndex: number;
+	readonly reason: string;
+}
+
+export interface FallbackPlanResult {
+	readonly success: true;
+	readonly plan: FallbackPlan;
+}
+
+export interface FallbackPlanFailure {
+	readonly success: false;
+	readonly reason: string;
+}
+
+export interface CommitResult {
+	readonly committed: boolean;
+	readonly state: FallbackState;
+}
+
+export interface MessagePart {
+	readonly type: string;
+	readonly [key: string]: unknown;
+}