@ducci/jarvis 1.0.20 → 1.0.22

package/docs/findings/004-agent-reliability-improvements.md

@@ -0,0 +1,162 @@
+# Finding 004: Agent Reliability — Failure Loops, Checkpoint Memory, and Iteration Awareness
+
+**Date:** 2026-02-27
+**Severity:** High — caused observed session failure with 54 tool calls, `format_error` crash, and no useful output after 42 minutes
+**Status:** Fixed
+
+---
+
+## What Happened
+
+A session was started to build a cybersecurity project installing three tools: Nuclei, Subfinder, and Naabu. The agent went through 5 handoffs (hitting `maxHandoffs`) and crashed with a `format_error` in the final iteration. Observations:
+
+- **181 exec calls** across 19 agent iterations
+- **21 perplexity_search calls**, including 11+ in the final iteration alone
+- The agent oscillated between download strategies (Docker → `go install` → tarball → direct binary) without memory of what had already failed
+- The existing loop detector never fired because each failed command had slightly different arguments (different URLs, different flags), producing different `callKey` values
+- Each handoff resumed with only `checkpoint.remaining` — no record of what approaches had already been exhausted
+- The model degraded and eventually produced a non-JSON response (`format_error`), crashing the session
+
+---
+
+## Root Causes
+
+### 1. Loop detection only caught exact-match repetition
+
+The existing `loopTracker` detects when the _exact same_ tool call (name + args + result) is repeated 3 times. It does not detect _semantic_ failure loops: repeated attempts to do the same thing via slightly different commands. In the session, each download attempt used a different URL or flags, so every `callKey` was unique.
+
+### 2. Checkpoint carried no memory of failed strategies
+
+`WRAP_UP_NOTE` asked the model for `progress` and `remaining`, but not for a record of what _failed_. Each new run after a handoff started with a blank slate — the model had no way to know that curl downloads, `go install`, and tarball extraction had already been tried and failed. It repeated them.
+
+### 3. No iteration budget awareness
+
+The model had no visibility into how many iterations remained in the current run. It kept taking exploratory steps as if budget were unlimited, then was surprised by the wrap-up call. A model that knows it has 2 iterations left will consolidate and report; one that doesn't will keep digging.
+
+### 4. `perplexity_search` used without restraint
+
+The tool description had no guidance on usage limits. The model searched Perplexity 21 times in one session (11 in the final iteration), including redundant queries for the same version information. Each search consumed an iteration and added latency without improving outcomes.
+
+### 5. System prompt had no "give up" rule
+
+The system prompt told the agent to "decide whether to retry with a corrected call or explain the failure to the user" — but gave no threshold for when to stop retrying. In practice, the agent always chose to retry, regardless of how many times the same approach had failed.
+
+---
+
+## Fixes
+
+### 1. Consecutive failure detection (`src/server/agent.js`)
+
+Added a `consecutiveFailures` counter that tracks back-to-back failed tool calls across all iterations within a run. A tool call counts as failed if `executeTool` throws (`toolStatus === 'error'`) _or_ the result object has `status === 'error'` (catching exec failures that are returned, not thrown). A successful call resets the counter to 0.
+
+After each iteration's tool calls, if `consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD` (3), a system break message is injected into the session and the counter resets:
+
+```js
+const resultObj = typeof result === 'object' && result !== null ? result : null;
+const toolFailed = toolStatus === 'error' || (resultObj && resultObj.status === 'error');
+if (toolFailed) {
+  consecutiveFailures++;
+} else {
+  consecutiveFailures = 0;
+}
+```
+
+```js
+if (consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD) {
+  session.messages.push({
+    role: 'user',
+    content: '[System: You have had 3 or more consecutive tool failures. Stop retrying the same approach. Either pivot to a fundamentally different strategy or provide your final response explaining what failed and why.]',
+  });
+  consecutiveFailures = 0;
+}
+```
+
+This complements the existing exact-match loop detector — together they cover both identical repetition and semantic failure loops.
+
+### 2. `failedApproaches` in checkpoint schema (`src/server/agent.js`)
+
+Updated `WRAP_UP_NOTE` to request a `failedApproaches` array alongside `progress` and `remaining`:
+
+```json
+{
+  "checkpoint": {
+    "progress": "...",
+    "remaining": "...",
+    "failedApproaches": ["downloading subfinder via curl from GitHub releases — connection reset", "..."]
+  }
+}
+```
+
+When resuming after a handoff, the agent loop now appends a system note to the resume message listing every failed approach from the previous run:
+
+```js
+let resumeContent = run.checkpoint.remaining || 'Continue with the task.';
+if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
+  resumeContent += `\n\n[System: The following approaches were tried and failed in the previous run — do not repeat them:\n${run.checkpoint.failedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
+}
+```
+
+The next run starts with concrete knowledge of what not to try, rather than repeating the same failed strategies.
+
+### 3. Iteration budget awareness (`src/server/agent.js`)
+
+Each model request now includes the remaining iteration count when 5 or fewer iterations are left in the run. The count is appended to the prepared messages (never stored in `session.messages`):
+
+```js
+const iterationsLeft = config.maxIterations - iteration + 1;
+const preparedMessages = iterationsLeft <= 5
+  ? [...base, { role: 'user', content: `[System: ${iterationsLeft} iteration${iterationsLeft === 1 ? '' : 's'} remaining in this run. Budget your remaining steps accordingly — if you cannot finish in time, consolidate progress and provide a checkpoint.]` }]
+  : base;
+```
+
+This gives the model enough warning to consolidate and produce a clean checkpoint rather than being cut off mid-task.
+
+### 4. `perplexity_search` description updated (`src/server/tools.js`)
+
+Added explicit usage guidance to the tool description:
+
+> Use sparingly — at most 3 searches per topic. Do not repeat the same query with minor variations; if an initial search does not yield what you need, switch to a different approach or verify locally with exec.
+
+### 5. "Failure Recovery" section added to system prompt (`docs/system-prompt.md`)
+
+Added a dedicated `## Failure Recovery` section making the give-up rule explicit:
+
+- Retry at most once with a meaningfully different approach; if it fails again, report to the user
+- Never repeat a failed strategy with minor variations
+- Use `perplexity_search` at most 3 times per topic
+- Escalate cleanly with a useful failure report rather than looping
+
+---
+
+## What Was Not Changed
+
+- The existing exact-match loop detector (`loopTracker`) — it remains and now works alongside the new consecutive failure detector
+- The checkpoint/handoff system, `maxHandoffs` limit, or tool history strip logic — unchanged
+- The `format_error` recovery path (fallback model + nudge retry) — unchanged
+- No per-session Perplexity call counter was added server-side; the guidance is model-facing
+
+---
+
+## Note: Homebrew as an Alternative for Binary Tool Installation
+
+During the session that exposed these issues, the agent struggled to install Nuclei, Subfinder, and Naabu from GitHub releases. All three tools from [ProjectDiscovery](https://projectdiscovery.io/) are available via Homebrew:
+
+```
+brew install nuclei
+brew install subfinder
+brew install naabu
+```
+
+Homebrew handles binary verification, PATH setup, and version management automatically — far more reliably than manual `curl` downloads or `go install`. On macOS (and Linux via Linuxbrew), this is the recommended installation method. The agent could discover this via `perplexity_search` or by checking `brew search projectdiscovery` — but only if it knows to try Homebrew _before_ attempting manual downloads.
+
+This is a guidance gap rather than a code bug: the system prompt doesn't mention package managers as a preferred strategy for binary installation. A future improvement could add: "When installing CLI tools, check for a package manager installation first (`brew install`, `apt install`, `snap install`) before attempting manual downloads."
+
+---
+
+## Outcome
+
+- Failure loops are now intercepted after 3 consecutive failures instead of running to exhaustion
+- Handoff runs start with knowledge of what has already failed, enabling genuine strategy pivots
+- The model receives iteration budget warnings before hitting the wrap-up call
+- Perplexity search overuse is constrained by both tool description and system prompt guidance
+- The system prompt now has an explicit rule for when to stop retrying and report

package/docs/findings/005-installation-timeout.md

@@ -0,0 +1,128 @@
+# Finding 005: 60-Second Exec Timeout Breaks Package Installation
+
+**Date:** 2026-02-27
+**Severity:** High — any package installation via exec will timeout, regardless of which package manager is used
+**Status:** Fixed
+
+---
+
+## What Happened
+
+In the session analysed in Finding 004, the agent attempted to install Nuclei, Subfinder, and Naabu using several strategies — `go install`, direct `curl` downloads, tarball extraction. All either timed out or failed with network errors.
+
+The natural follow-up question was: would switching to a proper package manager (`brew`, `apt-get`) solve the problem? The answer is no — not without fixing the timeout first.
+
+---
+
+## Root Cause
+
+### The `exec` tool has a hard 60-second timeout
+
+```js
+// exec seed tool
+const { stdout, stderr } = await execAsync(args.cmd, {
+  encoding: 'utf8',
+  timeout: 60000,   // ← 60 seconds
+  maxBuffer: 2 * 1024 * 1024,
+});
+```
+
+On top of that, `executeTool` wraps every tool in its own `Promise.race` against `TOOL_TIMEOUT_MS = 60_000`. This means even if a tool's internal `execAsync` had a longer timeout, the outer race would kill it at 60 seconds anyway.
+
+Package installation routinely takes longer than 60 seconds:
+
+| Operation | Typical duration |
+|---|---|
+| `apt-get update` | 15–60s (varies with server speed, mirror load) |
+| `apt-get install nuclei` | 10–60s (binary download + extraction) |
+| `apt-get update && apt-get install nuclei` | 30–120s combined |
+| `brew install nuclei` | 20–90s |
+| `go install github.com/...` | 60–180s (compilation) |
+
+So `go install` was almost guaranteed to timeout. `apt-get` with an update step would regularly exceed 60s too. Swapping the install method without fixing the timeout would not have solved the problem.
+
+### The `npm_install` tool has the same problem
+
+`npm_install` also uses a 60-second timeout — it would fail for large packages or slow networks for the same reason.
+
+### No per-tool timeout mechanism existed
+
+All tools shared the same `TOOL_TIMEOUT_MS` constant. There was no way to declare that a specific tool legitimately needed more time.
+
+---
+
+## Fix
+
+### 1. Per-tool timeout override (`src/server/tools.js`)
+
+`executeTool` now checks for a `timeout` property on the tool definition and uses it instead of the global `TOOL_TIMEOUT_MS`:
+
+```js
+const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;
+
+const timeout = new Promise((_, reject) =>
+  setTimeout(
+    () => reject(new Error(`Tool '${name}' timed out after ${timeoutMs / 1000}s`)),
+    timeoutMs
+  )
+);
+```
+
+Tools that don't declare a timeout continue to use the 60s default — no behaviour change for existing tools.
+
+### 2. `system_install` seed tool with 5-minute timeout (`src/server/tools.js`)
+
+A new built-in tool handles system binary installation:
+
+```js
+system_install: {
+  timeout: 300_000, // 5 minutes
+  ...
+}
+```
+
+Behaviour:
+- **Already installed check**: runs `which <package>` first. If the binary is already on PATH, returns immediately without installing — no wasted time.
+- **Auto-detection**: tries `brew`, `apt-get`, `snap` in order. Uses the first one found. Can be overridden with an explicit `packageManager` argument.
+- **apt-get**: always runs `apt-get update -qq` before `apt-get install -y` to avoid stale package list failures. Uses `DEBIAN_FRONTEND=noninteractive` to suppress interactive prompts.
+- **Inner timeout**: 4.5 minutes on the internal `execAsync`, leaving headroom before the outer 5-minute tool timeout fires.
+- **Structured errors**: returns `exitCode`, `stdout`, `stderr` on failure so the agent can read the actual error without guessing.
+
+### 3. System prompt updated (`docs/system-prompt.md`)
+
+Added explicit guidance in the "Tool Creation" section:
+
+> **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.
+
+This mirrors the existing `npm_install` guidance and gives the model an explicit directive to reach for `system_install` over `exec`.
+
+---
+
+## Why `system_install` Instead of Increasing the Global Timeout
+
+Increasing `TOOL_TIMEOUT_MS` globally would make every tool — including `exec` — hang for much longer before failing. A runaway `exec` command (e.g. `find / -name "*.js"`) that produces no output would block the event loop for 5 minutes instead of 60 seconds. The per-tool timeout keeps the safe default for general tools while letting installation tools declare a legitimate need for more time.
+
+---
+
+## Notes on Package Availability
+
+Not all tools are available in every package manager. For ProjectDiscovery tools (nuclei, subfinder, naabu) specifically:
+
+- **macOS (brew)**: `brew install nuclei`, `brew install subfinder`, `brew install naabu` — all available via the official Homebrew formulae
+- **Linux (apt-get)**: ProjectDiscovery does not maintain an official apt repository. `apt-get install nuclei` will likely fail with "package not found"
+- **Linux (snap)**: `snap install nuclei` is available on Ubuntu/Debian
+
+On Linux, if `system_install` fails because the package isn't in the apt repository, the agent should try snap, or fall back to the ProjectDiscovery install script:
+```sh
+curl -sL https://github.com/projectdiscovery/nuclei/releases/latest/download/nuclei_linux_amd64.zip -o nuclei.zip
+```
+This would still use `exec` for the download, but with the failure recovery guidance from Finding 004 the agent should report the failure rather than looping.
+
+---
+
+## Outcome
+
+- Package installation no longer races against a 60-second wall
+- The agent has a clear, named tool to reach for when installing system binaries
+- The system prompt actively directs the agent away from `exec` for this use case
+- Per-tool timeouts are now supported for any future tools that need them

package/docs/system-prompt.md

@@ -53,12 +53,22 @@ The `exec` tool runs real shell commands on the server. Use it responsibly:
 - **Prefer targeted reads.** Use `grep`, `head`, or `tail` instead of `cat` on files you haven't seen before. Large file output is truncated anyway — a targeted command gives you better signal.
 - **Avoid commands with unbounded runtime.** If a command could run indefinitely or scan an unknown-size tree, scope it first.
 
+## Failure Recovery
+
+When a tool or command fails:
+
+- **Retry at most once** with a meaningfully different approach (different command, different source, different strategy). If it fails a second time, stop and report the failure to the user — do not keep trying variations.
+- **Do not repeat a failed strategy.** If one download method fails, do not re-run it with minor changes. Try an entirely different installation method (e.g. package manager instead of curl), or explain the failure to the user.
+- **Use `perplexity_search` sparingly.** At most 3 searches per topic per session. If the first search didn't give you what you need, try a different query angle once — then stop searching and work with what you have or report the gap.
+- **Escalate cleanly.** If you cannot make progress after two distinct approaches, give the user a clear explanation of what was attempted, what failed, and what they can do manually. A useful failure report is better than an infinite retry loop.
+
 ## Tool Creation
 
 When building a custom tool with `save_tool`:
 
 - **Prefer npm packages** over reimplementing functionality from scratch. If a well-known package exists for the task (e.g. an API SDK, a parser, a utility library), use it.
 - **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).
 
 ## logSummary Guidelines

package/package.json

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

package/src/scripts/onboarding.js

@@ -300,6 +300,44 @@ async function run() {
     }
   }
 
