@ducci/jarvis 1.0.38 → 1.0.40

package/src/server/tools.js

@@ -120,77 +120,6 @@ const SEED_TOOLS = {
     },
     code: `const filePath = path.join(process.env.HOME, '.jarvis/data/user-info.json'); const raw = await fs.promises.readFile(filePath, 'utf8').catch(() => '{"items":[]}'); const { items } = JSON.parse(raw); return { status: 'ok', items };`,
   },
-  save_tool: {
-    definition: {
-      type: 'function',
-      function: {
-        name: 'save_tool',
-        description: 'Create or update a custom tool and make it available immediately in this session. Use this to build reusable JS tools for tasks you repeat. The tool code runs in Node.js and has access to: args, fs, path, process, require, __jarvisDir. To update an existing tool, first call get_tool to read its current code and parameters, then call save_tool with your modifications.',
-        parameters: {
-          type: 'object',
-          properties: {
-            name: {
-              type: 'string',
-              description: 'Tool name in snake_case (e.g. "parse_json_file"). Must be unique.',
-            },
-            description: {
-              type: 'string',
-              description: 'What the tool does. Be specific — the LLM uses this to decide when to call it.',
-            },
-            parameters: {
-              type: 'object',
-              description: 'JSON Schema object for the tool parameters (with type, properties, required fields).',
-            },
-            code: {
-              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: {...} }).' }; } 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: {
-      type: 'function',
-      function: {
-        name: 'get_tool',
-        description: 'Read the full definition and code of a single tool by name. Use this before updating an existing tool so you understand its current implementation.',
-        parameters: {
-          type: 'object',
-          properties: {
-            name: {
-              type: 'string',
-              description: 'The tool name to retrieve.',
-            },
-          },
-          required: ['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); const tool = tools[args.name]; if (!tool) return { status: 'not_found', name: args.name }; return { status: 'ok', name: args.name, definition: tool.definition, code: tool.code };`,
-  },
-  list_tools: {
-    definition: {
-      type: 'function',
-      function: {
-        name: 'list_tools',
-        description: 'List all available tools with their names and descriptions. Use this to see what tools exist before creating a new one.',
-        parameters: {
-          type: 'object',
-          properties: {},
-          required: [],
-        },
-      },
-    },
-    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); const list = Object.entries(tools).map(([name, t]) => ({ name, description: t.definition.function.description })); return { status: 'ok', tools: list };`,
-  },
   npm_install: {
     definition: {
       type: 'function',
@@ -352,7 +281,7 @@ const SEED_TOOLS = {
       type: 'function',
       function: {
         name: 'write_file',
-        description: 'Write content directly to a file on the filesystem, bypassing all shell escaping. Use this to create or overwrite any file — shell scripts, config files, code, etc. Content is written exactly as provided: dollar signs, backslashes, and special characters are preserved without modification. Always prefer this over exec+echo, exec+printf, or exec+heredoc for writing files. For shell scripts, pass mode: "755" to make the file executable. Example: write_file({ path: "/path/to/scan.sh", content: "#!/bin/bash\\nDOMAIN=$1\\n...", mode: "755" })',
+        description: 'Create a new file or completely overwrite an existing file. Content is written exactly as provided — dollar signs, backslashes, and special characters are preserved without modification. Always prefer this over exec+echo, exec+printf, or exec+heredoc. For shell scripts, pass mode: "755". For targeted edits to an existing file (changing a specific line or section), use edit_file instead.',
         parameters: {
           type: 'object',
           properties: {
@@ -384,6 +313,239 @@ const SEED_TOOLS = {
       return { status: 'ok', path: targetPath, bytes, mode: args.mode || '644' };
     `,
   },
+  edit_file: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'edit_file',
+        description: 'Replace an exact string in a file with a new string. Use this for targeted edits — you only need to provide the specific section to change, not the whole file. old_string must match exactly (including whitespace and indentation) and must appear exactly once in the file. If it appears more than once, add more surrounding context to make it unique. For creating new files or rewriting entire files, use write_file instead.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'Absolute or relative path to the file to edit.',
+            },
+            old_string: {
+              type: 'string',
+              description: 'The exact string to find and replace. Must match character-for-character including whitespace and indentation.',
+            },
+            new_string: {
+              type: 'string',
+              description: 'The string to replace old_string with.',
+            },
+          },
+          required: ['path', 'old_string', 'new_string'],
+        },
+      },
+    },
+    code: `
+      const targetPath = path.resolve(args.path);
+      const content = await fs.promises.readFile(targetPath, 'utf8');
+      const count = content.split(args.old_string).length - 1;
+      if (count === 0) {
+        return { status: 'error', error: 'old_string not found in file. Check for exact whitespace and indentation match.' };
+      }
+      if (count > 1) {
+        return { status: 'error', error: \`old_string found \${count} times. Add more surrounding context to make it unique.\` };
+      }
+      const updated = content.replace(args.old_string, args.new_string);
+      await fs.promises.writeFile(targetPath, updated, 'utf8');
+      return { status: 'ok', path: targetPath };
+    `,
+  },
+  get_current_time: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'get_current_time',
+        description: 'Returns the current server time. Call this before scheduling a cron job when the user specifies a relative time (e.g. "in 2 hours", "at 3pm today") so you can calculate the correct schedule.',
+        parameters: { type: 'object', properties: {}, required: [] },
+      },
+    },
+    code: `
+      const now = new Date();
+      return {
+        status: 'ok',
+        iso: now.toISOString(),
+        local: now.toLocaleString(),
+        utcOffset: -now.getTimezoneOffset() / 60,
+      };
+    `,
+  },
+  create_cron: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'create_cron',
+        description: 'Schedule a recurring or one-time task. The prompt is executed by a fresh agent with no prior context — write it as a self-contained task. For one-time tasks (e.g. "remind me in 2 hours"), set once: true. Call get_current_time first when calculating a relative schedule.',
+        parameters: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Short identifier for this cron, e.g. "backup-nightly".' },
+            schedule: { type: 'string', description: 'Cron expression, e.g. "0 3 * * *" for 3am daily. For a one-time task, compute the exact time from get_current_time and express it as a cron expression.' },
+            prompt: { type: 'string', description: 'The task prompt the agent will receive when this cron fires. Must be self-contained. Include "use send_telegram_message to notify the user with the result" if notification is desired.' },
+            once: { type: 'boolean', description: 'If true, the cron deletes itself after firing once. Use for one-time reminders or tasks.' },
+          },
+          required: ['name', 'schedule', 'prompt'],
+        },
+      },
+    },
+    code: `
+      const { randomUUID } = require('crypto');
+      const cronsFile = path.join(process.env.HOME, '.jarvis/data/crons.json');
+      const crons = JSON.parse(await fs.promises.readFile(cronsFile, 'utf8').catch(() => '[]'));
+      const entry = {
+        id: randomUUID(),
+        name: args.name,
+        schedule: args.schedule,
+        prompt: args.prompt,
+        once: args.once || false,
+        createdAt: new Date().toISOString(),
+      };
+      crons.push(entry);
+      await fs.promises.mkdir(path.dirname(cronsFile), { recursive: true });
+      await fs.promises.writeFile(cronsFile, JSON.stringify(crons, null, 2), 'utf8');
+      return { status: 'ok', cron: entry };
+    `,
+  },
+  list_crons: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'list_crons',
+        description: 'List all scheduled cron jobs.',
+        parameters: { type: 'object', properties: {}, required: [] },
+      },
+    },
+    code: `
+      const cronsFile = path.join(process.env.HOME, '.jarvis/data/crons.json');
+      const crons = JSON.parse(await fs.promises.readFile(cronsFile, 'utf8').catch(() => '[]'));
+      return { status: 'ok', crons };
+    `,
+  },
+  delete_cron: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'delete_cron',
+        description: 'Delete a scheduled cron job by name or id.',
+        parameters: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'The cron name to delete.' },
+            id: { type: 'string', description: 'The cron id to delete.' },
+          },
+        },
+      },
+    },
+    code: `
+      const cronsFile = path.join(process.env.HOME, '.jarvis/data/crons.json');
+      const crons = JSON.parse(await fs.promises.readFile(cronsFile, 'utf8').catch(() => '[]'));
+      const idx = crons.findIndex(c => c.id === args.id || c.name === args.name);
+      if (idx === -1) return { status: 'not_found' };
+      const [removed] = crons.splice(idx, 1);
+      await fs.promises.writeFile(cronsFile, JSON.stringify(crons, null, 2), 'utf8');
+      return { status: 'ok', id: removed.id, name: removed.name };
+    `,
+  },
+  send_telegram_message: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'send_telegram_message',
+        description: 'Send a message to the Telegram user. Use this inside cron prompts to notify the user with the result of a task.',
+        parameters: {
+          type: 'object',
+          properties: {
+            message: { type: 'string', description: 'The message text to send.' },
+          },
+          required: ['message'],
+        },
+      },
+    },
+    code: `
+      const https = require('https');
+      const token = process.env.TELEGRAM_BOT_TOKEN;
+      const settingsFile = path.join(process.env.HOME, '.jarvis/data/config/settings.json');
+      const settings = JSON.parse(await fs.promises.readFile(settingsFile, 'utf8'));
+      const chatId = settings.channels?.telegram?.allowedUserIds?.[0];
+      if (!chatId) return { status: 'error', error: 'No Telegram chat_id configured.' };
+      if (!token) return { status: 'error', error: 'No TELEGRAM_BOT_TOKEN configured.' };
+      const body = JSON.stringify({ chat_id: chatId, text: args.message });
+      await new Promise((resolve, reject) => {
+        const req = https.request({
+          hostname: 'api.telegram.org',
+          path: '/bot' + token + '/sendMessage',
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+        }, res => {
+          let data = '';
+          res.on('data', chunk => data += chunk);
+          res.on('end', () => {
+            const parsed = JSON.parse(data);
+            if (!parsed.ok) reject(new Error(parsed.description));
+            else resolve(parsed);
+          });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+      });
+      return { status: 'ok', chatId };
+    `,
+  },
+  read_cron_log: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'read_cron_log',
+        description: 'Read the execution log for a cron job. Returns the most recent runs with status, response, and logSummary.',
+        parameters: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'The cron id.' },
+            limit: { type: 'number', description: 'Max entries to return. Defaults to 20.' },
+          },
+          required: ['id'],
+        },
+      },
+    },
+    code: `
+      const logsDir = path.join(process.env.HOME, '.jarvis/logs');
+      const logFile = path.join(logsDir, 'cron-' + args.id + '.jsonl');
+      const content = await fs.promises.readFile(logFile, 'utf8').catch(() => '');
+      const lines = content.trim().split('\\n').filter(Boolean);
+      const limit = args.limit || 20;
+      const entries = lines.slice(-limit).map(line => JSON.parse(line));
+      return { status: 'ok', entries };
+    `,
+  },
+  read_skill: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'read_skill',
+        description: 'Read the full instructions of a skill by name. Call this before executing a skill so you have the complete workflow. The skill name must match one of the available skills listed in your system prompt.',
+        parameters: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'The skill name, e.g. "add-two-integers".',
+            },
+          },
+          required: ['name'],
+        },
+      },
+    },
+    code: `
+      const skillFile = path.join(process.env.HOME, '.jarvis/data/skills', args.name, 'skill.md');
+      const content = await fs.promises.readFile(skillFile, 'utf8').catch(() => null);
+      if (!content) return { status: 'not_found', name: args.name };
+      return { status: 'ok', name: args.name, content };
+    `,
+  },
   get_recent_sessions: {
     definition: {
       type: 'function',

package/docs/findings/001-context-explosion.md

@@ -1,116 +0,0 @@
-# Finding 001: Context Window Explosion via Tool Output Accumulation
-
-**Date:** 2026-02-26
-**Severity:** High — renders session completely unusable after enough handoffs
-**Status:** Fixed
-
----
-
-## What Happened
-
-A session was started with the question *"Hast du Zugriff auf deinen source code? Wo liegt er?"* (Does Jarvis have access to its own source code?). The agent began exploring the filesystem using `exec` and `list_dir`, running commands like `cat agent.js`, `cat tools.js`, `cat app.js`, and various `find` commands.
-
-The task required more than 10 iterations to complete, so the checkpoint/handoff mechanism fired. The agent ran 6 consecutive handoff runs before hitting `maxHandoffs` and stopping with `intervention_required`.
-
-By that point the session `conversation.json` had grown to **687KB**. On the very next user message (*"Why?"*), both the primary and fallback models returned a `400 Provider returned error`. The session was permanently broken — no further messages could be processed.
-
----
-
-## Root Cause
-
-Two compounding problems:
-
-### 1. Tool output stored verbatim, without size limit
-
-`exec` returns raw `stdout` from shell commands. When the model runs `cat agent.js` (440 lines, ~22 000 chars), that entire output gets stored in `session.messages` as a `role: "tool"` message. Every subsequent model request in that run — and in all future runs — sends this content in full.
-
-There was no cap anywhere on tool result content. A single run of 10 iterations with a few `cat` calls could easily produce 100–200 KB of tool messages.
-
-### 2. Handoff runs accumulated on top of each other
-
-When the iteration limit is hit, the checkpoint/handoff mechanism pushes `checkpoint.remaining` as a new user message and starts a fresh agent run — but on top of the **same, growing** `session.messages` array. Each of the 6 handoff runs added another 10 iterations of tool call messages to the history. Nothing was ever removed.
-
-After 6 runs × ~10 iterations × multiple `cat` commands each, the context reached approximately 170 000 tokens — exceeding the free model's 128 000 token limit. The `400` was the provider rejecting the oversized request.
-
-### Why the `400` appeared on the *next* user message, not during the run
-
-The session's final run hit `maxHandoffs` and stopped. At that point the context was already at or near the limit. When the user sent a new message, the full bloated history was loaded and sent again — this time slightly over the limit — causing the rejection.
-
----
-
-## Model Context Windows (for reference)
-
-| Model | Context Window |
-|---|---|
-| arcee-ai/trinity-large-preview:free | ~128 000 tokens |
-| Claude Sonnet 4.6 | 200 000 tokens |
-| Gemini 2.5 Pro / 2.0 Flash | 1 000 000 tokens |
-
-A larger model would have delayed the failure, but not prevented it. The conversation would still grow unboundedly.
-
----
-
-## What We Considered
-
-**Truncate tool results in `prepareMessages`** — works, but runs on every loop iteration and is the wrong place conceptually. The content is already stored in full in the session before `prepareMessages` is ever called.
-
-**Naive sliding window (drop oldest N messages)** — breaks the OpenRouter/OpenAI API contract. Every `role: "tool"` message must be paired with the assistant message containing the matching `tool_call_id`. Slicing arbitrarily through the message array orphans tool results and causes a `400` — the exact error we're trying to fix.
-
-**Token budget / summarisation** — more adaptive but significantly more complex. Requires either token counting per model or an extra LLM call. Overkill for v1.
-
----
-
-## Fix
-
-Two targeted changes to `src/server/agent.js`.
-
-### 1. Cap tool result content at write time (`MAX_TOOL_RESULT = 4000`)
-
-Right where a tool result is pushed to `session.messages`, cap the content to 4 000 characters. The full result is still passed to `runToolCalls` and therefore written to the JSONL session log — no information is lost for debugging. Only what the model sees is limited.
-
-```js
-const sessionContent = resultStr.length > MAX_TOOL_RESULT
-  ? resultStr.slice(0, MAX_TOOL_RESULT) + '\n[...truncated]'
-  : resultStr;
-session.messages.push({ role: 'tool', tool_call_id: toolCall.id, content: sessionContent });
-```
-
-4 000 chars is ~80 lines of code or a full `ls -la` listing — enough for the model to reason about any output. If more detail is needed, the model should use targeted commands (`grep`, `head`, `tail`) rather than `cat`-ing entire files.
-
-### 2. Strip intermediate tool messages before each handoff
-
-Before calling `runAgentLoop`, snapshot `session.messages.length` as `runStartIndex`. If the run ends with `checkpoint_reached`, splice out all messages added during that run *except the final wrap-up assistant response*, then push `checkpoint.remaining` as the new user message.
-
-```js
-const runStartIndex = session.messages.length;
-const run = await runAgentLoop(...);
-
-// on checkpoint_reached, before resuming:
-session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
-session.messages.push({ role: 'user', content: run.checkpoint.remaining });
-```
-
-**Before** (after 6 handoffs):
-```
-[system] [user: question] [assistant/tool ×10] [wrap-up] [user: checkpoint1]
-         [assistant/tool ×10] [wrap-up] [user: checkpoint2]
-         [assistant/tool ×10] [wrap-up] ...  →  687 KB
-```
-
-**After** (after 6 handoffs):
-```
-[system] [user: question] [wrap-up] [user: checkpoint1]
-         [wrap-up] [user: checkpoint2]
-         [wrap-up] ...  →  ~5 KB
-```
-
-Each handoff now adds 2 messages instead of 20+. The wrap-up message carries the relevant state (what was done, what remains) so the model is not flying blind — it just doesn't have the raw tool noise from previous runs.
-
----
-
-## Outcome
-
-- Sessions with long-running tasks no longer grow the context unboundedly.
-- The JSONL session log is unaffected — full tool outputs are always written there.
-- The model can still access previous run output via `read_session_log` if needed.
-- A follow-up message after a completed multi-handoff task will no longer receive a `400`.

package/docs/findings/002-handoff-edge-cases.md

@@ -1,84 +0,0 @@
-# Finding 002: Handoff Edge Cases Found During Review of Finding 001
-
-**Date:** 2026-02-26
-**Severity:** Medium
-**Status:** Fixed
-
----
-
-## Context
-
-While reviewing the fix for [Finding 001](./001-context-explosion.md), two edge cases in the handoff system were found. Neither caused problems in the observed debugging session, but both could cause failures under specific conditions.
-
----
-
-## Issue A: `checkpoint.remaining` could be `null`, causing a 400 on the next iteration
-
-### What could happen
-
-When the iteration limit is hit, the agent asks the model for a wrap-up response that includes a `checkpoint` field:
-
-```json
-{
-  "response": "...",
-  "logSummary": "...",
-  "checkpoint": {
-    "progress": "...",
-    "remaining": "..."
-  }
-}
-```
-
-The server then pushes `checkpoint.remaining` as a user message to start the next run:
-
-```js
-session.messages.push({ role: 'user', content: run.checkpoint.remaining });
-```
-
-Weaker or free models occasionally omit required fields or set them to `null`. If `remaining` is `null`, the session gets a `{ role: 'user', content: null }` message. Most providers reject a null content field with a `400 Bad Request` on the next model call — the same error that surfaced in Finding 001, but from a different cause.
-
-### Fix
-
-```js
-session.messages.push({ role: 'user', content: run.checkpoint.remaining || 'Continue with the task.' });
-```
-
----
-
-## Issue B: `intervention_required` did not strip tool history before saving
-
-### What could happen
-
-The tool history strip introduced in Finding 001 runs right before pushing `checkpoint.remaining` for the next run. But the `intervention_required` path (max handoffs exceeded) breaks out of the loop *before* reaching the strip:
-
-```js
-if (session.metadata.handoffCount > config.maxHandoffs) {
-  // ... log and set status ...
-  break;  // ← strip never ran
-}
-
-// strip only reached here, after the if-block
-session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
-```
-
-This meant a session that hit the handoff limit was saved with the full tool history of the last run still in it. When the user sends a new message after `intervention_required`, the model receives all of that accumulated tool history — the same context bloat risk as before the fix in Finding 001.
-
-### Fix
-
-Strip the tool history inside the `intervention_required` branch, before breaking:
-
-```js
-if (session.metadata.handoffCount > config.maxHandoffs) {
-  // ... log and set status ...
-  session.messages.splice(runStartIndex, session.messages.length - runStartIndex - 1);
-  break;
-}
-```
-
-The wrap-up assistant message (last in the array) is preserved — it gives the model context about what was attempted when the user resumes.
-
----
-
-## Why these weren't caught earlier
-
-Both issues only manifest under specific conditions (model omitting a field; hitting maxHandoffs exactly). The debugging session in Finding 001 stopped at `intervention_required` after 6 handoffs, but the 400 error on the next message was attributed to the overall context size, masking the fact that the strip hadn't run for that final run.

package/docs/findings/003-event-loop-blocking-and-reliability.md

@@ -1,120 +0,0 @@
-# Finding 003: Event Loop Blocking, Async File I/O, and Session Reliability
-
-**Date:** 2026-02-27
-**Severity:** High — caused observed 100% CPU and server unresponsiveness in production
-**Status:** Fixed
-
----
-
-## What Happened
-
-A session was started with the question *"Kannst du deinen source code finden und anschauen mittels Tools?"*. The agent used the `exec` tool to run two full-filesystem scans:
-
-```
-find / -type f \( -iname "*.js" -o -iname "*.ts" -o -iname "*.py" \) 2>/dev/null | head -20
-find / -type d -name "jarvis" 2>/dev/null
-```
-
-Both commands start from filesystem root `/`. The second has no output limit and scans everything: real disk filesystems, `/proc`, `/sys`, `/dev`, and any network mounts. On the affected Linux server this caused the CPU to reach 100% and the server became unresponsive. The server had to be shut down manually.
-
----
-
-## Root Cause
-
-### 1. `execSync` blocks the entire Node.js event loop
-
-Both `exec` and `list_dir` used `execSync` from `child_process`. `execSync` is a synchronous call that blocks the event loop for its entire duration. While any shell command runs:
-
-- Express cannot process incoming HTTP requests
-- The Telegram bot cannot receive or process new messages
-- All timers and async callbacks are frozen (including the Telegram `typingInterval`, so the user sees no activity indicator)
-
-The OS sees a CPU-hungry `find` child process running at full speed while Node.js sits blocked waiting for it. Combined, this presents as ~100% CPU with a completely unresponsive server.
-
-Additionally, `list_dir` used `execSync` with **no timeout at all**. A hanging command (e.g. `ls` on an NFS mount or a blocked `/proc` entry) would freeze the server permanently.
-
-### 2. All file I/O was synchronous
-
-`loadSession`, `saveSession`, `appendLog`, and `loadTools` all used `fs.*Sync` variants. In an async Node.js server these block the event loop on every request. For small files the impact is measured in microseconds, but the pattern is architecturally incorrect and accumulates under load.
-
-### 3. Session not saved on unexpected error
-
-In `handleChat`, `saveSession` was called unconditionally after the `try/catch` block. If the catch re-threw an unexpected error, `saveSession` was never reached. The user message had already been appended to the in-memory session but the on-disk version did not reflect it — leaving the session in an inconsistent state for the next request.
-
-### 4. No concurrency protection per session
-
-The Telegram channel uses `@grammyjs/runner`, which processes updates concurrently. If a user sent two messages in quick succession, both `handleChat` calls could load the same session simultaneously, run independent agent loops, and then overwrite each other's `saveSession` call. The second write would silently discard the first response.
-
-### 5. Seed tools never updated after initial creation
-
-`seedTools()` used `if (!existing[name])` — it only wrote a seed tool on first run. Any update to `exec` or `list_dir` in the source code would never propagate to an existing installation. This blocked the async fix for `exec` and `list_dir` from taking effect.
-
----
-
-## Fixes
-
-### 1. `exec` and `list_dir` → async (`src/server/tools.js`)
-
-**`exec`**: replaced `execSync` with `promisify(exec)`. The event loop is now free during shell command execution. Timeout (60s) and maxBuffer (2MB) are preserved.
-
-**`list_dir`**: replaced `execSync` with `promisify(execFile)`. `execFile` does not use a shell interpreter, which is safer against special characters in paths. Added a 10-second timeout (previously none).
-
-### 2. `executeTool` global timeout (`src/server/tools.js`)
-
-All tool executions — both built-in and AI-created — are now wrapped in `Promise.race` against a 60-second timeout. This protects against AI-created tools that hang on async operations (network requests, file I/O). The timeout matches the `exec` tool's own limit for consistency.
-
-```js
-const timeout = new Promise((_, reject) =>
-  setTimeout(() => reject(new Error(`Tool '${name}' timed out after 60s`)), 60_000)
-);
-return await Promise.race([fn(toolArgs, fs, path, process, _require), timeout]);
-```
-
-Note: this does not protect against synchronous CPU loops without `await` points — that would require Worker Threads. Such code is unlikely to be generated accidentally.
-
-### 3. Seed tools always updated (`src/server/tools.js`)
-
-`seedTools()` now compares the serialized content of each seed tool against the stored version and overwrites only when there is a difference. Updates to built-in tools propagate on the next server start without touching user-created tools.
-
-### 4. All file I/O → async (`src/server/sessions.js`, `src/server/logging.js`, `src/server/tools.js`)
-
-`loadSession`, `saveSession`, `appendLog`, and `loadTools` now use `fs.promises.*`. All callers in `agent.js` are updated to `await` these calls.
-
-### 5. `saveSession` moved to `finally` block (`src/server/agent.js`)
-
-The session is now always persisted — on success, on model error, and on unexpected errors. A failed save is caught and logged without masking the original error.
-
-```js
-} finally {
-  try {
-    await saveSession(sessionId, session);
-  } catch (saveErr) {
-    console.error(`Failed to save session ${sessionId}:`, saveErr);
-  }
-}
-```
-
-### 6. Session queue for concurrency control (`src/server/agent.js`)
-
-A module-level `Map<sessionId, Promise>` serializes concurrent requests for the same session. Each new request registers itself as the tail of the queue and waits for the previous request to resolve before starting. The map entry is cleaned up by whichever request is last in the chain.
-
-```js
-const previous = sessionQueues.get(sessionId) ?? Promise.resolve();
-let releaseLock;
-const current = new Promise(resolve => { releaseLock = resolve; });
-sessionQueues.set(sessionId, current);
-await previous;
-// ... process request ...
-// finally: releaseLock()
-```
-
-This is safe in Node.js because the event loop is single-threaded: `get`, `new Promise`, and `set` all execute synchronously before the first `await`, so there is no race between two requests reading the same `undefined` entry.
-
----
-
-## What Was Not Changed
-
-- The agent loop logic, checkpoint/handoff system, loop detection, and format recovery — all unchanged.
-- `seedTools()` remains synchronous (called once at startup, before the server accepts requests).
-- `createSession()` and `getToolDefinitions()` remain synchronous (pure functions, no I/O).
-- No rate limiting or HTTP authentication added — the server is intended for local/personal use only.