@ducci/jarvis 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# Jarvis
+
+A fully automated agent system that lives on a server. Will always run, can be started, stopped, restarted. Autorestarts on crash and can be configured via a setup phase. This README is the entry point and links to focused docs for each major topic.
+
+## Docs
+
+- Onboarding and Configuration: [docs/setup.md](./docs/setup.md)
+- CLI and Server Lifecycle: [docs/cli.md](./docs/cli.md)
+- Agent system details: [docs/agent.md](./docs/agent.md)
+- UI implementation: [docs/ui.md](./docs/ui.md)
+- Evaluation guide: [docs/evaluation.md](./docs/evaluation.md)
+
+## Principles (early draft)
+
+- Minimal surface area in v1
+- Clear defaults and predictable behavior
+- Simple local data model
+- No hidden automation
+
+## end goal (how i wish the system will be onced finished)
+- following what jarvis is doing is super easy to understand for a human
+- everything that goes wrong e.g. failed tool calls, or errors from exec calls should be easy to understand for a human
+- transparency is very important, without this we can not easily debug or improve the system
+- it should work autonomously, i.e. it does not need any instructions from me on decicions but instead decide itself how to achieve whatever its doing
+- when working autonomously on a task its given it should know when to stop (task is done in a good quality)
+
+## Implementation Roadmap
+
+To reach v1, we will follow this order:
+
+1.  **Phase 1: Project Skeleton [x]**
+    - Scaffolding (`package.json`, folder structure).
+    - Basic HTTP server on port `18008`.
+2.  **Phase 2: Onboarding & Config [x]**
+    - `jarvis setup` CLI command.
+    - Persistence for API keys (`.env`) and settings (`settings.json`).
+3.  **Phase 3: Core Agent Loop [x]**
+    - Request/Response flow with OpenRouter.
+    - Serial tool execution logic (`new Function`).
+    - Basic session persistence.
+    - Seed tool: `list_dir` (runs `ls -la`) to verify the full loop end-to-end.
+4.  **Phase 4: Lifecycle Management [x]**
+    - CLI `start/stop/status` using programmatic PM2.
+    - Pre-flight configuration checks.
+5.  **Phase 5: Tools & Refinement [x]**
+    - Implementation of built-in tools (`exec`, `user_info`).
+    - Standardized logging (JSONL).
+6.  **Phase 6: UI [x]**
+    - Vite + React + Tailwind chat interface in `ui/`.
+    - Server serves built UI as static files.
+
+## Usage
+
+### First-time setup
+
+```
+npm install
+npm run setup
+```
+
+This prompts for your OpenRouter API key and model selection.
+
+### Running in production (background via PM2)
+
+```
+npm start          # start the server in the background (auto-restarts on crash)
+npm run status     # check if it's running (PID, uptime, restarts)
+npm run stop       # stop the background server
+```
+
+The server runs on port `18008`. Open `http://localhost:18008` to use the chat UI.
+
+Logs are written to `~/.jarvis/logs/server.log`.
+
+### Running in development (foreground)
+
+```
+npm run dev        # start the server with nodemon (auto-reload on file changes)
+```
+
+To develop the UI with hot-reload:
+
+```
+cd ui
+npm install        # first time only
+npm run dev        # starts Vite on port 5173, proxies /api to localhost:18008
+```
+
+You need both the server (`npm run dev` in root) and the UI dev server (`npm run dev` in `ui/`) running at the same time. Open `http://localhost:5173` during UI development.
+
+### Building the UI for production
+
+```
+cd ui
+npm run build
+```
+
+This outputs to `ui/dist/`, which the Express server serves as static files automatically.
+
+### Global install
+
+```
+npm i -g @ducci/jarvis
+jarvis setup
+jarvis start
+jarvis stop
+jarvis status
+```
+
+## Security & Local Usage
+
+Jarvis is designed for **local use only**. There is no built-in authentication for the API. It is intended to be run on a trusted machine (e.g., your laptop or a private server) where the port is not exposed to the public internet.
+
+## Current status, IMPORTANT instructions for LLMs:
+- Phase 1 (Skeleton) is implemented.
+- Phase 2 (Onboarding & Config) is implemented.
+- Phase 3 (Core Agent Loop) is implemented.
+- Phase 4 (Lifecycle Management) is implemented.
+- Phase 5 (Tools & Refinement) is implemented.
+- Phase 6 (UI) is implemented.
+- the scope is only this jarvis folder and each file in it. no parent folders or any other outside of this

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ducci/jarvis",
+  "version": "1.0.0",
+  "description": "A fully automated agent system that lives on a server.",
+  "main": "./src/index.js",
+  "type": "module",
+  "bin": {
+    "jarvis": "./src/index.js",
+    "jarvis-setup": "./src/scripts/onboarding.js"
+  },
+  "files": [
+    "src",
+    "ui/dist"
+  ],
+  "scripts": {
+    "start": "node ./src/index.js start",
+    "stop": "node ./src/index.js stop",
+    "status": "node ./src/index.js status",
+    "setup": "node ./src/scripts/onboarding.js",
+    "dev": "nodemon ./src/server/app.js",
+    "prepare": "cd ui && npm install && npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["agent", "ai", "openrouter", "cli", "server"],
+  "author": "ducci",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "inquirer": "^12.11.1",
+    "openai": "^6.22.0",
+    "pm2": "^6.0.14"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.14"
+  }
+}

