@ducci/jarvis 1.0.33 → 1.0.35

package/docs/findings/017-looping-intervention-and-lossy-checkpoint.md

@@ -0,0 +1,110 @@
+# Finding 017: Looping Intervention and Lossy Checkpoint
+
+**Date:** 2026-03-04
+**Severity:** High — agent burned 40 iterations (4 full runs) on a structurally impossible task without escaping; concrete facts like file paths regressed between handoff runs
+**Status:** Fixed
+
+---
+
+## Observed Session
+
+Session from a remote server. Model: `nvidia/nemotron-3-nano-30b-a3b:free`. User requested a ZAP security scanning workflow (create project dir, write README + scan.sh, run a test scan).
+
+| Entry | Trigger | Status | Iterations | Notes |
+|-------|---------|--------|------------|-------|
+| 1 | "hello" | ok | 0 | greeting |
+| 2 | ZAP task | checkpoint_reached | 10 | ZAP daemon lock blocked scan |
+| 3 | handoff resume | checkpoint_reached | 10 | same lock, same result |
+| 4 | zero-progress | intervention_required | 0 | correctly detected |
+| 5 | "Ok can you do it?" | checkpoint_reached | 10 | loop restarted, same result |
+| 6 | handoff resume | checkpoint_reached | 10 | same lock again |
+| 7 | zero-progress | intervention_required | 0 | detected again, session abandoned |
+
+Total: 40 wasted iterations. Additionally, between Entry 2 and Entry 6, the agent changed the project path from `/root/.jarvis/projects/cybersecurity` to `/root/projects/cybersecurity`, causing `list_dir` to fail at the start of that run.
+
+---
+
+## Root Cause 1: Zero-Progress Detection Resets Across User Messages
+
+### What happened
+
+`previousRemaining` is a local variable initialized to `null` on every call to `_runHandleChat`. Zero-progress detection requires two identical `checkpoint.remaining` values, but both must occur within the same invocation. When `intervention_required` fires and the user sends a new message, `_runHandleChat` is called fresh with `previousRemaining = null`. The detection resets.
+
+The result: each new user message grants the agent 2 full runs (20 iterations) before zero-progress fires again — regardless of how many times the cycle has already repeated. The intervention mechanism correctly identifies "stuck" but provides no structural escape when the user replies.
+
+### Fix
+
+1. When zero-progress fires, persist `session.metadata.lastCheckpointRemaining = currentRemaining`.
+2. In `_runHandleChat`, initialize `previousRemaining` from `session.metadata.lastCheckpointRemaining` (cleared after reading). Zero-progress now fires after just one run (10 iterations) on the next user message if the agent produces the same remaining.
+3. Inject a note into `userMessageWithContext` when `lastCheckpointRemaining` was set:
+
+```
+[System: This task previously hit zero-progress and required intervention. If the user has given new direction or clarification, follow it. Otherwise, immediately explain what specific obstacle is blocking progress — do not resume the same failing approach.]
+```
+
+This gives the agent explicit guidance to respond to what the user actually asked instead of blindly resuming.
+
+**File:** `src/server/agent.js` — `_runHandleChat`
+
+---
+
+## Root Cause 2: Checkpoint Loses Concrete Facts Between Runs
+
+### What happened
+
+The checkpoint schema had `progress`, `remaining`, and `failedApproaches` — all natural-language prose. Concrete facts the agent discovers during a run (file paths, binary locations, config values) are paraphrased or omitted when the agent writes the summary. On resume, the model reconstructs these facts from vague prose and sometimes gets them wrong.
+
+In this session, the project directory `/root/.jarvis/projects/cybersecurity` was written correctly in runs 1–3 but reconstructed as `/root/projects/cybersecurity` in run 6. The first action of that run was `list_dir` on the wrong path, which failed.
+
+### Fix
+
+1. Added a `state` field to `WRAP_UP_NOTE`'s checkpoint schema: a flat key-value JSON object for concrete facts confirmed by tool output (file paths created, binary locations found, config values discovered).
+
+2. After each handoff, merge `run.checkpoint.state` into `session.metadata.checkpointState` (later runs overwrite earlier values for the same key).
+
+3. When building `resumeContent` for the next handoff run, inject the accumulated state:
+
+```
+[System: Known facts from previous runs:
+- projectDir: /root/.jarvis/projects/cybersecurity
+- zapBinary: /snap/bin/zaproxy
+- scanScriptPath: /root/.jarvis/projects/cybersecurity/scan.sh]
+```
+
+4. When re-entering after zero-progress (via `wasZeroProgress`), also include the state in the `userMessageWithContext` injection so facts are available immediately on the first run.
+
+5. `session.metadata.checkpointState` is reset on each new user message (same lifecycle as `failedApproaches`) to avoid stale facts from previous tasks leaking into new ones.
+
+**File:** `src/server/agent.js` — `WRAP_UP_NOTE`, checkpoint normalization, `_runHandleChat`
+
+---
+
+## Interaction Between the Two Fixes
+
+The zero-progress note injected into `userMessageWithContext` now also includes the `priorCheckpointState` (captured before the metadata reset), so the agent that receives the note also has the concrete facts it needs if the user does provide new direction. This means both fixes compound: the agent is told it was stuck AND given the facts it needs to act on whatever the user says.
+
+---
+
+## What Was Not Changed
+
+- The existing exact-match loop detector (`loopTracker`) — unchanged
+- The consecutive failure detector — unchanged
+- The `maxHandoffs` cap — unchanged
+- The `hasConsecutiveModelErrors` escalation — unchanged
+- The context strip on checkpoint/intervention — unchanged
+
+---
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `src/server/agent.js` | `WRAP_UP_NOTE` — added `state` field to checkpoint schema |
+| `src/server/agent.js` | Checkpoint normalization — normalize `cp.state` to `{}` if missing/malformed |
+| `src/server/agent.js` | `_runHandleChat` — capture `wasZeroProgress`, `priorCheckpointRemaining`, `priorCheckpointState` before metadata reset |
+| `src/server/agent.js` | `_runHandleChat` — inject zero-progress note + prior state into `userMessageWithContext` when applicable |
+| `src/server/agent.js` | `_runHandleChat` — reset `lastCheckpointRemaining` and `checkpointState` on new user message |
+| `src/server/agent.js` | `_runHandleChat` — initialize `previousRemaining` from `priorCheckpointRemaining` |
+| `src/server/agent.js` | Zero-progress block — persist `session.metadata.lastCheckpointRemaining` |
+| `src/server/agent.js` | Handoff accumulation — merge `run.checkpoint.state` into `session.metadata.checkpointState` |
+| `src/server/agent.js` | `resumeContent` — inject accumulated `checkpointState` as known facts |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",
@@ -36,6 +36,7 @@
   },
   "license": "ISC",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@grammyjs/runner": "^2.0.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",

