@ducci/jarvis 1.0.63 → 1.0.65

package/README.md

@@ -1,121 +1,86 @@
 # 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.
+A self-hosted AI agent that runs as a background server. Chat with it via a web UI or Telegram, give it tools to run shell commands and manage files, and schedule recurring tasks — all powered by any model on OpenRouter, z.ai, or the Anthropic API.
 
-## Docs
+## Features
+
+- **Agent loop** — runs tools autonomously, hands off to a fresh context when it hits the iteration limit, and keeps going until the task is done
+- **Web UI** — built-in chat interface served at `http://localhost:18008`
+- **Telegram** — optional channel adapter; chat from your phone, send photos, get proactive notifications
+- **Cron scheduler** — schedule recurring or one-time tasks in plain English; agent runs them autonomously and can notify you via Telegram
+- **Skills** — Markdown-defined workflows the agent discovers and follows for specific task types
+- **Custom tools** — define tools in JSON (name, description, JS code); the agent picks them up without a restart
+- **Multi-provider** — OpenRouter, z.ai, or Anthropic directly (with prompt caching)
+- **Persistent sessions** — full conversation history per session, sliding context window
 
-- 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
+## Quick start
 
 ```
-npm install
-npm run setup
+npm i -g @ducci/jarvis
+jarvis setup       # configure API key, model, and optionally Telegram
+jarvis start       # start the background server (auto-restarts on crash)
 ```
 
-This prompts for your OpenRouter API key and model selection.
-
-### Running in production (background via PM2)
+Open `http://localhost:18008` to use the chat UI.
 
 ```
-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
+jarvis stop        # stop the server
+jarvis status      # show PID, uptime, restart count
 ```
 
-The server runs on port `18008`. Open `http://localhost:18008` to use the chat UI.
+## Recommended models
 
-Logs are written to `~/.jarvis/logs/server.log`.
+Any OpenRouter model works, but here's what's worth trying right now:
 
