@link-assistant/agent 0.16.3 → 0.16.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "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

@@ -0,0 +1,33 @@
+/**
+ * CLI argument utilities for parsing process.argv directly
+ * These provide safeguards against yargs caching issues (#192)
+ */
+
+/**
+ * Extract model argument directly from process.argv
+ * This is a safeguard against yargs caching issues (#192)
+ * @returns The model argument from CLI or null if not found
+ */
+export function getModelFromProcessArgv(): string | null {
+  const args = process.argv;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    // Handle --model=value format
+    if (arg.startsWith('--model=')) {
+      return arg.substring('--model='.length);
+    }
+    // Handle --model value format
+    if (arg === '--model' && i + 1 < args.length) {
+      return args[i + 1];
+    }
+    // Handle -m=value format
+    if (arg.startsWith('-m=')) {
+      return arg.substring('-m='.length);
+    }
+    // Handle -m value format (but not if it looks like another flag)
+    if (arg === '-m' && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+      return args[i + 1];
+    }
+  }
+  return null;
+}

package/src/cli/model-config.js

@@ -0,0 +1,147 @@
+import { getModelFromProcessArgv } from './argv.ts';
+import { Log } from '../util/log.ts';
+
+/**
+ * Parse model config from argv. Supports "provider/model" or short "model" format.
+ * @param {object} argv - Parsed command line arguments
+ * @param {function} outputError - Function to output error messages
+ * @param {function} outputStatus - Function to output status messages
+ * @returns {Promise<{providerID: string, modelID: string}>}
+ */
+export async function parseModelConfig(argv, outputError, outputStatus) {
+  // Safeguard: validate argv.model against process.argv to detect yargs/cache mismatch (#192, #196)
+  // This is critical because yargs under Bun may fail to parse --model correctly,
+  // returning the default value instead of the user's CLI argument.
+  const cliModelArg = getModelFromProcessArgv();
+  let modelArg = argv.model;
+
+  // ALWAYS prefer the CLI value over yargs when available (#196)
+  // The yargs default 'opencode/kimi-k2.5-free' can silently override user's --model argument
+  if (cliModelArg) {
+    if (cliModelArg !== modelArg) {
+      Log.Default.warn(() => ({
+        message: 'model argument mismatch detected - using CLI value',
+        yargsModel: modelArg,
+        cliModel: cliModelArg,
+        processArgv: process.argv.join(' '),
+      }));
+    }
+    // Always use CLI value when available, even if it matches yargs
+    // This ensures we use the actual CLI argument, not a cached/default yargs value
+    modelArg = cliModelArg;
+  }
+
+  let providerID;
+  let modelID;
+
+  // Check if model includes explicit provider prefix
+  if (modelArg.includes('/')) {
+    // Explicit provider/model format - respect user's choice
+    const modelParts = modelArg.split('/');
+    providerID = modelParts[0];
+    modelID = modelParts.slice(1).join('/');
+
+    // Validate that providerID and modelID are not empty
+    // Do NOT fall back to defaults - if the user provided an invalid format, fail clearly (#196)
+    if (!providerID || !modelID) {
+      throw new Error(
+        `Invalid model format: "${modelArg}". Expected "provider/model" format (e.g., "opencode/kimi-k2.5-free"). ` +
+          `Provider: "${providerID || '(empty)'}", Model: "${modelID || '(empty)'}".`
+      );
+    }
+
+    // Log raw and parsed values to help diagnose model routing issues (#171)
+    Log.Default.info(() => ({
+      message: 'using explicit provider/model',
+      rawModel: modelArg,
+      providerID,
+      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
+    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(() => ({
+          message:
+            'model not found in provider - will attempt anyway (provider may support unlisted models)',
+          providerID,
+          modelID,
+          availableModels,
+        }));
+      }
+    } catch (validationError) {
+      // Don't fail on validation errors - the model may still work
+      // This is a best-effort check
+      Log.Default.info(() => ({
+        message: 'skipping model existence validation',
+        reason: validationError?.message,
+      }));
+    }
+  } else {
+    // Short model name - resolve to appropriate provider
+    // Import Provider to use parseModelWithResolution
+    const { Provider } = await import('../provider/provider.ts');
+    const resolved = await Provider.parseModelWithResolution(modelArg);
+    providerID = resolved.providerID;
+    modelID = resolved.modelID;
+
+    Log.Default.info(() => ({
+      message: 'resolved short model name',
+      input: modelArg,
+      providerID,
+      modelID,
+    }));
+  }
+
+  // Handle --use-existing-claude-oauth option
+  // This reads OAuth credentials from ~/.claude/.credentials.json (Claude Code CLI)
+  // For new authentication, use: agent auth login (select Anthropic > Claude Pro/Max)
+  if (argv['use-existing-claude-oauth']) {
+    // Import ClaudeOAuth to check for credentials from Claude Code CLI
+    const { ClaudeOAuth } = await import('../auth/claude-oauth.ts');
+    const creds = await ClaudeOAuth.getCredentials();
+
+    if (!creds?.accessToken) {
+      const compactJson = argv['compact-json'] === true;
+      outputError(
+        {
+          errorType: 'AuthenticationError',
+          message:
+            'No Claude OAuth credentials found in ~/.claude/.credentials.json. Either authenticate with Claude Code CLI first, or use: agent auth login (select Anthropic > Claude Pro/Max)',
+        },
+        compactJson
+      );
+      process.exit(1);
+    }
+
+    // Set environment variable for the provider to use
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = creds.accessToken;
+
+    // If user specified the default model (opencode/kimi-k2.5-free), switch to claude-oauth
+    // If user explicitly specified kilo or another provider, warn but respect their choice
+    if (providerID === 'opencode' && modelID === 'kimi-k2.5-free') {
+      providerID = 'claude-oauth';
+      modelID = 'claude-sonnet-4-5';
+    } else if (!['claude-oauth', 'anthropic'].includes(providerID)) {
+      // If user specified a different provider explicitly, warn them
+      const compactJson = argv['compact-json'] === true;
+      outputStatus(
+        {
+          type: 'warning',
+          message: `--use-existing-claude-oauth is set but model uses provider "${providerID}". Using specified provider.`,
+        },
+        compactJson
+      );
+      // Don't override - respect user's explicit provider choice
+    }
+  }
+
+  return { providerID, modelID };
+}

package/src/index.js

@@ -5,6 +5,7 @@ setProcessName('agent');
 import { Server } from './server/server.ts';
 import { Instance } from './project/instance.ts';
 import { Log } from './util/log.ts';
+import { parseModelConfig } from './cli/model-config.js';
 // Bus is used via createBusEventSubscription in event-handler.js
 import { Session } from './session/index.ts';
 import { SessionPrompt } from './session/prompt.ts';
@@ -134,110 +135,6 @@ function readStdinWithTimeout(timeout = null) {
   });
 }
 