package/src/channels/telegram/index.js

@@ -1,6 +1,7 @@
 import { Bot } from 'grammy';
 import { run } from '@grammyjs/runner';
 import { handleChat } from '../../server/agent.js';
+import { loadSession } from '../../server/sessions.js';
 import { load, save } from './sessions.js';
 
 export async function startTelegramChannel(config) {
@@ -13,8 +14,33 @@ export async function startTelegramChannel(config) {
 
   await bot.api.setMyCommands([
     { command: 'new', description: 'Start a fresh session' },
+    { command: 'usage', description: 'Show token usage for the current session' },
   ]);
 
+  bot.command('usage', async (ctx) => {
+    const userId = ctx.from?.id;
+    if (!allowedUserIds.includes(userId)) return;
+
+    const chatId = ctx.chat.id;
+    const sessionId = sessions[chatId];
+    if (!sessionId) {
+      await ctx.reply('No active session. Send a message to start one.');
+      return;
+    }
+
+    const session = await loadSession(sessionId);
+    const u = session?.metadata?.tokenUsage;
+    if (!u || (u.prompt === 0 && u.completion === 0)) {
+      await ctx.reply('No token usage recorded for this session yet.');
+      return;
+    }
+
+    const total = u.prompt + u.completion;
+    await ctx.reply(
+      `Token usage for current session:\nIn:    ${u.prompt.toLocaleString()}\nOut:   ${u.completion.toLocaleString()}\nTotal: ${total.toLocaleString()}`
+    );
+  });
+
   bot.command('new', async (ctx) => {
     const userId = ctx.from?.id;
     if (!allowedUserIds.includes(userId)) return;

package/src/scripts/onboarding.js

@@ -52,17 +52,13 @@ function saveSettings(settings) {
   fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2), 'utf8');
 }
 
-async function fetchModels(apiKey) {
+async function fetchOpenRouterModels(apiKey) {
   console.log(chalk.blue('Fetching models from OpenRouter...'));
   try {
     const response = await fetch('https://openrouter.ai/api/v1/models', {
-      headers: {
-        'Authorization': `Bearer ${apiKey}`
-      }
+      headers: { 'Authorization': `Bearer ${apiKey}` }
     });
-    if (!response.ok) {
-      throw new Error(`HTTP error! status: ${response.status}`);
-    }
+    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
     const data = await response.json();
     return data.data;
   } catch (error) {
@@ -71,55 +67,114 @@ async function fetchModels(apiKey) {
   }
 }
 
+const ANTHROPIC_MODELS_FALLBACK = [
+  { id: 'claude-opus-4-6', description: 'Most capable' },
+  { id: 'claude-sonnet-4-6', description: 'Balanced' },
+  { id: 'claude-3-5-sonnet-20241022', description: 'Balanced (stable)' },
+  { id: 'claude-haiku-4-5-20251001', description: 'Fast & cheap' },
+  { id: 'claude-3-5-haiku-20241022', description: 'Fast & cheap (stable)' },
+];
+
+async function fetchAnthropicModels(apiKey) {
+  try {
+    const response = await fetch('https://api.anthropic.com/v1/models', {
+      headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' }
+    });
+    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+    const data = await response.json();
+    return data.data.map(m => ({ id: m.id, description: '' }));
+  } catch {
+    return ANTHROPIC_MODELS_FALLBACK;
+  }
+}
+
 async function run() {
   ensureDirectories();
 
   console.log(chalk.green.bold('\n=== Jarvis Setup ===\n'));
 
+  let settings = loadSettings();
+
+  // --- PROVIDER STEP ---
+  const { provider } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'provider',
+      message: 'Which AI provider do you want to use?',
+      choices: [
+        { name: 'OpenRouter (access many models via one key)', value: 'openrouter' },
+        { name: 'Anthropic Direct (use your Anthropic API key)', value: 'anthropic' },
+      ],
+      default: settings.provider || 'openrouter',
+    }
+  ]);
+
   // --- API KEY STEP ---
-  let existingKey = loadEnvVar('OPENROUTER_API_KEY');
-  let apiKey = existingKey;
+  let apiKey;
 
-  if (existingKey) {
-    const { keepKey } = await inquirer.prompt([
-      {
-        type: 'confirm',
-        name: 'keepKey',
-        message: 'An OPENROUTER_API_KEY is already configured. Do you want to keep it?',
-        default: true
-      }
-    ]);
+  if (provider === 'anthropic') {
+    const existingKey = loadEnvVar('ANTHROPIC_API_KEY');
+    apiKey = existingKey;
+
+    if (existingKey) {
+      const { keepKey } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'keepKey',
+          message: 'An ANTHROPIC_API_KEY is already configured. Do you want to keep it?',
+          default: true,
+        }
+      ]);
+      if (!keepKey) apiKey = null;
+    }
+
+    if (!apiKey) {
+      const { newKey } = await inquirer.prompt([
+        {
+          type: 'password',
+          name: 'newKey',
+          message: 'Enter your Anthropic API key:',
+          validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.',
+        }
+      ]);
+      apiKey = newKey;
+      saveEnvVar('ANTHROPIC_API_KEY', apiKey);
+      console.log(chalk.green('Anthropic API key saved.'));
+    }
+  } else {
+    const existingKey = loadEnvVar('OPENROUTER_API_KEY');
+    apiKey = existingKey;
+
+    if (existingKey) {
+      const { keepKey } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'keepKey',
+          message: 'An OPENROUTER_API_KEY is already configured. Do you want to keep it?',
+          default: true,
+        }
+      ]);
+      if (!keepKey) apiKey = null;
+    }
 