+  // --- PERPLEXITY STEP (OPTIONAL) ---
+  const existingPerplexityKey = loadEnvVar('PERPLEXITY_API_KEY');
+  const { configurePerplexity } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'configurePerplexity',
+      message: 'Do you want to configure Perplexity web search?',
+      default: !!existingPerplexityKey
+    }
+  ]);
+
+  if (configurePerplexity) {
+    let keepPerplexityKey = false;
+    if (existingPerplexityKey) {
+      const { keep } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'keep',
+          message: 'A PERPLEXITY_API_KEY is already configured. Do you want to keep it?',
+          default: true
+        }
+      ]);
+      keepPerplexityKey = keep;
+    }
+    if (!keepPerplexityKey) {
+      const { perplexityKey } = await inquirer.prompt([
+        {
+          type: 'password',
+          name: 'perplexityKey',
+          message: 'Enter your Perplexity API key (from perplexity.ai/settings/api):',
+          validate: (input) => input.trim().length > 0 || 'API key cannot be empty.'
+        }
+      ]);
+      saveEnvVar('PERPLEXITY_API_KEY', perplexityKey.trim());
+      console.log(chalk.green('Perplexity API key saved.'));
+    }
+  }
+
   console.log(chalk.green.bold('\nSetup complete!'));
 }
 

