@ducci/jarvis 1.0.6 → 1.0.7

package/docs/agent.md

@@ -0,0 +1,525 @@
+# Agent System
+
+This document defines the v1 agent loop, tool handling, and logging. It is intended as the implementation source of truth.
+
+## Goals
+
+- Simple request/response flow (no streaming)
+- Serial tool execution for predictable behavior
+- Clear, minimal logs that explain what happened
+
+## Core Loop (v1)
+
+1. Build a request from the current conversation state and system prompt.
+2. Send a single model request.
+3. If the model returns no tool calls, return the response and stop.
+4. If the model returns tool calls:
+   - Execute tools in order, serially (no parallel execution).
+   - Capture each tool result or error.
+   - Send one follow-up model request that includes the tool results.
+5. Repeat step 3-4 until no tools are requested or the **max iteration limit** is reached.
+
+**Iteration Limit & Handoff**: The default limit is **10 iterations**. If the limit is reached before the task is complete, the server triggers a dedicated wrap-up call:
+
+1. The server appends a one-time, non-stored system note to the conversation and sends one extra model request (does not count toward the iteration limit):
+
+```
+[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.]
+```
+
+2. The server reads `checkpoint.remaining` from the response and uses it as the starting prompt for a fresh agent run.
+3. The server marks the run status as `checkpoint_reached`.
+
+- **Handoff Cap**: To prevent infinite autonomous loops, the server tracks consecutive handoffs in the session `metadata`. If `handoffCount` exceeds `maxHandoffs` (default 5), the server stops and marks the status as `intervention_required` instead of starting a new run.
+- **Handoff Reset**: `handoffCount` resets to `0` whenever the server receives a new user message for that session, since this implies human review.
+
+**Completion Logic**: The agent stops when the model returns a final text response instead of tool calls. This response is then returned to the client as the final answer.
+
+Tool calls use the provider tool-calling API for reliability. The final user-facing response is structured JSON so we can store a human-readable summary without an extra call.
+
+Notes:
+
+- The loop is bounded (default 10 iterations) to avoid runaway behavior and context bloat.
+- If a tool fails, its error is recorded and the model still receives the error result.
+
+## Triggering and Execution
+
+Jarvis runs only when explicitly triggered. In v1, a run starts when a user sends a message to the `POST /api/chat` endpoint. Each user message creates a single agent run:
+
+1. Receive the user message and `sessionId`.
+2. **Session Lookup**: Load the full conversation history for the `sessionId` from `~/.jarvis/data/conversations/<sessionId>.json`. If the session doesn't exist, initialize a new history with the system prompt.
+3. **User Info Injection**: Before sending to the model, replace the `{{user_info}}` placeholder in the system prompt with the current contents of `user-info.json`. If no user info exists, replace with `(none yet)`. This resolved system prompt is sent to the model but never written back to disk — the placeholder is always preserved in the stored history.
+4. **Append Message**: Append the new user message to the loaded history.
+5. **Execute Core Loop**: Run the agent loop using the full conversation history.
+6. **Return Response**: Return the final response and log the summary.
+7. **Persistence**: Save the updated history (including any tool calls/results) back to disk.
+
+There are no automatic background runs unless we add a scheduler later.
+
+## Entry Points (v1)
+
+Jarvis accepts messages only via HTTP:
+
+- `POST /api/chat` with a JSON body
+
+Port: `18008` (default)
+
+Request contract (v1):
+
+```json
+{
+  "sessionId": "string (optional)",
+  "message": "string"
+}
+```
+
+**Notes on Request**:
+- The client sends only the **latest** message.
+- The server is responsible for maintaining and loading the full history via the `sessionId`.
+- `sessionId` is optional. If omitted, the server creates a new session and generates a UUID v4 session ID via `crypto.randomUUID()`.
+- If a `sessionId` is provided, the server loads the existing session. If no session is found for that ID, a new one is created.
+
+Response contract (v1):
+
+```json
+{
+  "sessionId": "string",
+  "response": "string",
+  "logSummary": "string",
+  "toolCalls": [
+    {
+      "name": "string",
+      "args": {},
+      "status": "ok | error",
+      "result": "string"
+    }
+  ]
+}
+```
+
+`toolCalls` is an array of all tool calls made during the run, in execution order. It is always present (empty array if no tools were called). The data is already collected during the agent loop for JSONL logging, so this adds no extra work.
+
+The `sessionId` is always returned so the client can use it for follow-up messages. On the first message (no `sessionId` sent), the client must read this value and store it to continue the session.
+
+**Channel adapter pattern**: External channels (e.g. a Telegram bot) act as thin adapters. They store a mapping of their own identifier (e.g. Telegram `chat_id`) to a Jarvis `sessionId`. On the first message they omit `sessionId` and store the one returned; on subsequent messages they pass it through. This keeps session management centralized on the server — no adapter needs to implement its own ID generation or session logic.
+
+Error responses:
+
+- `400 Bad Request` for invalid input
+- `500 Internal Server Error` for runtime failures
+
+```json
+{
+  "error": "string",
+  "status": "model_error | format_error | tool_failed"
+}
+```
+
+Interaction flow:
+
+1. Client sends `POST /api/chat` with an optional `sessionId` and a `message`.
+2. Server creates or loads the session, then runs the agent loop.
+3. Server returns `sessionId`, `response`, and `logSummary` as JSON.
+4. Server appends a JSONL log entry for the run.
+
+## System Prompt (v1)
+
+The authoritative system prompt text lives in [docs/system-prompt.md](./system-prompt.md). It is sent as the first message (`role: "system"`) in every session and stored verbatim in the conversation history.
+
+## Tools
+
+All tools — built-in and user-defined — live in a single registry file (`tools.json`) and are executed via the same `new Function()` path. There is no separate execution mechanism for built-ins.
+
+**Built-in tools** (seeded into `tools.json` on first server start if missing):
+
+- `get_recent_sessions` — returns the most recent sessions (default: last 2, configurable via `limit`)
+- `read_session_log` — returns JSONL log entries for a given session; the agent-accessible way to inspect failures and previous run summaries
+- `save_user_info` — persists user facts to `user-info.json`
+- `read_user_info` — returns all stored user facts
+- `exec` — runs arbitrary shell commands as the server user; no safeguards
+
+If a built-in entry is missing from `tools.json` at startup, the server re-seeds it from its default definition. This means built-ins can be inspected and edited in place, and will be restored if accidentally deleted.
+
+Tools are powerful (file access, network, shell) and run with the same permissions as the server.
+
+## Tool Registry Format
+
+Jarvis uses the same simple tool registry pattern as dai: a JSON file that maps tool names to `definition` and `code`.
+
+Path:
+
+- `~/.jarvis/data/tools/tools.json`
+
+Schema example:
+
+```json
+{
+  "read_user_info": {
+    "definition": {
+      "type": "function",
+      "function": {
+        "name": "read_user_info",
+        "description": "Read all stored user facts.",
+        "parameters": { "type": "object", "properties": {}, "required": [] }
+      }
+    },
+    "code": "const raw = await fs.promises.readFile(path.join(process.env.HOME, '.jarvis/data/user-info.json'), 'utf8').catch(() => '{\"items\":[]}'); const { items } = JSON.parse(raw); return { status: 'ok', items };"
+  }
+}
+```
+
+At runtime, the server loads each tool and compiles `code` into an async function using `new Function('args', 'fs', 'path', 'process', 'require', code)`, called as `fn(args, fs, path, process, require)`.
+
+**Tool descriptions are critical.** The system prompt does not list available tools — the model discovers them exclusively via the `tools` field in each API request. The `description` field in every tool definition is therefore the only guidance the model has for deciding when and how to use a tool. Descriptions must be specific about the tool's purpose, when to call it, and what its output means.
+
+**Concurrency**: The server supports concurrent sessions. While tools are executed serially *within* a single run, multiple sessions can be processed in parallel by the server.
+
+Seed tool included for sanity checks:
+
+- `list_dir`
+  - Purpose: list directory contents similar to `ls -la`
+  - Input: `{ "path": "." }` (optional; defaults to current working directory)
+  - Output should include the resolved path that was actually listed
+
+## Tool Call Contract
+
+Jarvis uses the provider tool-calling API:
+
+1. The model returns an assistant message containing a `tool_calls` array.
+2. Jarvis appends that assistant message to the conversation history as-is.
+3. Jarvis executes those tools in order, serially.
+4. Each tool result is appended to the conversation as a `role: "tool"` message with a matching `tool_call_id`.
+5. Jarvis calls the model again with the updated conversation.
+6. When no tool calls are returned, the model must respond with JSON `{ response, logSummary }`.
+
+Assistant message shape (appended to history when the model requests tools):
+
+```json
+{
+  "role": "assistant",
+  "content": null,
+  "tool_calls": [
+    {
+      "id": "call_abc123",
+      "type": "function",
+      "function": {
+        "name": "tool_name",
+        "arguments": "{\"key\":\"value\"}"
+      }
+    }
+  ]
+}
+```
+
+Tool result message shape (appended to history after execution):
+
+```json
+{
+  "role": "tool",
+  "tool_call_id": "call_abc123",
+  "content": "{\"status\":\"ok\",\"result\":\"...\"}"
+}
+```
+
+The `tool_call_id` in the tool message must match the `id` of the corresponding entry in the assistant's `tool_calls` array. Without this pairing, the provider will reject the request.
+
+## Tool Argument Validation
+
+Jarvis does not validate tool arguments against schemas in v1. Tool code receives the raw args and is responsible for handling missing or invalid inputs.
+
+## Exec Tool
+
+`exec` runs a shell command as the server user with no safeguards.
+
+Input:
+
+```json
+{ "cmd": "string" }
+```
+
+Output (stringified JSON in tool message content):
+
+```json
+{
+  "status": "ok" | "error",
+  "exitCode": 0,
+  "stdout": "...",
+  "stderr": "..."
+}
+```
+
+## Conversation Storage
+
+Full conversation history is stored per session ID so the agent can keep context across messages. This is separate from the human log.
+
+Path:
+
+- `~/.jarvis/data/conversations/<sessionId>.json`
+
+To support persistent tracking (like `handoffCount`), each file contains a JSON object with `metadata` and an ordered list of `messages`:
+
+```json
+{
+  "metadata": {
+    "handoffCount": 0,
+    "createdAt": "...",
+    "updatedAt": "..."
+  },
+  "messages": [
+    { "role": "system", "content": "..." },
+    { "role": "user", "content": "What do you know about me?" },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        {
+          "id": "call_abc123",
+          "type": "function",
+          "function": { "name": "read_user_info", "arguments": "{}" }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_abc123",
+      "content": "{\"status\":\"ok\",\"items\":[]}"
+    },
+    {
+      "role": "assistant",
+      "content": "{\"response\":\"...\",\"logSummary\":\"...\"}"
+    }
+  ]
+}
+```
+
+The system prompt is stored as the first message in the `messages` array. The full turn sequence — user → assistant (with tool_calls) → tool → assistant (final) — is stored verbatim so that subsequent requests can be sent to the provider without any transformation.
+
+## Provider Message Format
+
+When sending the conversation to OpenRouter, messages must follow the OpenAI-compatible chat format.
+
+Example tool-call flow:
+
+**Step 1 — Initial request:**
+
+```json
+{
+  "model": "openrouter/model-name",
+  "messages": [
+    { "role": "system", "content": "..." },
+    { "role": "user", "content": "What do you know about me?" }
+  ]
+}
+```
+
+**Step 2 — Provider response (contains tool call):**
+
+```json
+{
+  "role": "assistant",
+  "content": null,
+  "tool_calls": [
+    {
+      "id": "call_abc123",
+      "type": "function",
+      "function": {
+        "name": "read_user_info",
+        "arguments": "{}"
+      }
+    }
+  ]
+}
+```
+
+**Step 3 — Follow-up request (after tool execution):**
+
+Jarvis appends the assistant message from Step 2 and then the tool result to the history and sends:
+
+```json
+{
+  "model": "openrouter/model-name",
+  "messages": [
+    { "role": "system", "content": "..." },
+    { "role": "user", "content": "What do you know about me?" },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        {
+          "id": "call_abc123",
+          "type": "function",
+          "function": { "name": "read_user_info", "arguments": "{}" }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_abc123",
+      "content": "{\"status\":\"ok\",\"items\":[{\"key\":\"timezone\",\"value\":\"Europe/Berlin\"}]}"
+    }
+  ]
+}
+```
+
+**Step 4 — Final model response (JSON):**
+
+```json
+{
+  "response": "I know your timezone is Europe/Berlin.",
+  "logSummary": "Read user info and reported timezone."
+}
+```
+
+Internal flow summary:
+
+1. Send request to provider.
+2. Receive assistant message — if it contains `tool_calls`, append it to the conversation history.
+3. Execute tool calls locally, in order.
+4. Append each tool result as a `role: "tool"` message with matching `tool_call_id`.
+5. Call the model again with the updated conversation.
+6. Repeat until no tool calls are returned.
+
+## Logging
+
+We store a minimal, append-only JSONL log per session for human readability. Each line is one request/response cycle.
+
+Path:
+
+- `~/.jarvis/logs/session-<sessionId>.jsonl`
+
+Each log entry includes only the essentials (no full message history). The model provides a concise `logSummary` alongside the user-facing response.
+
+**Logging Philosophy**:
+- **Transparency**: The `logSummary` must be written for a *human observer*. It should explain not just what tools were called, but the reasoning behind them.
+- **Understandability**: A developer should be able to follow the agent's intent and identify where a plan went off-track just by reading the `logSummary` entries.
+
+```json
+{
+  "ts": "2026-02-13T12:34:56.789Z",
+  "sessionId": "abc123",
+  "iteration": 1,
+  "model": "openrouter/model-name",
+  "userInput": "...",
+  "toolCalls": [
+    {
+      "name": "tool_name",
+      "args": { "key": "value" },
+      "status": "ok",
+      "result": "..."
+    }
+  ],
+  "response": "...",
+  "logSummary": "...",
+  "status": "ok"
+}
+```
+
+Status values:
+
+- `ok`: normal completion
+- `tool_failed`: at least one tool failed
+- `model_error`: model request failed
+- `checkpoint_reached`: max iterations hit; task handed off or paused
+- `intervention_required`: max handoffs reached; human input needed to proceed
+- `format_error`: malformed JSON response
+
+This log is meant to be readable without digging through raw prompts.
+
+Tool inputs/outputs:
+
+- `read_session_log`
+  - Input: `{ "sessionId": "string", "limit": 20 }`
+  - Output: `{ "status": "ok", "entries": [...] }`
+
+## Error Handling and Retries
+
+- Model call failures: try the selected model once, then one fallback model attempt. If both fail, end the run with a `500` error and a clear message.
+- Tool failures: pass the error result back to the model and continue the loop. Best case would be that the next model response include another tool call to fix the previous tool call. All tool errors (especially `exec` failures) must be reported in the `logSummary` with enough detail for a human to understand the cause.
+- Malformed JSON on final response: log the failure and stop the run with a formatted error message.
+
+**Error Payload Structure**:
+
+```json
+{
+  "error": "Short, human-readable description of the error",
+  "details": "Optional stack trace or additional context"
+}
+```
+
+- Use `400 Bad Request` for invalid client inputs.
+- Use `500 Internal Server Error` for API failures, tool runtime errors, or model communication issues.
+- Always append a log entry on failure so the outcome is visible in the session log.
+
+Model configuration:
+
+- Selected model ID is stored in the same config file created during setup.
+- If the first model call fails, retry once using `fallbackModel`.
+
+Config file:
+
+- `~/.jarvis/data/config/settings.json`
+
+Schema:
+
+```json
+{
+  "selectedModel": "openrouter/...",
+  "fallbackModel": "openrouter/free"
+}
+```
+
+## Limits and Timeouts
+
+- Max iterations per run: 10 (default).
+- `checkpoint_reached` status is used when the limit is hit to trigger a handoff.
+- **Handoff Safety**: `maxHandoffs` (default 5) limits the number of autonomous restarts for a single user trigger. If reached, status changes to `intervention_required`.
+- No separate wall-clock timeout in v1; iterations are the only limiter.
+- No additional per-run tool-call cap beyond iterations.
+- No token limit enforcement in v1.
+
+## User Info
+
+User info is stored as a small JSON file in the Jarvis data directory: `~/.jarvis/data/user-info.json`. `save_user_info` appends to the collection, and `read_user_info` returns the full set.
+
+Schema:
+
+```json
+{
+  "items": [
+    { "key": "string", "value": "string", "ts": "2026-02-13T12:34:56.789Z" }
+  ]
+}
+```
+
+Tool inputs/outputs:
+
+- `save_user_info`
+  - Input: `{ "items": [{ "key": "string", "value": "string" }] }`
+  - Behavior: overwrite existing items with the same `key` and update `ts`.
+  - Output: `{ "status": "ok", "saved": <number> }`
+
+- `read_user_info`
+  - Input: `{}`
+  - Output: `{ "status": "ok", "items": [...] }`
+
+## Session Titles
+
+Session titles are derived from the first `logSummary` in the session log, truncated for display. `get_recent_sessions` should return these titles alongside session IDs to keep results human-readable.
+
+Tool inputs/outputs:
+
+- `get_recent_sessions`
+  - Input: `{ "limit": 2 }`
+  - Output: `{ "status": "ok", "sessions": [{ "sessionId": "...", "title": "...", "lastTs": "..." }] }`