-    if (!keepKey) {
+    if (!apiKey) {
       const { newKey } = await inquirer.prompt([
         {
           type: 'password',
           name: 'newKey',
           message: 'Enter your OpenRouter API key:',
-          validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.'
+          validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.',
         }
       ]);
       apiKey = newKey;
       saveEnvVar('OPENROUTER_API_KEY', apiKey);
-      console.log(chalk.green('API key updated.'));
+      console.log(chalk.green('OpenRouter API key saved.'));
     }
-  } else {
-    const { newKey } = await inquirer.prompt([
-      {
-        type: 'password',
-        name: 'newKey',
-        message: 'Enter your OpenRouter API key:',
-        validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.'
-      }
-    ]);
-    apiKey = newKey;
-    saveEnvVar('OPENROUTER_API_KEY', apiKey);
-    console.log(chalk.green('API key saved.'));
   }
 
   // --- MODEL SELECTION STEP ---
-  let settings = loadSettings();
-  let selectedModel = settings.selectedModel;
+  // Reset model selection when switching providers
+  let selectedModel = settings.provider === provider ? settings.selectedModel : null;
 
   if (selectedModel) {
     const { keepModel } = await inquirer.prompt([
@@ -129,88 +184,115 @@ async function run() {
         message: `Current model is ${chalk.yellow(selectedModel)}. Do you want to keep it or change it?`,
         choices: [
           { name: 'Keep current model', value: true },
-          { name: 'Change model', value: false }
+          { name: 'Change model', value: false },
         ]
       }
     ]);
-
-    if (!keepModel) {
-      selectedModel = null;
-    }
+    if (!keepModel) selectedModel = null;
   }
 
   if (!selectedModel) {
-    const { modelSelectionMethod } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'modelSelectionMethod',
-        message: 'How would you like to select a model?',
-        choices: [
-          { name: 'Browse OpenRouter models', value: 'browse' },
-          { name: 'Enter model ID manually', value: 'manual' }
-        ]
-      }
-    ]);
+    if (provider === 'anthropic') {
+      console.log(chalk.blue('Fetching available Claude models...'));
+      const models = await fetchAnthropicModels(apiKey);
+      const choices = models.map(m => ({
+        name: m.description ? `${m.id}  ${chalk.dim(m.description)}` : m.id,
+        value: m.id,
+      }));
+      choices.push({ name: 'Enter model ID manually', value: '__manual__' });
 
-    if (modelSelectionMethod === 'manual') {
-      const { manualModel } = await inquirer.prompt([
+      const { browsedModel } = await inquirer.prompt([
         {
-          type: 'input',
-          name: 'manualModel',
-          message: 'Enter OpenRouter model ID (e.g., anthropic/claude-3.5-sonnet):',
-          validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.'
+          type: 'list',
+          name: 'browsedModel',
+          message: 'Select a Claude model:',
+          choices,
+          pageSize: 20,
         }
       ]);
-      selectedModel = manualModel.trim();
-    } else {
-      const models = await fetchModels(apiKey);
-      if (models.length === 0) {
-        console.log(chalk.yellow('Falling back to manual entry due to fetch failure.'));
+
+      if (browsedModel === '__manual__') {
         const { manualModel } = await inquirer.prompt([
           {
             type: 'input',
             name: 'manualModel',
-            message: 'Enter OpenRouter model ID:',
-            validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.'
+            message: 'Enter Anthropic model ID (e.g., claude-sonnet-4-6):',
+            validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.',
           }
         ]);
         selectedModel = manualModel.trim();
       } else {
-        // Sort models: free first, then alphabetical
-        models.sort((a, b) => {
-          const isFreeA = a.pricing && parseFloat(a.pricing.prompt) === 0 && parseFloat(a.pricing.completion) === 0;
-          const isFreeB = b.pricing && parseFloat(b.pricing.prompt) === 0 && parseFloat(b.pricing.completion) === 0;
-
-          if (isFreeA && !isFreeB) return -1;
-          if (!isFreeA && isFreeB) return 1;
-          return a.id.localeCompare(b.id);
-        });
-
-        const choices = models.map(m => {
-          const isFree = m.pricing && parseFloat(m.pricing.prompt) === 0 && parseFloat(m.pricing.completion) === 0;
-          return {
-            name: `${m.id} ${isFree ? chalk.green('(Free)') : ''}`,
-            value: m.id
-          };
-        });
-
-        const { browsedModel } = await inquirer.prompt([
+        selectedModel = browsedModel;
+      }
+    } else {
+      const { modelSelectionMethod } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'modelSelectionMethod',
+          message: 'How would you like to select a model?',
+          choices: [
+            { name: 'Browse OpenRouter models', value: 'browse' },
+            { name: 'Enter model ID manually', value: 'manual' },
+          ]
+        }
+      ]);
+
+      if (modelSelectionMethod === 'manual') {
+        const { manualModel } = await inquirer.prompt([
           {
-            type: 'list',
-            name: 'browsedModel',
-            message: 'Select a model:',
-            choices: choices,
-            pageSize: 20
+            type: 'input',
+            name: 'manualModel',
+            message: 'Enter OpenRouter model ID (e.g., anthropic/claude-3.5-sonnet):',
+            validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.',
           }
         ]);
-        selectedModel = browsedModel;
+        selectedModel = manualModel.trim();
+      } else {
+        const models = await fetchOpenRouterModels(apiKey);
+        if (models.length === 0) {
+          console.log(chalk.yellow('Falling back to manual entry due to fetch failure.'));
+          const { manualModel } = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'manualModel',
+              message: 'Enter OpenRouter model ID:',
+              validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.',
+            }
+          ]);
+          selectedModel = manualModel.trim();
+        } else {
+          models.sort((a, b) => {
+            const isFreeA = a.pricing && parseFloat(a.pricing.prompt) === 0 && parseFloat(a.pricing.completion) === 0;
+            const isFreeB = b.pricing && parseFloat(b.pricing.prompt) === 0 && parseFloat(b.pricing.completion) === 0;
+            if (isFreeA && !isFreeB) return -1;
+            if (!isFreeA && isFreeB) return 1;
+            return a.id.localeCompare(b.id);
+          });
+          const choices = models.map(m => {
+            const isFree = m.pricing && parseFloat(m.pricing.prompt) === 0 && parseFloat(m.pricing.completion) === 0;
+            return { name: `${m.id} ${isFree ? chalk.green('(Free)') : ''}`, value: m.id };
+          });
+          const { browsedModel } = await inquirer.prompt([
+            {
+              type: 'list',
+              name: 'browsedModel',
+              message: 'Select a model:',
+              choices,
+              pageSize: 20,
+            }
+          ]);
+          selectedModel = browsedModel;
+        }
       }
     }
   }
 
