@cortexkit/opencode-magic-context 0.49.17 → 0.49.19

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

@@ -89,11 +89,26 @@ export interface PromptRetryOptions {
      *     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.
+     *     to handle these. The exception is an attempt cut by
+     *     `firstOutputTimeoutMs` (see there), which moves on to the next model.
      *   - On all-failed, the LAST error is thrown (matches legacy behavior when
      *     `fallbackModels` is empty).
      */
     fallbackModels?: readonly ModelInput[];
+    /**
+     * How long an attempt may go without the model producing anything (no
+     * streamed text, reasoning, tool call, or token usage) before the model is
+     * treated as hung. The attempt is then stopped and the next configured model
+     * runs with whatever is left of `timeoutMs`, so a dead model costs this
+     * bound instead of the whole timeout. An attempt that has produced output
+     * keeps its full timeout and, if that expires, still ends the chain.
+     *
+     * Applies only to an attempt that has a later model to move to, is capped at
+     * half that attempt's timeout so the next model keeps a usable share, and
+     * only works with transports that watch the child for output (OpenCode's
+     * `prompt_async` wait). Undefined = no first-output deadline.
+     */
+    firstOutputTimeoutMs?: number;
     /**
      * Identifier for structured logging (e.g. "dreamer:consolidate",
      * "historian", "compressor", "dreamer"). Helps correlate fallback
@@ -168,9 +183,53 @@ export function isHostTimeoutError(error: unknown): boolean {
     );
 }
 
+/**
+ * The model chain cut this attempt short because the model had produced nothing
+ * (no streamed text, reasoning, tool call, or token usage) by the first-output
+ * deadline. A model that has not answered at all is treated like a provider
+ * failure, so the next configured model gets the rest of the time.
+ */
+export class ModelProducedNoOutputError extends Error {
+    constructor(readonly waitedMs: number) {
+        // Keeps "timed out after Nms" so ledgers record the attempt as timed out.
+        super(`prompt timed out after ${waitedMs}ms with no model output`);
+        this.name = "ModelProducedNoOutputError";
+    }
+}
+
+/**
+ * What a transport has seen of the model during one attempt. `monitored` means
+ * the transport watches the child's messages and will set `received` as soon as
+ * the model streams anything. Transports that cannot see progress never set
+ * `monitored`, and the first-output deadline then never fires for them.
+ */
+interface ModelActivity {
+    monitored: boolean;
+    received: boolean;
+}
+
+/** Keyed by the per-attempt abort signal that `promptWithTimeout` hands the transport. */
+const modelActivityBySignal = new WeakMap<AbortSignal, ModelActivity>();
+
+/** A transport calls this once it is watching the child for model output. */
+export function noteModelActivityMonitored(signal: AbortSignal | undefined): void {
+    const activity = signal ? modelActivityBySignal.get(signal) : undefined;
+    if (activity) activity.monitored = true;
+}
+
+/** A transport calls this when it sees the model produce anything for this attempt. */
+export function noteModelOutputReceived(signal: AbortSignal | undefined): void {
+    const activity = signal ? modelActivityBySignal.get(signal) : undefined;
+    if (activity) {
+        activity.monitored = true;
+        activity.received = true;
+    }
+}
+
 /** Our own slice expiry (see `promptWithTimeout`) or a host request timer. */
 export function isPromptTimeoutError(error: unknown): boolean {
     if (isHostTimeoutError(error)) return true;
+    if (error instanceof ModelProducedNoOutputError) return true;
     return error instanceof Error && /^prompt timed out after \d+ms$/.test(error.message);
 }
 
@@ -275,6 +334,7 @@ async function promptWithTimeout(
     timeoutMs: number,
     signal?: AbortSignal,
     transport?: PromptTransport,
+    firstOutputTimeoutMs?: number,
 ): Promise<void> {
     // Bail immediately if the caller's signal is already aborted (e.g.
     // lease loss before this attempt was scheduled). Per spec
@@ -287,6 +347,23 @@ async function promptWithTimeout(
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const activity: ModelActivity = { monitored: false, received: false };
+    modelActivityBySignal.set(controller.signal, activity);
+    // Set when the first-output deadline, not the attempt timeout, ended the attempt.
+    let silent = false;
+    const firstOutputTimer =
+        firstOutputTimeoutMs !== undefined && firstOutputTimeoutMs < timeoutMs
+            ? setTimeout(() => {
+                  // Only a transport that watches the child can say the model is silent.
+                  if (!activity.monitored || activity.received) return;
+                  silent = true;
+                  controller.abort();
+              }, firstOutputTimeoutMs)
+            : undefined;
+    const timeoutError = () =>
+        silent && firstOutputTimeoutMs !== undefined
+            ? new ModelProducedNoOutputError(firstOutputTimeoutMs)
+            : new Error(`prompt timed out after ${timeoutMs}ms`);
 
     // Link external signal to internal controller so external abort cancels the fetch
     const onExternalAbort = () => controller.abort();
@@ -319,7 +396,7 @@ async function promptWithTimeout(
             if (!transport || transport.childSessionId) {
                 await abortChildRun(client, transport?.childSessionId ?? args.path.id);
             }
-            throw new Error(`prompt timed out after ${timeoutMs}ms`);
+            throw timeoutError();
         }
         if (isHostTimeoutError(error)) {
             // The host client's own request timer fired. Only our side of the
@@ -333,6 +410,7 @@ async function promptWithTimeout(
         throw error;
     } finally {
         clearTimeout(timeout);
+        if (firstOutputTimer) clearTimeout(firstOutputTimer);
         signal?.removeEventListener("abort", onExternalAbort);
     }
     // Some transports resolve with an error result when their fetch is aborted.
@@ -341,11 +419,7 @@ async function promptWithTimeout(
         if (!transport || transport.childSessionId) {
             await abortChildRun(client, transport?.childSessionId ?? args.path.id);
         }
-        throw new Error(
-            signal?.aborted
-                ? externalAbortMessage(signal)
-                : `prompt timed out after ${timeoutMs}ms`,
-        );
+        throw signal?.aborted ? new Error(externalAbortMessage(signal)) : timeoutError();
     }
 }
 
@@ -382,7 +456,12 @@ async function abortChildRun(client: Client, sessionId: string): Promise<void> {
  *     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).
+ *     level (e.g. historian's MAX_HISTORIAN_RETRIES loop). This covers an
+ *     attempt that ran out its whole time, whether or not the model answered.
+ *
+ * A `ModelProducedNoOutputError` is the exception: no output was observed
+ * before the first-output deadline, which points at the model rather than the
+ * prompt, so the chain gives the next model the time that is left.
  *
  * Everything else (auth errors, ProviderModelNotFoundError without suggestion,
  * rate limits, transient network failures, etc.) is considered retryable on a
@@ -397,6 +476,8 @@ function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
     )
         return true;
 
+    if (error instanceof ModelProducedNoOutputError) return false;
+
     if (error instanceof Error) {
         if (error.name === "AbortError") return true;
         // promptWithTimeout wraps both abort cases in plain `Error` with a
@@ -442,7 +523,11 @@ function classifyPromptFailure(
     if (externalSignal?.aborted || message === "prompt aborted by external signal") {
         return "child_aborted";
     }
-    if (/^prompt timed out after \d+ms$/.test(message) || isHostTimeoutError(error)) {
+    if (
+        error instanceof ModelProducedNoOutputError ||
+        /^prompt timed out after \d+ms$/.test(message) ||
+        isHostTimeoutError(error)
+    ) {
         return "provider_timeout";
     }
     if (phase === "validation") {
@@ -513,6 +598,7 @@ async function attemptOnce(
     label: string,
     transport?: PromptTransport,
     allowModelSuggestions = true,
+    firstOutputTimeoutMs?: number,
 ): Promise<void> {
     // Keep this snapshot separate from the object passed to the client. A
     // failed prompt facade may rewrite its request body before rejecting; the
@@ -520,7 +606,14 @@ async function attemptOnce(
     const originalBody = { ...args.body };
     const attemptArgs = copyPromptArgs(args, originalBody);
     try {
-        await promptWithTimeout(client, attemptArgs, timeoutMs, signal, transport);
+        await promptWithTimeout(
+            client,
+            attemptArgs,
+            timeoutMs,
+            signal,
+            transport,
+            firstOutputTimeoutMs,
+        );
         return;
     } catch (error) {
         // Non-retryable failures and callers with model suggestions disabled
@@ -551,10 +644,48 @@ async function attemptOnce(
             timeoutMs,
             signal,
             transport,
+            firstOutputTimeoutMs,
         );
     }
 }
 
+/**
+ * Per-attempt timing across one model chain. An attempt cut by the first-output
+ * deadline has the time it used taken out of every later attempt's timeout, so
+ * a silent model never stretches the caller's overall wait past `timeoutMs`.
+ * Attempts that fail for other reasons keep the existing full per-attempt budget.
+ */
+function createChainClock(options: PromptRetryOptions, timeoutMs: number) {
+    const fallbacks = options.fallbackModels ?? [];
+    const hasValidFallbackFrom = (index: number) =>
+        fallbacks.slice(index).some((fallback) => {
+            const entry = toModelEntry(fallback);
+            return entry ? parseProviderModel(entry.model) !== null : false;
+        });
+    let silentSpentMs = 0;
+    return {
+        /** Budget for an attempt whose next candidate is `fallbacks[nextFallbackIndex]`. */
+        budget(nextFallbackIndex: number): { timeoutMs: number; firstOutputTimeoutMs?: number } {
+            const attemptTimeoutMs = Math.max(1, timeoutMs - silentSpentMs);
+            // The last model in the chain has nothing to move to, so it keeps the
+            // plain timeout rather than being cut short for no benefit.
+            if (
+                options.firstOutputTimeoutMs === undefined ||
+                !hasValidFallbackFrom(nextFallbackIndex)
+            )
+                return { timeoutMs: attemptTimeoutMs };
+            const bound = Math.min(options.firstOutputTimeoutMs, Math.floor(attemptTimeoutMs / 2));
+            return bound > 0
+                ? { timeoutMs: attemptTimeoutMs, firstOutputTimeoutMs: bound }
+                : { timeoutMs: attemptTimeoutMs };
+        },
+        settle(error: unknown, startedAt: number): void {
+            if (error instanceof ModelProducedNoOutputError)
+                silentSpentMs += Date.now() - startedAt;
+        },
+    };
+}
+
 /**
  * Run an OpenCode subagent prompt with model fallback support.
  *
@@ -591,21 +722,26 @@ export async function promptSyncWithModelSuggestionRetry(
             : "primary";
 
     let lastError: unknown = null;
+    const clock = createChainClock(options, timeoutMs);
 
+    const primaryStartedAt = Date.now();
     try {
+        const budget = clock.budget(0);
         await attemptOnce(
             client,
             baseArgs,
-            timeoutMs,
+            budget.timeoutMs,
             options.signal,
             callContext,
             explicitPrimaryLabel,
             options.transport,
             options.allowModelSuggestions,
+            budget.firstOutputTimeoutMs,
         );
         return;
     } catch (error) {
         lastError = error;
+        clock.settle(error, primaryStartedAt);
         if (isNonRetryable(error, options.signal)) throw error;
 
         if (fallbacks.length === 0) {
@@ -637,16 +773,19 @@ export async function promptSyncWithModelSuggestionRetry(
             ...(fallback?.qualifier ? { variant: fallback.qualifier } : {}),
         });
 
+        const attemptStartedAt = Date.now();
         try {
+            const budget = clock.budget(i + 1);
             await attemptOnce(
                 client,
                 attemptArgs,
-                timeoutMs,
+                budget.timeoutMs,
                 options.signal,
                 callContext,
                 label,
                 options.transport,
                 options.allowModelSuggestions,
+                budget.firstOutputTimeoutMs,
             );
             log(
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
@@ -654,6 +793,7 @@ export async function promptSyncWithModelSuggestionRetry(
             return;
         } catch (error) {
             lastError = error;
+            clock.settle(error, attemptStartedAt);
             if (isNonRetryable(error, options.signal)) throw error;
 
             const remaining = fallbacks.length - i - 1;
@@ -682,6 +822,7 @@ async function attemptAndValidate<TOutput, TValidated>(
     callContext: string,
     attempt: PromptAttemptInfo,
     options: ValidatedPromptRetryOptions<TOutput, TValidated>,
+    firstOutputTimeoutMs?: number,
 ): Promise<ValidatedPromptRetryResult<TOutput, TValidated>> {
     try {
         await attemptOnce(
@@ -693,6 +834,7 @@ async function attemptAndValidate<TOutput, TValidated>(
             attempt.label,
             options.transport,
             options.allowModelSuggestions,
+            firstOutputTimeoutMs,
         );
     } catch (error) {
         throw {
@@ -779,7 +921,9 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
     let firstError: unknown = null;
     let lastError: unknown = null;
     const cooledPrimary = primaryQuotaFailure(explicitPrimaryLabel);
+    const clock = createChainClock(options, timeoutMs);
 
+    const primaryStartedAt = Date.now();
     try {
         if (cooledPrimary)
             throw {
@@ -794,10 +938,11 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
                     skipped: true,
                 },
             } satisfies FailedAttempt;
+        const budget = clock.budget(0);
         return await attemptAndValidate(
             client,
             baseArgs,
-            timeoutMs,
+            budget.timeoutMs,
             options.signal,
             callContext,
             {
@@ -808,10 +953,12 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
                 model: baseBody.model,
             },
             options,
+            budget.firstOutputTimeoutMs,
         );
     } catch (caught) {
         const failure = caught as FailedAttempt;
         failedAttempts.push(failure);
+        clock.settle(failure.error, primaryStartedAt);
         firstError = failure.error;
         lastError = failure.error;
         if (
@@ -876,15 +1023,18 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
             model: parsed,
         };
 
+        const attemptStartedAt = Date.now();
         try {
+            const budget = clock.budget(i + 1);
             const result = await attemptAndValidate(
                 client,
                 attemptArgs,
-                timeoutMs,
+                budget.timeoutMs,
                 options.signal,
                 callContext,
                 attempt,
                 options,
+                budget.firstOutputTimeoutMs,
             );
             log(
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
@@ -893,6 +1043,7 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
         } catch (caught) {
             const failure = caught as FailedAttempt;
             failedAttempts.push(failure);
+            clock.settle(failure.error, attemptStartedAt);
             lastError = failure.error;
             if (isNonRetryable(failure.error, options.signal)) {
                 throwWithPromptFailure(

package/src/shared/prompt-async-transport.test.ts

@@ -645,3 +645,110 @@ test("session errors belonging to another child do not fail the run", async () =
     await promptAsyncAndWaitForIdle(host.client, request(), { pollIntervalMs: 1 });
     expect(host.polls()).toBe(1);
 });
+
+describe("prompt_async transport and the first-output deadline", () => {
+    /**
+     * A child session where each model answers its own way. "dead" leaves the
+     * empty assistant row the host writes before the provider responds and stays
+     * busy forever; "partial" streams a text part and then stays busy; "answer"
+     * settles with a final assistant message on the next poll.
+     */
+    function modelHost(behaviours: Record<string, "dead" | "partial" | "answer">) {
+        const messages: Message[] = [];
+        let current: "dead" | "partial" | "answer" | null = null;
+        const sent: string[] = [];
+        const promptAsync = mock(
+            async (request: { body: { model?: { providerID: string; modelID: string } } }) => {
+                const model = request.body.model
+                    ? `${request.body.model.providerID}/${request.body.model.modelID}`
+                    : "primary";
+                sent.push(model);
+                current = behaviours[model] ?? "answer";
+                messages.push({
+                    info: { id: `msg_user_${messages.length}`, role: "user", time: { created: 1 } },
+                    parts: [{ type: "text", text: "go" }],
+                });
+                messages.push({
+                    info: {
+                        id: `msg_assistant_${messages.length}`,
+                        role: "assistant",
+                        time: { created: 2 },
+                    },
+                    parts: current === "partial" ? [{ type: "text", text: "<classify>" }] : [],
+                });
+                return { data: undefined };
+            },
+        );
+        const abort = mock(async () => {
+            current = null;
+            return { data: true };
+        });
+        const status = mock(async () => {
+            if (current === "dead" || current === "partial")
+                return { data: { "ses-child": { type: "busy" } } };
+            if (current === "answer") {
+                const last = messages.at(-1);
+                if (last && !last.info.time.completed) {
+                    last.info.time.completed = 3;
+                    last.info.finish = "stop";
+                    last.parts = [{ type: "text", text: "<classify></classify>" }];
+                }
+            }
+            return { data: {} };
+        });
+        const list = mock(async () => ({ data: messages.map((message) => ({ ...message })) }));
+        return {
+            client: { session: { promptAsync, abort, status, messages: list } } as never,
+            sent,
+            abort,
+        };
+    }
+
+    async function runChain(
+        host: ReturnType<typeof modelHost>,
+        timeoutMs: number,
+        firstOutputTimeoutMs: number,
+    ) {
+        const transport = createPromptAsyncTransport(host.client, "ses-child", {
+            pollIntervalMs: 5,
+        });
+        return promptSyncWithValidatedOutputRetry(
+            host.client,
+            {
+                ...request(),
+                body: {
+                    model: { providerID: "opencode", modelID: "free-model" },
+                    parts: [{ type: "text", text: "go" }],
+                },
+            },
+            {
+                transport,
+                timeoutMs,
+                firstOutputTimeoutMs,
+                fallbackModels: ["anthropic/claude-sonnet-5-5"],
+                fetchOutput: async () => "<classify></classify>",
+                validateOutput: (output: string) => output,
+            },
+        );
+    }
+
+    test("a model that never answers is cut at the deadline and the fallback completes", async () => {
+        const host = modelHost({ "opencode/free-model": "dead" });
+        const startedAt = Date.now();
+
+        const run = await runChain(host, 5_000, 60);
+
+        expect(run.attempt.label).toBe("anthropic/claude-sonnet-5-5");
+        expect(host.sent).toEqual(["opencode/free-model", "anthropic/claude-sonnet-5-5"]);
+        // The dead model's run is stopped on the host before the fallback is sent.
+        expect(host.abort).toHaveBeenCalledWith({ path: { id: "ses-child" } });
+        expect(Date.now() - startedAt).toBeLessThan(2_000);
+    });
+
+    test("a model that streamed part of an answer keeps its timeout and does not fall back", async () => {
+        const host = modelHost({ "opencode/free-model": "partial" });
+
+        await expect(runChain(host, 200, 40)).rejects.toThrow("prompt timed out after 200ms");
+        expect(host.sent).toEqual(["opencode/free-model"]);
+    });
+});

package/src/shared/prompt-async-transport.ts

@@ -11,6 +11,7 @@ import { sumTokensFromChildMessages } from "../features/magic-context/subagent-t
 import { describeAssistantError } from "./assistant-message-extractor";
 import { sessionLog } from "./logger";
 import type { PromptArgs, PromptTransport } from "./model-suggestion-retry";
+import { noteModelActivityMonitored, noteModelOutputReceived } from "./model-suggestion-retry";
 
 type Client = ReturnType<typeof createOpencodeClient> | undefined;
 
@@ -202,6 +203,29 @@ function isTerminalAssistant(message: unknown): boolean {
     );
 }
 
+/**
+ * True when an assistant row shows the model has answered: any token usage, or a
+ * non-empty text or reasoning part, or a tool call. A row the host creates before
+ * the provider responds carries none of these.
+ */
+function showsModelOutput(message: unknown): boolean {
+    if (infoOf(message).role !== "assistant") return false;
+    const tokens = sumTokensFromChildMessages([message]);
+    if (tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite > 0) return true;
+    const parts = (message as { parts?: unknown } | null)?.parts;
+    if (!Array.isArray(parts)) return false;
+    return parts.some((part) => {
+        if (!part || typeof part !== "object") return false;
+        const { type, text } = part as { type?: unknown; text?: unknown };
+        if (type === "tool") return true;
+        return (
+            (type === "text" || type === "reasoning") &&
+            typeof text === "string" &&
+            text.trim().length > 0
+        );
+    });
+}
+
 function unwrapData(response: unknown): unknown {
     if (response && typeof response === "object" && "data" in response) {
         return (response as { data?: unknown }).data;
@@ -324,6 +348,10 @@ export async function promptAsyncAndWaitForIdle(
         }
         let sentAt = Date.now();
         let sawBusy = false;
+        // From here on this wait reports whether the model has produced anything,
+        // which lets the model chain tell a silent model from a slow answer.
+        noteModelActivityMonitored(signal);
+        let sawOutput = false;
 
         for (;;) {
             await sleep(pollIntervalMs, signal);
@@ -341,6 +369,17 @@ export async function promptAsyncAndWaitForIdle(
             }
             const status = await readStatus(session, sessionId, dir, signal);
             const messages = await readMessages(session, sessionId, dir, signal);
+            if (
+                !sawOutput &&
+                messages.some((message) => {
+                    const id = messageId(message);
+                    // Rows from before this send belong to an earlier attempt.
+                    return id !== null && !initialBaseline.has(id) && showsModelOutput(message);
+                })
+            ) {
+                sawOutput = true;
+                noteModelOutputReceived(signal);
+            }
             if (budget) {
                 const latest = messages.at(-1);
                 const latestId = messageId(latest);