@ducci/jarvis 1.0.38 → 1.0.39

package/docs/findings/006-malformed-tool-schema.md

@@ -1,118 +0,0 @@
-# Finding 006: Malformed Tool Schema Poisons Every Subsequent Request
-
-**Date:** 2026-02-27
-**Severity:** High — permanently breaks all model calls for the session until tools.json is manually repaired
-**Status:** Fixed
-
----
-
-## What Happened
-
-During a session installing security tools (Nuclei, Subfinder, Naabu), the agent called `save_tool` to create a custom `scan` tool. The model passed the `parameters` field as a **JSON-serialized string** instead of a JSON object:
-
-```json
-"parameters": "{\"type\":\"object\",\"properties\":{\"domain\":{\"type\":\"string\",...}}}"
-```
-
-`save_tool` stored this verbatim — no validation occurred. The malformed tool definition was written to `~/.jarvis/data/tools/tools.json` as tool index 12.
-
-On the very next model call (within the same run), Jarvis reloaded tools after `save_tool` completed (`toolsModified = true`) and sent all tool definitions to the provider. OpenRouter's provider API returned:
-
-```
-400 Provider returned error
-[{'type': 'dict_type', 'loc': ('body', 'tools', 12, 'function', 'parameters'),
-  'msg': 'Input should be a valid dictionary', 'input': '{"type":"object",...}'}]
-```
-
-Every subsequent user message — including trivial ones like "Was ist schief gegangen?" and "Wie ist deine session id" — also failed with the same 400. The malformed tool was permanently in `tools.json` and included in every model request.
-
----
-
-## Root Cause
-
-### 1. `save_tool` did not validate `parameters`
-
-The `save_tool` code stored `args.parameters` directly into `tools.json` without checking its type. The OpenAI tool-calling spec requires `parameters` to be a JSON Schema object (a dictionary). When a model passes a JSON string instead of an object — a common mistake with weaker models — the result is a permanently malformed tool definition.
-
-### 2. `getToolDefinitions` sent all tools to the provider without validation
-
-`getToolDefinitions` returned all tool definitions unconditionally. A single malformed tool poisoned every request that included the tools list — which is every request, since tool definitions are always sent.
-
-These two gaps compound each other: the first allows bad data in, the second ensures it breaks everything downstream.
-
----
-
-## Why it Persists Across All Subsequent Messages
-
-Every `handleChat` call loads tools fresh from `tools.json` via `loadTools()`. The malformed `scan` tool is always in the list. Every model call sends all tool definitions. The provider rejects every request. The session is stuck until `tools.json` is manually repaired.
-
----
-
-## Intermittent Behavior
-
-The failure is not always immediate. In the debugging session, two tool calls succeeded in later runs before the 400 fired. This is consistent with free/preview model providers (nvidia via OpenRouter) applying schema validation inconsistently across backend instances. The bug is therefore not "always broken" but **reliably broken under load** — which is harder to detect and debug than a consistent failure.
-
----
-
-## Fix
-
-Two targeted changes to `src/server/tools.js`.
-
-### 1. `save_tool` validates and auto-corrects `parameters`
-
-Before writing to `tools.json`, the `save_tool` code now:
-- If `parameters` is a string, attempts `JSON.parse()` — models commonly serialize the object when they should pass it directly. If parsing succeeds and yields an object, the corrected value is used silently.
-- If `parameters` is still not a plain object after the attempted parse, returns an error immediately with a clear message. Nothing is written to disk.
-
-```js
-let parameters = args.parameters;
-if (typeof parameters === 'string') {
-  try {
-    parameters = JSON.parse(parameters);
-  } catch {
-    return { status: 'error', error: 'parameters must be a JSON Schema object, not a string. Pass the object directly, not as a JSON-serialized string.' };
-  }
-}
-if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) {
-  return { status: 'error', error: 'parameters must be a JSON Schema object (e.g. { type: "object", properties: {...} }).' };
-}
-```
-
-### 2. `getToolDefinitions` filters out malformed tools
-
-`getToolDefinitions` now validates `parameters` on each tool before including it in the definitions sent to the provider. A tool with a non-object `parameters` is skipped with a `console.warn`, not thrown — this is a defence-in-depth guard, not a primary error path.
-
-```js
-export function getToolDefinitions(tools) {
-  const defs = [];
-  for (const [name, t] of Object.entries(tools)) {
-    const params = t.definition?.function?.parameters;
-    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
-      console.warn(`[tools] Skipping tool '${name}': parameters is not a valid object (got ${typeof params})`);
-      continue;
-    }
-    defs.push(t.definition);
-  }
-  return defs;
-}
-```
-
-Together: Fix 1 prevents malformed tools from entering `tools.json`. Fix 2 ensures that even if a malformed tool somehow ends up in `tools.json` (e.g. from an older version, manual edit, or a bug that slips through), it is silently excluded from every model request rather than poisoning the session.
-
----
-
-## Secondary Issue: Agent Hallucinated Successful Action
-
-In the run that preceded the `save_tool` call, the agent responded with:
-
-> "The scanning script has been created at /root/.jarvis/projects/cybersecurity/scan.sh."
-
-No such file was ever created — the agent had only installed Nuclei successfully. This hallucination forced the next run to attempt recovery via `save_tool`, which is where the malformed tool was introduced. The hallucination itself is a model-quality issue with the free nvidia model, not a Jarvis bug.
-
----
-
-## Outcome
-
-- `save_tool` auto-corrects the common case (string instead of object) and rejects the rest with a clear error before writing to disk
-- A pre-existing malformed tool in `tools.json` no longer poisons model requests — it is silently skipped per call
-- Sessions are no longer permanently broken by a single bad `save_tool` call