+  const previousProvider = settings.provider || 'openrouter';
+  settings.provider = provider;
   settings.selectedModel = selectedModel;
-  if (!settings.fallbackModel) {
-    settings.fallbackModel = 'openrouter/free';
+  // Reset fallback to provider-appropriate default when switching providers or on first run
+  if (!settings.fallbackModel || previousProvider !== provider) {
+    settings.fallbackModel = provider === 'anthropic' ? 'claude-haiku-4-5-20251001' : 'openrouter/free';
   }
   if (settings.maxIterations === undefined) {
     settings.maxIterations = 10;

package/src/server/agent.js

@@ -1,5 +1,5 @@
 import crypto from 'crypto';
-import OpenAI from 'openai';
+import { createClient } from './provider.js';
 import { loadSystemPrompt, resolveSystemPrompt } from './config.js';
 import { loadSession, saveSession, createSession } from './sessions.js';
 import { loadTools, getToolDefinitions, executeTool } from './tools.js';
@@ -20,17 +20,25 @@ Respond with your normal JSON, but add a checkpoint field:
   "checkpoint": {
     "progress": "What has been fully completed — only include items confirmed by tool output (e.g., successful exec with exit code 0, or verified by ls/cat). Do not report planned steps as completed.",
     "remaining": "What still needs to be done to finish the task — as a plain text string, never an array or object.",
-    "failedApproaches": ["Concise description of each approach that was tried and failed, e.g. 'downloading subfinder via curl from GitHub releases — connection reset'. Omit array entries for things that succeeded. Leave as empty array if nothing failed."]
+    "failedApproaches": ["Concise description of each approach that was tried and failed, e.g. 'downloading subfinder via curl from GitHub releases — connection reset'. Omit array entries for things that succeeded. Leave as empty array if nothing failed."],
+    "state": {"factKey": "factValue — concrete facts confirmed by tool output this run: file paths created, binary locations found, config values discovered. Use short stable keys, e.g. projectDir, zapBinary, scanScriptPath. Omit or use {} if nothing concrete was discovered."}
   }
 }
 
-The checkpoint field will be used to automatically resume the task in the next run. failedApproaches is injected into the next run so the agent does not waste iterations repeating strategies that already failed. remaining must be a plain text string. failedApproaches must be a JSON array of strings.]`;
+The checkpoint field will be used to automatically resume the task in the next run. failedApproaches is injected into the next run so the agent does not waste iterations repeating strategies that already failed. state is injected verbatim so the next run does not need to rediscover file paths or binary locations. remaining must be a plain text string. failedApproaches must be a JSON array of strings. state must be a flat JSON object.]`;
 
 // Serializes concurrent requests for the same session. Maps sessionId to the
 // tail of the current request chain (a Promise that resolves when the last
 // queued request finishes).
 const sessionQueues = new Map();
 
