@ducci/jarvis 1.0.13 → 1.0.15

package/docs/findings/001-context-explosion.md

@@ -0,0 +1,116 @@
+# Finding 001: Context Window Explosion via Tool Output Accumulation
+
+**Date:** 2026-02-26
+**Severity:** High — renders session completely unusable after enough handoffs
+**Status:** Fixed
+
+---
+
+## What Happened
+
+A session was started with the question *"Hast du Zugriff auf deinen source code? Wo liegt er?"* (Does Jarvis have access to its own source code?). The agent began exploring the filesystem using `exec` and `list_dir`, running commands like `cat agent.js`, `cat tools.js`, `cat app.js`, and various `find` commands.
+
+The task required more than 10 iterations to complete, so the checkpoint/handoff mechanism fired. The agent ran 6 consecutive handoff runs before hitting `maxHandoffs` and stopping with `intervention_required`.
+
+By that point the session `conversation.json` had grown to **687KB**. On the very next user message (*"Why?"*), both the primary and fallback models returned a `400 Provider returned error`. The session was permanently broken — no further messages could be processed.
+
+---
+
+## Root Cause
+
+Two compounding problems:
+
+### 1. Tool output stored verbatim, without size limit
+
+`exec` returns raw `stdout` from shell commands. When the model runs `cat agent.js` (440 lines, ~22 000 chars), that entire output gets stored in `session.messages` as a `role: "tool"` message. Every subsequent model request in that run — and in all future runs — sends this content in full.
+
+There was no cap anywhere on tool result content. A single run of 10 iterations with a few `cat` calls could easily produce 100–200 KB of tool messages.
+
+### 2. Handoff runs accumulated on top of each other
+
+When the iteration limit is hit, the checkpoint/handoff mechanism pushes `checkpoint.remaining` as a new user message and starts a fresh agent run — but on top of the **same, growing** `session.messages` array. Each of the 6 handoff runs added another 10 iterations of tool call messages to the history. Nothing was ever removed.
+
+After 6 runs × ~10 iterations × multiple `cat` commands each, the context reached approximately 170 000 tokens — exceeding the free model's 128 000 token limit. The `400` was the provider rejecting the oversized request.
+
+### Why the `400` appeared on the *next* user message, not during the run
+
+The session's final run hit `maxHandoffs` and stopped. At that point the context was already at or near the limit. When the user sent a new message, the full bloated history was loaded and sent again — this time slightly over the limit — causing the rejection.
+
+---
+
+## Model Context Windows (for reference)
+
+| Model | Context Window |
+|---|---|
+| arcee-ai/trinity-large-preview:free | ~128 000 tokens |
+| Claude Sonnet 4.6 | 200 000 tokens |
+| Gemini 2.5 Pro / 2.0 Flash | 1 000 000 tokens |
+
+A larger model would have delayed the failure, but not prevented it. The conversation would still grow unboundedly.
+
+---
+
+## What We Considered
+
+**Truncate tool results in `prepareMessages`** — works, but runs on every loop iteration and is the wrong place conceptually. The content is already stored in full in the session before `prepareMessages` is ever called.
+
+**Naive sliding window (drop oldest N messages)** — breaks the OpenRouter/OpenAI API contract. Every `role: "tool"` message must be paired with the assistant message containing the matching `tool_call_id`. Slicing arbitrarily through the message array orphans tool results and causes a `400` — the exact error we're trying to fix.
+
+**Token budget / summarisation** — more adaptive but significantly more complex. Requires either token counting per model or an extra LLM call. Overkill for v1.
+
+---
+
+## Fix
+
+Two targeted changes to `src/server/agent.js`.
+
+### 1. Cap tool result content at write time (`MAX_TOOL_RESULT = 4000`)
+
+Right where a tool result is pushed to `session.messages`, cap the content to 4 000 characters. The full result is still passed to `runToolCalls` and therefore written to the JSONL session log — no information is lost for debugging. Only what the model sees is limited.
+
+```js
+const sessionContent = resultStr.length > MAX_TOOL_RESULT
+  ? resultStr.slice(0, MAX_TOOL_RESULT) + '\n[...truncated]'
+  : resultStr;
+session.messages.push({ role: 'tool', tool_call_id: toolCall.id, content: sessionContent });
+```
+
+4 000 chars is ~80 lines of code or a full `ls -la` listing — enough for the model to reason about any output. If more detail is needed, the model should use targeted commands (`grep`, `head`, `tail`) rather than `cat`-ing entire files.
+
+### 2. Strip intermediate tool messages before each handoff
+
+Before calling `runAgentLoop`, snapshot `session.messages.length` as `runStartIndex`. If the run ends with `checkpoint_reached`, splice out all messages added during that run *except the final wrap-up assistant response*, then push `checkpoint.remaining` as the new user message.
+
+```js
+const runStartIndex = session.messages.length;
+const run = await runAgentLoop(...);
+
+// on checkpoint_reached, before resuming:
+session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
+session.messages.push({ role: 'user', content: run.checkpoint.remaining });
+```
+
+**Before** (after 6 handoffs):
+```
+[system] [user: question] [assistant/tool ×10] [wrap-up] [user: checkpoint1]
+         [assistant/tool ×10] [wrap-up] [user: checkpoint2]
+         [assistant/tool ×10] [wrap-up] ...  →  687 KB
+```
+
+**After** (after 6 handoffs):
+```
+[system] [user: question] [wrap-up] [user: checkpoint1]
+         [wrap-up] [user: checkpoint2]
+         [wrap-up] ...  →  ~5 KB
+```
+
+Each handoff now adds 2 messages instead of 20+. The wrap-up message carries the relevant state (what was done, what remains) so the model is not flying blind — it just doesn't have the raw tool noise from previous runs.
+
+---
+
+## Outcome
+
+- Sessions with long-running tasks no longer grow the context unboundedly.
+- The JSONL session log is unaffected — full tool outputs are always written there.
+- The model can still access previous run output via `read_session_log` if needed.
+- A follow-up message after a completed multi-handoff task will no longer receive a `400`.

