@wolfx/opencode-magic-context 0.21.8-patch.1

package/src/shared/model-suggestion-retry.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import { promptSyncWithModelSuggestionRetry } from "./model-suggestion-retry";
+
+type PromptCall = {
+    body: { model?: { providerID: string; modelID: string } };
+    signal?: AbortSignal;
+};
+
+function createClient(prompt: ReturnType<typeof mock>) {
+    return {
+        session: {
+            prompt,
+        },
+    } as never;
+}
+
+function createArgs(model?: { providerID: string; modelID: string }) {
+    return {
+        path: { id: "ses-test" },
+        body: model ? { model } : {},
+    };
+}
+
+describe("promptSyncWithModelSuggestionRetry", () => {
+    test("primary succeeds, no fallback iteration", async () => {
+        const prompt = mock(async () => ({}));
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(client, createArgs(), {
+            fallbackModels: ["anthropic/claude-sonnet-4-6"],
+        });
+
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
+    test("primary succeeds with no fallbacks configured", async () => {
+        const prompt = mock(async () => ({}));
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(client, createArgs());
+
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
+    test("primary fails, fallback[0] succeeds", async () => {
+        const prompt = mock(async () => {
+            if (prompt.mock.calls.length === 1) throw new Error("primary failed");
+            return {};
+        });
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(client, createArgs(), {
+            fallbackModels: ["anthropic/claude-sonnet-4-6"],
+        });
+
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect((prompt.mock.calls[1]?.[0] as PromptCall).body.model).toEqual({
+            providerID: "anthropic",
+            modelID: "claude-sonnet-4-6",
+        });
+    });
+
+    test("primary fails, fallback[0] fails, fallback[1] succeeds", async () => {
+        const prompt = mock(async () => {
+            if (prompt.mock.calls.length <= 2)
+                throw new Error(`failed ${prompt.mock.calls.length}`);
+            return {};
+        });
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(client, createArgs(), {
+            fallbackModels: ["anthropic/claude-sonnet-4-6", "google/gemini-3-flash"],
+        });
+
+        expect(prompt).toHaveBeenCalledTimes(3);
+        expect((prompt.mock.calls[2]?.[0] as PromptCall).body.model).toEqual({
+            providerID: "google",
+            modelID: "gemini-3-flash",
+        });
+    });
+
+    test("all attempts fail throws the last fallback error", async () => {
+        const primaryError = new Error("primary failed");
+        const firstFallbackError = new Error("fallback 0 failed");
+        const lastFallbackError = new Error("fallback 1 failed");
+        const errors = [primaryError, firstFallbackError, lastFallbackError];
+        const prompt = mock(async () => {
+            throw errors[prompt.mock.calls.length - 1];
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                fallbackModels: ["anthropic/claude-sonnet-4-6", "google/gemini-3-flash"],
+            }),
+        ).rejects.toBe(lastFallbackError);
+        expect(prompt).toHaveBeenCalledTimes(3);
+    });
+
+    test("abort signal short-circuits", async () => {
+        const controller = new AbortController();
+        controller.abort();
+        const prompt = mock(async () => {
+            throw new Error("provider noticed abort");
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                signal: controller.signal,
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            }),
+        ).rejects.toThrow("prompt aborted by external signal");
+        // Pre-aborted signal MUST short-circuit before any upstream prompt
+        // call — Audit Finding #1 hardening. No round-trip wasted on a
+        // request the caller has already cancelled.
+        expect(prompt).toHaveBeenCalledTimes(0);
+    });
+
+    test("AbortError name short-circuits", async () => {
+        const abortError = new Error("aborted by provider");
+        abortError.name = "AbortError";
+        const prompt = mock(async () => {
+            throw abortError;
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            }),
+        ).rejects.toBe(abortError);
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
+    test("timeout short-circuits", async () => {
+        const timeoutError = new Error("prompt timed out after 5000ms");
+        const prompt = mock(async () => {
+            throw timeoutError;
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            }),
+        ).rejects.toBe(timeoutError);
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
+    test("context overflow short-circuits", async () => {
+        const overflowError = new Error("prompt is too long: 50000 tokens > 32000");
+        const prompt = mock(async () => {
+            throw overflowError;
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                fallbackModels: ["anthropic/claude-sonnet-4-6"],
+            }),
+        ).rejects.toBe(overflowError);
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
+    test("suggestion retry within attempt succeeds", async () => {
+        const suggestionError = new Error("model not found");
+        suggestionError.name = "ProviderModelNotFoundError";
+        Object.assign(suggestionError, {
+            data: {
+                providerID: "anthropic",
+                modelID: "claude-sonnet-4-6",
+                suggestions: ["claude-sonnet-4-7"],
+            },
+        });
+        const prompt = mock(async () => {
+            if (prompt.mock.calls.length === 1) throw suggestionError;
+            return {};
+        });
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(
+            client,
+            createArgs({ providerID: "anthropic", modelID: "claude-sonnet-4-6" }),
+            { fallbackModels: ["google/gemini-3-flash"] },
+        );
+
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect((prompt.mock.calls[1]?.[0] as PromptCall).body.model).toEqual({
+            providerID: "anthropic",
+            modelID: "claude-sonnet-4-7",
+        });
+    });
+
+    test("invalid fallback specs are skipped", async () => {
+        const prompt = mock(async () => {
+            if (prompt.mock.calls.length === 1) throw new Error("primary failed");
+            return {};
+        });
+        const client = createClient(prompt);
+
+        await promptSyncWithModelSuggestionRetry(client, createArgs(), {
+            fallbackModels: ["no-slash", "/leading", "valid/model"],
+        });
+
+        expect(prompt).toHaveBeenCalledTimes(2);
+        expect((prompt.mock.calls[1]?.[0] as PromptCall).body.model).toEqual({
+            providerID: "valid",
+            modelID: "model",
+        });
+    });
+
+    test("iteration order respected", async () => {
+        const prompt = mock(async () => {
+            throw new Error(`failed ${prompt.mock.calls.length}`);
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), {
+                fallbackModels: [
+                    "anthropic/claude-sonnet-4-6",
+                    "google/gemini-3-flash",
+                    "openrouter/qwen3-coder",
+                ],
+            }),
+        ).rejects.toThrow("failed 4");
+
+        expect(prompt).toHaveBeenCalledTimes(4);
+        expect(prompt.mock.calls.map((call) => (call[0] as PromptCall).body.model)).toEqual([
+            undefined,
+            { providerID: "anthropic", modelID: "claude-sonnet-4-6" },
+            { providerID: "google", modelID: "gemini-3-flash" },
+            { providerID: "openrouter", modelID: "qwen3-coder" },
+        ]);
+    });
+
+    test("empty fallbackModels = legacy", async () => {
+        const originalError = new Error("primary failed without suggestion");
+        const prompt = mock(async () => {
+            throw originalError;
+        });
+        const client = createClient(prompt);
+
+        await expect(
+            promptSyncWithModelSuggestionRetry(client, createArgs(), { fallbackModels: [] }),
+        ).rejects.toBe(originalError);
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+});

package/src/shared/model-suggestion-retry.ts

@@ -0,0 +1,348 @@
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+import { detectOverflow } from "../features/magic-context/overflow-detection";
+import { log } from "./logger";
+import { parseProviderModel } from "./resolve-fallbacks";
+
+type Client = ReturnType<typeof createOpencodeClient>;
+
+type PromptBody = {
+    model?: { providerID: string; modelID: string };
+    [key: string]: unknown;
+};
+
+type PromptArgs = {
+    path: { id: string };
+    body: PromptBody;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+};
+
+export interface PromptRetryOptions {
+    timeoutMs?: number;
+    /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
+    signal?: AbortSignal;
+    /**
+     * Ordered list of "provider/modelID" alternates to try if the primary call
+     * (and its single-suggestion retry) fails. Empty / undefined = no fallback
+     * iteration (legacy behavior).
+     *
+     * Fallback policy:
+     *   - Each fallback gets the FULL `timeoutMs` budget (per-attempt, not total).
+     *   - Suggestion-retry runs inside each attempt (so "did you mean X?" errors
+     *     still self-heal at the primary AND at each fallback).
+     *   - Iteration stops immediately on abort/timeout/context-overflow errors —
+     *     fallbacks won't help and the caller's emergency-recovery path needs
+     *     to handle these.
+     *   - On all-failed, the LAST error is thrown (matches legacy behavior when
+     *     `fallbackModels` is empty).
+     */
+    fallbackModels?: readonly string[];
+    /**
+     * Identifier for structured logging (e.g. "dreamer:consolidate",
+     * "historian", "compressor", "sidekick"). Helps correlate fallback
+     * attempts to a specific call site in `magic-context.log`. Defaults to
+     * "subagent" if not provided.
+     */
+    callContext?: string;
+}
+
+export interface ModelSuggestionInfo {
+    providerID: string;
+    modelID: string;
+    suggestion: string;
+}
+
+function extractMessage(error: unknown): string {
+    if (typeof error === "string") return error;
+    if (error instanceof Error) return error.message;
+    if (typeof error === "object" && error !== null) {
+        const obj = error as Record<string, unknown>;
+        if (typeof obj.message === "string") return obj.message;
+    }
+
+    try {
+        return JSON.stringify(error);
+    } catch (_error) {
+        return String(error);
+    }
+}
+
+export function parseModelSuggestion(error: unknown): ModelSuggestionInfo | null {
+    if (!error) return null;
+
+    if (typeof error === "object" && error !== null) {
+        const errObj = error as Record<string, unknown>;
+
+        if (
+            errObj.name === "ProviderModelNotFoundError" &&
+            typeof errObj.data === "object" &&
+            errObj.data !== null
+        ) {
+            const data = errObj.data as Record<string, unknown>;
+            const suggestions = data.suggestions;
+            if (Array.isArray(suggestions) && typeof suggestions[0] === "string") {
+                return {
+                    providerID: String(data.providerID ?? ""),
+                    modelID: String(data.modelID ?? ""),
+                    suggestion: suggestions[0],
+                };
+            }
+        }
+
+        for (const key of ["data", "error", "cause"] as const) {
+            const nested = errObj[key];
+            if (nested && typeof nested === "object") {
+                const result = parseModelSuggestion(nested);
+                if (result) return result;
+            }
+        }
+    }
+
+    const message = extractMessage(error);
+    const modelMatch = message.match(/model not found:\s*([^/\s]+)\s*\/\s*([^.,\s]+)/i);
+    const suggestionMatch = message.match(/did you mean:\s*([^,?]+)/i);
+
+    if (!modelMatch || !suggestionMatch) {
+        return null;
+    }
+
+    return {
+        providerID: modelMatch[1].trim(),
+        modelID: modelMatch[2].trim(),
+        suggestion: suggestionMatch[1].trim(),
+    };
+}
+
+async function promptWithTimeout(
+    client: Client,
+    args: PromptArgs,
+    timeoutMs: number,
+    signal?: AbortSignal,
+): Promise<void> {
+    // Bail immediately if the caller's signal is already aborted (e.g.
+    // lease loss before this attempt was scheduled). Per spec
+    // `addEventListener('abort', ...)` on an already-aborted signal fires
+    // synchronously in modern Node/Bun, but an explicit guard is clearer
+    // and avoids one wasted upstream `client.session.prompt` round-trip
+    // before `isNonRetryable` catches the cancellation at the chain loop.
+    if (signal?.aborted) {
+        throw new Error("prompt aborted by external signal");
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    // Link external signal to internal controller so external abort cancels the fetch
+    const onExternalAbort = () => controller.abort();
+    signal?.addEventListener("abort", onExternalAbort);
+
+    try {
+        await client.session.prompt({
+            ...args,
+            signal: controller.signal,
+        } as Parameters<typeof client.session.prompt>[0]);
+    } catch (error) {
+        if (signal?.aborted) {
+            throw new Error("prompt aborted by external signal");
+        }
+        if (controller.signal.aborted) {
+            throw new Error(`prompt timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    } finally {
+        clearTimeout(timeout);
+        signal?.removeEventListener("abort", onExternalAbort);
+    }
+}
+
+/**
+ * Returns true if the error indicates a NON-RETRYABLE condition where iterating
+ * to a fallback model would be pointless or harmful:
+ *
+ *   - External abort (user cancellation, lease loss, etc.) — caller wants to
+ *     stop, not retry.
+ *   - Context overflow — same prompt will overflow on any reasonably-sized
+ *     model. Caller has its own emergency-recovery path for this.
+ *   - Timeout — same wall-clock budget on the same prompt is unlikely to
+ *     succeed on another model. Caller decides whether to retry at a higher
+ *     level (e.g. historian's MAX_HISTORIAN_RETRIES loop).
+ *
+ * Everything else (auth errors, ProviderModelNotFoundError without suggestion,
+ * rate limits, transient network failures, etc.) is considered retryable on a
+ * different model.
+ */
+function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
+    if (externalSignal?.aborted) return true;
+
+    if (error instanceof Error) {
+        if (error.name === "AbortError") return true;
+        // promptWithTimeout wraps both abort cases in plain `Error` with a
+        // recognizable message.
+        if (error.message === "prompt aborted by external signal") return true;
+        if (/^prompt timed out after \d+ms$/.test(error.message)) return true;
+    }
+
+    if (detectOverflow(error).isOverflow) return true;
+
+    return false;
+}
+
+function shortErr(error: unknown): string {
+    if (error instanceof Error) {
+        return error.name && error.name !== "Error"
+            ? `${error.name}: ${error.message}`
+            : error.message;
+    }
+    return extractMessage(error);
+}
+
+/**
+ * Try a single prompt attempt against the supplied body, with the existing
+ * single-suggestion retry layered inside (so "did you mean X?" still self-heals
+ * per attempt). Throws on failure; returns on success.
+ */
+async function attemptOnce(
+    client: Client,
+    args: PromptArgs,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+    callContext: string,
+    label: string,
+): Promise<void> {
+    try {
+        await promptWithTimeout(client, args, timeoutMs, signal);
+        return;
+    } catch (error) {
+        // If non-retryable (abort, overflow, timeout), bubble up immediately.
+        // Don't even try suggestion retry — caller needs the original error.
+        if (isNonRetryable(error, signal)) throw error;
+
+        const suggestion = parseModelSuggestion(error);
+        if (!suggestion || !args.body.model) {
+            // No suggestion available — caller's fallback loop will decide
+            // whether to try the next chain entry.
+            throw error;
+        }
+
+        log(`[${callContext}] ${label}: model not found, retrying with suggestion`, {
+            original: `${suggestion.providerID}/${suggestion.modelID}`,
+            suggested: suggestion.suggestion,
+        });
+
+        await promptWithTimeout(
+            client,
+            {
+                ...args,
+                body: {
+                    ...args.body,
+                    model: {
+                        providerID: suggestion.providerID,
+                        modelID: suggestion.suggestion,
+                    },
+                },
+            },
+            timeoutMs,
+            signal,
+        );
+    }
+}
+
+/**
+ * Run an OpenCode subagent prompt with model fallback support.
+ *
+ * Attempts the configured primary model first (whatever `args.body.model` or
+ * the registered agent default resolves to), then iterates through
+ * `options.fallbackModels` if provided. Each attempt internally retries once on
+ * the SDK's "model not found, did you mean X?" suggestion. Aborts, timeouts,
+ * and context-overflow errors short-circuit the fallback loop because retrying
+ * the same prompt against another model won't help.
+ *
+ * Behavior with `fallbackModels` empty/undefined is identical to the pre-v0.18
+ * single-suggestion retry — fully backward-compatible for callers that haven't
+ * been updated to thread a chain.
+ */
+export async function promptSyncWithModelSuggestionRetry(
+    client: Client,
+    args: PromptArgs,
+    options: PromptRetryOptions = {},
+): Promise<void> {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const callContext = options.callContext ?? "subagent";
+    const fallbacks = options.fallbackModels ?? [];
+
+    // Attempt 0 = whatever the agent or explicit body.model resolves to.
+    // Subsequent attempts override body.model with each fallback in order.
+    const explicitPrimaryLabel =
+        args.body.model?.providerID && args.body.model.modelID
+            ? `${args.body.model.providerID}/${args.body.model.modelID}`
+            : "primary";
+
+    let lastError: unknown = null;
+
+    try {
+        await attemptOnce(
+            client,
+            args,
+            timeoutMs,
+            options.signal,
+            callContext,
+            explicitPrimaryLabel,
+        );
+        return;
+    } catch (error) {
+        lastError = error;
+        if (isNonRetryable(error, options.signal)) throw error;
+
+        if (fallbacks.length === 0) {
+            // No fallbacks configured — behave exactly like legacy: propagate
+            // the original error (which may already have had its suggestion
+            // retry attempted inside `attemptOnce`).
+            throw error;
+        }
+
+        log(
+            `[${callContext}] primary (${explicitPrimaryLabel}) failed: ${shortErr(error)}; trying ${fallbacks.length} fallback(s)`,
+        );
+    }
+
+    // Iterate fallbacks.
+    for (let i = 0; i < fallbacks.length; i += 1) {
+        const parsed = parseProviderModel(fallbacks[i]);
+        if (!parsed) {
+            log(`[${callContext}] skipping invalid fallback spec: ${fallbacks[i]}`);
+            continue;
+        }
+
+        const label = `${parsed.providerID}/${parsed.modelID}`;
+        const attemptArgs: PromptArgs = {
+            ...args,
+            body: { ...args.body, model: parsed },
+        };
+
+        try {
+            await attemptOnce(client, attemptArgs, timeoutMs, options.signal, callContext, label);
+            log(
+                `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
+            );
+            return;
+        } catch (error) {
+            lastError = error;
+            if (isNonRetryable(error, options.signal)) throw error;
+
+            const remaining = fallbacks.length - i - 1;
+            if (remaining > 0) {
+                log(
+                    `[${callContext}] ${label} failed: ${shortErr(error)}; ${remaining} fallback(s) left`,
+                );
+            }
+        }
+    }
+
+    // All exhausted. Log the full chain and throw the last error so the
+    // caller's report (e.g. /ctx-dream tasks_json) still surfaces a real
+    // diagnostic.
+    log(
+        `[${callContext}] all models exhausted; tried: ${[explicitPrimaryLabel, ...fallbacks].join(", ")}; last error: ${shortErr(lastError)}`,
+    );
+    throw lastError ?? new Error("All fallback models failed");
+}