package/src/server/agent.js

@@ -8,6 +8,7 @@ import chalk from 'chalk';
 
 const FORMAT_NUDGE = 'Your previous response was not valid JSON. Respond only with the required JSON object: {"response": "...", "logSummary": "..."}';
 const LOOP_DETECTION_THRESHOLD = 3;
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
 const MAX_TOOL_RESULT = 4000;
 
 const WRAP_UP_NOTE = `[System: You have reached the iteration limit. This is your final response for this run.
@@ -18,11 +19,12 @@ Respond with your normal JSON, but add a checkpoint field:
   "logSummary": "Human-readable summary of what happened in this run.",
   "checkpoint": {
     "progress": "What has been fully completed so far.",
-    "remaining": "What still needs to be done to finish the task."
+    "remaining": "What still needs to be done to finish the task.",
+    "failedApproaches": ["Concise description of each approach that was tried and failed, e.g. 'downloading subfinder via curl from GitHub releases — connection reset'. Omit array entries for things that succeeded. Leave as empty array if nothing failed."]
   }
 }
 
-The checkpoint field will be used to automatically resume the task in the next run.]`;
+The checkpoint field will be used to automatically resume the task in the next run. failedApproaches is injected into the next run so the agent does not waste iterations repeating strategies that already failed.]`;
 
 // Serializes concurrent requests for the same session. Maps sessionId to the
 // tail of the current request chain (a Promise that resolves when the last
@@ -81,12 +83,17 @@ async function runAgentLoop(client, config, session, prepareMessages) {
   let response = '';
   let logSummary = '';
   let status = 'ok';
+  let consecutiveFailures = 0;
 
   while (iteration < config.maxIterations) {
     iteration++;
 
     let modelResult;
-    const preparedMessages = prepareMessages(session.messages);
+    const iterationsLeft = config.maxIterations - iteration + 1;
+    const base = prepareMessages(session.messages);
+    const preparedMessages = iterationsLeft <= 5
+      ? [...base, { role: 'user', content: `[System: ${iterationsLeft} iteration${iterationsLeft === 1 ? '' : 's'} remaining in this run. Budget your remaining steps accordingly — if you cannot finish in time, consolidate progress and provide a checkpoint.]` }]
+      : base;
     try {
       modelResult = await callModelWithFallback(client, config, preparedMessages, toolDefs);
     } catch (e) {
@@ -154,6 +161,14 @@ async function runAgentLoop(client, config, session, prepareMessages) {
           toolsModified = true;
         }
 
+        const resultObj = typeof result === 'object' && result !== null ? result : null;
+        const toolFailed = toolStatus === 'error' || (resultObj && resultObj.status === 'error');
+        if (toolFailed) {
+          consecutiveFailures++;
+        } else {
+          consecutiveFailures = 0;
+        }
+
         const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
         runToolCalls.push({ name: toolName, args: toolArgs, status: toolStatus, result: resultStr });
 
@@ -170,6 +185,14 @@ async function runAgentLoop(client, config, session, prepareMessages) {
         loopTracker.set(callKey, (loopTracker.get(callKey) || 0) + 1);
       }
 
+      if (consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD) {
+        session.messages.push({
+          role: 'user',
+          content: '[System: You have had 3 or more consecutive tool failures. Stop retrying the same approach. Either pivot to a fundamentally different strategy or provide your final response explaining what failed and why.]',
+        });
+        consecutiveFailures = 0;
+      }
+
       const loopDetected = [...loopTracker.values()].some(count => count >= LOOP_DETECTION_THRESHOLD);
       if (loopDetected) {
         session.messages.push({
@@ -455,7 +478,12 @@ async function _runHandleChat(config, sessionId, userMessage) {
 
       // Resume with checkpoint.remaining as new prompt.
       // Guard against null/undefined in case the model omitted the field.
-      session.messages.push({ role: 'user', content: run.checkpoint.remaining || 'Continue with the task.' });
+      // Prepend any failed approaches so the next run doesn't repeat them.
+      let resumeContent = run.checkpoint.remaining || 'Continue with the task.';
+      if (run.checkpoint.failedApproaches && run.checkpoint.failedApproaches.length > 0) {
+        resumeContent += `\n\n[System: The following approaches were tried and failed in the previous run — do not repeat them:\n${run.checkpoint.failedApproaches.map((a, i) => `${i + 1}. ${a}`).join('\n')}]`;
+      }
+      session.messages.push({ role: 'user', content: resumeContent });
     }
   } catch (e) {
     await appendLog(sessionId, {

package/src/server/tools.js

@@ -221,6 +221,127 @@ const SEED_TOOLS = {
       }
     `,
   },
