@ducci/jarvis 1.0.63 → 1.0.64

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.64",
   "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"