-### Running in development (foreground)
+| Model | Provider | Notes |
+|---|---|---|
+| `glm-5` | [z.ai](https://z.ai) directly | Personal pick — strong at coding and tool use, great value |
 
-```
-npm run dev        # start the server with nodemon (auto-reload on file changes)
-```
+**z.ai tip**: z.ai offers a "Coding Plan Pro" subscription that gives you direct, high-rate access to GLM-5. If you do a lot of agentic coding tasks, it's worth it. Run `jarvis setup` and select z.ai as your provider — it will configure the endpoint and model automatically.
 
-To develop the UI with hot-reload:
+Fallback recommendation: set `fallbackModel` to `openrouter/auto` in `settings.json` so failed requests automatically retry on a capable free model.
 
-```
-cd ui
-npm install        # first time only
-npm run dev        # starts Vite on port 5173, proxies /api to localhost:18008
-```
+## Docs
 
-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.
+- [Setup and configuration](./docs/setup.md)
+- [CLI and server lifecycle](./docs/cli.md)
+- [Agent system](./docs/agent.md)
+- [Telegram channel](./docs/telegram.md)
+- [Cron scheduler](./docs/crons.md)
+- [Skills](./docs/skills.md)
+- [Identity and persona](./docs/identity.md)
+- [UI](./docs/ui.md)
 
-### Building the UI for production
+## Development
 
 ```
-cd ui
-npm run build
+npm run dev        # start server with nodemon (auto-reload)
 ```
 
-This outputs to `ui/dist/`, which the Express server serves as static files automatically.
+For UI hot-reload, run both the server and the Vite dev server:
+
+```
+npm run dev        # server on :18008
+cd ui && npm install && npm run dev   # UI on :5173, proxies /api to :18008
+```
 
-### Global install
+Build the UI for production:
 
 ```
-npm i -g @ducci/jarvis
-jarvis setup
-jarvis start
-jarvis stop
-jarvis status
+cd ui && npm run build   # outputs to ui/dist/, served automatically by the server
 ```
 
-## Security & Local Usage
+## Security
+
+Jarvis is designed for **local or private server use only**. The API has no authentication — do not expose port `18008` to the public internet. The `exec` tool runs shell commands with the same permissions as the server process.
+
+## Data
 
-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.
+All runtime data lives in `~/.jarvis/` and is never stored in the repo:
 
-## 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
+- `~/.jarvis/.env` — API keys
+- `~/.jarvis/data/config/settings.json` — model, port, channel config
+- `~/.jarvis/data/conversations/` — session history
+- `~/.jarvis/data/tools/tools.json` — tool registry
+- `~/.jarvis/data/skills/` — skill definitions
+- `~/.jarvis/logs/` — per-session JSONL logs, cron logs, PM2 stdout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.63",
+  "version": "1.0.65",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",
@@ -30,6 +30,10 @@
     "cli",
     "server"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duc-gp/-ducci-jarvis.git"
+  },
   "author": "ducci",
   "engines": {
     "node": ">=18"

package/src/channels/telegram/index.js

@@ -58,6 +58,11 @@ export async function startTelegramChannel(config) {
   const bot = new Bot(token);
   const sessions = load();
 
+  // Tracks chats with an active agent run and buffers messages arriving during that run.
+  // When the run finishes all buffered messages are merged into one combined run.
+  const isRunning = new Set();
+  const pendingMessages = new Map(); // chatId -> [{text, attachments, ts}]
+
   await bot.api.setMyCommands([
     { command: 'new', description: 'Start a fresh session' },
     { command: 'usage', description: 'Show token usage for the current session' },
@@ -97,6 +102,7 @@ export async function startTelegramChannel(config) {
     if (!allowedUserIds.includes(userId)) return;
 
     const chatId = ctx.chat.id;
+    pendingMessages.delete(chatId);
     if (sessions[chatId]) {
       await appendTelegramChatLog(chatId, sessions[chatId], 'SYSTEM', '--- /new: session reset ---');
       delete sessions[chatId];
@@ -107,22 +113,74 @@ export async function startTelegramChannel(config) {
     await ctx.reply('New session started.');
   });
 
+  // Runs one or more batches until the pending queue is drained.
+  // Each iteration takes all currently pending messages, merges them into a
+  // single user turn, calls handleChat once, and sends one response.
+  async function processQueue(api, chatId, firstBatch) {
+    let batch = firstBatch;
+    while (batch.length > 0) {
+      const sessionId = sessions[chatId] || null;
+      const combinedText = batch.length === 1
+        ? batch[0].text
+        : batch.map(m => m.text).join('\n\n');
+      const allAttachments = batch.flatMap(m => m.attachments);
+
+      let result;
+      try {
+        result = await handleChat(config, sessionId, combinedText, allAttachments);
+      } catch (e) {
+        console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
+        const errText = e.message
+          ? `Sorry, something went wrong: ${e.message}`
+          : 'Sorry, something went wrong. Please try again.';
+        await api.sendMessage(chatId, errText).catch(() => {});
+        batch = pendingMessages.get(chatId) || [];
+        pendingMessages.delete(chatId);
+        continue;
+      }
+
+      if (!sessions[chatId]) {
+        sessions[chatId] = result.sessionId;
+        save(sessions);
+        console.log(`[telegram] session created sessionId=${result.sessionId.slice(0, 8)}`);
+      }
+
+      // Log each original message individually with its own timestamp
+      for (const m of batch) {
+        await appendTelegramChatLog(chatId, result.sessionId, 'USER', m.text || '[photo]', m.ts);
+      }
+
+      try {
+        const rawResponse = typeof result.response === 'string'
+          ? result.response
+          : result.response != null ? JSON.stringify(result.response, null, 2) : '';
+        const text = rawResponse.trim()
+          || 'The agent encountered an error and could not produce a response. Please try again.';
+        await appendTelegramChatLog(chatId, result.sessionId, 'JARVIS', text);
+        await sendMessage(api, chatId, text, result.sessionId);
+        console.log(`[telegram] response sent chat_id=${chatId} length=${text.length}`);
+      } catch (e) {
+        console.error(`[telegram] delivery error chat_id=${chatId}: ${e.message}`);
+        await api.sendMessage(chatId, 'Sorry, something went wrong sending the response. Please try again.').catch(() => {});
+      }
+
+      // Drain any messages that arrived while we were running
+      batch = pendingMessages.get(chatId) || [];
+      pendingMessages.delete(chatId);
+    }
+  }
+
   bot.on('message:photo', async (ctx) => {
     const userId = ctx.from?.id;
     if (!allowedUserIds.includes(userId)) return;
 
     const chatId = ctx.chat.id;
-    const sessionId = sessions[chatId] || null;
+    const ts = new Date().toISOString();
 
     console.log(`[telegram] incoming photo chat_id=${chatId}`);
 
-    await ctx.api.sendChatAction(chatId, 'typing');
-    const typingInterval = setInterval(() => {
-      ctx.api.sendChatAction(chatId, 'typing').catch(() => {});
-    }, 4000);
-
-    const userTs = new Date().toISOString();
-    let result;
+    // Download the photo first regardless of whether we buffer or run immediately
+    let attachment;
     try {
       const photo = ctx.message.photo.filter(p => p.width <= 800).at(-1)
         ?? ctx.message.photo[0];
@@ -131,42 +189,33 @@ export async function startTelegramChannel(config) {
       const imgResponse = await fetch(fileUrl);
       const buffer = await imgResponse.arrayBuffer();
       const base64 = Buffer.from(buffer).toString('base64');
-      const dataUrl = `data:image/jpeg;base64,${base64}`;
-      const caption = ctx.message.caption || '';
-      result = await handleChat(config, sessionId, caption, [{ url: dataUrl }]);
+      attachment = { url: `data:image/jpeg;base64,${base64}` };
     } catch (e) {
-      console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
-      const errText = e.message
-        ? `Sorry, something went wrong: ${e.message}`
-        : 'Sorry, something went wrong. Please try again.';
-      await ctx.reply(errText).catch(() => {});
-      clearInterval(typingInterval);
+      console.error(`[telegram] photo download error chat_id=${chatId}: ${e.message}`);
+      await ctx.reply('Sorry, could not process the photo.').catch(() => {});
       return;
     }
 
-    if (!sessions[chatId]) {
-      sessions[chatId] = result.sessionId;
-      save(sessions);
-      console.log(`[telegram] session created sessionId=${result.sessionId.slice(0, 8)}`);
+    const entry = { text: ctx.message.caption || '', attachments: [attachment], ts };
+
+    if (isRunning.has(chatId)) {
+      if (!pendingMessages.has(chatId)) pendingMessages.set(chatId, []);
+      pendingMessages.get(chatId).push(entry);
+      console.log(`[telegram] buffered photo chat_id=${chatId} pending=${pendingMessages.get(chatId).length}`);
+      return;
     }
 
-    const captionText = ctx.message.caption || '[photo]';
-    await appendTelegramChatLog(chatId, result.sessionId, 'USER', `[photo] ${captionText}`, userTs);
+    isRunning.add(chatId);
+    await ctx.api.sendChatAction(chatId, 'typing');
+    const typingInterval = setInterval(() => {
+      ctx.api.sendChatAction(chatId, 'typing').catch(() => {});
+    }, 4000);
 
     try {
-      const rawResponse = typeof result.response === 'string'
-        ? result.response
-        : result.response != null ? JSON.stringify(result.response, null, 2) : '';
-      const text = rawResponse.trim()
-        || 'The agent encountered an error and could not produce a response. Please try again.';
-      await appendTelegramChatLog(chatId, result.sessionId, 'JARVIS', text);
-      await sendMessage(ctx.api, chatId, text, result.sessionId);
-      console.log(`[telegram] response sent chat_id=${chatId} length=${text.length}`);
-    } catch (e) {
-      console.error(`[telegram] delivery error chat_id=${chatId}: ${e.message}`);
-      await ctx.api.sendMessage(chatId, 'Sorry, something went wrong sending the response. Please try again.').catch(() => {});
+      await processQueue(ctx.api, chatId, [entry]);
     } finally {
       clearInterval(typingInterval);
+      isRunning.delete(chatId);
     }
   });
 
@@ -177,53 +226,28 @@ export async function startTelegramChannel(config) {
     if (!allowedUserIds.includes(userId)) return;
 
     const chatId = ctx.chat.id;
-    const sessionId = sessions[chatId] || null;
+    const ts = new Date().toISOString();
+    const entry = { text: ctx.message.text, attachments: [], ts };
 
-    console.log(`[telegram] incoming chat_id=${chatId}`);
+    if (isRunning.has(chatId)) {
+      if (!pendingMessages.has(chatId)) pendingMessages.set(chatId, []);
+      pendingMessages.get(chatId).push(entry);
+      console.log(`[telegram] buffered message chat_id=${chatId} pending=${pendingMessages.get(chatId).length}`);
+      return;
+    }
 
+    isRunning.add(chatId);
+    console.log(`[telegram] incoming chat_id=${chatId}`);
     await ctx.api.sendChatAction(chatId, 'typing');
     const typingInterval = setInterval(() => {
       ctx.api.sendChatAction(chatId, 'typing').catch(() => {});
     }, 4000);
 
-    const userTs = new Date().toISOString();
-    let result;
-    try {
-      result = await handleChat(config, sessionId, ctx.message.text);
-    } catch (e) {
-      console.error(`[telegram] agent error chat_id=${chatId}: ${e.message}`);
-      const errText = e.message
-        ? `Sorry, something went wrong: ${e.message}`
-        : 'Sorry, something went wrong. Please try again.';
-      await ctx.reply(errText).catch(() => {});
-      clearInterval(typingInterval);
-      return;
-    }
-
-    // Persist new session mapping on first message
-    if (!sessions[chatId]) {
-      sessions[chatId] = result.sessionId;
-      save(sessions);
-      console.log(`[telegram] session created sessionId=${result.sessionId.slice(0, 8)}`);
-    }
-
-    await appendTelegramChatLog(chatId, result.sessionId, 'USER', ctx.message.text, userTs);
-
     try {
-      // Guard against empty or non-string response (e.g. model returns array instead of string)
-      const rawResponse = typeof result.response === 'string'
-        ? result.response
-        : result.response != null ? JSON.stringify(result.response, null, 2) : '';
-      const text = rawResponse.trim()
-        || 'The agent encountered an error and could not produce a response. Please try again.';
-      await appendTelegramChatLog(chatId, result.sessionId, 'JARVIS', text);
-      await sendMessage(ctx.api, chatId, text, result.sessionId);
-      console.log(`[telegram] response sent chat_id=${chatId} length=${text.length}`);
-    } catch (e) {
-      console.error(`[telegram] delivery error chat_id=${chatId}: ${e.message}`);
-      await ctx.api.sendMessage(chatId, 'Sorry, something went wrong sending the response. Please try again.').catch(() => {});
+      await processQueue(ctx.api, chatId, [entry]);
     } finally {
       clearInterval(typingInterval);
+      isRunning.delete(chatId);
     }
   });