package/docs/cli.md

@@ -0,0 +1,49 @@
+# CLI and Server Lifecycle
+
+This document specifies the requirements for the `jarvis` CLI and its relationship with the Jarvis server.
+
+## Architectural Separation
+
+Jarvis consists of two distinct components:
+
+1.  **The Server**: The core agent system that handles chat requests, triggers tools, and manages persistent memory.
+2.  **The CLI**: A management tool used for configuration (onboarding) and controlling the server process.
+
+## Global Installation Requirements
+
+The project must be prepared for global installation via `npm i -g`. This requires the `package.json` to define appropriate `bin` entries:
+
+```json
+{
+  "name": "jarvis",
+  "bin": {
+    "jarvis": "./src/index.js",
+    "jarvis-setup": "./src/scripts/onboarding.js"
+  }
+}
+```
+
+## Server Lifecycle Commands
+
+Lifecycle management is handled by the CLI using the **programmatic PM2 API** for process stability and fine-grained control.
+
+### `jarvis start`
+- **Pre-flight Check**: Verifies that `.env` and `settings.json` exist. If missing, it prints an error message ("Please run `jarvis setup` first") and exits with code 1. This prevents PM2 from infinite restart loops when no configuration is present.
+- Starts the server as a background process using the PM2 API.
+- The process is named `jarvis-server`.
+- Enables `autorestart` on crash.
+- Merges logs into a single file in the user's data directory.
+
+### `jarvis stop`
+- Stops the background process named `jarvis-server` using PM2.
+
+### `jarvis status`
+- (Planned) Displays the current status of the `jarvis-server` process.
+
+## Local Development
+
+For development in the repository, the server can be run in the foreground:
+
+### `npm run dev`
+- Starts the server directly without PM2 or daemonization.
+- Uses the same environment loading logic as production.

