@link-assistant/agent 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.19.2",
+  "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/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';
 
@@ -173,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
@@ -194,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/provider/provider.ts

@@ -1731,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 = [
@@ -1758,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',
@@ -1841,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/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;
       }