package/docs/findings/002-handoff-edge-cases.md

@@ -0,0 +1,84 @@
+# Finding 002: Handoff Edge Cases Found During Review of Finding 001
+
+**Date:** 2026-02-26
+**Severity:** Medium
+**Status:** Fixed
+
+---
+
+## Context
+
+While reviewing the fix for [Finding 001](./001-context-explosion.md), two edge cases in the handoff system were found. Neither caused problems in the observed debugging session, but both could cause failures under specific conditions.
+
+---
+
+## Issue A: `checkpoint.remaining` could be `null`, causing a 400 on the next iteration
+
+### What could happen
+
+When the iteration limit is hit, the agent asks the model for a wrap-up response that includes a `checkpoint` field:
+
+```json
+{
+  "response": "...",
+  "logSummary": "...",
+  "checkpoint": {
+    "progress": "...",
+    "remaining": "..."
+  }
+}
+```
+
+The server then pushes `checkpoint.remaining` as a user message to start the next run:
+
+```js
+session.messages.push({ role: 'user', content: run.checkpoint.remaining });
+```
+
+Weaker or free models occasionally omit required fields or set them to `null`. If `remaining` is `null`, the session gets a `{ role: 'user', content: null }` message. Most providers reject a null content field with a `400 Bad Request` on the next model call — the same error that surfaced in Finding 001, but from a different cause.
+
+### Fix
+
+```js
+session.messages.push({ role: 'user', content: run.checkpoint.remaining || 'Continue with the task.' });
+```
+
+---
+
+## Issue B: `intervention_required` did not strip tool history before saving
+
+### What could happen
+
+The tool history strip introduced in Finding 001 runs right before pushing `checkpoint.remaining` for the next run. But the `intervention_required` path (max handoffs exceeded) breaks out of the loop *before* reaching the strip:
+
+```js
+if (session.metadata.handoffCount > config.maxHandoffs) {
+  // ... log and set status ...
+  break;  // ← strip never ran
+}
+
+// strip only reached here, after the if-block
+session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
+```
+
+This meant a session that hit the handoff limit was saved with the full tool history of the last run still in it. When the user sends a new message after `intervention_required`, the model receives all of that accumulated tool history — the same context bloat risk as before the fix in Finding 001.
+
+### Fix
+
+Strip the tool history inside the `intervention_required` branch, before breaking:
+
+```js
+if (session.metadata.handoffCount > config.maxHandoffs) {
+  // ... log and set status ...
+  session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
+  break;
+}
+```
+
+The wrap-up assistant message (last in the array) is preserved — it gives the model context about what was attempted when the user resumes.
+
+---
+
+## Why these weren't caught earlier
+
+Both issues only manifest under specific conditions (model omitting a field; hitting maxHandoffs exactly). The debugging session in Finding 001 stopped at `intervention_required` after 6 handoffs, but the 400 error on the next message was attributed to the overall context size, masking the fact that the strip hadn't run for that final run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",

