@ducci/jarvis 1.0.38 → 1.0.39

package/docs/findings/015-failed-run-context-strip.md

@@ -1,142 +0,0 @@
-# Finding 015: Failed Runs Leave Tool History in Context (Context Bloat Death Spiral)
-
-**Date:** 2026-03-02
-**Severity:** High — caused 3 consecutive `model_error: Empty choices array` failures; session unusable
-**Status:** Fixed
-
----
-
-## Observed Session
-
-Session `6123209d-ce5a-44d0-be12-29aac58b4cf3`. Model: `nvidia/nemotron-3-nano-30b-a3b:free`. User requested a ZAP security scanning project.
-
-| Entry | Trigger | Status | messageCount at failure | toolCalls |
-|-------|---------|--------|------------------------|-----------|
-| 1 | "hi all good?" | ok | — | 0 |
-| 2 | ZAP task (run 1) | checkpoint_reached | — | 10 |
-| 3 | handoff resume (run 2) | checkpoint_reached | — | 10 |
-| 4 | handoff resume (run 3) | model_error (empty choices, iter 7) | 22 | 26 |
-| 5 | "Why I get Model returned an empty response?" | model_error (empty choices, iter 3) | 27 | 2 |
-| 6 | "Why I get Model returned an empty response again?!!" | model_error (empty choices, iter 5) | 37 | 4 |
-
-The session ended without producing any result. The user received `'Model returned an empty response.'` three times.
-
----
-
-## Root Cause 1: Failed runs leave tool call history in session
-
-### What happened
-
-The handoff loop strips tool call messages for `checkpoint_reached` runs:
-
-```js
-session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
-```
-
-Runs that end with `model_error` or `format_error` received **no strip**. Every tool call message (assistant+tool pair, nudge injections) from the failed run remained in `session.messages`, with only a synthetic error note appended afterward.
-
-Run 3 had 26 tool calls across 7 iterations — approximately 13 messages added to the session. These were preserved verbatim. Each subsequent user turn started with more context than the last.
-
-### Message count growth
-
-- Before run 3: ~8 messages (runs 1 and 2 were both checkpoint_reached and stripped correctly)
-- After entry 4 (model_error, no strip): 21 messages + synthetic note = 22
-- After entry 5 (model_error, no strip): 27 messages + synthetic note = 28
-- At entry 6: 37 messages in context
-
-The free model returns `choices: []` when the context exceeds what it can handle. Each failure added more context, making the next failure more likely: a **positive feedback death spiral**.
-
-### Fix
-
-Apply the same splice that checkpoint runs already use:
-
-```js
-if (finalStatus === 'model_error' || finalStatus === 'format_error') {
-  session.messages.splice(runStartIndex, session.messages.length - runStartIndex);
-  // then push synthetic error note as before
-}
-```
-
-The strip runs before the synthetic error note is pushed, returning the session to its pre-run state plus one concise note. The JSONL log preserves all tool results for retrospective inspection via `read_session_log`.
-
-**File**: `src/server/agent.js` — `_runHandleChat`, non-checkpoint break path
-
----
-
-## Root Cause 2: No detection or escalation for consecutive model_errors
-
-### What happened
-
-After two consecutive `model_error: Empty choices array` entries (4 and 5), no protective mechanism fired. The system continued accepting new user messages and spawning new runs indefinitely.
-
-Existing protection mechanisms all missed this case:
-- `maxHandoffs` — only applies to `checkpoint_reached` runs
-- `consecutiveFailures` — tracks tool failures within a single run
-- Zero-progress detection — only applies to `checkpoint_reached` runs
-
-### Fix
-
-Detect the pattern structurally in `session.messages` before starting each new run: if the last two assistant messages are both synthetic `model_error` notes, the session is in a confirmed failure loop. Escalate to `intervention_required` without running another agent loop.
-
-```js
-function hasConsecutiveModelErrors(messages) {
-  const assistantTail = messages.filter(m => m.role === 'assistant').slice(-2);
-  return (
-    assistantTail.length === 2 &&
-    assistantTail.every(
-      m =>
-        typeof m.content === 'string' &&
-        m.content.startsWith('[System: Previous run failed (model_error)')
-    )
-  );
-}
-```
-
-This uses no additional state: it reads the session history directly. Old sessions are handled correctly. One failure is allowed (transient errors are real); two consecutive failures mean the session cannot self-recover.
-
-Combined with Fix 1, consecutive model_errors in this session would have played out as:
-1. Entry 4 (run 3): model_error → strip → synthetic note. Session back to 9 messages.
-2. Entry 5 (user "Why?"): run 4 starts with 10 messages. If it still fails → strip → synthetic note. Two model_error notes now in session.
-3. Entry 6 (user "Why again?!"): `hasConsecutiveModelErrors` fires → `intervention_required` returned immediately. User gets a clear message: start a new session or switch model.
-
-**File**: `src/server/agent.js` — `hasConsecutiveModelErrors` function + check at top of handoff loop
-
----
-
-## Root Cause 3: Empty choices error message provides no actionable guidance
-
-### What happened
-
-The `choices.length === 0` path returned:
-
-```
-Model returned an empty response.
-```
-
-When the user asked "why?", the agent — with ZAP tool call context still present — continued ZAP investigation instead of explaining the API failure. The opaque error and the polluted context compounded: the model had no clear signal about what went wrong and no guidance on how to recover.
-
-### Fix
-
-Include the context size and recovery guidance in the response:
-
-```js
-response: `Model returned an empty response (${preparedMessages.length} messages in context). This typically happens when the conversation is too long for the model. Try starting a new session or switching to a model with a larger context window.`,
-```
-
-**File**: `src/server/agent.js` — `runAgentLoop`, empty choices early return
-
----
-
-## Why Fix 1 is Primary
-
-Fix 1 is the root fix. With context stripped after each failure, the model operates on a tiny session (~10 messages) on subsequent turns. The free model handles this easily. Fix 2 is a safety net for persistent non-context failures. Fix 3 improves user-facing error messages for the residual cases that slip through.
-
----
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/server/agent.js` | Strip tool history on `model_error`/`format_error` (same as checkpoint) |
-| `src/server/agent.js` | `hasConsecutiveModelErrors` function + check before each run in handoff loop |
-| `src/server/agent.js` | Include message count in empty choices response |

package/docs/findings/016-file-writing-corruption-and-stderr-loop.md

@@ -1,119 +0,0 @@
-# Finding 016: File Writing Corruption, Misleading Stderr Nudge, and Repeated-Error Loop
-
-**Date:** 2026-03-02
-**Severity:** High — agent burned 10 iterations on the wrong diagnosis; task abandoned
-**Status:** Fixed
-
----
-
-## Observed Session
-
-Session `a25fd973-3e92-4902-a96d-536ef0eb3005`. Model: `nvidia/nemotron-3-nano-30b-a3b:free`. User asked to run a ZAP security scanner script.
-
-The script (`scan.sh`) failed immediately with `$ZAP_CMD: command not found`. The agent used all 10 iterations investigating PATH issues and gave up without solving the problem or producing a handoff checkpoint.
-
----
-
-## Root Cause 1: Shell Script Written with Escaped Dollar Signs
-
-### What happened
-
-`scan.sh` was written in a prior session by the agent using `exec` with a shell command (echo or heredoc). Multi-layered escaping — JS string → JSON encoding → bash variable expansion — caused every `$` in the script to be written as `\$` in the file.
-
-In bash, `"\$VAR"` (backslash-dollar in double quotes) suppresses variable expansion and produces the literal string `$VAR`. The script ran but nothing expanded:
-
-```
-bash -x scan.sh http://testphp.vulnweb.com:
-
-+ DOMAIN='$1'                              ← should be 'http://testphp.vulnweb.com'
-+ OUTPUT_DIR='/path/results/$DOMAIN'       ← should be '/path/results/http://...'
-+ '$ZAP_CMD' -cmd ...                      ← tries to run a command literally named '$ZAP_CMD'
-scan.sh: line 27: $ZAP_CMD: command not found
-```
-
-Secondary confirmation: the project directory contained folders literally named `$OUTPUT_DIR` and `$RESULTS_DIR`, created by a prior run of the broken script.
-
-### Fix
-
-Added `write_file` as a seed tool. It calls `fs.promises.writeFile` directly — content arrives as a JSON string and is written to disk verbatim. No shell is involved, so no escaping layer can corrupt dollar signs or backslashes.
-
-Added an optional `mode` parameter (e.g. `"755"`) to make scripts executable in the same call.
-
-Updated the system prompt with a dedicated "Writing Files" section (peer-level to "exec Safety") stating: use `write_file` for all file creation — never `exec` with `echo`, `printf`, or heredoc.
-
-**Files changed:**
-- `src/server/tools.js` — `write_file` added to `SEED_TOOLS`
-- `docs/system-prompt.md` — new "Writing Files" section; removed the buried `echo -e` bullet from exec Safety
-
----
-
-## Root Cause 2: Stderr Nudge Misdirected the Model
-
-### What happened
-
-After every failed tool call with stderr output, the system injected:
-
-> *"Examine the stderr field in the tool result carefully — it likely describes the root cause of the failure."*
-
-The stderr was `$ZAP_CMD: command not found` — which looks like a PATH problem. The real diagnostic clue was in the **stdout** of `bash -x`: `DOMAIN='$1'` (variable not expanded). By directing the model to stderr, the nudge trained its attention away from the evidence.
-
-The model then spent iterations on: explicit PATH overrides, `command -v` checks, `sed -n l`, `cat -A`, `which bash` — all stderr-adjacent investigation — and never examined what the `-x` trace was actually showing.
-
-### Fix
-
-Changed the stderr nudge to cover both stdout and stderr, with an explicit callout to `bash -x` as a debug tool whose key output is in stdout:
-
-```
-[System: A command failed. Examine both the stdout AND stderr fields in the tool result —
-stderr names the error, but stdout (especially from debug commands like bash -x) often shows
-the root cause. Do not retry without first understanding what the full output is telling you.]
-```
-
-**File changed:** `src/server/agent.js` — `stderrErrorInIteration` nudge
-
----
-
-## Root Cause 3: No Detection for the Same Error Repeating Across Different Commands
-
-### What happened
-
-The existing loop detector tracks `tool + args + result` triples. Because the model varied its tool calls each iteration (different PATH strings, different diagnostic commands), this never triggered. Meanwhile `$ZAP_CMD: command not found` appeared in stderr across 5+ tool calls from entirely different commands — a strong signal that the diagnosis is wrong, not the approach.
-
-Existing detectors that missed this:
-- `loopTracker` — requires identical tool + args + result; missed because args varied
-- `consecutiveFailures` — tracks back-to-back failures; partially reset when some calls succeeded
-- `maxHandoffs` / zero-progress — apply only to checkpoint-reached runs
-
-### Fix
-
-Added `stderrTracker = new Map()` in `runAgentLoop` (parallel to `loopTracker`). After each failed tool call, the first line of stderr is extracted as the key and its count incremented.
-
-When any stderr string reaches `CONSECUTIVE_FAILURE_THRESHOLD` (3), a targeted "step back" nudge is injected, quoting the repeating error, instead of the basic stderr nudge:
-
-```
-[System: The error "$ZAP_CMD: command not found" has now appeared 3 times across different
-commands. You are repeatedly diagnosing the wrong thing. Stop, step back, and reconsider
-from scratch — what is this error fundamentally telling you about the state of the system?]
-```
-
-Using only the first line of stderr (not the full message) makes the tracker robust to verbose multi-line output where later lines may contain timestamps or variable content.
-
-**File changed:** `src/server/agent.js` — `stderrTracker`, `firstStderrLine` extraction, `repeatedStderr` check replacing basic stderr nudge when threshold reached
-
----
-
-## Why the Session Never Produced a Checkpoint
-
-The model produced a final text response on iteration 10 (it didn't time out — it gave up). This means `!done` was never true after the while loop, so the wrap-up / checkpoint path never ran. The model exhausted its budget investigating PATH and on the last iteration concluded it couldn't solve the problem.
-
-Fix 3 (repeated-error nudge) would have fired by iteration 5–6 with the specific message quoting `$ZAP_CMD: command not found`. At that point the model would have had a chance to reconsider what the error was telling it rather than continuing PATH investigation.
-
----
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/server/tools.js` | Added `write_file` seed tool |
-| `docs/system-prompt.md` | Added "Writing Files" section; removed `echo -e` bullet from exec Safety |
-| `src/server/agent.js` | Added `stderrTracker`; first-line stderr key extraction; repeated-error nudge overriding basic stderr nudge; broadened stderr nudge wording to cover stdout |

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