package/docs/evaluation.md

@@ -0,0 +1,44 @@
+# Evaluation
+
+This document exists so that an AI coding agent (e.g. Claude Code) can evaluate how well Jarvis is working and propose concrete improvements — to the system prompt, tool definitions, or server code.
+
+## How to Use This Document
+
+When asked to evaluate Jarvis, an AI coding agent should:
+
+1. Read the relevant files listed below
+2. Identify signals that indicate problems
+3. Propose specific improvements (to code, `tools.json`, or the system prompt)
+
+The agent should not make changes without user approval.
+
+## Relevant Files
+
+- `~/.jarvis/logs/session-*.jsonl` — one log file per session; each line is one agent run
+- `~/.jarvis/data/tools/tools.json` — all tool definitions and their code
+- `~/.jarvis/data/conversations/*.json` — full conversation histories
+- `docs/system-prompt.md` — the system prompt sent to the model on every session
+
+## What "Good" Looks Like
+
+- Tasks complete within a small number of iterations (well under the limit of 10)
+- `intervention_required` status is rare
+- `checkpoint_reached` status is occasional but not frequent
+- `logSummary` entries are specific and explain reasoning, not just actions
+- Tool errors (`tool_failed`) are rare and the agent recovers from them
+
+## Problem Signals
+
+| Signal | Possible Cause |
+|---|---|
+| Frequent `intervention_required` | Agent loops without making progress; possibly a prompt or tool issue |
+| Frequent `checkpoint_reached` | Tasks are too complex for the iteration limit, or the agent is inefficient |
+| Frequent `tool_failed` | Tool code is broken, or the agent is calling tools with wrong arguments |
+| Vague `logSummary` (e.g. "Called exec.") | System prompt guidance for logSummary is not being followed |
+| Frequent `format_error` | Model is not following the JSON response format; system prompt may need adjustment |
+
+## What Can Be Improved
+
+- **System prompt** (`docs/system-prompt.md`) — if the agent is behaving incorrectly or producing poor logSummaries
+- **Tool definitions** (`~/.jarvis/data/tools/tools.json`) — if tools are failing or their descriptions are causing misuse
+- **Server code** (`src/`) — if there are bugs in the agent loop, error handling, or session management