package/src/index.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import pm2 from 'pm2';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const JARVIS_DIR = path.join(os.homedir(), '.jarvis');
+const ENV_FILE = path.join(JARVIS_DIR, '.env');
+const SETTINGS_FILE = path.join(JARVIS_DIR, 'data', 'config', 'settings.json');
+const SERVER_SCRIPT = path.join(__dirname, 'server', 'app.js');
+const PROCESS_NAME = 'jarvis-server';
+const LOG_FILE = path.join(JARVIS_DIR, 'logs', 'server.log');
+
+function preflight() {
+  if (!fs.existsSync(ENV_FILE)) {
+    console.error('Error: .env not found. Please run `jarvis setup` first.');
+    process.exit(1);
+  }
+  if (!fs.existsSync(SETTINGS_FILE)) {
+    console.error('Error: settings.json not found. Please run `jarvis setup` first.');
+    process.exit(1);
+  }
+  // Ensure logs directory exists for PM2 output
+  fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+}
+
+function connectPm2() {
+  return new Promise((resolve, reject) => {
+    pm2.connect((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+function pm2Start() {
+  return new Promise((resolve, reject) => {
+    pm2.start({
+      script: SERVER_SCRIPT,
+      name: PROCESS_NAME,
+      autorestart: true,
+      output: LOG_FILE,
+      error: LOG_FILE,
+      merge_logs: true,
+    }, (err, proc) => {
+      if (err) reject(err);
+      else resolve(proc);
+    });
+  });
+}
+
+function pm2Stop() {
+  return new Promise((resolve, reject) => {
+    pm2.stop(PROCESS_NAME, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+function pm2Delete() {
+  return new Promise((resolve, reject) => {
+    pm2.delete(PROCESS_NAME, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+function pm2Describe() {
+  return new Promise((resolve, reject) => {
+    pm2.describe(PROCESS_NAME, (err, desc) => {
+      if (err) reject(err);
+      else resolve(desc);
+    });
+  });
+}
+
+const program = new Command();
+
+program
+  .name('jarvis')
+  .description('A fully automated agent system that lives on a server.')
+  .version('1.0.0');
+
+program
+  .command('setup')
+  .description('Run interactive onboarding to configure API key and model.')
+  .action(() => {
+    const onboardingScript = path.join(__dirname, 'scripts', 'onboarding.js');
+    spawnSync('node', [onboardingScript], { stdio: 'inherit' });
+  });
+
+program
+  .command('start')
+  .description('Start the Jarvis server in the background.')
+  .action(async () => {
+    preflight();
+    try {
+      await connectPm2();
+      // Check if already running
+      const desc = await pm2Describe().catch(() => []);
+      if (desc.length > 0 && desc[0].pm2_env?.status === 'online') {
+        console.log('Jarvis server is already running.');
+        pm2.disconnect();
+        return;
+      }
+      await pm2Start();
+      console.log('Jarvis server started.');
+      pm2.disconnect();
+    } catch (e) {
+      console.error('Failed to start Jarvis server:', e.message);
+      pm2.disconnect();
+      process.exit(1);
+    }
+  });
+
+program
+  .command('stop')
+  .description('Stop the Jarvis server.')
+  .action(async () => {
+    try {
+      await connectPm2();
+      await pm2Stop();
+      await pm2Delete();
+      console.log('Jarvis server stopped.');
+      pm2.disconnect();
+    } catch (e) {
+      console.error('Failed to stop Jarvis server:', e.message);
+      pm2.disconnect();
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Display the status of the Jarvis server.')
+  .action(async () => {
+    try {
+      await connectPm2();
+      const desc = await pm2Describe().catch(() => []);
+      if (desc.length === 0) {
+        console.log('Jarvis server is not running.');
+      } else {
+        const proc = desc[0];
+        const env = proc.pm2_env || {};
+        console.log(`Name:      ${proc.name}`);
+        console.log(`Status:    ${env.status}`);
+        console.log(`PID:       ${proc.pid}`);
+        console.log(`Uptime:    ${env.pm_uptime ? new Date(env.pm_uptime).toISOString() : 'N/A'}`);
+        console.log(`Restarts:  ${env.restart_time || 0}`);
+        console.log(`Log file:  ${LOG_FILE}`);
+      }
+      pm2.disconnect();
+    } catch (e) {
+      console.error('Failed to get status:', e.message);
+      pm2.disconnect();
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/scripts/onboarding.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+
+const jarvisDir = path.join(os.homedir(), '.jarvis');
+const envFile = path.join(jarvisDir, '.env');
+const configDir = path.join(jarvisDir, 'data', 'config');
+const logsDir = path.join(jarvisDir, 'logs');
+const settingsFile = path.join(configDir, 'settings.json');
+
+function ensureDirectories() {
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.mkdirSync(logsDir, { recursive: true });
+}
+
+function loadEnv() {
+  if (fs.existsSync(envFile)) {
+    const content = fs.readFileSync(envFile, 'utf8');
+    const match = content.match(/^OPENROUTER_API_KEY=(.*)$/m);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+  return null;
+}
+
+function saveEnv(apiKey) {
+  let content = '';
+  if (fs.existsSync(envFile)) {
+    content = fs.readFileSync(envFile, 'utf8');
+    if (content.match(/^OPENROUTER_API_KEY=/m)) {
+      content = content.replace(/^OPENROUTER_API_KEY=.*$/m, `OPENROUTER_API_KEY=${apiKey}`);
+    } else {
+      content += `\nOPENROUTER_API_KEY=${apiKey}\n`;
+    }
+  } else {
+    content = `OPENROUTER_API_KEY=${apiKey}\n`;
+  }
+  fs.writeFileSync(envFile, content.trim() + '\n', 'utf8');
+}
+
+function loadSettings() {
+  if (fs.existsSync(settingsFile)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    } catch (e) {
+      return {};
+    }
+  }
+  return {};
+}
+
+function saveSettings(settings) {
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2), 'utf8');
+}
+
+async function fetchModels(apiKey) {
+  console.log(chalk.blue('Fetching models from OpenRouter...'));
+  try {
+    const response = await fetch('https://openrouter.ai/api/v1/models', {
+      headers: {
+        'Authorization': `Bearer ${apiKey}`
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.data;
+  } catch (error) {
+    console.error(chalk.red('Failed to fetch models:'), error.message);
+    return [];
+  }
+}
+
+async function run() {
+  ensureDirectories();
+
+  console.log(chalk.green.bold('\n=== Jarvis Setup ===\n'));
+
+  // --- API KEY STEP ---
+  let existingKey = loadEnv();
+  let apiKey = existingKey;
+
+  if (existingKey) {
+    const { keepKey } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'keepKey',
+        message: 'An OPENROUTER_API_KEY is already configured. Do you want to keep it?',
+        default: true
+      }
+    ]);
+
+    if (!keepKey) {
+      const { newKey } = await inquirer.prompt([
+        {
+          type: 'password',
+          name: 'newKey',
+          message: 'Enter your OpenRouter API key:',
+          validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.'
+        }
+      ]);
+      apiKey = newKey;
+      saveEnv(apiKey);
+      console.log(chalk.green('API key updated.'));
+    }
+  } else {
+    const { newKey } = await inquirer.prompt([
+      {
+        type: 'password',
+        name: 'newKey',
+        message: 'Enter your OpenRouter API key:',
+        validate: (input) => input.length >= 10 || 'API key must be at least 10 characters long.'
+      }
+    ]);
+    apiKey = newKey;
+    saveEnv(apiKey);
+    console.log(chalk.green('API key saved.'));
+  }
+
+  // --- MODEL SELECTION STEP ---
+  let settings = loadSettings();
+  let selectedModel = settings.selectedModel;
+
+  if (selectedModel) {
+    const { keepModel } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'keepModel',
+        message: `Current model is ${chalk.yellow(selectedModel)}. Do you want to keep it or change it?`,
+        choices: [
+          { name: 'Keep current model', value: true },
+          { name: 'Change model', value: false }
+        ]
+      }
+    ]);
+
+    if (!keepModel) {
+      selectedModel = null;
+    }
+  }
+
+  if (!selectedModel) {
+    const { modelSelectionMethod } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'modelSelectionMethod',
+        message: 'How would you like to select a model?',
+        choices: [
+          { name: 'Browse OpenRouter models', value: 'browse' },
+          { name: 'Enter model ID manually', value: 'manual' }
+        ]
+      }
+    ]);
+
+    if (modelSelectionMethod === 'manual') {
+      const { manualModel } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'manualModel',
+          message: 'Enter OpenRouter model ID (e.g., anthropic/claude-3.5-sonnet):',
+          validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.'
+        }
+      ]);
+      selectedModel = manualModel.trim();
+    } else {
+      const models = await fetchModels(apiKey);
+      if (models.length === 0) {
+        console.log(chalk.yellow('Falling back to manual entry due to fetch failure.'));
+        const { manualModel } = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'manualModel',
+            message: 'Enter OpenRouter model ID:',
+            validate: (input) => input.trim().length > 0 || 'Model ID cannot be empty.'
+          }
+        ]);
+        selectedModel = manualModel.trim();
+      } else {
+        // Sort models: free first, then alphabetical
+        models.sort((a, b) => {
+          const isFreeA = a.pricing && parseFloat(a.pricing.prompt) === 0 && parseFloat(a.pricing.completion) === 0;
+          const isFreeB = b.pricing && parseFloat(b.pricing.prompt) === 0 && parseFloat(b.pricing.completion) === 0;
+
+          if (isFreeA && !isFreeB) return -1;
+          if (!isFreeA && isFreeB) return 1;
+          return a.id.localeCompare(b.id);
+        });
+
+        const choices = models.map(m => {
+          const isFree = m.pricing && parseFloat(m.pricing.prompt) === 0 && parseFloat(m.pricing.completion) === 0;
+          return {
+            name: `${m.id} ${isFree ? chalk.green('(Free)') : ''}`,
+            value: m.id
+          };
+        });
+
+        const { browsedModel } = await inquirer.prompt([
+          {
+            type: 'list',
+            name: 'browsedModel',
+            message: 'Select a model:',
+            choices: choices,
+            pageSize: 20
+          }
+        ]);
+        selectedModel = browsedModel;
+      }
+    }
+  }
+
+  settings.selectedModel = selectedModel;
+  if (!settings.fallbackModel) {
+    settings.fallbackModel = 'openrouter/free';
+  }
+  if (settings.maxIterations === undefined) {
+    settings.maxIterations = 10;
+  }
+  if (settings.maxHandoffs === undefined) {
+    settings.maxHandoffs = 5;
+  }
+  if (settings.port === undefined) {
+    settings.port = 18008;
+  }
+
+  saveSettings(settings);
+  console.log(chalk.green(`\nModel ${chalk.bold(selectedModel)} saved to settings.`));
+  console.log(chalk.green.bold('Setup complete! You can now start the Jarvis server.'));
+}
+
+run().catch(error => {
+  console.error(chalk.red('Setup failed:'), error);
+  process.exit(1);
+});

package/src/server/agent.js

@@ -0,0 +1,287 @@
+import crypto from 'crypto';
+import OpenAI from 'openai';
+import { loadSystemPrompt, resolveSystemPrompt } from './config.js';
+import { loadSession, saveSession, createSession } from './sessions.js';
+import { loadTools, getToolDefinitions, executeTool } from './tools.js';
+import { appendLog } from './logging.js';
+
+const WRAP_UP_NOTE = `[System: You have reached the iteration limit. This is your final response for this run.
+Respond with your normal JSON, but add a checkpoint field:
+
+{
+  "response": "Brief message to the user that the task is still in progress.",
+  "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."
+  }
+}
+
+The checkpoint field will be used to automatically resume the task in the next run.]`;
+
+async function callModel(client, model, messages, tools) {
+  const params = { model, messages };
+  if (tools && tools.length > 0) {
+    params.tools = tools;
+  }
+  return await client.chat.completions.create(params);
+}
+
+async function callModelWithFallback(client, config, messages, tools) {
+  try {
+    return await callModel(client, config.selectedModel, messages, tools);
+  } catch (primaryErr) {
+    try {
+      return await callModel(client, config.fallbackModel, messages, tools);
+    } catch (fallbackErr) {
+      throw new Error(
+        `Both primary (${config.selectedModel}) and fallback (${config.fallbackModel}) models failed. Last error: ${fallbackErr.message}`
+      );
+    }
+  }
+}
+
+/**
+ * Runs a single agent loop up to maxIterations.
+ * Returns { iteration, response, logSummary, status, runToolCalls, checkpoint }.
+ */
+async function runAgentLoop(client, config, session, tools, toolDefs, prepareMessages) {
+  let iteration = 0;
+  const runToolCalls = [];
+  let done = false;
+  let response = '';
+  let logSummary = '';
+  let status = 'ok';
+
+  while (iteration < config.maxIterations) {
+    iteration++;
+
+    let modelResult;
+    try {
+      modelResult = await callModelWithFallback(client, config, prepareMessages(session.messages), toolDefs);
+    } catch (e) {
+      return {
+        iteration,
+        response: e.message,
+        logSummary: `Model error on iteration ${iteration}: ${e.message}`,
+        status: 'model_error',
+        runToolCalls,
+        checkpoint: null,
+      };
+    }
+
+    const assistantMessage = modelResult.choices[0].message;
+
+    // Tool calls present — execute serially and continue loop
+    if (assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+      session.messages.push({
+        role: 'assistant',
+        content: assistantMessage.content || null,
+        tool_calls: assistantMessage.tool_calls,
+      });
+
+      for (const toolCall of assistantMessage.tool_calls) {
+        const toolName = toolCall.function.name;
+        let toolArgs;
+        try {
+          toolArgs = JSON.parse(toolCall.function.arguments || '{}');
+        } catch {
+          toolArgs = {};
+        }
+
+        let result;
+        let toolStatus = 'ok';
+        try {
+          result = await executeTool(tools, toolName, toolArgs);
+        } catch (e) {
+          result = { status: 'error', error: e.message };
+          toolStatus = 'error';
+        }
+
+        const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+        runToolCalls.push({ name: toolName, args: toolArgs, status: toolStatus, result: resultStr });
+
+        session.messages.push({
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          content: resultStr,
+        });
+      }
+
+      continue;
+    }
+
+    // No tool calls — final response
+    const content = assistantMessage.content || '';
+    session.messages.push({ role: 'assistant', content });
+
+    try {
+      const parsed = JSON.parse(content);
+      response = parsed.response || content;
+      logSummary = parsed.logSummary || '';
+    } catch {
+      response = content;
+      logSummary = 'Model returned non-JSON final response.';
+      status = 'format_error';
+    }
+
+    done = true;
+    break;
+  }
+
+  // Hit iteration limit without completing — wrap-up call
+  if (!done) {
+    const wrapUpMessages = [
+      ...prepareMessages(session.messages),
+      { role: 'user', content: WRAP_UP_NOTE },
+    ];
+
+    let wrapUpResult;
+    try {
+      wrapUpResult = await callModelWithFallback(client, config, wrapUpMessages, []);
+    } catch (e) {
+      return {
+        iteration,
+        response: 'Agent reached iteration limit and wrap-up call also failed.',
+        logSummary: `Iteration limit reached. Wrap-up failed: ${e.message}`,
+        status: 'model_error',
+        runToolCalls,
+        checkpoint: null,
+      };
+    }
+
+    const wrapUpContent = wrapUpResult.choices[0].message.content || '';
+    // Store the wrap-up response (but NOT the temporary system note)
+    session.messages.push({ role: 'assistant', content: wrapUpContent });
+
+    try {
+      const parsed = JSON.parse(wrapUpContent);
+      response = parsed.response || '';
+      logSummary = parsed.logSummary || '';
+
+      if (parsed.checkpoint) {
+        return {
+          iteration,
+          response,
+          logSummary,
+          status: 'checkpoint_reached',
+          runToolCalls,
+          checkpoint: parsed.checkpoint,
+        };
+      }
+    } catch {
+      response = wrapUpContent;
+      logSummary = 'Wrap-up response was not valid JSON.';
+    }
+
+    status = 'checkpoint_reached';
+  }
+
+  return { iteration, response, logSummary, status, runToolCalls, checkpoint: null };
+}
+
+/**
+ * Main entry point: handles a single POST /api/chat request.
+ * Manages the handoff loop across multiple agent runs.
+ */
+export async function handleChat(config, requestSessionId, userMessage) {
+  const client = new OpenAI({
+    baseURL: 'https://openrouter.ai/api/v1',
+    apiKey: config.apiKey,
+  });
+
+  const systemPromptTemplate = loadSystemPrompt();
+  const sessionId = requestSessionId || crypto.randomUUID();
+  let session = loadSession(sessionId);
+
+  if (!session) {
+    session = createSession(systemPromptTemplate);
+  }
+
+  // Append user message and reset handoff counter
+  session.messages.push({ role: 'user', content: userMessage });
+  session.metadata.handoffCount = 0;
+
+  const tools = loadTools();
+  const toolDefs = getToolDefinitions(tools);
+
+  // Resolves {{user_info}} in system prompt at runtime (never persisted)
+  function prepareMessages(messages) {
+    return messages.map((msg, i) => {
+      if (i === 0 && msg.role === 'system') {
+        return { ...msg, content: resolveSystemPrompt(msg.content) };
+      }
+      return msg;
+    });
+  }
+
+  const allToolCalls = [];
+  let finalResponse = '';
+  let finalLogSummary = '';
+  let finalStatus = 'ok';
+
+  // Handoff loop
+  while (true) {
+    const run = await runAgentLoop(client, config, session, tools, toolDefs, prepareMessages);
+    allToolCalls.push(...run.runToolCalls);
+
+    if (run.status !== 'checkpoint_reached') {
+      finalResponse = run.response;
+      finalLogSummary = run.logSummary;
+      finalStatus = run.status;
+
+      appendLog(sessionId, {
+        iteration: run.iteration,
+        model: config.selectedModel,
+        userInput: userMessage,
+        toolCalls: allToolCalls,
+        response: finalResponse,
+        logSummary: finalLogSummary,
+        status: finalStatus,
+      });
+      break;
+    }
+
+    // Checkpoint reached — log this run
+    appendLog(sessionId, {
+      iteration: run.iteration,
+      model: config.selectedModel,
+      userInput: userMessage,
+      toolCalls: run.runToolCalls,
+      response: run.response,
+      logSummary: run.logSummary,
+      status: 'checkpoint_reached',
+    });
+
+    // Check handoff limit
+    session.metadata.handoffCount++;
+    if (session.metadata.handoffCount > config.maxHandoffs) {
+      finalResponse = run.response;
+      finalLogSummary = run.logSummary;
+      finalStatus = 'intervention_required';
+
+      appendLog(sessionId, {
+        iteration: 0,
+        model: config.selectedModel,
+        userInput: userMessage,
+        toolCalls: [],
+        response: finalResponse,
+        logSummary: 'Max handoffs exceeded. Human intervention required.',
+        status: 'intervention_required',
+      });
+      break;
+    }
+
+    // Resume with checkpoint.remaining as new prompt
+    session.messages.push({ role: 'user', content: run.checkpoint.remaining });
+  }
+
+  saveSession(sessionId, session);
+
+  return {
+    sessionId,
+    response: finalResponse,
+    logSummary: finalLogSummary,
+    toolCalls: allToolCalls,
+  };
+}

package/src/server/app.js

@@ -0,0 +1,73 @@
+import express from 'express';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { loadConfig, ensureDirectories } from './config.js';
+import { seedTools } from './tools.js';
+import { handleChat } from './agent.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+app.use(express.json());
+
+// Serve the built UI as static files
+const uiDist = path.join(__dirname, '..', '..', 'ui', 'dist');
+app.use(express.static(uiDist));
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+app.post('/api/chat', async (req, res) => {
+  const { sessionId, message } = req.body;
+
+  if (!message || typeof message !== 'string' || message.trim().length === 0) {
+    return res.status(400).json({ error: 'message is required', status: 'format_error' });
+  }
+
+  try {
+    const result = await handleChat(app.locals.config, sessionId || null, message.trim());
+    res.json(result);
+  } catch (e) {
+    console.error('Chat error:', e);
+    res.status(500).json({ error: e.message, status: 'model_error' });
+  }
+});
+
+// SPA fallback: serve index.html for non-API routes
+app.use((req, res, next) => {
+  if (req.method === 'GET' && !req.path.startsWith('/api') && !req.path.startsWith('/health')) {
+    res.sendFile(path.join(uiDist, 'index.html'), (err) => {
+      if (err) next();
+    });
+  } else {
+    next();
+  }
+});
+
+function startServer() {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+
+  ensureDirectories();
+  seedTools();
+
+  app.locals.config = config;
+
+  const PORT = config.port;
+  app.listen(PORT, () => {
+    console.log(`Jarvis server listening on port ${PORT}`);
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  startServer();
+}
+
+export { app, startServer };

package/src/server/config.js

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const JARVIS_DIR = path.join(os.homedir(), '.jarvis');
+
+export const PATHS = {
+  jarvisDir: JARVIS_DIR,
+  envFile: path.join(JARVIS_DIR, '.env'),
+  configDir: path.join(JARVIS_DIR, 'data', 'config'),
+  settingsFile: path.join(JARVIS_DIR, 'data', 'config', 'settings.json'),
+  conversationsDir: path.join(JARVIS_DIR, 'data', 'conversations'),
+  toolsDir: path.join(JARVIS_DIR, 'data', 'tools'),
+  toolsFile: path.join(JARVIS_DIR, 'data', 'tools', 'tools.json'),
+  logsDir: path.join(JARVIS_DIR, 'logs'),
+  userInfoFile: path.join(JARVIS_DIR, 'data', 'user-info.json'),
+  systemPromptFile: path.join(__dirname, '..', '..', 'docs', 'system-prompt.md'),
+};
+
+export function ensureDirectories() {
+  for (const dir of [PATHS.configDir, PATHS.conversationsDir, PATHS.toolsDir, PATHS.logsDir]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function loadConfig() {
+  dotenv.config({ path: PATHS.envFile });
+
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error('OPENROUTER_API_KEY not found. Run `jarvis setup` first.');
+  }
+
+  if (!fs.existsSync(PATHS.settingsFile)) {
+    throw new Error('settings.json not found. Run `jarvis setup` first.');
+  }
+
+  const settings = JSON.parse(fs.readFileSync(PATHS.settingsFile, 'utf8'));
+
+  return {
+    apiKey,
+    selectedModel: settings.selectedModel,
+    fallbackModel: settings.fallbackModel || 'openrouter/free',
+    maxIterations: settings.maxIterations || 10,
+    maxHandoffs: settings.maxHandoffs || 5,
+    port: settings.port || 18008,
+  };
+}
+
+export function loadSystemPrompt() {
+  const content = fs.readFileSync(PATHS.systemPromptFile, 'utf8');
+  const match = content.match(/```\n([\s\S]*?)```/);
+  if (!match) throw new Error('Could not parse system prompt from docs/system-prompt.md');
+  return match[1].trim();
+}
+
+export function resolveSystemPrompt(promptTemplate) {
+  let userInfo = '(none yet)';
+  try {
+    const raw = fs.readFileSync(PATHS.userInfoFile, 'utf8');
+    const { items } = JSON.parse(raw);
+    if (items && items.length > 0) {
+      userInfo = items.map(i => `- ${i.key}: ${i.value}`).join('\n');
+    }
+  } catch {
+    // File doesn't exist yet
+  }
+  return promptTemplate.replace('{{user_info}}', userInfo);
+}

package/src/server/logging.js

@@ -0,0 +1,9 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from './config.js';
+
+export function appendLog(sessionId, entry) {
+  const logFile = path.join(PATHS.logsDir, `session-${sessionId}.jsonl`);
+  const line = JSON.stringify({ ts: new Date().toISOString(), sessionId, ...entry }) + '\n';
+  fs.appendFileSync(logFile, line, 'utf8');
+}

package/src/server/sessions.js

@@ -0,0 +1,31 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from './config.js';
+
+export function loadSession(sessionId) {
+  const filePath = path.join(PATHS.conversationsDir, `${sessionId}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(sessionId, session) {
+  session.metadata.updatedAt = new Date().toISOString();
+  const filePath = path.join(PATHS.conversationsDir, `${sessionId}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(session, null, 2), 'utf8');
+}
+
+export function createSession(systemPromptTemplate) {
+  return {
+    metadata: {
+      handoffCount: 0,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+    messages: [
+      { role: 'system', content: systemPromptTemplate },
+    ],
+  };
+}

package/src/server/tools.js

@@ -0,0 +1,183 @@
+import fs from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+import { PATHS } from './config.js';
+
+const _require = createRequire(import.meta.url);
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
+const SEED_TOOLS = {
+  list_dir: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'list_dir',
+        description: 'List directory contents (similar to ls -la). Use this to explore the filesystem and see what files and directories exist at a given path.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'Directory path to list. Defaults to the current working directory if omitted.',
+            },
+          },
+          required: [],
+        },
+      },
+    },
+    code: 'const targetPath = args.path || process.cwd(); const resolved = path.resolve(targetPath); const { execSync } = require("child_process"); const output = execSync(`ls -la "${resolved}"`, { encoding: "utf8" }); return { status: "ok", path: resolved, output };',
+  },
+  exec: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'exec',
+        description: 'Execute an arbitrary shell command on the server. Returns stdout, stderr, and exit code. Use this for any system operation: running scripts, installing packages, managing files, etc.',
+        parameters: {
+          type: 'object',
+          properties: {
+            cmd: {
+              type: 'string',
+              description: 'The shell command to execute.',
+            },
+          },
+          required: ['cmd'],
+        },
+      },
+    },
+    code: 'const { execSync } = require("child_process"); try { const stdout = execSync(args.cmd, { encoding: "utf8", timeout: 60000 }); return { status: "ok", exitCode: 0, stdout, stderr: "" }; } catch (e) { return { status: "error", exitCode: e.status || 1, stdout: e.stdout || "", stderr: e.stderr || e.message }; }',
+  },
+  save_user_info: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'save_user_info',
+        description: 'Persist facts about the user (e.g., name, timezone, preferences). Items with the same key are overwritten. Use this whenever the user shares personal information worth remembering.',
+        parameters: {
+          type: 'object',
+          properties: {
+            items: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  key: { type: 'string', description: 'Fact identifier (e.g., "timezone", "name").' },
+                  value: { type: 'string', description: 'The fact value.' },
+                },
+                required: ['key', 'value'],
+              },
+              description: 'Array of key-value facts to save.',
+            },
+          },
+          required: ['items'],
+        },
+      },
+    },
+    code: `const filePath = path.join(process.env.HOME, '.jarvis/data/user-info.json'); const raw = await fs.promises.readFile(filePath, 'utf8').catch(() => '{"items":[]}'); const data = JSON.parse(raw); const items = args.items || []; for (const item of items) { const idx = data.items.findIndex(i => i.key === item.key); const entry = { key: item.key, value: item.value, ts: new Date().toISOString() }; if (idx >= 0) data.items[idx] = entry; else data.items.push(entry); } await fs.promises.mkdir(path.dirname(filePath), { recursive: true }); await fs.promises.writeFile(filePath, JSON.stringify(data, null, 2), 'utf8'); return { status: 'ok', saved: items.length };`,
+  },
+  read_user_info: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'read_user_info',
+        description: 'Read all stored user facts. Returns the full list of known user information. Use this when you need to recall something about the user.',
+        parameters: {
+          type: 'object',
+          properties: {},
+          required: [],
+        },
+      },
+    },
+    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 };`,
+  },
+  get_recent_sessions: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'get_recent_sessions',
+        description: 'Returns the most recent sessions with their titles and timestamps. Use this to find previous conversations.',
+        parameters: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Number of recent sessions to return. Defaults to 2.',
+            },
+          },
+          required: [],
+        },
+      },
+    },
+    code: `const logsDir = path.join(process.env.HOME, '.jarvis/logs'); const limit = args.limit || 2; const files = await fs.promises.readdir(logsDir).catch(() => []); const sessionFiles = files.filter(f => f.startsWith('session-') && f.endsWith('.jsonl')); const sessions = []; for (const file of sessionFiles) { const sessionId = file.replace('session-', '').replace('.jsonl', ''); const content = await fs.promises.readFile(path.join(logsDir, file), 'utf8'); const lines = content.trim().split('\\n').filter(Boolean); if (lines.length === 0) continue; const firstEntry = JSON.parse(lines[0]); const lastEntry = JSON.parse(lines[lines.length - 1]); sessions.push({ sessionId, title: (firstEntry.logSummary || '').substring(0, 80), lastTs: lastEntry.ts }); } sessions.sort((a, b) => new Date(b.lastTs) - new Date(a.lastTs)); return { status: 'ok', sessions: sessions.slice(0, limit) };`,
+  },
+  read_session_log: {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'read_session_log',
+        description: 'Read JSONL log entries for a given session. Use this to inspect what happened in a previous run, including tool calls, errors, and summaries.',
+        parameters: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'The session ID to read logs for.',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of entries to return (from the end). Defaults to 20.',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+    },
+    code: `const logsDir = path.join(process.env.HOME, '.jarvis/logs'); const logFile = path.join(logsDir, 'session-' + args.sessionId + '.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 };`,
+  },
+};
+
+export function seedTools() {
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(PATHS.toolsFile, 'utf8'));
+  } catch {
+    // File doesn't exist yet
+  }
+
+  let changed = false;
+  for (const [name, tool] of Object.entries(SEED_TOOLS)) {
+    if (!existing[name]) {
+      existing[name] = tool;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    fs.mkdirSync(PATHS.toolsDir, { recursive: true });
+    fs.writeFileSync(PATHS.toolsFile, JSON.stringify(existing, null, 2), 'utf8');
+  }
+
+  return existing;
+}
+
+export function loadTools() {
+  try {
+    return JSON.parse(fs.readFileSync(PATHS.toolsFile, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function getToolDefinitions(tools) {
+  return Object.values(tools).map(t => t.definition);
+}
+
+export async function executeTool(tools, name, toolArgs) {
+  const tool = tools[name];
+  if (!tool) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+
+  const fn = new AsyncFunction('args', 'fs', 'path', 'process', 'require', tool.code);
+  return await fn(toolArgs, fs, path, process, _require);
+}