@@ -1,110 +0,0 @@
-# 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/docs/findings/018-anthropic-oauth-token-support.md

@@ -1,72 +0,0 @@
-# Finding 018: Anthropic OAuth Token Not Supported
-
-**Date:** 2026-03-06
-**Severity:** High — every request fails with 401; server completely non-functional with OAuth credentials
-**Status:** Fixed
-
----
-
-## Observed Session
-
-Session `ee5ec010-667d-4964-92c6-d45106f72911`. Provider: Anthropic direct API. Key prefix: `sk-ant-oat01-` (OAuth token generated via `claude setup-token`).
-
-| Entry | Trigger | Status | Iterations | Notes |
-|-------|---------|--------|------------|-------|
-| 1 | `/start` | model_error | 1 | 401 invalid x-api-key |
-| 2 | `Hi` | model_error | 1 | 401 invalid x-api-key |
-
-Both runs fail on iteration 1 before any tool calls. Zero useful work done.
-
----
-
-## Root Cause
-
-`createAnthropicClient` in `src/server/provider.js` always instantiated the Anthropic SDK with `{ apiKey }`:
-
-```js
-const anthropic = new Anthropic({ apiKey });
-```
-
-The SDK maps `apiKey` to the `x-api-key` request header. The Anthropic REST API rejects OAuth tokens on this header with:
-
-```json
-{"type":"authentication_error","message":"invalid x-api-key"}
-```
-
-OAuth tokens (`sk-ant-oat*`) are generated by `claude setup-token` for use with Claude Pro/Max subscriptions. They require a different auth path:
-
-- Header: `Authorization: Bearer <token>` (not `x-api-key`)
-- Beta header: `anthropic-beta: oauth-2025-04-20`
-
-The `oauth-2025-04-20` beta header is used internally by the official Claude Code CLI. Without it, the API returns `"OAuth authentication is currently not supported."` even with the correct `Authorization: Bearer` header.
-
----
-
-## Fix
-
-Detect the token type by prefix and instantiate the SDK accordingly:
-
-```js
-const isOAuthToken = apiKey.startsWith('sk-ant-oat');
-const anthropic = isOAuthToken
-  ? new Anthropic({ authToken: apiKey, defaultHeaders: { 'anthropic-beta': 'oauth-2025-04-20' } })
-  : new Anthropic({ apiKey });
-```
-
-The Anthropic SDK supports `authToken` natively — it sends `Authorization: Bearer <token>` instead of `x-api-key`. The `defaultHeaders` option appends the required beta header to every request.
-
-No changes to the adapter interface or anywhere else in the codebase. Both paths produce identical output shape.
-
----
-
-## Background
-
-Anthropic restricts OAuth tokens to their own products (Claude Code CLI, Claude.ai) via ToS. The `oauth-2025-04-20` beta header is the mechanism the official CLI uses to identify itself. Using it in Jarvis enables the same auth path.
-
----
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/server/provider.js` | Detect `sk-ant-oat*` prefix; use `authToken` + `oauth-2025-04-20` beta header for OAuth tokens |