package/docs/setup.md

@@ -0,0 +1,81 @@
+# Setup and Start
+
+This document is the implementation spec for how Jarvis is configured and started.
+Another LLM should be able to implement the CLI and startup behavior from this alone.
+
+## Dependencies
+
+Jarvis relies on the following key libraries:
+
+- `commander`: CLI framework for handling commands and arguments.
+- `pm2`: For process management and daemonization of the Jarvis server.
+- `dotenv`: To load environment variables from `.env`.
+- `openai`: Official SDK for interacting with the OpenRouter (OpenAI-compatible) API.
+- `inquirer`: For interactive CLI prompts during onboarding.
+- `chalk`: For terminal styling and colored output.
+
+## Commands
+
+### `jarvis setup` (interactive onboarding)
+
+Purpose: collect API key and model selection and persist them on disk.
+
+Behavior:
+
+1. API key step
+   - Read existing `.env` from the Jarvis config directory (see Data Layout).
+   - If `OPENROUTER_API_KEY` exists, prompt to keep or replace.
+   - If missing, prompt for a new key (password input, min length 10).
+   - Write/update `OPENROUTER_API_KEY=...` in `.env`.
+
+2. Model selection step
+   - Read current model from `data/config/settings.json` under key `selectedModel`.
+   - If a model exists, prompt to keep or change it.
+   - If changing, offer two paths:
+     - Manual entry of model ID.
+     - Browse models from OpenRouter:
+       - Fetch `https://openrouter.ai/api/v1/models` with Bearer auth.
+       - Sort models with free models first, then alphabetical.
+       - Show a paginated list (page size ~20).
+
+- Persist the chosen model as `selectedModel` in `data/config/settings.json`.
+- Set `fallbackModel` to `openrouter/free` only if it is not set yet.
+
+Notes:
+
+- The setup command can be run as many times as desired.
+- The setup command must be usable even if the server is not running.
+- For local development without a global install, run the setup script directly
+  (example: `npm run setup` in the server directory).
+
+## Data Layout
+
+Jarvis data is always stored in the user home directory and never in the repo.
+There is no environment variable override for this path.
+
+Base directory:
+
+- `~/.jarvis/`
+
+Within this directory:
+
+- `.env` (OpenRouter API key)
+- `data/`
+  - `config/settings.json`:
+    ```json
+    {
+      "selectedModel": "openrouter/anthropic/claude-3.5-sonnet",
+      "fallbackModel": "openrouter/free",
+      "maxIterations": 10,
+      "maxHandoffs": 5,
+      "port": 18008
+    }
+    ```
+- `logs/`
+  - `server.log`
+
+## First Run Flow
+
+1. User installs Jarvis globally.
+2. User runs `jarvis setup` to configure API keys and model.
+3. User runs `jarvis start` to launch the background server.