-// outputStatus is now imported from './cli/output.ts'
-// It outputs to stdout for non-error messages, stderr for errors
-
-/**
- * Parse model configuration from argv
- * Supports both explicit provider/model format and short model names.
- *
- * Format examples:
- * - "kilo/glm-5-free" -> uses kilo provider with glm-5-free model (explicit)
- * - "opencode/kimi-k2.5-free" -> uses opencode provider (explicit)
- * - "glm-5-free" -> resolved to kilo provider (unique free model)
- * - "kimi-k2.5-free" -> resolved to opencode provider (shared model, opencode preferred)
- *
- * @param {object} argv - Command line arguments
- * @returns {object} - { providerID, modelID }
- */
-async function parseModelConfig(argv) {
-  const modelArg = argv.model;
-
-  let providerID;
-  let modelID;
-
-  // Check if model includes explicit provider prefix
-  if (modelArg.includes('/')) {
-    // Explicit provider/model format - respect user's choice
-    const modelParts = modelArg.split('/');
-    providerID = modelParts[0];
-    modelID = modelParts.slice(1).join('/');
-
-    // Validate that providerID and modelID are not empty
-    if (!providerID || !modelID) {
-      providerID = providerID || 'opencode';
-      modelID = modelID || 'kimi-k2.5-free';
-    }
-
-    // Log raw and parsed values to help diagnose model routing issues (#171)
-    Log.Default.info(() => ({
-      message: 'using explicit provider/model',
-      rawModel: modelArg,
-      providerID,
-      modelID,
-    }));
-  } else {
-    // Short model name - resolve to appropriate provider
-    // Import Provider to use parseModelWithResolution
-    const { Provider } = await import('./provider/provider.ts');
-    const resolved = await Provider.parseModelWithResolution(modelArg);
-    providerID = resolved.providerID;
-    modelID = resolved.modelID;
-
-    Log.Default.info(() => ({
-      message: 'resolved short model name',
-      input: modelArg,
-      providerID,
-      modelID,
-    }));
-  }
-
-  // Handle --use-existing-claude-oauth option
-  // This reads OAuth credentials from ~/.claude/.credentials.json (Claude Code CLI)
-  // For new authentication, use: agent auth login (select Anthropic > Claude Pro/Max)
-  if (argv['use-existing-claude-oauth']) {
-    // Import ClaudeOAuth to check for credentials from Claude Code CLI
-    const { ClaudeOAuth } = await import('./auth/claude-oauth.ts');
-    const creds = await ClaudeOAuth.getCredentials();
-
-    if (!creds?.accessToken) {
-      const compactJson = argv['compact-json'] === true;
-      outputError(
-        {
-          errorType: 'AuthenticationError',
-          message:
-            'No Claude OAuth credentials found in ~/.claude/.credentials.json. Either authenticate with Claude Code CLI first, or use: agent auth login (select Anthropic > Claude Pro/Max)',
-        },
-        compactJson
-      );
-      process.exit(1);
-    }
-
-    // Set environment variable for the provider to use
-    process.env.CLAUDE_CODE_OAUTH_TOKEN = creds.accessToken;
-
-    // If user specified the default model (opencode/kimi-k2.5-free), switch to claude-oauth
-    // If user explicitly specified kilo or another provider, warn but respect their choice
-    if (providerID === 'opencode' && modelID === 'kimi-k2.5-free') {
-      providerID = 'claude-oauth';
-      modelID = 'claude-sonnet-4-5';
-    } else if (!['claude-oauth', 'anthropic'].includes(providerID)) {
-      // If user specified a different provider explicitly, warn them
-      const compactJson = argv['compact-json'] === true;
-      outputStatus(
-        {
-          type: 'warning',
-          message: `--use-existing-claude-oauth is set but model uses provider "${providerID}". Using specified provider.`,
-        },
-        compactJson
-      );
-      // Don't override - respect user's explicit provider choice
-    }
-  }
-
-  return { providerID, modelID };
-}
-
 /**
  * Read system message from files if specified
  * @param {object} argv - Command line arguments
@@ -320,7 +217,11 @@ async function runAgentMode(argv, request) {
     fn: async () => {
       // Parse model config inside Instance.provide context
       // This allows parseModelWithResolution to access the provider state
-      const { providerID, modelID } = await parseModelConfig(argv);
+      const { providerID, modelID } = await parseModelConfig(
+        argv,
+        outputError,
+        outputStatus
+      );
 
       if (argv.server) {
         // SERVER MODE: Start server and communicate via HTTP
@@ -396,7 +297,11 @@ async function runContinuousAgentMode(argv) {
     fn: async () => {
       // Parse model config inside Instance.provide context
       // This allows parseModelWithResolution to access the provider state
-      const { providerID, modelID } = await parseModelConfig(argv);
+      const { providerID, modelID } = await parseModelConfig(
+        argv,
+        outputError,
+        outputStatus
+      );
 
       if (argv.server) {
         // SERVER MODE: Start server and communicate via HTTP

package/src/provider/provider.ts

@@ -1593,13 +1593,20 @@ export namespace Provider {
    * Parse a model string that may or may not include a provider prefix.
    * If no provider is specified, attempts to resolve the short model name to the appropriate provider.
    *
+   * IMPORTANT: If the model cannot be resolved, this function throws an error instead of
+   * silently falling back to a default. This ensures the user gets their requested model
+   * or a clear error explaining why it's not available.
+   *
    * Examples:
    * - "kilo/glm-5-free" -> { providerID: "kilo", modelID: "glm-5-free" }
    * - "glm-5-free" -> { providerID: "kilo", modelID: "glm-5-free" } (resolved)
    * - "kimi-k2.5-free" -> { providerID: "opencode", modelID: "kimi-k2.5-free" } (resolved)
+   * - "nonexistent-model" -> throws ModelNotFoundError
    *
    * @param model - Model string with or without provider prefix
    * @returns Parsed provider ID and model ID
+   * @throws ModelNotFoundError if the model cannot be found in any provider
+   * @see https://github.com/link-assistant/agent/issues/194
    */
   export async function parseModelWithResolution(
     model: string
@@ -1616,15 +1623,36 @@ export namespace Provider {
       return resolved;
     }
 
-    // Unable to resolve - fall back to default behavior (opencode provider)
-    log.warn(() => ({
-      message: 'unable to resolve short model name, using opencode as default',
-      modelID: model,
+    // Unable to resolve - fail with a clear error instead of silently falling back
+    // This prevents the issue where user requests model X but gets model Y
+    // See: https://github.com/link-assistant/agent/issues/194
+    const s = await state();
+    const availableModels: string[] = [];
+
+    // Collect some available models to suggest
+    for (const [providerID, provider] of Object.entries(s.providers)) {
+      for (const modelID of Object.keys(provider.info.models).slice(0, 3)) {
+        availableModels.push(`${providerID}/${modelID}`);
+      }
+      if (availableModels.length >= 6) break;
+    }
+
+    const suggestion =
+      availableModels.length > 0
+        ? `Model "${model}" not found in any provider. Available models include: ${availableModels.join(', ')}. Use --model provider/model-id format for explicit selection.`
+        : `Model "${model}" not found. No providers are currently available. Check your API keys or authentication.`;
+
+    log.error(() => ({
+      message: 'model not found - refusing to silently fallback',
+      requestedModel: model,
+      availableModels,
     }));
-    return {
-      providerID: 'opencode',
+
+    throw new ModelNotFoundError({
+      providerID: 'unknown',
       modelID: model,
-    };
+      suggestion,
+    });
   }
 
   /**

package/src/session/processor.ts

@@ -273,6 +273,26 @@ export namespace SessionProcessor {
                       }
                     }
                   }
+
+                  // CRITICAL FIX for issue #194: Infer finish reason from tool calls
+                  // If finishReason is still undefined but we have pending tool calls,
+                  // the model intended to make tool calls - infer 'tool-calls' as the reason.
+                  // This prevents premature loop exit when providers don't return finishReason.
+                  // See: https://github.com/link-assistant/agent/issues/194
+                  if (rawFinishReason === undefined) {
+                    const pendingToolCallCount = Object.keys(toolcalls).length;
+                    if (pendingToolCallCount > 0) {
+                      log.info(() => ({
+                        message:
+                          'inferred tool-calls finish reason from pending tool calls',
+                        pendingToolCallCount,
+                        providerID: input.providerID,
+                        hint: 'Provider returned undefined finishReason but made tool calls',
+                      }));
+                      rawFinishReason = 'tool-calls';
+                    }
+                  }
+
                   const finishReason = Session.toFinishReason(rawFinishReason);
                   input.assistantMessage.finish = finishReason;
                   input.assistantMessage.cost += usage.cost;

package/src/session/prompt.ts

@@ -272,13 +272,70 @@ export namespace SessionPrompt {
         throw new Error(
           'No user message found in stream. This should never happen.'
         );
+
+      // Check if we should exit the agentic loop
+      // We exit when: the assistant has a finish reason, it's not 'tool-calls',
+      // and the assistant message is newer than the last user message
       if (
         lastAssistant?.finish &&
         lastAssistant.finish !== 'tool-calls' &&
         lastUser.id < lastAssistant.id
       ) {
-        log.info(() => ({ message: 'exiting loop', sessionID }));
-        break;
+        // SAFETY CHECK for issue #194: If finish reason is 'unknown', check for tool calls
+        // Some providers (e.g., Kimi K2.5 via OpenCode) return undefined finishReason
+        // which gets converted to 'unknown'. If there were tool calls made, we should
+        // continue the loop to execute them instead of prematurely exiting.
+        // See: https://github.com/link-assistant/agent/issues/194
+        if (lastAssistant.finish === 'unknown') {
+          // SAFETY CHECK for issue #196: Detect zero-token responses as provider failures
+          // When all tokens are 0 and finish reason is 'unknown', this indicates the provider
+          // returned an empty/error response (e.g., rate limit, model unavailable, API failure).
+          // Log a clear error message so the problem is visible in logs.
+          const tokens = lastAssistant.tokens;
+          if (
+            tokens.input === 0 &&
+            tokens.output === 0 &&
+            tokens.reasoning === 0
+          ) {
+            log.error(() => ({
+              message:
+                'provider returned zero tokens with unknown finish reason - possible API failure',
+              sessionID,
+              finishReason: lastAssistant.finish,
+              tokens,
+              cost: lastAssistant.cost,
+              model: lastAssistant.model,
+              hint: 'This usually indicates the provider failed to process the request. Check provider status, model availability, and API keys.',
+              issue: 'https://github.com/link-assistant/agent/issues/196',
+            }));
+            break;
+          }
+
+          const lastAssistantParts = msgs.find(
+            (m) => m.info.id === lastAssistant.id
+          )?.parts;
+          const hasToolCalls = lastAssistantParts?.some(
+            (p) =>
+              p.type === 'tool' &&
+              (p.state.status === 'completed' || p.state.status === 'running')
+          );
+          if (hasToolCalls) {
+            log.info(() => ({
+              message:
+                'continuing loop despite unknown finish reason - tool calls detected',
+              sessionID,
+              finishReason: lastAssistant.finish,
+              hint: 'Provider returned undefined finishReason but made tool calls',
+            }));
+            // Don't break - continue the loop to handle tool call results
+          } else {
+            log.info(() => ({ message: 'exiting loop', sessionID }));
+            break;
+          }
+        } else {
+          log.info(() => ({ message: 'exiting loop', sessionID }));
+          break;
+        }
       }
 
       step++;