package/docs/findings/007-telegram-errors-and-handoff-stalling.md

@@ -1,271 +0,0 @@
-# Finding 007: Telegram Error Opacity, Empty Responses, and Handoff Stalling
-
-**Date:** 2026-02-28
-**Severity:** High — caused "Sorry, something went wrong" with no context, silent empty responses, and 40+ wasted iterations on a stuck task
-**Status:** Fixed
-
----
-
-## Observed Session
-
-The session (`fdb3fb46`) ran on a Linux server using `nvidia/nemotron-3-nano-30b-a3b:free`. The user asked Jarvis to implement a cybersecurity scanning project and run a scan against `https://dviet.de`. The session produced 10 agent runs over approximately 2 hours, including 4 consecutive handoff runs that made no real progress, two "Sorry, something went wrong" errors in Telegram, and one completely silent (empty) Telegram message.
-
----
-
-## What Happened — Full Run Sequence
-
-| Run | Trigger | Status | Telegram received |
-|-----|---------|--------|-------------------|
-| 1 | "Hi" | ok | "Hello Duc! 👋" |
-| 2 | "Weißt du wo das cybersecurity Projekt liegt?" | ok (9 iterations) | Location found |
-| 3 | "Kannst du das readme lesen..." | ok | README analysis |
-| 4 | "Yes implement the missing pieces..." | **format_error** | **Empty message (silent)** |
-| 5 | "What exactly went wrong?" (handoff 1) | checkpoint_reached | — (internal handoff loop) |
-| 6 | handoff 2 | checkpoint_reached | — (internal) |
-| 7 | handoff 3 | checkpoint_reached | — (internal) |
-| 8 | handoff 4 | **model_error** | **"Sorry, something went wrong: ..."** |
-| 9 | "What is your session id" | ok | Session ID |
-| 10 | "Do exec ls" | **model_error** | **"Sorry, something went wrong: ..."** |
-
----
-
-## Issue 1: Generic "Sorry, something went wrong" with no context
-
-### What happened
-
-Runs 8 and 10 failed with `model_error: Empty choices array` — the nvidia free model returned a response with `choices: []`, producing no content at all. When `handleChat` threw an error, the Telegram channel's catch block sent:
-
-```
-Sorry, something went wrong. Please try again.
-```
-
-This is maximally unhelpful. The user has no idea whether the model failed, whether a tool crashed, whether the session is broken, or whether retrying will help.
-
-### Root cause
-
-The catch block in `src/channels/telegram/index.js` used a hardcoded string regardless of the actual error:
-
-```js
-} catch (e) {
-  console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
-  await ctx.reply('Sorry, something went wrong. Please try again.');
-  clearInterval(typingInterval);
-  return;
-}
-```
-
-The error message was logged to `console.error` (only visible in server logs, not to the user) and discarded.
-
-### Fix (`src/channels/telegram/index.js`)
-
-Pass `e.message` to the user reply:
-
-```js
-const errText = e.message
-  ? `Sorry, something went wrong: ${e.message}`
-  : 'Sorry, something went wrong. Please try again.';
-await ctx.reply(errText).catch(() => {});
-```
-
-The `.catch(() => {})` guards against a second failure when the Telegram API itself is unreachable — without it, a failed `ctx.reply` inside the catch block would throw an unhandled rejection.
-
----
-
-## Issue 2: Empty Telegram message on `format_error`
-
-### What happened
-
-Run 4 ended with `format_error` — the model produced a non-JSON final response and all three recovery attempts (fallback model, nudge retry) also failed. The agent returned with `response: ""` (empty string). The Telegram handler then called:
-
-```js
-const text = result.response;  // ""
-await ctx.reply(text);          // ctx.reply("") — Telegram silently rejects empty messages
-```
-
-The user saw nothing. No error, no confirmation, no indication that anything had happened. From their perspective the message was sent and never received a reply.
-
-### Root cause
-
-The delivery block in `src/channels/telegram/index.js` used `result.response` directly without guarding against empty or null values. When `format_error` returns an empty string, `ctx.reply("")` is called and Telegram's API rejects it silently (HTTP 400 from Telegram, swallowed by grammy).
-
-Additionally, the error log in the delivery catch block used `result.response.length`, which would throw a `TypeError` if `result.response` was `null` rather than `""`.
-
-### Fix (`src/channels/telegram/index.js`)
-
-Guard with `?.trim()` and a fallback message:
-
-```js
-const text = result.response?.trim()
-  || 'The agent encountered an error and could not produce a response. Please try again.';
-```
-
-Also updated the delivery catch block to not reference `result.response.length` (which crashes on null).
-
----
-
-## Issue 3: `failedApproaches` memory lost across handoff runs
-
-### What happened
-
-Runs 5, 6, 7, and 8 were all consecutive handoff runs triggered by a single user message ("What exactly went wrong?"). Each run correctly produced a `failedApproaches` array in its checkpoint — for example, "nuclei scan command timed out". However, the resume message for the next run was built using only the **current run's** `failedApproaches`:
-
-```js
-if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
-  resumeContent += `\n\n[System: The following approaches were tried and failed in the previous run — ...]`
-  // ↑ only the last run's failures, not all previous runs
-}
-```
-
-Run 6 started knowing about run 5's failures. Run 7 started knowing about run 6's failures — but had forgotten run 5's. Run 8 started knowing about run 7's failures — but had forgotten runs 5 and 6. The model could only see one run of history at a time and kept rediscovering and re-attempting strategies it had already tried.
-
-The session JSONL log shows runs 5, 6, 7, and 8 all executing nearly identical tool call sequences:
-
-- `nuclei -update-templates`
-- `nuclei -h`
-- `mkdir -p results/dviet.de`
-- `which node`
-- `ls -al /usr/local/share/nuclei` → error (directory doesn't exist)
-- `echo -e '#!/bin/bash...'` → broken scan.sh
-- `nuclei -silent ... -u https://dviet.de` → **60s timeout**
-- `nmap -sV -p 80,443 dviet.de` → host down
-- `nuclei -silent -t http-title ...` → **60s timeout**
-
-32 tool calls in run 8 alone, across only 3 model iterations — the model was dumping the same 10-call batch per iteration, learning nothing.
-
-### Fix (`src/server/agent.js`, `src/server/sessions.js`)
-
-**1.** Added `failedApproaches: []` to `session.metadata` in `createSession()`. This gives old sessions a graceful upgrade path (the field will be initialized to `[]` on the first new user message that resets handoff state).
-
-**2.** On every new user message, `failedApproaches` is reset alongside `handoffCount`:
-
-```js
-session.metadata.handoffCount = 0;
-session.metadata.failedApproaches = [];
-```
-
-**3.** After each `checkpoint_reached` run, the current run's failures are pushed onto the session-level accumulator:
-
-```js
-if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
-  if (!session.metadata.failedApproaches) session.metadata.failedApproaches = [];
-  session.metadata.failedApproaches.push(...run.checkpoint.failedApproaches);
-}
-```
-
-**4.** The resume message uses the full accumulated list instead of just the last run's:
-
-```js
-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')}]`;
-}
-```
-
-The message changed from "in the **previous run**" to "in **previous runs**" to accurately reflect the scope.
-
----
-
-## Issue 4: Zero-progress handoffs not detected
-
-### What happened
-
-Runs 5, 6, and 7 all hit `checkpoint_reached` with nearly identical `remaining` fields. Each run used 10 full iterations yet made no real progress — the `remaining` list after run 7 was essentially the same as after run 5. The handoff loop continued spawning new runs until `maxHandoffs` was hit, burning 30 more iterations and about 90 minutes of wall time.
-
-The existing `maxHandoffs` limit (default 5) is the only backstop, but it doesn't distinguish between runs that make real progress and runs that achieve nothing. It allows up to 5 useless handoffs before stopping.
-
-### Root cause
-
-No comparison was made between consecutive `checkpoint.remaining` values. The handoff loop always continued as long as `handoffCount <= maxHandoffs`, with no check that the agent had actually made forward progress.
-
-### Fix (`src/server/agent.js`)
-
-Introduced a `previousRemaining` variable in the handoff loop. Before each handoff continuation, the current `checkpoint.remaining` (trimmed) is compared against the previous run's value. If they are identical, the session is stopped immediately with `intervention_required`:
-
-```js
-let previousRemaining = null;
-
-// ... inside handoff loop, after checkpoint_reached:
-const currentRemaining = (run.checkpoint.remaining || '').trim();
-if (previousRemaining !== null && currentRemaining === previousRemaining) {
-  finalStatus = 'intervention_required';
-  finalLogSummary = 'Zero progress detected: task state unchanged after a full run. Human intervention required.';
-  // log, strip, break
-}
-previousRemaining = currentRemaining;
-```
-
-This fires on the **second** handoff with identical remaining — one repeat is allowed because the model may be working on the same items in a different order. Identical remaining on two consecutive runs means it is genuinely stuck.
-
-**Effect on the debugging session**: instead of running 4 useless handoffs (runs 5–8), the agent would have stopped at run 6 with `intervention_required`, saving 20 iterations and about 60 minutes.
-
----
-
-## Issue 5: `echo -e` creates broken shell scripts on Ubuntu
-
-### What happened
-
-The model attempted to create `scan.sh` using:
-
-```sh
-echo -e '#!/bin/bash\n# Simple wrapper...\n...'
-```
-
-On Ubuntu, the default shell for non-interactive commands is `/bin/dash`, not `/bin/bash`. `dash` does not support `echo -e` — it treats `-e` as a literal argument, so the file started with:
-
-```
--e #!/bin/bash
-# Simple wrapper...
-```
-
-Every attempt to run `scan.sh` failed with:
-
-```
-/root/.jarvis/projects/cybersecurity/scan.sh: 1: -e: not found
-```
-
-The model detected the error on the first try, but each subsequent handoff run repeated the exact same broken creation command, presumably because the `echo -e` pattern was deep in the model's training distribution for "create a shell script".
-
-### Root cause
-
-The system prompt's `## exec Safety` section gave guidance about filesystem scans and `cat` vs `grep`, but said nothing about portable file creation. The `echo -e` pattern works on bash but not on sh/dash, and this distinction is invisible to a model working through `exec`.
-
-### Fix (`docs/system-prompt.md`)
-
-Added a bullet to `## exec Safety`:
-
-```
-- **Writing multi-line files**: use `printf '...'` or a heredoc (`cat <<'EOF' > file`) instead of
-  `echo -e`. The `-e` flag is not portable — on Ubuntu `/bin/sh` it is treated as literal text,
-  corrupting the file.
-```
-
----
-
-## What Was Not Changed
-
-- The `model_error: Empty choices array` path in `runAgentLoop` — this is a provider-side failure, no server-side fix can prevent the model from returning nothing. The fix is at the Telegram delivery layer (surfacing the error to the user), not at the agent layer.
-- The `maxHandoffs` limit — it remains as a hard cap. Zero-progress detection fires before `maxHandoffs` in the case of a truly stuck task, so the two mechanisms are complementary.
-- The `consecutiveFailures` detector and exact-match loop tracker — unchanged; they work alongside the new zero-progress check.
-- No per-session Perplexity call counter was added server-side.
-
----
-
-## Secondary Observation: nuclei templates were present but never found
-
-Nuclei was installed at `/usr/local/bin/nuclei`. Its templates were at `/root/nuclei-templates` (visible in the `list_dir /root` output from run 2). However, the model never connected these two facts — it searched `/usr/local/share/nuclei`, `/root/.nuclei`, and various `/usr` subdirectories, missing the templates that were right there in `/root`.
-
-Running `nuclei -u https://dviet.de -t /root/nuclei-templates/...` (or just `nuclei -u https://dviet.de` with the templates auto-discovered from `~/nuclei-templates`) would likely have worked. The scan also failed because `nmap` reported "host seems down" for `dviet.de` — the host was either rate-limiting ICMP or the port scan was blocked. Using `nmap -Pn` to skip host discovery would have bypassed this.
-
-Neither of these is a Jarvis bug — they are model reasoning failures specific to this session and this free model. A more capable model would have spotted the template path and the nmap flag.
-
----
-
-## Outcome
-
-| Fix | Files changed |
-|-----|--------------|
-| Better error text in Telegram catch block | `src/channels/telegram/index.js` |
-| Guard against empty response before `ctx.reply()` | `src/channels/telegram/index.js` |
-| Accumulate `failedApproaches` across all handoffs in `session.metadata` | `src/server/agent.js`, `src/server/sessions.js` |
-| Zero-progress handoff detection via `previousRemaining` comparison | `src/server/agent.js` |
-| Shell script writing guidance (`printf`/heredoc over `echo -e`) | `docs/system-prompt.md` |

