@link-assistant/agent 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/auth/plugins.ts

@@ -1542,9 +1542,12 @@ const GooglePlugin: AuthPlugin = {
 
     /**
      * Check if a response status is retryable (transient error).
+     * Includes 500/502 for intermittent server errors (#231).
      */
     const isRetryableStatus = (status: number): boolean => {
-      return status === 429 || status === 503;
+      return (
+        status === 429 || status === 500 || status === 502 || status === 503
+      );
     };
 
     /**

package/src/cli/argv.ts

@@ -69,3 +69,14 @@ export function getCompactionModelFromProcessArgv(): string | null {
 export function getCompactionSafetyMarginFromProcessArgv(): string | null {
   return getArgFromProcessArgv('compaction-safety-margin');
 }
+
+/**
+ * Extract --compaction-models argument directly from process.argv
+ * The value is a links notation references sequence, e.g.:
+ *   "(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)"
+ * @returns The compaction models argument from CLI or null if not found
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+export function getCompactionModelsFromProcessArgv(): string | null {
+  return getArgFromProcessArgv('compaction-models');
+}

package/src/cli/defaults.ts

@@ -6,7 +6,7 @@
  */
 
 /** Default model used when no `--model` CLI argument is provided. */
-export const DEFAULT_MODEL = 'opencode/minimax-m2.5-free';
+export const DEFAULT_MODEL = 'opencode/qwen3.6-plus-free';
 
 /** Default provider ID extracted from DEFAULT_MODEL. */
 export const DEFAULT_PROVIDER_ID = DEFAULT_MODEL.split('/')[0];
@@ -23,6 +23,29 @@ export const DEFAULT_MODEL_ID = DEFAULT_MODEL.split('/').slice(1).join('/');
  */
 export const DEFAULT_COMPACTION_MODEL = 'opencode/gpt-5-nano';
 
+/**
+ * Default compaction models cascade, ordered from smallest/cheapest context to largest.
+ * During compaction, the system tries each model in order. If the used context exceeds
+ * a model's context limit, it skips to the next larger model. If a model's rate limit
+ * is reached, it also skips to the next model.
+ * The special value "same" means use the same model as `--model`.
+ *
+ * Parsed as links notation references sequence (single anonymous link):
+ *   "(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)"
+ *
+ * Context limits (approximate):
+ *   big-pickle:            ~200K
+ *   nemotron-3-super-free: ~262K
+ *   minimax-m2.5-free:     ~200K
+ *   gpt-5-nano:            ~400K
+ *   qwen3.6-plus-free:     ~1M
+ *   same:                  (base model's context)
+ *
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+export const DEFAULT_COMPACTION_MODELS =
+  '(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)';
+
 /**
  * Default compaction safety margin as a percentage of usable context window.
  * Applied only when the compaction model has a context window equal to or smaller

package/src/cli/model-config.js

@@ -1,6 +1,7 @@
 import {
   getModelFromProcessArgv,
   getCompactionModelFromProcessArgv,
+  getCompactionModelsFromProcessArgv,
   getCompactionSafetyMarginFromProcessArgv,
 } from './argv.ts';
 import { Log } from '../util/log.ts';
@@ -8,6 +9,7 @@ import {
   DEFAULT_PROVIDER_ID,
   DEFAULT_MODEL_ID,
   DEFAULT_COMPACTION_MODEL,
+  DEFAULT_COMPACTION_MODELS,
   DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT,
 } from './defaults.ts';
 
@@ -68,29 +70,39 @@ export async function parseModelConfig(argv, outputError, outputStatus) {
       modelID,
     }));
 
-    // Validate that the model exists in the provider (#196)
-    // Without this check, a non-existent model silently proceeds and fails at API call time
-    // with confusing "reason: unknown" and zero tokens
+    // Validate that the model exists in the provider (#196, #231)
+    // If user explicitly specified provider/model and the model is not found,
+    // fail immediately instead of silently falling back to a different model.
     try {
       const { Provider } = await import('../provider/provider.ts');
       const s = await Provider.state();
       const provider = s.providers[providerID];
       if (provider && !provider.info.models[modelID]) {
-        // Provider exists but model doesn't - warn and suggest alternatives
-        const availableModels = Object.keys(provider.info.models).slice(0, 5);
-        Log.Default.warn(() => ({
+        // Provider exists but model doesn't — fail with a clear error (#231)
+        // Silent fallback caused kimi-k2.5-free to be routed to minimax-m2.5-free
+        const availableModels = Object.keys(provider.info.models).slice(0, 10);
+        Log.Default.error(() => ({
           message:
-            'model not found in provider - will attempt anyway (provider may support unlisted models)',
+            'model not found in provider — refusing to proceed with explicit provider/model',
           providerID,
           modelID,
           availableModels,
         }));
+        throw new Error(
+          `Model "${modelID}" not found in provider "${providerID}". ` +
+            `Available models include: ${availableModels.join(', ')}. ` +
+            `Use --model ${providerID}/<model-id> with a valid model, or omit the provider prefix for auto-resolution.`
+        );
       }
     } catch (validationError) {
-      // Don't fail on validation errors - the model may still work
-      // This is a best-effort check
+      // Re-throw if this is our own validation error (not an infrastructure issue)
+      if (validationError?.message?.includes('not found in provider')) {
+        throw validationError;
+      }
+      // For infrastructure errors (e.g. can't load provider state), log and continue
       Log.Default.info(() => ({
-        message: 'skipping model existence validation',
+        message:
+          'skipping model existence validation due to infrastructure error',
         reason: validationError?.message,
       }));
     }
@@ -163,20 +175,71 @@ export async function parseModelConfig(argv, outputError, outputStatus) {
   return { providerID, modelID, compactionModel: compactionModelResult };
 }
 
+/**
+ * Parse a links notation references sequence string into an array of model names.
+ * Format: "(model1 model2 model3)" — parenthesized space-separated list.
+ * @param {string} notation - Links notation sequence string
+ * @returns {string[]} Array of model name strings
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+function parseLinksNotationSequence(notation) {
+  const trimmed = notation.trim();
+  // Remove surrounding parentheses if present
+  const inner =
+    trimmed.startsWith('(') && trimmed.endsWith(')')
+      ? trimmed.slice(1, -1)
+      : trimmed;
+  // Split on whitespace and filter empty strings
+  return inner.split(/\s+/).filter((s) => s.length > 0);
+}
+
+/**
+ * Resolve a single compaction model entry (short name, provider/model, or "same").
+ * @returns {{ providerID: string, modelID: string, useSameModel: boolean }}
+ */
+async function resolveCompactionModelEntry(
+  modelArg,
+  baseProviderID,
+  baseModelID
+) {
+  const useSameModel = modelArg.toLowerCase() === 'same';
+
+  if (useSameModel) {
+    return {
+      providerID: baseProviderID,
+      modelID: baseModelID,
+      useSameModel: true,
+    };
+  }
+
+  if (modelArg.includes('/')) {
+    const parts = modelArg.split('/');
+    return {
+      providerID: parts[0],
+      modelID: parts.slice(1).join('/'),
+      useSameModel: false,
+    };
+  }
+
+  // Short name resolution
+  const { Provider } = await import('../provider/provider.ts');
+  const resolved = await Provider.parseModelWithResolution(modelArg);
+  return {
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    useSameModel: false,
+  };
+}
+
 /**
  * Parse compaction model config from argv.
- * Resolves --compaction-model and --compaction-safety-margin CLI arguments.
+ * Supports both --compaction-model (single) and --compaction-models (cascade).
+ * When --compaction-models is specified, it overrides --compaction-model.
  * The special value "same" means use the base model for compaction.
  * @see https://github.com/link-assistant/agent/issues/219
+ * @see https://github.com/link-assistant/agent/issues/232
  */
 async function parseCompactionModelConfig(argv, baseProviderID, baseModelID) {
-  // Get compaction model from CLI (safeguard against yargs caching)
-  const cliCompactionModelArg = getCompactionModelFromProcessArgv();
-  const compactionModelArg =
-    cliCompactionModelArg ??
-    argv['compaction-model'] ??
-    DEFAULT_COMPACTION_MODEL;
-
   // Get safety margin from CLI
   const cliSafetyMarginArg = getCompactionSafetyMarginFromProcessArgv();
   const compactionSafetyMarginPercent = cliSafetyMarginArg
@@ -184,49 +247,97 @@ async function parseCompactionModelConfig(argv, baseProviderID, baseModelID) {
     : (argv['compaction-safety-margin'] ??
       DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT);
 
-  // Special "same" alias — use the base model for compaction
-  const useSameModel = compactionModelArg.toLowerCase() === 'same';
+  // Check for --compaction-models (cascade) first — it overrides --compaction-model
+  const cliCompactionModelsArg = getCompactionModelsFromProcessArgv();
+  const compactionModelsArg =
+    cliCompactionModelsArg ??
+    argv['compaction-models'] ??
+    DEFAULT_COMPACTION_MODELS;
 
-  let compactionProviderID;
-  let compactionModelID;
+  // Parse the links notation sequence into an array of model names
+  const modelNames = parseLinksNotationSequence(compactionModelsArg);
+
+  if (modelNames.length > 0) {
+    // Resolve each model in the cascade
+    const compactionModels = [];
+    for (const name of modelNames) {
+      try {
+        const resolved = await resolveCompactionModelEntry(
+          name,
+          baseProviderID,
+          baseModelID
+        );
+        compactionModels.push({
+          providerID: resolved.providerID,
+          modelID: resolved.modelID,
+          useSameModel: resolved.useSameModel,
+        });
+      } catch (err) {
+        // If a model can't be resolved, log and skip it
+        Log.Default.warn(() => ({
+          message: 'skipping unresolvable compaction model in cascade',
+          model: name,
+          error: err?.message,
+        }));
+      }
+    }
 
-  if (useSameModel) {
-    compactionProviderID = baseProviderID;
-    compactionModelID = baseModelID;
-    Log.Default.info(() => ({
-      message:
-        'compaction model set to "same" — using base model for compaction',
-      compactionProviderID,
-      compactionModelID,
-    }));
-  } else if (compactionModelArg.includes('/')) {
-    const parts = compactionModelArg.split('/');
-    compactionProviderID = parts[0];
-    compactionModelID = parts.slice(1).join('/');
-    Log.Default.info(() => ({
-      message: 'using explicit compaction model',
-      compactionProviderID,
-      compactionModelID,
-    }));
-  } else {
-    // Short name resolution
-    const { Provider } = await import('../provider/provider.ts');
-    const resolved =
-      await Provider.parseModelWithResolution(compactionModelArg);
-    compactionProviderID = resolved.providerID;
-    compactionModelID = resolved.modelID;
     Log.Default.info(() => ({
-      message: 'resolved short compaction model name',
-      input: compactionModelArg,
-      compactionProviderID,
-      compactionModelID,
+      message: 'compaction models cascade configured',
+      models: compactionModels.map((m) =>
+        m.useSameModel ? 'same' : `${m.providerID}/${m.modelID}`
+      ),
+      source: cliCompactionModelsArg ? 'cli' : 'default',
     }));
+
+    // Use the first model as the primary compaction model (for backward compatibility)
+    // The full cascade is stored in compactionModels array
+    const primary = compactionModels[0] || {
+      providerID: baseProviderID,
+      modelID: baseModelID,
+      useSameModel: true,
+    };
+
+    return {
+      providerID: primary.providerID,
+      modelID: primary.modelID,
+      useSameModel: primary.useSameModel,
+      compactionSafetyMarginPercent,
+      compactionModels,
+    };
   }
 
+  // Fallback to single --compaction-model
+  const cliCompactionModelArg = getCompactionModelFromProcessArgv();
+  const compactionModelArg =
+    cliCompactionModelArg ??
+    argv['compaction-model'] ??
+    DEFAULT_COMPACTION_MODEL;
+
+  const resolved = await resolveCompactionModelEntry(
+    compactionModelArg,
+    baseProviderID,
+    baseModelID
+  );
+
+  Log.Default.info(() => ({
+    message: 'using single compaction model',
+    compactionProviderID: resolved.providerID,
+    compactionModelID: resolved.modelID,
+    useSameModel: resolved.useSameModel,
+  }));
+
   return {
-    providerID: compactionProviderID,
-    modelID: compactionModelID,
-    useSameModel,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    useSameModel: resolved.useSameModel,
     compactionSafetyMarginPercent,
+    compactionModels: [
+      {
+        providerID: resolved.providerID,
+        modelID: resolved.modelID,
+        useSameModel: resolved.useSameModel,
+      },
+    ],
   };
 }

package/src/cli/run-options.js

@@ -1,6 +1,7 @@
 import {
   DEFAULT_MODEL,
   DEFAULT_COMPACTION_MODEL,
+  DEFAULT_COMPACTION_MODELS,
   DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT,
 } from './defaults.ts';
 
@@ -151,9 +152,17 @@ export function buildRunOptions(yargs) {
     .option('compaction-model', {
       type: 'string',
       description:
-        'Model to use for context compaction in format providerID/modelID. Use "same" to use the base model. Default: opencode/gpt-5-nano (free, 400K context).',
+        'Model to use for context compaction in format providerID/modelID. Use "same" to use the base model. Default: opencode/gpt-5-nano (free, 400K context). Overridden by --compaction-models if both are specified.',
       default: DEFAULT_COMPACTION_MODEL,
     })
+    .option('compaction-models', {
+      type: 'string',
+      description:
+        'Ordered cascade of compaction models in links notation sequence format: "(model1 model2 ... same)". ' +
+        "Models are tried from smallest/cheapest context to largest. If used context exceeds a model's limit or its rate limit is reached, the next model is tried. " +
+        'The special value "same" uses the base model. Overrides --compaction-model when specified.',
+      default: DEFAULT_COMPACTION_MODELS,
+    })
     .option('compaction-safety-margin', {
       type: 'number',
       description:

package/src/index.js

@@ -27,7 +27,10 @@ import { McpCommand } from './cli/cmd/mcp.ts';
 import { AuthCommand } from './cli/cmd/auth.ts';
 import { FormatError } from './cli/error.ts';
 import { UI } from './cli/ui.ts';
-import { createVerboseFetch } from './util/verbose-fetch.ts';
+import {
+  createVerboseFetch,
+  registerPendingStreamLogExitHandler,
+} from './util/verbose-fetch.ts';
 import {
   runContinuousServerMode,
   runContinuousDirectMode,
@@ -822,6 +825,8 @@ async function main() {
             caller: 'global',
           });
           globalThis.__agentVerboseFetchInstalled = true;
+          // Register handler to warn about pending stream logs at process exit (#231)
+          registerPendingStreamLogExitHandler();
         }
       })
       .fail((msg, err, yargs) => {

package/src/provider/provider.ts

@@ -1623,35 +1623,30 @@ export namespace Provider {
     }
 
     if (!isSyntheticProvider && !info) {
-      // Still not found after refresh - create fallback info and try anyway
-      // Provider may support unlisted models
+      // Model not found even after cache refresh — fail with a clear error (#231)
+      // Previously this created synthetic fallback info, which allowed the API call
+      // to proceed with the wrong model (e.g., kimi-k2.5-free routed to minimax-m2.5-free)
       const availableInProvider = Object.keys(provider.info.models).slice(
         0,
         10
       );
-      log.warn(() => ({
+      log.error(() => ({
         message:
-          'model not in provider catalog after refresh - attempting anyway (may be unlisted)',
+          'model not found in provider catalog after refresh — refusing to proceed',
         providerID,
         modelID,
         availableModels: availableInProvider,
         totalModels: Object.keys(provider.info.models).length,
       }));
 
-      // Create a minimal fallback model info so SDK loading can proceed
-      // Use sensible defaults - the provider will reject if the model truly doesn't exist
-      info = {
-        id: modelID,
-        name: modelID,
-        release_date: '',
-        attachment: false,
-        reasoning: false,
-        temperature: true,
-        tool_call: true,
-        cost: { input: 0, output: 0 },
-        limit: { context: 128000, output: 16384 },
-        options: {},
-      } as ModelsDev.Model;
+      throw new ModelNotFoundError({
+        providerID,
+        modelID,
+        suggestion:
+          `Model "${modelID}" not found in provider "${providerID}" (checked ${Object.keys(provider.info.models).length} models). ` +
+          `Available models include: ${availableInProvider.join(', ')}. ` +
+          `Use --model ${providerID}/<model-id> with a valid model.`,
+      });
     }
 
     try {
@@ -1736,7 +1731,13 @@ export namespace Provider {
       priority = priority.filter((m) => m !== 'claude-haiku-4.5');
     }
     if (providerID === 'opencode' || providerID === 'local') {
-      priority = ['minimax-m2.5-free', 'gpt-5-nano', 'big-pickle'];
+      priority = [
+        'qwen3.6-plus-free',
+        'minimax-m2.5-free',
+        'gpt-5-nano',
+        'nemotron-3-super-free',
+        'big-pickle',
+      ];
     }
     if (providerID === 'kilo') {
       priority = [
@@ -1763,7 +1764,9 @@ export namespace Provider {
   }
 
   const priority = [
+    'qwen3.6-plus-free',
     'glm-5-free',
+    'nemotron-3-super-free',
     'minimax-m2.5-free',
     'gpt-5-nano',
     'big-pickle',
@@ -1846,7 +1849,7 @@ export namespace Provider {
    * 1. If model is uniquely available in one provider, use that provider
    * 2. If model is available in multiple providers, prioritize based on free model availability:
    *    - kilo: glm-5-free, glm-4.5-air-free, minimax-m2.5-free, giga-potato-free, deepseek-r1-free (unique to Kilo)
-   *    - opencode: big-pickle, gpt-5-nano (unique to OpenCode)
+   *    - opencode: big-pickle, gpt-5-nano, qwen3.6-plus-free, nemotron-3-super-free (unique to OpenCode)
    * 3. For shared models, prefer OpenCode first, then fall back to Kilo on rate limit
    *
    * @param modelID - Short model name without provider prefix

package/src/provider/retry-fetch.ts

@@ -2,10 +2,11 @@ import { Log } from '../util/log';
 import { config } from '../config/config';
 
 /**
- * Custom fetch wrapper that handles rate limits (HTTP 429) using time-based retry logic.
+ * Custom fetch wrapper that handles rate limits (HTTP 429) and server errors (HTTP 5xx)
+ * using time-based retry logic.
  *
- * This wrapper intercepts 429 responses at the HTTP level before the AI SDK's internal
- * retry mechanism can interfere. It respects:
+ * This wrapper intercepts 429 and 5xx responses at the HTTP level before the AI SDK's
+ * internal retry mechanism can interfere. It respects:
  * - retry-after headers (both seconds and HTTP date formats)
  * - retry-after-ms header for millisecond precision
  * - LINK_ASSISTANT_AGENT_RETRY_TIMEOUT for global time-based retry limit
@@ -15,10 +16,12 @@ import { config } from '../config/config';
  * The AI SDK's internal retry uses a fixed count (default 3 attempts) and ignores
  * retry-after headers. When providers return long retry-after values (e.g., 64 minutes),
  * the SDK exhausts its retries before the agent can properly wait.
+ * Additionally, server errors (500, 502, 503) from providers like OpenCode API were not
+ * retried, causing compaction cycles to be lost silently.
  *
  * Solution:
- * By wrapping fetch, we handle rate limits at the HTTP layer with time-based retries,
- * ensuring the agent's 7-week global timeout is respected.
+ * By wrapping fetch, we handle rate limits and server errors at the HTTP layer with
+ * time-based retries, ensuring the agent's 7-week global timeout is respected.
  *
  * Important: Rate limit waits use ISOLATED AbortControllers that are NOT subject to
  * provider/stream timeouts. This prevents long rate limit waits (e.g., 15 hours) from
@@ -26,6 +29,7 @@ import { config } from '../config/config';
  *
  * @see https://github.com/link-assistant/agent/issues/167
  * @see https://github.com/link-assistant/agent/issues/183
+ * @see https://github.com/link-assistant/agent/issues/231
  * @see https://github.com/vercel/ai/issues/12585
  */
 
@@ -37,6 +41,20 @@ export namespace RetryFetch {
   const RETRY_BACKOFF_FACTOR = 2;
   const RETRY_MAX_DELAY_NO_HEADERS = 30_000;
 
+  // Maximum number of retries for server errors (5xx) — unlike rate limits (429)
+  // which retry indefinitely within the global timeout, server errors use a fixed
+  // retry count to avoid retrying permanently broken endpoints (#231)
+  const SERVER_ERROR_MAX_RETRIES = 3;
+
+  /**
+   * Check if an HTTP status code is a retryable server error.
+   * Retries on 500 (Internal Server Error), 502 (Bad Gateway), and 503 (Service Unavailable).
+   * @see https://github.com/link-assistant/agent/issues/231
+   */
+  function isRetryableServerError(status: number): boolean {
+    return status === 500 || status === 502 || status === 503;
+  }
+
   // Minimum retry interval to prevent rapid retries (default: 30 seconds)
   // Can be configured via AGENT_MIN_RETRY_INTERVAL env var
   function getMinRetryInterval(): number {
@@ -298,19 +316,20 @@ export namespace RetryFetch {
   };
 
   /**
-   * Create a fetch function that handles rate limits with time-based retry logic.
+   * Create a fetch function that handles rate limits and server errors with retry logic.
    *
    * This wrapper:
-   * 1. Intercepts HTTP 429 responses
-   * 2. Parses retry-after headers
-   * 3. Waits for the specified duration (respecting global timeout)
-   * 4. Retries the request
+   * 1. Intercepts HTTP 429 (rate limit) responses — retries with retry-after headers
+   * 2. Intercepts HTTP 500/502/503 (server error) responses — retries up to SERVER_ERROR_MAX_RETRIES
+   * 3. Parses retry-after headers for 429 responses
+   * 4. Uses exponential backoff for server errors and network errors
+   * 5. Respects global LINK_ASSISTANT_AGENT_RETRY_TIMEOUT for all retries
    *
    * If retry-after exceeds LINK_ASSISTANT_AGENT_RETRY_TIMEOUT, the original 429 response is returned
    * to let higher-level error handling take over.
    *
    * @param options Configuration options
-   * @returns A fetch function with rate limit retry handling
+   * @returns A fetch function with rate limit and server error retry handling
    */
   export function create(options: RetryFetchOptions = {}): typeof fetch {
     const baseFetch = options.baseFetch ?? fetch;
@@ -365,7 +384,74 @@ export namespace RetryFetch {
           throw error;
         }
 
-        // Only handle rate limit errors (429)
+        // Handle retryable server errors (500, 502, 503) with limited retries (#231)
+        // Unlike rate limits (429) which retry indefinitely within timeout,
+        // server errors use a fixed count to avoid retrying broken endpoints.
+        if (isRetryableServerError(response.status)) {
+          if (attempt > SERVER_ERROR_MAX_RETRIES) {
+            // Read response body for diagnostics before returning (#231)
+            // This ensures the actual server error is visible in logs,
+            // preventing misleading downstream errors like "input_tokens undefined"
+            let errorBody = '';
+            try {
+              errorBody = await response.clone().text();
+            } catch {
+              errorBody = '<failed to read response body>';
+            }
+            log.warn(() => ({
+              message:
+                'server error max retries exceeded, returning error response',
+              sessionID,
+              status: response.status,
+              attempt,
+              maxRetries: SERVER_ERROR_MAX_RETRIES,
+              responseBody: errorBody.slice(0, 500),
+            }));
+            return response;
+          }
+
+          const elapsed = Date.now() - startTime;
+          if (elapsed >= maxRetryTimeout) {
+            let errorBody = '';
+            try {
+              errorBody = await response.clone().text();
+            } catch {
+              errorBody = '<failed to read response body>';
+            }
+            log.warn(() => ({
+              message:
+                'retry timeout exceeded for server error, returning error response',
+              sessionID,
+              status: response.status,
+              elapsedMs: elapsed,
+              maxRetryTimeoutMs: maxRetryTimeout,
+              responseBody: errorBody.slice(0, 500),
+            }));
+            return response;
+          }
+
+          // Use exponential backoff for server errors (no retry-after expected)
+          const delay = addJitter(
+            Math.min(
+              RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1),
+              Math.min(maxBackoffDelay, RETRY_MAX_DELAY_NO_HEADERS)
+            )
+          );
+
+          log.info(() => ({
+            message: 'server error, will retry',
+            sessionID,
+            status: response.status,
+            attempt,
+            maxRetries: SERVER_ERROR_MAX_RETRIES,
+            delayMs: delay,
+          }));
+
+          await sleep(delay, init?.signal ?? undefined);
+          continue;
+        }
+
+        // Only handle rate limit errors (429) beyond this point
         if (response.status !== 429) {
           return response;
         }

package/src/session/compaction.ts

@@ -36,15 +36,35 @@ export namespace SessionCompaction {
    */
   export const OVERFLOW_SAFETY_MARGIN = 0.85;
 
+  /**
+   * A single compaction model entry in the cascade.
+   * @see https://github.com/link-assistant/agent/issues/232
+   */
+  export interface CompactionModelEntry {
+    providerID: string;
+    modelID: string;
+    useSameModel: boolean;
+  }
+
   /**
    * Compaction model configuration passed from CLI.
+   * Supports both single model (backward compat) and cascade of models (#232).
    * @see https://github.com/link-assistant/agent/issues/219
+   * @see https://github.com/link-assistant/agent/issues/232
    */
   export interface CompactionModelConfig {
     providerID: string;
     modelID: string;
     useSameModel: boolean;
     compactionSafetyMarginPercent: number;
+    /**
+     * Ordered cascade of compaction models from smallest/cheapest to largest.
+     * When present, the system tries each model in order during compaction.
+     * If used context exceeds a model's limit or its rate limit is reached,
+     * the next model is tried.
+     * @see https://github.com/link-assistant/agent/issues/232
+     */
+    compactionModels?: CompactionModelEntry[];
   }
 
   /**

package/src/session/message-v2.ts

@@ -398,6 +398,15 @@ export namespace MessageV2 {
         modelID: z.string(),
         useSameModel: z.boolean(),
         compactionSafetyMarginPercent: z.number(),
+        compactionModels: z
+          .array(
+            z.object({
+              providerID: z.string(),
+              modelID: z.string(),
+              useSameModel: z.boolean(),
+            })
+          )
+          .optional(),
       })
       .optional(),
     system: z.string().optional(),

package/src/session/prompt.ts

@@ -95,6 +95,15 @@ export namespace SessionPrompt {
         modelID: z.string(),
         useSameModel: z.boolean(),
         compactionSafetyMarginPercent: z.number(),
+        compactionModels: z
+          .array(
+            z.object({
+              providerID: z.string(),
+              modelID: z.string(),
+              useSameModel: z.boolean(),
+            })
+          )
+          .optional(),
       })
       .optional(),
     agent: z.string().optional(),
@@ -542,27 +551,109 @@ export namespace SessionPrompt {
 
       // pending compaction
       if (task?.type === 'compaction') {
-        // Use compaction model if configured, otherwise fall back to base model
+        // Use compaction model cascade if configured (#232)
         const compactionModelConfig = lastUser.compactionModel;
-        const compactionProviderID =
-          compactionModelConfig && !compactionModelConfig.useSameModel
-            ? compactionModelConfig.providerID
-            : model.providerID;
-        const compactionModelID =
-          compactionModelConfig && !compactionModelConfig.useSameModel
-            ? compactionModelConfig.modelID
-            : model.modelID;
-        const result = await SessionCompaction.process({
-          messages: msgs,
-          parentID: lastUser.id,
-          abort,
-          model: {
-            providerID: compactionProviderID,
-            modelID: compactionModelID,
-          },
-          sessionID,
-        });
-        if (result === 'stop') break;
+        const cascade = compactionModelConfig?.compactionModels;
+
+        if (cascade && cascade.length > 0) {
+          // Cascade logic: try each model in order (smallest to largest context)
+          // Skip models whose context limit is smaller than current used tokens
+          // Skip models that hit rate limits (try next)
+          const currentTokens = lastFinished
+            ? lastFinished.tokens.input +
+              lastFinished.tokens.cache.read +
+              lastFinished.tokens.output
+            : 0;
+
+          let compactionResult = 'stop';
+          for (const entry of cascade) {
+            const entryProviderID = entry.useSameModel
+              ? model.providerID
+              : entry.providerID;
+            const entryModelID = entry.useSameModel
+              ? model.modelID
+              : entry.modelID;
+
+            // Check if this model's context is large enough for the current tokens
+            if (!entry.useSameModel) {
+              try {
+                const entryModel = await Provider.getModel(
+                  entryProviderID,
+                  entryModelID
+                );
+                const entryContextLimit = entryModel.info?.limit?.context ?? 0;
+                if (
+                  entryContextLimit > 0 &&
+                  currentTokens > entryContextLimit
+                ) {
+                  log.info(() => ({
+                    message:
+                      'skipping compaction model — context too small for current tokens',
+                    modelID: entryModelID,
+                    providerID: entryProviderID,
+                    contextLimit: entryContextLimit,
+                    currentTokens,
+                  }));
+                  continue;
+                }
+              } catch {
+                log.info(() => ({
+                  message:
+                    'could not resolve compaction cascade model — skipping',
+                  modelID: entryModelID,
+                  providerID: entryProviderID,
+                }));
+                continue;
+              }
+            }
+
+            try {
+              compactionResult = await SessionCompaction.process({
+                messages: msgs,
+                parentID: lastUser.id,
+                abort,
+                model: {
+                  providerID: entryProviderID,
+                  modelID: entryModelID,
+                },
+                sessionID,
+              });
+              // If compaction succeeded, break the cascade
+              break;
+            } catch (err) {
+              // If rate limited or error, try next model in cascade
+              log.warn(() => ({
+                message: 'compaction model failed — trying next in cascade',
+                modelID: entryModelID,
+                providerID: entryProviderID,
+                error: err?.message,
+              }));
+              continue;
+            }
+          }
+          if (compactionResult === 'stop') break;
+        } else {
+          // Single model fallback (backward compatibility)
+          const compactionProviderID =
+            compactionModelConfig && !compactionModelConfig.useSameModel
+              ? compactionModelConfig.providerID
+              : model.providerID;
+          const compactionModelID =
+            compactionModelConfig && !compactionModelConfig.useSameModel
+              ? compactionModelConfig.modelID
+              : model.modelID;
+          const result = await SessionCompaction.process({
+            messages: msgs,
+            parentID: lastUser.id,
+            abort,
+            model: {
+              providerID: compactionProviderID,
+              modelID: compactionModelID,
+            },
+            sessionID,
+          });
+          if (result === 'stop') break;
+        }
         continue;
       }
 

package/src/storage/storage.ts

@@ -180,8 +180,19 @@ export namespace Storage {
     for (let index = migration; index < MIGRATIONS.length; index++) {
       log.info(() => ({ message: 'running migration', index }));
       const migration = MIGRATIONS[index];
-      await migration(dir).catch(() =>
-        log.error(() => ({ message: 'failed to run migration', index }))
+      await migration(dir).catch((migrationError) =>
+        log.error(() => ({
+          message: 'failed to run migration',
+          index,
+          error:
+            migrationError instanceof Error
+              ? {
+                  name: migrationError.name,
+                  message: migrationError.message,
+                  stack: migrationError.stack,
+                }
+              : String(migrationError),
+        }))
       );
       await Bun.write(path.join(dir, 'migration'), (index + 1).toString());
     }

package/src/util/verbose-fetch.ts

@@ -24,6 +24,21 @@ const log = Log.create({ service: 'http' });
 /** Global call counter shared across all verbose fetch wrappers */
 let globalHttpCallCount = 0;
 
+/**
+ * Track pending async stream log operations (#231).
+ * When the process exits while stream logging is in progress, we log a warning
+ * so missing HTTP response bodies are visible in the logs rather than silently lost.
+ */
+let pendingStreamLogs = 0;
+
+/**
+ * Get the current count of pending stream log operations.
+ * Useful for diagnostics and testing.
+ */
+export function getPendingStreamLogCount(): number {
+  return pendingStreamLogs;
+}
+
 /**
  * Sanitize HTTP headers by masking sensitive values.
  * Masks authorization, x-api-key, and api-key headers.
@@ -196,7 +211,8 @@ export function createVerboseFetch(
           if (isStreaming) {
             const [sdkStream, logStream] = response.body.tee();
 
-            // Consume log stream asynchronously
+            // Consume log stream asynchronously, tracking pending operations (#231)
+            pendingStreamLogs++;
             (async () => {
               try {
                 const reader = logStream.getReader();
@@ -225,6 +241,8 @@ export function createVerboseFetch(
                 });
               } catch {
                 // Ignore logging errors
+              } finally {
+                pendingStreamLogs--;
               }
             })();
 
@@ -304,3 +322,18 @@ export function getHttpCallCount(): number {
 export function resetHttpCallCount(): void {
   globalHttpCallCount = 0;
 }
+
+/**
+ * Register a process exit handler that warns about pending stream log operations.
+ * Call this once at startup when verbose mode is enabled (#231).
+ */
+export function registerPendingStreamLogExitHandler(): void {
+  process.once('exit', () => {
+    if (pendingStreamLogs > 0) {
+      // Use stderr directly since the process is exiting and log infrastructure may be unavailable
+      process.stderr.write(
+        `[verbose] warning: ${pendingStreamLogs} HTTP stream response log(s) were still pending at process exit — response bodies may be missing from logs\n`
+      );
+    }
+  });
+}