+function accumulateUsage(accum, result) {
+  const u = result?.usage;
+  if (!u) return;
+  accum.prompt += u.prompt_tokens || 0;
+  accum.completion += u.completion_tokens || 0;
+}
+
 async function callModel(client, model, messages, tools) {
   const params = { model, messages };
   if (tools && tools.length > 0) {
@@ -92,7 +100,7 @@ function hasConsecutiveModelErrors(messages) {
  * Runs a single agent loop up to maxIterations.
  * Returns { iteration, response, logSummary, status, runToolCalls, checkpoint }.
  */
-async function runAgentLoop(client, config, session, prepareMessages) {
+async function runAgentLoop(client, config, session, prepareMessages, usageAccum) {
   let tools = await loadTools();
   let toolDefs = getToolDefinitions(tools);
   let iteration = 0;
@@ -116,6 +124,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
       : base;
     try {
       modelResult = await callModelWithFallback(client, config, preparedMessages, toolDefs);
+      accumulateUsage(usageAccum, modelResult);
     } catch (e) {
       return {
         iteration,
@@ -279,6 +288,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
           { role: 'user', content: 'You returned an empty response. ' + FORMAT_NUDGE },
         ];
         const nudgeResult = await callModelWithFallback(client, config, emptyNudge, []);
+        accumulateUsage(usageAccum, nudgeResult);
         const nudgeContent = nudgeResult.choices[0]?.message?.content || '';
         // Persist nudge text before parsing — if JSON parse throws, content still
         // carries the model's best-effort text so the !parsed handler can show it
@@ -297,6 +307,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
         // Step 1: retry with fallback model
         try {
           const fallbackResult = await callModel(client, config.fallbackModel, preparedMessages, toolDefs);
+          accumulateUsage(usageAccum, fallbackResult);
           const fallbackContent = fallbackResult.choices[0]?.message?.content || '';
           parsed = JSON.parse(fallbackContent);
           content = fallbackContent;
@@ -305,6 +316,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
           try {
             const nudgeMessages = [...preparedMessages, { role: 'user', content: FORMAT_NUDGE }];
             const nudgeResult = await callModelWithFallback(client, config, nudgeMessages, toolDefs);
+            accumulateUsage(usageAccum, nudgeResult);
             const nudgeContent = nudgeResult.choices[0]?.message?.content || '';
             parsed = JSON.parse(nudgeContent);
             content = nudgeContent;
@@ -345,6 +357,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
     let wrapUpResult;
     try {
       wrapUpResult = await callModelWithFallback(client, config, wrapUpMessages, []);
+      accumulateUsage(usageAccum, wrapUpResult);
     } catch (e) {
       return {
         iteration,
@@ -381,6 +394,7 @@ async function runAgentLoop(client, config, session, prepareMessages) {
       try {
         const nudgeMessages = [...wrapUpMessages, { role: 'user', content: FORMAT_NUDGE }];
         const nudgeResult = await callModelWithFallback(client, config, nudgeMessages, []);
+        accumulateUsage(usageAccum, nudgeResult);
         const nudgeContent = nudgeResult.choices[0]?.message?.content || '';
         parsedWrapUp = JSON.parse(nudgeContent);
         wrapUpContent = nudgeContent;
@@ -414,6 +428,9 @@ async function runAgentLoop(client, config, session, prepareMessages) {
             typeof item === 'string' ? item : JSON.stringify(item)
           );
         }
+        if (typeof cp.state !== 'object' || cp.state === null || Array.isArray(cp.state)) {
+          cp.state = {};
+        }
         return {
           iteration,
           response,
@@ -468,10 +485,7 @@ export async function handleChat(config, requestSessionId, userMessage) {
  * session lock.
  */
 async function _runHandleChat(config, sessionId, userMessage) {
-  const client = new OpenAI({
-    baseURL: 'https://openrouter.ai/api/v1',
-    apiKey: config.apiKey,
-  });
+  const client = createClient(config);
 
   const systemPromptTemplate = loadSystemPrompt();
   let session = await loadSession(sessionId);
@@ -480,6 +494,11 @@ async function _runHandleChat(config, sessionId, userMessage) {
     session = createSession(systemPromptTemplate);
   }
 
+  // Capture persisted state BEFORE resetting metadata so we can inject it below.
+  const wasZeroProgress = !!session.metadata.lastCheckpointRemaining;
+  const priorCheckpointRemaining = session.metadata.lastCheckpointRemaining || null;
+  const priorCheckpointState = session.metadata.checkpointState || {};
+
   // Preserve accumulated failedApproaches in conversation history before resetting
   // so the model retains knowledge of what failed in the previous batch of handoff runs.
   let userMessageWithContext = userMessage;
@@ -487,10 +506,24 @@ async function _runHandleChat(config, sessionId, userMessage) {
     userMessageWithContext += `\n\n[System: The following approaches were tried and failed in previous runs — consider them exhausted:\n${session.metadata.failedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
   }
 
+  // If this message follows a zero-progress intervention, tell the agent explicitly so
+  // it responds to the user's input instead of blindly resuming the same failing approach.
+  if (wasZeroProgress) {
+    const stateLines = Object.entries(priorCheckpointState).map(([k, v]) => `- ${k}: ${v}`);
+    let note = `\n\n[System: This task previously hit zero-progress and required intervention. If the user has given new direction or clarification, follow it. Otherwise, immediately explain what specific obstacle is blocking progress — do not resume the same failing approach.`;
+    if (stateLines.length > 0) {
+      note += `\n\nKnown facts from previous run:\n${stateLines.join('\n')}`;
+    }
+    note += `]`;
+    userMessageWithContext += note;
+  }
+
   // Append user message and reset handoff state
   session.messages.push({ role: 'user', content: userMessageWithContext });
   session.metadata.handoffCount = 0;
   session.metadata.failedApproaches = [];
+  session.metadata.lastCheckpointRemaining = null;
+  session.metadata.checkpointState = {};
 
   // Resolves {{user_info}} in system prompt at runtime (never persisted)
   function prepareMessages(messages) {
@@ -503,11 +536,15 @@ async function _runHandleChat(config, sessionId, userMessage) {
   }
 
   const allToolCalls = [];
+  const usageAccum = { prompt: 0, completion: 0 };
   let finalResponse = '';
   let finalLogSummary = '';
   let finalStatus = 'ok';
-  // Tracks checkpoint.remaining from the previous handoff run to detect zero progress
-  let previousRemaining = null;
+  // Tracks checkpoint.remaining from the previous handoff run to detect zero progress.
+  // Initialized from persisted metadata so detection works across user messages too —
+  // if the agent was stuck before and produces the same remaining again on the next
+  // user turn, zero-progress fires after just one run instead of two.
+  let previousRemaining = priorCheckpointRemaining;
 
   try {
     // Handoff loop
@@ -532,7 +569,7 @@ async function _runHandleChat(config, sessionId, userMessage) {
       }
 
       const runStartIndex = session.messages.length;
-      const run = await runAgentLoop(client, config, session, prepareMessages);
+      const run = await runAgentLoop(client, config, session, prepareMessages, usageAccum);
       allToolCalls.push(...run.runToolCalls);
 
       if (run.status !== 'checkpoint_reached') {
@@ -590,6 +627,15 @@ async function _runHandleChat(config, sessionId, userMessage) {
         session.metadata.failedApproaches.push(...run.checkpoint.failedApproaches);
       }
 
+      // Merge concrete facts from this run's checkpoint.state into session metadata.
+      // Later runs overwrite earlier values for the same key (newer discoveries win).
+      if (run.checkpoint.state && Object.keys(run.checkpoint.state).length > 0) {
+        session.metadata.checkpointState = {
+          ...(session.metadata.checkpointState || {}),
+          ...run.checkpoint.state,
+        };
+      }
+
       // Zero-progress detection: if checkpoint.remaining is identical to the previous
       // handoff's remaining, the agent completed a full run without making any progress.
       // Stop immediately rather than burning more iterations on a stuck task.
@@ -599,6 +645,10 @@ async function _runHandleChat(config, sessionId, userMessage) {
         finalLogSummary = 'Zero progress detected: task state unchanged after a full run. Human intervention required.';
         finalStatus = 'intervention_required';
 
+        // Persist so that the next user message initializes previousRemaining from this
+        // value — zero-progress will then fire after just one run instead of two.
+        session.metadata.lastCheckpointRemaining = currentRemaining;
+
         await appendLog(sessionId, {
           iteration: 0,
           model: config.selectedModel,
@@ -642,13 +692,17 @@ async function _runHandleChat(config, sessionId, userMessage) {
 
       // Resume with checkpoint.remaining as new prompt.
       // Guard against null/undefined in case the model omitted the field.
-      // Use the full accumulated failedApproaches list across ALL handoff runs so the
-      // agent has complete memory of what has already been tried and failed.
+      // Inject the full accumulated failedApproaches and concrete state so the agent
+      // has complete memory of what failed and what was already discovered.
       let resumeContent = run.checkpoint.remaining || 'Continue with the task.';
       const allFailedApproaches = session.metadata.failedApproaches || [];
       if (allFailedApproaches.length > 0) {
         resumeContent += `\n\n[System: The following approaches were tried and failed in previous runs — do not repeat them:\n${allFailedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
       }
+      const stateToInject = session.metadata.checkpointState || {};
+      if (Object.keys(stateToInject).length > 0) {
+        resumeContent += `\n\n[System: Known facts from previous runs:\n${Object.entries(stateToInject).map(([k, v]) => `- ${k}: ${v}`).join('\n')}]`;
+      }
       session.messages.push({ role: 'user', content: resumeContent });
     }
   } catch (e) {
@@ -664,6 +718,11 @@ async function _runHandleChat(config, sessionId, userMessage) {
     });
     throw e;
   } finally {
+    // Accumulate token usage into session metadata so /usage can read it
+    if (!session.metadata.tokenUsage) session.metadata.tokenUsage = { prompt: 0, completion: 0 };
+    session.metadata.tokenUsage.prompt += usageAccum.prompt;
+    session.metadata.tokenUsage.completion += usageAccum.completion;
+
     // Always persist the session — even if an unexpected error occurred.
     // A failed save must not mask the original error.
     try {

package/src/server/config.js

@@ -31,21 +31,27 @@ export function ensureDirectories() {
 export function loadConfig() {
   dotenv.config({ path: PATHS.envFile });
 
-  const apiKey = process.env.OPENROUTER_API_KEY;
-  if (!apiKey) {
-    throw new Error('OPENROUTER_API_KEY not found. Run `jarvis setup` first.');
-  }
-
   if (!fs.existsSync(PATHS.settingsFile)) {
     throw new Error('settings.json not found. Run `jarvis setup` first.');
   }
 
   const settings = JSON.parse(fs.readFileSync(PATHS.settingsFile, 'utf8'));
+  const provider = settings.provider || 'openrouter';
+
+  let apiKey;
+  if (provider === 'anthropic') {
+    apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) throw new Error('ANTHROPIC_API_KEY not found. Run `jarvis setup` first.');
+  } else {
+    apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey) throw new Error('OPENROUTER_API_KEY not found. Run `jarvis setup` first.');
+  }
 
   return {
+    provider,
     apiKey,
     selectedModel: settings.selectedModel,
-    fallbackModel: settings.fallbackModel || 'openrouter/free',
+    fallbackModel: settings.fallbackModel || (provider === 'anthropic' ? 'claude-haiku-4-5-20251001' : 'openrouter/free'),
     maxIterations: settings.maxIterations || 10,
     maxHandoffs: settings.maxHandoffs || 5,
     port: settings.port || 18008,

package/src/server/provider.js

@@ -0,0 +1,149 @@
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+
+// Convert OpenAI tool definitions to Anthropic format
+function openAIToolsToAnthropic(tools) {
+  if (!tools || tools.length === 0) return [];
+  return tools.map(t => ({
+    name: t.function.name,
+    description: t.function.description || '',
+    input_schema: t.function.parameters || { type: 'object', properties: {}, required: [] },
+  }));
+}
+
+// Convert OpenAI message history to Anthropic format.
+// Key differences:
+//   - system message becomes a separate `system` param, not part of messages
+//   - assistant tool_calls → content array with tool_use blocks
+//   - role:'tool' messages → content array with tool_result blocks inside a user message
+//   - Anthropic requires strict user/assistant alternation; consecutive user messages
+//     (e.g. tool results followed by a system note) are merged
+function openAIMessagesToAnthropic(messages) {
+  let system;
+  let rest = messages;
+
+  if (messages[0]?.role === 'system') {
+    system = messages[0].content;
+    rest = messages.slice(1);
+  }
+
+  const result = [];
+
+  for (let i = 0; i < rest.length; i++) {
+    const msg = rest[i];
+
+    if (msg.role === 'user') {
+      const last = result[result.length - 1];
+      if (last && last.role === 'user') {
+        // Merge into previous user message to maintain strict alternation
+        const newPart = { type: 'text', text: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content) };
+        if (typeof last.content === 'string') {
+          last.content = [{ type: 'text', text: last.content }, newPart];
+        } else {
+          last.content.push(newPart);
+        }
+      } else {
+        result.push({ role: 'user', content: msg.content });
+      }
+
+    } else if (msg.role === 'assistant') {
+      const content = [];
+      if (msg.content) content.push({ type: 'text', text: msg.content });
+      if (msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+          let input = {};
+          try { input = JSON.parse(tc.function.arguments || '{}'); } catch { /* ignore */ }
+          content.push({ type: 'tool_use', id: tc.id, name: tc.function.name, input });
+        }
+      }
+      result.push({ role: 'assistant', content: content.length > 0 ? content : [{ type: 'text', text: '' }] });
+
+      // Collect following tool-result messages into a single user message
+      const toolResults = [];
+      while (i + 1 < rest.length && rest[i + 1].role === 'tool') {
+        i++;
+        toolResults.push({
+          type: 'tool_result',
+          tool_use_id: rest[i].tool_call_id,
+          content: rest[i].content,
+        });
+      }
+      if (toolResults.length > 0) {
+        result.push({ role: 'user', content: toolResults });
+      }
+
+    }
+    // role:'tool' messages that were not consumed above are skipped (shouldn't happen)
+  }
+
+  return { system, messages: result };
+}
+
+// Normalize an Anthropic response to the shape agent.js expects from the OpenAI SDK
+function anthropicResponseToOpenAI(response) {
+  const textParts = response.content.filter(c => c.type === 'text');
+  const toolParts = response.content.filter(c => c.type === 'tool_use');
+
+  const text = textParts.map(t => t.text).join('') || null;
+  const toolCalls = toolParts.length > 0
+    ? toolParts.map(t => ({
+        id: t.id,
+        type: 'function',
+        function: { name: t.name, arguments: JSON.stringify(t.input) },
+      }))
+    : undefined;
+
+  return {
+    choices: [{
+      message: {
+        role: 'assistant',
+        content: toolCalls ? null : text,
+        ...(toolCalls && { tool_calls: toolCalls }),
+      },
+      finish_reason: response.stop_reason === 'tool_use' ? 'tool_calls' : 'stop',
+    }],
+    usage: {
+      prompt_tokens: response.usage?.input_tokens ?? 0,
+      completion_tokens: response.usage?.output_tokens ?? 0,
+      total_tokens: (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0),
+    },
+  };
+}
+
+// Build an Anthropic adapter that exposes the same interface as the OpenAI SDK client
+function createAnthropicClient(apiKey) {
+  const anthropic = new Anthropic({ apiKey });
+
+  return {
+    chat: {
+      completions: {
+        create: async ({ model, messages, tools }) => {
+          const { system, messages: anthropicMessages } = openAIMessagesToAnthropic(messages);
+          const anthropicTools = openAIToolsToAnthropic(tools);
+
+          const params = {
+            model,
+            max_tokens: 8096,
+            messages: anthropicMessages,
+          };
+          if (system) params.system = system;
+          if (anthropicTools.length > 0) params.tools = anthropicTools;
+
+          const response = await anthropic.messages.create(params);
+          return anthropicResponseToOpenAI(response);
+        },
+      },
+    },
+  };
+}
+
+export function createClient(config) {
+  if (config.provider === 'anthropic') {
+    return createAnthropicClient(config.apiKey);
+  }
+  // Default: OpenRouter (OpenAI-compatible)
+  return new OpenAI({
+    baseURL: 'https://openrouter.ai/api/v1',
+    apiKey: config.apiKey,
+  });
+}