package/docs/findings/008-exec-timeout-architecture.md

@@ -1,118 +0,0 @@
-# Finding 008: exec Timeout Architecture — Agent Cannot Increase Its Own Timeout
-
-**Date:** 2026-02-28
-**Severity:** Medium — caused 5 wasted user interactions and agent confusion; no crashes or data loss
-**Status:** Fixed
-
----
-
-## What Happened
-
-A user asked Jarvis to run a cybersecurity scan script (`nuclei` + `nmap`) against `https://dviet.de`. The script ran via the `exec` tool and timed out after 60 seconds. The user then asked the agent to "increase the timeout to 5 minutes."
-
-The agent attempted this in two ways:
-
-1. **Run 11**: Used `exec` to run `sed -i 's/"timeout": 60000/"timeout": 300000/g' tools.json` — changing the `timeout` value inside the exec tool's `code` string from 60s to 300s.
-2. **Run 13**: Called `save_tool` to recreate the exec tool with a "5-minute timeout" description and modified code.
-
-Both attempts failed. The scan timed out at 60s in every subsequent run. The agent and user concluded "the platform enforces a 60-second cap" — true, but neither understood why the agent's changes had no effect.
-
----
-
-## Root Cause
-
-### The Two-Level Timeout Architecture
-
-Every tool execution is governed by two independent timeouts:
-
-**Layer 1 — Outer wrapper** (`executeTool` in `src/server/tools.js`):
-
-```js
-const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;  // TOOL_TIMEOUT_MS = 60_000
-const timeout = new Promise((_, reject) =>
-  setTimeout(() => reject(new Error(`Tool '${name}' timed out after ${timeoutMs / 1000}s`)), timeoutMs)
-);
-return await Promise.race([fn(toolArgs, ...), timeout]);
-```
-
-`tool.timeout` is a **top-level property on the tool registry entry** — not inside `definition` or `code`. Only `system_install` had this property set (to 300,000ms). The exec tool had no top-level `timeout`, so it always used the 60s default.
-
-**Layer 2 — Inner timeout** (inside the tool's `code`):
-
-The exec seed tool's code contains `execAsync(args.cmd, { timeout: 60000 })`. This is just a string stored in tools.json. Changing this number (via sed or save_tool) only affects the inner `execAsync` behavior — the outer Promise.race at 60s fires first anyway.
-
-### Why the Agent's Fixes Had No Effect
-
-1. **sed on the code string**: Changed the inner `execAsync` timeout from 60s to 300s. But the outer wrapper uses `tool.timeout || 60_000`, and `exec` has no `tool.timeout` property. The outer race still fires at 60s and wins.
-
-2. **`save_tool` recreation**: `save_tool` writes `{ definition, code }` to tools.json — it had no `timeout` parameter. The exec entry still had no top-level `timeout` after `save_tool`. Same result.
-
-### Why seedTools() Makes This Permanent
-
-Even if a manual edit to tools.json successfully added `exec.timeout = 300000`, the next server restart would run `seedTools()`, compare against `SEED_TOOLS.exec` (which has no timeout), and restore it — losing the change.
-
----
-
-## What Changed
-
-### 1. `exec` seed tool now has a 5-minute timeout (`src/server/tools.js`)
-
-Added `timeout: 300_000` as a top-level property on the exec seed tool — the simplest fix:
-
-```js
-exec: {
-  timeout: 300_000, // 5 minutes — Layer 1 outer wrapper reads this
-  definition: { ... },
-  code: `... execAsync(args.cmd, { timeout: 270000 }) ...` // 4.5 min inner, leaves headroom
-}
-```
-
-The inner `execAsync` timeout was also updated from 60s to 270s (4.5 min) so it fires cleanly before the outer wrapper, giving a proper error message rather than a hard kill.
-
-### 2. `save_tool` now accepts a `timeout` parameter (`src/server/tools.js`)
-
-The `save_tool` tool now accepts an optional `timeout` field (in milliseconds, max 600,000 = 10 minutes). When provided, it is written as a top-level property on the tool entry:
-
-```js
-const entry = { definition: { ... }, code: args.code };
-if (args.timeout !== undefined) {
-  const t = Number(args.timeout);
-  entry.timeout = Math.min(t, 600_000);
-}
-tools[args.name] = entry;
-```
-
-This allows the agent to create custom tools with explicit timeout declarations when wrapping slow operations.
-
-### 3. System prompt updated (`docs/system-prompt.md`)
-
-Added a `## Execution Timeouts` section documenting:
-- `exec` = 5-minute cap (covers scans, builds, and most long-running commands)
-- `system_install` = 5-minute cap, use for package installation
-- Custom tools via `save_tool` = 60s default, pass `timeout` param to extend
-- Background execution pattern for processes > 5 minutes
-
-### 4. `agent.md` updated (`docs/agent.md`)
-
-Added a `### Two-Level Tool Timeout Architecture` subsection under `## Limits and Timeouts` explaining:
-- The outer wrapper and how `tool.timeout` is read
-- The inner timeout in tool code and its relationship to the outer
-- How to declare a custom timeout via `save_tool`
-- Why seed tool modifications via `save_tool` don't change the outer timeout (seedTools() restores on restart)
-
----
-
-## What Was Not Changed
-
-- `TOOL_TIMEOUT_MS` constant — remains at 60,000ms (the default for tools without an explicit timeout)
-- `system_install` — unchanged
-- The handoff system, checkpoint memory, loop detection — all unchanged
-- `seedTools()` update detection logic — unchanged
-
----
-
-## Outcome
-
-- `exec` now has a 5-minute timeout — long-running scans, builds, and downloads work without any workaround
-- The agent can set custom timeouts on tools it creates via `save_tool`
-- The system prompt and docs explain the architecture so the agent doesn't waste iterations on an unsolvable problem

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

@@ -1,153 +0,0 @@
-# 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.