@ducci/jarvis 1.0.26 → 1.0.27

package/docs/findings/010-checkpoint-field-type-safety.md

@@ -0,0 +1,121 @@
+# Finding 010: Non-String `checkpoint.remaining` Crashes Zero-Progress Detection
+
+**Date:** 2026-03-01
+**Severity:** High — caused "Sorry, something went wrong" in Telegram with no useful context; crashed the handoff loop mid-run
+**Status:** Fixed
+
+---
+
+## Observed Session
+
+The session ran 13+ agent runs working on OWASP ZAP installation. Runs 8–13 were consecutive `checkpoint_reached` handoffs. On entry 14 (immediately after entry 13), the server logged:
+
+```
+status: error
+response: "An unexpected server error occurred: (run.checkpoint.remaining || "").trim is not a function"
+```
+
+The Telegram user received:
+
+```
+Sorry, something went wrong: (run.checkpoint.remaining || "").trim is not a function
+```
+
+---
+
+## Bug Chain
+
+### Step 1 — Wrap-up call returns non-string `remaining`
+
+At iteration limit, `runAgentLoop` sends the `WRAP_UP_NOTE` and parses the model's JSON response. The model returned `checkpoint.remaining` as a non-string value (array or object) instead of a plain text string. `parsedWrapUp.checkpoint` was stored and returned with no type validation.
+
+### Step 2 — Zero-progress detection crashes on `.trim()`
+
+In `_runHandleChat`, finding 007 introduced zero-progress detection:
+
+```js
+const currentRemaining = (run.checkpoint.remaining || '').trim();
+```
+
+The `|| ''` guard only catches falsy values (null, undefined). A truthy non-string (array, object) passes through the `||` and `.trim()` is called on a non-string:
+
+```
+TypeError: (run.checkpoint.remaining || "").trim is not a function
+```
+
+### Step 3 — Outer catch logs the error and re-throws
+
+The `try/catch` at the top of the handoff loop caught the TypeError, wrote an `error` status log entry, and re-threw. The Telegram handler surfaced the raw error message.
+
+---
+
+## Secondary Issues
+
+**`resumeContent` (line 520)**: `run.checkpoint.remaining || 'Continue with the task.'` — if `remaining` is a truthy non-string, it would be pushed directly into `session.messages` as the next user message content. The message API expects a string, so this would produce a malformed conversation message.
+
+**`failedApproaches` spread (lines 461–463)**: If the model returns `failedApproaches` as a non-array (string, object), `push(...value)` would spread wrong data. A string spreads individual characters; an object spreads its enumerable values.
+
+---
+
+## Root Cause
+
+Same class of bug as finding 009 (non-string `response` field). Finding 009 hardened `response` and `logSummary` extraction, but the `checkpoint` sub-object fields were not included in that hardening pass. Models — especially smaller/free models under iteration-limit pressure — sometimes return structured data (arrays, objects) in fields the system prompt specifies as plain text strings.
+
+---
+
+## Fix
+
+### `src/server/agent.js` — normalize checkpoint fields at source
+
+Added a normalization block immediately inside the `if (parsedWrapUp.checkpoint)` branch, before any checkpoint field is accessed downstream:
+
+```js
+const cp = parsedWrapUp.checkpoint;
+// remaining must be a string — used as the next run's resume prompt
+if (typeof cp.remaining !== 'string') {
+  cp.remaining = Array.isArray(cp.remaining)
+    ? cp.remaining.map(String).join('\n')
+    : cp.remaining != null ? JSON.stringify(cp.remaining) : '';
+}
+// failedApproaches must be an array of strings — spread into session metadata
+if (!Array.isArray(cp.failedApproaches)) {
+  cp.failedApproaches = [];
+} else {
+  cp.failedApproaches = cp.failedApproaches.map(item =>
+    typeof item === 'string' ? item : JSON.stringify(item)
+  );
+}
+```
+
+**Array coercion for `remaining`**: when the model returns an array (e.g., `["install Java", "create symlink"]`), elements are joined with newlines rather than JSON-stringified — producing a natural readable resume prompt rather than raw JSON syntax.
+
+**Centralized normalization**: fixing at source (right after parse) rather than at each use site means lines 469 and 520 need no change. Any future use of `checkpoint.remaining` or `checkpoint.failedApproaches` is automatically safe.
+
+### `src/server/agent.js` — update `WRAP_UP_NOTE`
+
+Added explicit type constraints to the `remaining` field description and a trailing instruction:
+
+```
+"remaining": "What still needs to be done — as a plain text string, never an array or object."
+...
+remaining must be a plain text string. failedApproaches must be a JSON array of strings.
+```
+
+---
+
+## What Was Not Changed
+
+- `agent.js` lines 469 and 520 — no changes needed; normalization at source makes them safe
+- `src/channels/telegram/index.js` — finding 007 and 009 already added `.catch(() => {})` and type guards on delivery
+- `sessions.js`, `tools.js` — no changes needed
+
+---
+
+## Outcome
+
+| Fix | Files changed |
+|-----|--------------|
+| Normalize `checkpoint.remaining` to string and `checkpoint.failedApproaches` to string array at source | `src/server/agent.js` |
+| Add explicit type constraints to WRAP_UP_NOTE | `src/server/agent.js` |
+
+**Effect**: instead of a `TypeError` crash mid-handoff-loop, the model's non-string `remaining` value is coerced to a readable string and used as the resume prompt. The session continues normally.

package/package.json

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

package/src/server/agent.js

@@ -19,12 +19,12 @@ Respond with your normal JSON, but add a checkpoint field:
   "logSummary": "Human-readable summary of what happened in this run.",
   "checkpoint": {
     "progress": "What has been fully completed so far.",
-    "remaining": "What still needs to be done to finish the task.",
+    "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."]
   }
 }
 
-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.]`;
+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.]`;
 
 // Serializes concurrent requests for the same session. Maps sessionId to the
 // tail of the current request chain (a Promise that resolves when the last
@@ -319,6 +319,22 @@ async function runAgentLoop(client, config, session, prepareMessages) {
         : parsedWrapUp.response != null ? JSON.stringify(parsedWrapUp.response, null, 2) : '';
       logSummary = parsedWrapUp.logSummary || '';
       if (parsedWrapUp.checkpoint) {
+        // Normalize checkpoint fields to their expected types. Models sometimes
+        // return arrays or objects in fields that must be strings — the same class
+        // of bug fixed for `response` in finding 009.
+        const cp = parsedWrapUp.checkpoint;
+        if (typeof cp.remaining !== 'string') {
+          cp.remaining = Array.isArray(cp.remaining)
+            ? cp.remaining.map(String).join('\n')
+            : cp.remaining != null ? JSON.stringify(cp.remaining) : '';
+        }
+        if (!Array.isArray(cp.failedApproaches)) {
+          cp.failedApproaches = [];
+        } else {
+          cp.failedApproaches = cp.failedApproaches.map(item =>
+            typeof item === 'string' ? item : JSON.stringify(item)
+          );
+        }
         return {
           iteration,
           response,