package/docs/system-prompt.md

@@ -0,0 +1,53 @@
+# System Prompt (v1)
+
+This is the authoritative system prompt sent to the model at the start of every session. It is stored as the first message (`role: "system"`) in the conversation history.
+
+Before sending to the model, the server replaces the `{{user_info}}` placeholder with the current contents of `user-info.json`. This happens at runtime on every request — the placeholder is never stored in the conversation history.
+
+---
+
+```
+You are Jarvis, a fully autonomous agent running on a local server. You have access to tools and can execute shell commands on the machine you run on.
+
+## Known User Context
+
+{{user_info}}
+
+## Response Format
+
+There are two types of responses depending on whether you need to use tools:
+
+**While using tools**: respond using the tool-calling protocol. No text content is expected or required — your tool calls speak for themselves.
+
+**Final response** (when you have no more tool calls to make): your text content MUST be a JSON object and nothing else:
+
+{
+  "response": "Your message to the user, in plain text.",
+  "logSummary": "A concise explanation of what you did and why, written for a human reading the logs."
+}
+
+Never include markdown code fences, preamble, or any text outside this JSON object. If you cannot complete a task, explain why in the `response` field — still as valid JSON.
+
+## Tool Use
+
+You have access to a set of tools. Each tool has a name and description that tells you what it does and when to use it — read those descriptions carefully.
+
+- Always use a tool to perform an action. Never claim to have done something without actually calling the relevant tool.
+- Call tools one at a time. You will receive the result before deciding on the next step.
+- After a tool call, verify the result before declaring the task done.
+- Stop as soon as the task is complete and verified. Do not do extra work that was not asked for.
+- If a tool fails, record the error in `logSummary` and decide whether to retry with a corrected call or explain the failure to the user.
+- If the user shares personal information, persist it using the appropriate tool.
+- Prefer using tools over making assumptions about the state of the system.
+
+## logSummary Guidelines
+
+The `logSummary` is written for a human observer, not for the user. It must:
+- Explain the reasoning behind tool calls, not just list what was called.
+- Include enough detail that a developer can understand your intent and pinpoint where things went wrong.
+- Report any tool errors with the relevant output (exit code, stderr snippet, etc.).
+
+Example of a bad logSummary: "Called exec."
+Example of a good logSummary: "User asked for their timezone. Found Europe/Berlin in the injected user context. No tool call needed."
+
+```

