@ducci/jarvis 1.0.25 → 1.0.26

package/docs/findings/009-non-string-response-field.md

@@ -0,0 +1,153 @@
+# Finding 009: Non-String `response` Field Crashes Telegram Delivery
+
+**Date:** 2026-03-01
+**Severity:** High — caused "Sorry, something went wrong sending the response" with no useful information for the user
+**Status:** Fixed
+
+---
+
+## Observed Session
+
+The session ran 19 agent runs, all completing successfully (`ok` or `checkpoint_reached`). The crash occurred on run 19. The user asked:
+
+> "List me all tool calls you did In this session. Tool name and args are enough to display for each entry."
+
+The model returned valid JSON but placed the list of tool calls as a JSON **array** (not a string) in the `response` field:
+
+```json
+{
+  "response": [
+    { "tool": "exec", "args": { "cmd": "find ..." } },
+    ...16 entries...
+  ],
+  "logSummary": "Enumerated every tool call made during the session..."
+}
+```
+
+The Telegram user received: **"Sorry, something went wrong sending the response. Please try again."**
+
+---
+
+## Bug Chain
+
+### Step 1 — Agent parses valid JSON, stores non-string response
+
+`runAgentLoop` in `src/server/agent.js` successfully parsed the model's response JSON. The extraction logic had no type check:
+
+```js
+response = parsed.response || content;
+```
+
+`parsed.response` was an array (truthy) → `response` was set to the array. No validation. The array propagated through `finalResponse` all the way to the return value of `handleChat`.
+
+### Step 2 — Telegram handler crashes calling `.trim()` on an array
+
+In `src/channels/telegram/index.js`:
+
+```js
+const text = result.response?.trim()
+  || 'The agent encountered an error...';
+```
+
+`?.` guards against `null` and `undefined` only — not against wrong types. Arrays do not have a `.trim()` method. This threw:
+
+```
+TypeError: result.response.trim is not a function
+```
+
+### Step 3 — Delivery catch block sends the generic error
+
+The TypeError was caught by the outer delivery try/catch, which replied:
+
+```
+Sorry, something went wrong sending the response. Please try again.
+```
+
+The user had no idea what failed. The agent had completed successfully — only the delivery step crashed.
+
+---
+
+## Root Causes
+
+**Primary**: `agent.js` never validates that `parsed.response` is a string after JSON parsing. The response contract ("Your message to the user, in plain text.") is documented but never enforced. Any JSON value — array, object, number, null — passes through silently.
+
+**Secondary**: `telegram/index.js` assumed `result.response` would always be a string or null/undefined, and called `.trim()` without type-guarding.
+
+The same primary bug exists in the wrap-up path (line ~315):
+```js
+response = parsedWrapUp.response || '';
+```
+This would fail identically if the wrap-up model returned a non-string `response`.
+
+---
+
+## What Was Not Caught Earlier
+
+- The JSONL log stored `response: [array]` but the run status was `ok` — nothing flagged as an error on the agent side.
+- The error only surfaces in the Telegram delivery layer, which has no visibility into the JSONL log.
+- The model had valid intent (listing tool calls as a structured data type) — it just put the data in the wrong JSON field type.
+
+---
+
+## Fix
+
+### 1. `src/server/agent.js` — normalize response to string at both sites
+
+**Main response path:**
+```js
+// Before:
+response = parsed.response || content;
+
+// After:
+response = typeof parsed.response === 'string'
+  ? parsed.response
+  : JSON.stringify(parsed.response, null, 2);
+```
+
+**Wrap-up path:**
+```js
+// Before:
+response = parsedWrapUp.response || '';
+
+// After:
+response = typeof parsedWrapUp.response === 'string'
+  ? parsedWrapUp.response
+  : parsedWrapUp.response != null ? JSON.stringify(parsedWrapUp.response, null, 2) : '';
+```
+
+When the model returns a non-string (array, object), it is JSON-stringified with 2-space indentation. The user gets a readable representation of the intended content rather than a crash. This preserves the model's intent while enforcing the string contract.
+
+### 2. `src/channels/telegram/index.js` — defense-in-depth type guard
+
+```js
+// Before:
+const text = result.response?.trim()
+  || 'The agent encountered an error and could not produce a response. Please try again.';
+
+// After:
+const rawResponse = typeof result.response === 'string'
+  ? result.response
+  : result.response != null ? JSON.stringify(result.response, null, 2) : '';
+const text = rawResponse.trim()
+  || 'The agent encountered an error and could not produce a response. Please try again.';
+```
+
+### 3. `docs/system-prompt.md` — explicit type constraint on `response`
+
+Added one sentence to the `## Response Format` section:
+
+```
+The `response` value must be a plain text string — never an array or object. If you need to present structured data (e.g. a list of items), format it as text within the string value.
+```
+
+---
+
+## Outcome
+
+| Fix | Files changed |
+|-----|--------------|
+| Coerce `parsed.response` to string in main and wrap-up paths | `src/server/agent.js` |
+| Type guard before `.trim()` call | `src/channels/telegram/index.js` |
+| Explicit type constraint on `response` field | `docs/system-prompt.md` |
+
+**Effect on the debugging session**: instead of "Sorry, something went wrong sending the response", the user would have received the tool call list formatted as a readable JSON string.

package/docs/system-prompt.md

@@ -30,6 +30,8 @@ There are two types of responses depending on whether you need to use tools:
   "logSummary": "A concise explanation of what you did and why, written for a human reading the logs."
 }
 
+The `response` value must be a plain text string — never an array or object. If you need to present structured data (e.g. a list of items), format it as text within the string value.
+
 Never include markdown code fences, preamble, or any text outside this JSON object. If you cannot complete a task, explain why in the `response` field — still as valid JSON.
 
 ## Tool Use

package/package.json

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

package/src/channels/telegram/index.js

@@ -67,8 +67,11 @@ export async function startTelegramChannel(config) {
 
     try {
       const MAX_TG = 4096;
-      // Guard against empty response (e.g. format_error returns empty string)
-      const text = result.response?.trim()
+      // Guard against empty or non-string response (e.g. model returns array instead of string)
+      const rawResponse = typeof result.response === 'string'
+        ? result.response
+        : result.response != null ? JSON.stringify(result.response, null, 2) : '';
+      const text = rawResponse.trim()
         || 'The agent encountered an error and could not produce a response. Please try again.';
       if (text.length <= MAX_TG) {
         await ctx.reply(text);

package/src/server/agent.js

@@ -247,7 +247,9 @@ async function runAgentLoop(client, config, session, prepareMessages) {
     }
 
     session.messages.push({ role: 'assistant', content });
-    response = parsed.response || content;
+    response = typeof parsed.response === 'string'
+      ? parsed.response
+      : JSON.stringify(parsed.response, null, 2);
     logSummary = parsed.logSummary || '';
 
     done = true;
@@ -312,7 +314,9 @@ async function runAgentLoop(client, config, session, prepareMessages) {
     session.messages.push({ role: 'assistant', content: wrapUpContent });
 
     if (parsedWrapUp) {
-      response = parsedWrapUp.response || '';
+      response = typeof parsedWrapUp.response === 'string'
+        ? parsedWrapUp.response
+        : parsedWrapUp.response != null ? JSON.stringify(parsedWrapUp.response, null, 2) : '';
       logSummary = parsedWrapUp.logSummary || '';
       if (parsedWrapUp.checkpoint) {
         return {