+  perplexity_search: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'perplexity_search',
+        description: 'Search the web using Perplexity AI. Returns an answer grounded in real-time web results with citations. Use this for current events, factual lookups, or research questions. Use sparingly — at most 3 searches per topic. Do not repeat the same query with minor variations; if an initial search does not yield what you need, switch to a different approach or verify locally with exec.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: {
+              type: 'string',
+              description: 'The search query or question.',
+            },
+            model: {
+              type: 'string',
+              enum: ['sonar', 'sonar-pro', 'sonar-deep-research'],
+              description: 'Search model to use. sonar: fast and cheap, good for simple lookups. sonar-pro: deeper multi-step search, more citations, better for complex questions. sonar-deep-research: long-form research reports. Defaults to sonar.',
+            },
+            search_recency_filter: {
+              type: 'string',
+              enum: ['hour', 'day', 'week', 'month', 'year'],
+              description: 'Optional time filter to restrict results to recent content.',
+            },
+          },
+          required: ['query'],
+        },
+      },
+    },
+    code: `
+      const OpenAI = require('openai');
+      const client = new OpenAI({
+        apiKey: process.env.PERPLEXITY_API_KEY,
+        baseURL: 'https://api.perplexity.ai',
+      });
+      const params = {
+        model: args.model || 'sonar',
+        messages: [{ role: 'user', content: args.query }],
+      };
+      if (args.search_recency_filter) params.search_recency_filter = args.search_recency_filter;
+      const response = await client.chat.completions.create(params);
+      const answer = response.choices[0].message.content;
+      const citations = response.citations || [];
+      return { answer, citations };
+    `,
+  },
+  system_install: {
+    timeout: 300_000, // 5 minutes — package downloads and installs routinely exceed 60s
+    definition: {
+      type: 'function',
+      function: {
+        name: 'system_install',
+        description: 'Install a system binary using the available package manager (brew on macOS, apt-get on Debian/Ubuntu, snap as fallback). Always use this instead of exec for installing system packages — it auto-detects the package manager and has a 5-minute timeout sized for real downloads. If the binary is already on PATH it returns immediately without installing. Examples: nuclei, subfinder, naabu, jq, curl, git.',
+        parameters: {
+          type: 'object',
+          properties: {
+            package: {
+              type: 'string',
+              description: 'The package name to install, e.g. "nuclei", "jq", "curl".',
+            },
+            packageManager: {
+              type: 'string',
+              enum: ['brew', 'apt-get', 'snap'],
+              description: 'Optional. Force a specific package manager instead of auto-detecting.',
+            },
+          },
+          required: ['package'],
+        },
+      },
+    },
+    code: `
+      const { exec } = require('child_process');
+      const { promisify } = require('util');
+      const execAsync = promisify(exec);
+
+      // If the binary is already installed, return immediately.
+      try {
+        const { stdout: whichOut } = await execAsync('which ' + args.package, { timeout: 5000 });
+        if (whichOut.trim()) {
+          return { status: 'ok', alreadyInstalled: true, package: args.package, path: whichOut.trim() };
+        }
+      } catch {}
+
+      // Auto-detect package manager if not specified.
+      let pm = args.packageManager;
+      if (!pm) {
+        for (const candidate of ['brew', 'apt-get', 'snap']) {
+          try {
+            await execAsync('which ' + candidate, { timeout: 5000 });
+            pm = candidate;
+            break;
+          } catch {}
+        }
+      }
+
+      if (!pm) {
+        return { status: 'error', package: args.package, error: 'No supported package manager found (brew, apt-get, snap). Install one first or use exec to install manually.' };
+      }
+
+      // Build install command. apt-get always runs update first to avoid stale
+      // package lists causing "package not found" errors.
+      let cmd;
+      if (pm === 'apt-get') {
+        cmd = 'DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ' + args.package;
+      } else if (pm === 'brew') {
+        cmd = 'brew install ' + args.package;
+      } else {
+        cmd = pm + ' install ' + args.package;
+      }
+
+      try {
+        const { stdout, stderr } = await execAsync(cmd, {
+          encoding: 'utf8',
+          timeout: 270000, // 4.5 min — leaves headroom before the outer 5-min tool timeout
+          maxBuffer: 2 * 1024 * 1024,
+        });
+        return { status: 'ok', packageManager: pm, package: args.package, stdout, stderr };
+      } catch (e) {
+        return { status: 'error', packageManager: pm, package: args.package, exitCode: e.code || 1, stdout: e.stdout || '', stderr: e.stderr || e.message };
+      }
+    `,
+  },
   get_recent_sessions: {
     definition: {
       type: 'function',
@@ -314,10 +435,14 @@ export async function executeTool(tools, name, toolArgs) {
 
   const fn = new AsyncFunction('args', 'fs', 'path', 'process', 'require', '__jarvisDir', tool.code);
 
+  // Tools can declare their own timeout (e.g. system_install needs 5 min).
+  // Falls back to the global default of 60s.
+  const timeoutMs = tool.timeout || TOOL_TIMEOUT_MS;
+
   const timeout = new Promise((_, reject) =>
     setTimeout(
-      () => reject(new Error(`Tool '${name}' timed out after ${TOOL_TIMEOUT_MS / 1000}s`)),
-      TOOL_TIMEOUT_MS
+      () => reject(new Error(`Tool '${name}' timed out after ${timeoutMs / 1000}s`)),
+      timeoutMs
     )
   );