@ducci/jarvis 1.0.24 → 1.0.26

package/docs/agent.md

@@ -503,6 +503,23 @@ Schema:
 - No additional per-run tool-call cap beyond iterations.
 - No token limit enforcement in v1.
 
+### Two-Level Tool Timeout Architecture
+
+Every tool execution is governed by two independent timeout layers:
+
+**Layer 1 — Outer wrapper** (`executeTool` in `src/server/tools.js`):
+```js
+const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;  // TOOL_TIMEOUT_MS = 60_000
+return await Promise.race([fn(toolArgs, ...), timeout]);
+```
+This is the hard cap. `tool.timeout` is a top-level property on the tool registry entry (not inside `definition` or `code`). `exec` has `timeout: 300_000` (5 minutes); `system_install` also has 5 minutes; all other tools default to 60s.
+
+**Layer 2 — Inner timeout** (inside the tool's `code`): e.g. `execAsync(cmd, { timeout: 270000 })`. Should be slightly shorter than Layer 1 to ensure a clean error from the inner call rather than a hard kill from the outer wrapper.
+
+**Declaring a custom timeout on a tool** (via `save_tool`): pass the optional `timeout` parameter (in ms, capped at 600,000). This writes the top-level `timeout` property to the tool entry in `tools.json`.
+
+**Important**: Modifying a seed tool's code via `save_tool` does NOT change its outer timeout — seed tools are restored to their original definition on server restart via `seedTools()`.
+
 ## User Info
 
 User info is stored as a small JSON file in the Jarvis data directory: `~/.jarvis/data/user-info.json`. `save_user_info` appends to the collection, and `read_user_info` returns the full set.

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

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

@@ -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
@@ -54,6 +56,21 @@ The `exec` tool runs real shell commands on the server. Use it responsibly:
 - **Avoid commands with unbounded runtime.** If a command could run indefinitely or scan an unknown-size tree, scope it first.
 - **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.
 
+## Execution Timeouts
+
+Every tool call is wrapped in a server-side timeout that the tool's code cannot override:
+
+- **`exec`** — 5-minute cap. Sufficient for scans, builds, and most long-running commands.
+- **`system_install`** — 5-minute cap. Use for installing system binaries via a package manager.
+- **Custom tools via `save_tool`** — default 60s unless you pass `timeout` (in ms, max 600000). If a custom tool wraps a slow operation, set `timeout` explicitly.
+
+**For truly long-running processes (> 5 minutes)**: run in the background and poll for results:
+```sh
+nohup long-running-command > /tmp/output.log 2>&1 & echo $!
+# Check progress later
+cat /tmp/output.log
+```
+
 ## Failure Recovery
 
 When a tool or command fails:
@@ -71,6 +88,7 @@ When building a custom tool with `save_tool`:
 - **Installing an npm package**: use the `npm_install` tool — it handles the correct install directory automatically. Then create the tool with `save_tool`. The tool code can `require('<package-name>')` directly.
 - **Installing a system binary** (e.g. nuclei, jq, ffmpeg, git): use the `system_install` tool — never use exec for this. It auto-detects the available package manager (brew/apt-get/snap) and has a 5-minute timeout sized for real downloads.
 - **Available bindings in tool code**: `args`, `fs`, `path`, `process`, `require`, `__jarvisDir` (absolute path to the jarvis server directory).
+- **Long-running custom tools**: if your tool wraps an operation that takes more than 60 seconds (e.g. a network call, a slow computation), pass `timeout` in milliseconds to `save_tool` (max 600000 = 10 minutes). Example: `save_tool({ name: "run_scan", timeout: 300000, ... })`.
 
 ## logSummary Guidelines
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.24",
+  "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 {

package/src/server/tools.js

@@ -43,6 +43,7 @@ const SEED_TOOLS = {
     `,
   },
   exec: {
+    timeout: 300_000, // 5 minutes — scans, builds, and long commands need more than 60s
     definition: {
       type: 'function',
       function: {
@@ -67,7 +68,7 @@ const SEED_TOOLS = {
       try {
         const { stdout, stderr } = await execAsync(args.cmd, {
           encoding: "utf8",
-          timeout: 60000,
+          timeout: 270000, // 4.5 min — leaves headroom before the outer 5-min tool timeout
           maxBuffer: 2 * 1024 * 1024,
         });
         return { status: "ok", exitCode: 0, stdout, stderr };
@@ -144,12 +145,16 @@ const SEED_TOOLS = {
               type: 'string',
               description: 'The body of an async function. Must end with a return statement — the returned value becomes the tool result. Available bindings: args (your tool parameters), fs (node:fs), path (node:path), process, require, __jarvisDir (absolute path to the jarvis server directory — use path.resolve(__jarvisDir, "../..") to get the project root for npm installs). Do NOT wrap in a function declaration. Example: const raw = await fs.promises.readFile(args.filePath, "utf8"); const data = JSON.parse(raw); return { count: data.length, first: data[0] };',
             },
+            timeout: {
+              type: 'number',
+              description: 'Optional execution timeout in milliseconds for this tool (max 600000 = 10 minutes). Use this when the tool wraps a slow operation (e.g. a network request or long computation) that exceeds the default 60-second limit. If omitted, the default 60-second timeout applies.',
+            },
           },
           required: ['name', 'description', 'parameters', 'code'],
         },
       },
     },
-    code: `const toolsFile = path.join(process.env.HOME, '.jarvis/data/tools/tools.json'); const raw = await fs.promises.readFile(toolsFile, 'utf8').catch(() => '{}'); const tools = JSON.parse(raw); 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: {...} }).' }; } tools[args.name] = { definition: { type: 'function', function: { name: args.name, description: args.description, parameters } }, code: args.code }; await fs.promises.writeFile(toolsFile, JSON.stringify(tools, null, 2), 'utf8'); return { status: 'ok', saved: args.name };`,
+    code: `const toolsFile = path.join(process.env.HOME, '.jarvis/data/tools/tools.json'); const raw = await fs.promises.readFile(toolsFile, 'utf8').catch(() => '{}'); const tools = JSON.parse(raw); 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: {...} }).' }; } const entry = { definition: { type: 'function', function: { name: args.name, description: args.description, parameters } }, code: args.code }; if (args.timeout !== undefined) { const t = Number(args.timeout); if (!Number.isFinite(t) || t <= 0) return { status: 'error', error: 'timeout must be a positive number in milliseconds.' }; entry.timeout = Math.min(t, 600_000); } tools[args.name] = entry; await fs.promises.writeFile(toolsFile, JSON.stringify(tools, null, 2), 'utf8'); return { status: 'ok', saved: args.name, timeout: entry.timeout || 60000 };`,
   },
   get_tool: {
     definition: {