package/docs/ui.md

@@ -0,0 +1,71 @@
+# UI
+
+A minimal chat interface to interact with the Jarvis agent. The goal is function over form — just enough UI to send messages, read responses, and inspect tool calls.
+
+## Stack
+
+- Vite + React + Tailwind
+- Lives in a `ui/` folder at the project root (separate from server code)
+
+## Layout
+
+Single page, three regions:
+
+1. **Header** — app name ("Jarvis") on the left, "New Session" button on the right
+2. **Message area** — scrollable list of messages, newest at the bottom
+3. **Input area** — textarea + send button, pinned to the bottom
+
+Light mode only. Minimal styling — no shadows, gradients, or animations.
+
+## Message Types
+
+**User message** — right-aligned, plain text.
+
+**Assistant message** — left-aligned. Shows the `response` field from the API.
+
+**Tool call block** — rendered inline inside the assistant turn, above the final response text. Each tool call shows:
+- Tool name
+- Args (JSON, collapsed by default)
+- Status (`ok` or `error`)
+- Result (truncated if long, expandable)
+
+Tool call blocks use a monospace font and a light gray background to visually separate them from chat text.
+
+## Session Management
+
+- On load: no `sessionId` — the first message creates a new session
+- After the first response: store the returned `sessionId` in React state and pass it on every subsequent request
+- "New Session" button: clears messages and resets `sessionId` to null
+
+## API Communication
+
+All requests go to `POST /api/chat` on the same host/port.
+
+Request:
+```json
+{ "sessionId": "string | null", "message": "string" }
+```
+
+Response fields used by the UI: `sessionId`, `response`, `toolCalls`.
+
+`logSummary` is not displayed in the UI.
+
+While waiting for a response, the input is disabled and a simple loading indicator is shown in the message area.
+
+## Development
+
+Vite dev server runs on its default port (5173) and proxies `/api` requests to `http://localhost:18008`. Configure this in `vite.config.js`:
+
+```js
+export default {
+  server: {
+    proxy: {
+      '/api': 'http://localhost:18008'
+    }
+  }
+}
+```
+
+## Production
+
+The server serves the built UI (`ui/dist/`) as static files at `/`. The Express static middleware is added in `src/server/app.js`. No separate process needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducci/jarvis",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A fully automated agent system that lives on a server.",
   "main": "./src/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "docs",
     "ui/dist"
   ],
   "scripts": {