package/src/index.js

@@ -180,6 +180,30 @@ program
     }
   });
 
+program
+  .command('restart')
+  .description('Restart the Jarvis server (starts it if not running).')
+  .action(async () => {
+    preflight();
+    try {
+      await connectPm2();
+      const desc = await pm2Describe().catch(() => []);
+      const isRunning = desc.length > 0 && desc[0].pm2_env?.status === 'online';
+      if (isRunning) {
+        await pm2Restart();
+        console.log('Jarvis server restarted.');
+      } else {
+        await pm2Start();
+        console.log('Jarvis server started.');
+      }
+      pm2.disconnect();
+    } catch (e) {
+      console.error('Failed to restart Jarvis server:', e.message);
+      pm2.disconnect();
+      process.exit(1);
+    }
+  });
+
 program
   .command('status')
   .description('Display the status of the Jarvis server.')

package/src/server/agent.js

@@ -8,6 +8,7 @@ import chalk from 'chalk';
 
 const FORMAT_NUDGE = 'Your previous response was not valid JSON. Respond only with the required JSON object: {"response": "...", "logSummary": "..."}';
 const LOOP_DETECTION_THRESHOLD = 3;
+const MAX_TOOL_RESULT = 4000;
 
 const WRAP_UP_NOTE = `[System: You have reached the iteration limit. This is your final response for this run.
 Respond with your normal JSON, but add a checkpoint field:
@@ -151,10 +152,13 @@ async function runAgentLoop(client, config, session, prepareMessages) {
         const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
         runToolCalls.push({ name: toolName, args: toolArgs, status: toolStatus, result: resultStr });
 
+        const sessionContent = resultStr.length > MAX_TOOL_RESULT
+          ? resultStr.slice(0, MAX_TOOL_RESULT) + '\n[...truncated]'
+          : resultStr;
         session.messages.push({
           role: 'tool',
           tool_call_id: toolCall.id,
-          content: resultStr,
+          content: sessionContent,
         });
 
         const callKey = `${toolName}|${JSON.stringify(toolArgs)}|${resultStr}`;
@@ -344,6 +348,7 @@ export async function handleChat(config, requestSessionId, userMessage) {
   // Handoff loop
   try {
     while (true) {
+      const runStartIndex = session.messages.length;
       const run = await runAgentLoop(client, config, session, prepareMessages);
       allToolCalls.push(...run.runToolCalls);
 
@@ -405,11 +410,20 @@ export async function handleChat(config, requestSessionId, userMessage) {
           logSummary: 'Max handoffs exceeded. Human intervention required.',
           status: 'intervention_required',
         });
+        // Strip tool history even when stopping — prevents context bloat on the
+        // next user message when human intervention resumes the session.
+        session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
         break;
       }
 
-      // Resume with checkpoint.remaining as new prompt
-      session.messages.push({ role: 'user', content: run.checkpoint.remaining });
+      // Strip intermediate tool messages from this run before resuming.
+      // Keep only the wrap-up assistant response (last message added by runAgentLoop) —
+      // it summarises what was done and is far cheaper context than the raw tool history.
+      session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
+
+      // Resume with checkpoint.remaining as new prompt.
+      // Guard against null/undefined in case the model omitted the field.
+      session.messages.push({ role: 'user', content: run.checkpoint.remaining || 'Continue with the task.' });
     }
   } catch (e) {
     const errorLog = {