neoagent 2.4.4-beta.9 → 2.5.0

package/README.md

@@ -4,90 +4,97 @@
 
 <h1 align="center">NeoAgent</h1>
 
-<p align="center"><strong>Your agent. Your server. Your rules.</strong></p>
+<p align="center"><strong>A self-hosted AI agent that can keep working after the chat ends.</strong></p>
 
-<p align="center">A self-hosted AI agent that runs as a service, operates Android over ADB, and connects to 15+ messaging platforms while keeping credentials on your server.</p>
+<p align="center">
+  NeoAgent runs as a service on your server. It can use a browser and terminal,
+  control Android devices, connect to your accounts, remember useful context,
+  and run scheduled or event-triggered work.
+</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/neoagent"><img src="https://img.shields.io/npm/v/neoagent?style=flat-square&label=npm" alt="npm version"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-20+-5fa04e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
-  <a href="https://sqlite.org"><img src="https://img.shields.io/badge/SQLite-WAL-003b57?style=flat-square&logo=sqlite&logoColor=white" alt="SQLite"></a>
-  <a href="https://flutter.dev"><img src="https://img.shields.io/badge/Flutter-web%20%2B%20android-02569B?style=flat-square&logo=flutter&logoColor=white" alt="Flutter"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-a855f7?style=flat-square" alt="License"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-20%2B-5fa04e?style=flat-square" alt="Node.js 20 or newer"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-a855f7?style=flat-square" alt="AGPL-3.0 license"></a>
 </p>
 
 <p align="center">
-  <img src="demo.gif" alt="NeoAgent demo" width="100%">
+  <img src="demo.gif" alt="NeoAgent operator interface" width="100%">
 </p>
 
-## Why NeoAgent
-
-| Android that the agent can operate | Credentials that stay server-side |
-| --- | --- |
-| NeoAgent can inspect the UI, take screenshots, tap, swipe, type, launch apps, install APKs, and run `adb shell` against a connected device or emulator. | API keys, OAuth tokens, messaging credentials, history, and runtime data are stored under `~/.neoagent` on the server, never in the client. |
+## 🚀 Install
 
-## Quick Start
-
-Requires Node.js 20 or newer.
+NeoAgent supports macOS and Linux hosts. You need Node.js 20 or newer; the
+installer handles the rest of the application setup and attempts to install
+QEMU for the isolated browser and terminal runtime.
 
 ```bash
 npm install -g neoagent
 neoagent install
 ```
 
-`neoagent install` checks the host, creates secure runtime configuration,
-installs dependencies and supported system tools, and starts the service. Open
-**http://localhost:3333** when it finishes.
+Open `http://localhost:3333`, create the first account, and configure a model.
+Local models can run through [Ollama](https://ollama.com/); hosted providers
+can be configured in the application.
 
-No hosted-model key is required when using local [Ollama](https://ollama.com/).
-See [Getting Started](docs/getting-started.md) for prerequisites and first-run
-setup.
+Read the [installation guide](docs/getting-started.md) before exposing the
+service to a network.
 
-## What It Does
+## ✨ What makes it different
 
-- **15+ messaging platforms**: Telegram, WhatsApp, Discord, Signal, Slack, Matrix, iMessage, Teams, IRC, LINE, Mattermost, Telnyx Voice, and webhook bridges.
-- **Automation**: cron schedules, integration and weather triggers, reusable skills, MCP tools, and subagents.
-- **Browser and shell**: an isolated browser runtime plus a full PTY terminal on the NeoAgent server.
-- **Integrations**: Google Workspace, Microsoft 365, Notion, Home Assistant, Trello, Spotify, Slack, Figma, GitHub, and more.
-- **Recordings and memory**: audio capture, transcription, transcript search, long-term memory, session history, and health summaries.
-- **Model choice**: Anthropic, OpenAI, Gemini, Grok, MiniMax, NVIDIA NIM, OpenRouter, GitHub Copilot, OpenAI Codex, or local Ollama.
+**It is a service, not just a chat window.** NeoAgent keeps tasks, integrations,
+memory, connected devices, and messaging channels available between sessions.
 
-## Interfaces
+**Memory is stored as structured local data.** Durable facts are separated from
+conversation history, scoped by user and agent, and updated when newer
+information replaces older information. NeoAgent can also index supported
+integration content with source references. See [How memory works](docs/memory.md).
 
-| | | | |
-| --- | --- | --- | --- |
-| <img alt="WebUI" src="https://github.com/user-attachments/assets/3c76d59a-b6e3-4698-929b-9c94741ccf1e" height="420"> | <img height="494" alt="Android" src="https://github.com/user-attachments/assets/e8a0af7a-6881-485d-ad52-f3bc6f2023ca"> | <img alt="Mobile Telegram" src="https://github.com/user-attachments/assets/1fd41a9b-5452-4aa4-9478-888c8ad7363a" height="420"> | <img height="494" alt="image" src="https://github.com/user-attachments/assets/d5a57282-0851-4902-9588-d8de4b82d45c"> |
+**It operates real devices.** The agent can use an isolated browser and shell,
+control an Android device or emulator over ADB, or work through a paired Chrome
+extension and desktop companion.
 
-## Service Commands
+**Automation can start without a message.** Tasks can run on a schedule or from
+supported Gmail, Outlook, Slack, Teams, personal WhatsApp, and weather events.
+Android notifications can also start an agent run.
 
-```bash
-neoagent status
-neoagent start
-neoagent stop
-neoagent restart
-neoagent update
-neoagent fix
-neoagent logs
-```
+**Agents and users have separate state.** Specialist agents can have their own
+memory, settings, tools, account assignments, conversations, and task history.
+Multi-user deployments include administrative account controls and optional
+email confirmation.
 
-## Project Status
+**The same server has several interfaces.** NeoAgent includes web, Android,
+desktop, and Android launcher clients, messaging bridges, a Chrome extension,
+and firmware for a supported ESP32-S3 wearable.
 
-NeoAgent is beta software maintained by one person. Expect rough edges, and
-please report failures with enough detail to reproduce them. Contributions to
-the backend, Flutter clients, integrations, skills, tests, and documentation
-are welcome.
+## 🖥️ Interfaces
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Review
-the documented [security boundaries](docs/security-boundaries.md) before
-installing on a machine with sensitive data. Security issues should be reported
-privately according to [SECURITY.md](SECURITY.md).
+| Operator interface | Memory | Remote devices |
+| --- | --- | --- |
+| ![NeoAgent dashboard](landing/images/dashboard-dark.png) | ![NeoAgent memory view](landing/images/memory-dark.png) | ![NeoAgent device controls](landing/images/remote-devices-dark.png) |
 
-## Documentation
+## 🔎 NeoAgent, OpenClaw, and Hermes
 
-[Docs](https://neolabs-systems.github.io/NeoAgent/) | [Getting Started](docs/getting-started.md) | [Configuration](docs/configuration.md) | [Capabilities](docs/capabilities.md) | [Security Boundaries](docs/security-boundaries.md) | [Skills and MCP](docs/skills.md) | [Operations](docs/operations.md) | [Discussions](https://github.com/NeoLabs-Systems/NeoAgent/discussions) | [Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
+NeoAgent is aimed at people who want a UI-first, self-hosted agent with
+structured local memory, multi-user administration, automation, and direct
+Android control in one installation.
 
----
+OpenClaw has a broader gateway and node ecosystem. Hermes is oriented around a
+terminal-first agent workflow. NeoAgent is a different tradeoff rather than a
+blanket replacement for either project.
 
-<p align="center">
-  Made by <a href="https://github.com/neooriginal">Neo</a> | <a href="https://github.com/NeoLabs-Systems">NeoLabs Systems</a>
-</p>
+The [comparison page](docs/why-neoagent.md) records the concrete differences
+and links to the source material used.
+
+## 🧪 Project status
+
+NeoAgent is beta software maintained primarily by one person. Expect breaking
+changes and rough edges. Review the
+[security boundaries](docs/security-boundaries.md) before connecting sensitive
+accounts or giving the agent access to a personal workstation.
+
+Start with the [documentation](https://neolabs-systems.github.io/NeoAgent/docs/).
+Use [GitHub Discussions](https://github.com/NeoLabs-Systems/NeoAgent/discussions)
+for questions and [GitHub Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
+for reproducible bugs. Security reports belong in the process described by
+[SECURITY.md](SECURITY.md).

package/docs/agent-run-lifecycle.md

@@ -0,0 +1,65 @@
+# Agent run lifecycle
+
+An agent run is the durable execution record for a chat request, scheduled
+task, integration event, messaging event, widget refresh, or delegated job.
+
+## 1. Resolve context
+
+The caller supplies the user, agent, trigger source, conversation, and optional
+model override. The engine resolves the effective agent settings and available
+models, then creates the run record.
+
+The prompt context can include:
+
+- Agent identity and behavior settings
+- Conversation history and working summary
+- Core memory and the auto-maintained user profile
+- Query-specific recalled memory
+- Installed skills
+- Available integrations, MCP tools, and runtime health
+- Platform-specific output guidance
+
+Large history and tool results are compacted before model calls.
+
+## 2. Analyze and select tools
+
+The engine classifies the request as a direct response or an execution task,
+selects a planning depth, and activates a bounded tool catalog. Complex runs
+can produce an execution plan, use subagents, and request a final verification
+pass.
+
+Model selection is scoped to the user and agent. Explicit run or task
+overrides take precedence when the requested model is enabled and available.
+
+## 3. Execute the loop
+
+Each model turn can return text, completion state, or tool calls. Before a tool
+runs:
+
+1. Arguments are normalized.
+2. The `before_tool_call` hooks execute.
+3. Server security policy can deny or suspend the call for approval.
+4. The tool is dispatched to its service or runtime backend.
+5. The result is compacted and appended to the next model turn.
+
+The engine records steps, run events, model usage, timing, and artifacts.
+Repetition guards and loop limits prevent unbounded retries.
+
+## 4. Complete and deliver
+
+The final response is sanitized and stored. Messaging-triggered runs send an
+explicit message or use the final response as a fallback when nothing visible
+was already delivered.
+
+The engine emits `run:complete`, persists prompt and usage metrics, refreshes
+conversation summaries and working state, and cancels unfinished subagents.
+Failures and user stops produce separate terminal run states.
+
+## 5. Post-run processing
+
+Completed conversations can run structured memory consolidation. The engine
+extracts durable candidates, reconciles updates, and invalidates prompt caches
+after memory changes.
+
+The `on_loop_end` hook provides a non-blocking observer for learning and
+analytics. Hook errors cannot change the completed run outcome.

package/docs/agents-and-users.md

@@ -0,0 +1,48 @@
+# Agents and users
+
+NeoAgent separates two concepts:
+
+- A **user** is an account that can sign in to the server.
+- An **agent** is a configured AI identity owned by a user.
+
+## Agents
+
+The main agent is created automatically. Additional agents are managed in the
+operator interface and can be used as specialists.
+
+Each agent has its own conversations, memory, model settings, integrations,
+messaging assignments, tasks, and run history. This separation lets one user
+maintain, for example, a personal agent and a work agent without merging their
+context.
+
+Agents can also be marked for orchestrator use. An orchestrator can delegate
+work to other agents; a normal specialist is intended to complete its assigned
+run directly.
+
+## User accounts
+
+Self-hosted installations can support more than one account. Administrative
+controls include account management, provider configuration, logs, and runtime
+updates.
+
+Optional SMTP configuration enables:
+
+- Signup confirmation
+- Password reset
+- Email-change confirmation
+- New-device or unusual-login notifications
+- Password and account-change notifications
+
+See [Configuration](configuration.md#service-email) for the server variables.
+
+## Isolation model
+
+Application data is scoped by user and, where applicable, agent. The default
+browser and terminal runtime is created per user. Official integration
+credentials remain server-side and are assigned to a particular user and
+agent.
+
+This is application and runtime isolation, not a promise that every capability
+runs inside a VM. Android commands run through ADB on the NeoAgent host, and a
+paired desktop or Chrome profile grants access to that paired machine. Read
+[Security boundaries](security-boundaries.md) before hosting untrusted users.

package/docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+NeoAgent is a Node.js service with Flutter clients. The server owns
+authentication, model access, agent execution, tools, integrations, automation,
+memory, persistence, and real-time state.
+
+## Main components
+
+```text
+Flutter clients and messaging channels
+                |
+        Express + Socket.IO
+                |
+  agents / AI engine / tasks / integrations
+                |
+ runtime backends / SQLite / agent data
+```
+
+### Server
+
+`server/index.js` creates the application and service managers. Express routes
+handle HTTP boundaries and delegate behavior to services. Socket.IO publishes
+run progress, approvals, messages, device state, and operational updates.
+
+The server uses CommonJS. Routes should remain thin; business logic belongs in
+`server/services/`.
+
+### Clients
+
+The Flutter codebase produces the web operator interface, Android client,
+desktop clients, and Android launcher build. `MainController` is the root
+application state object. Platform behavior is implemented through conditional
+bridge files and native Android code where required.
+
+### Persistence
+
+NeoAgent uses one `better-sqlite3` database instance. It stores users, agents,
+settings, conversations, runs, tasks, integration connections, memory,
+recordings, health data, permissions, and operational state.
+
+Runtime files live outside the package source under `NEOAGENT_HOME`. Schema
+changes are applied through the migration layer rather than ad hoc service SQL.
+
+### Execution runtimes
+
+Browser and terminal tools normally use the per-user isolated runtime. A user
+can select a paired Chrome extension for browser work or a paired desktop
+client for shell and desktop control. Android remains a host ADB capability.
+
+## Subsystem guides
+
+- [Agent run lifecycle](agent-run-lifecycle.md)
+- [Memory architecture](memory-architecture.md)
+- [Runtime and tool execution](runtime-and-tools.md)
+- [Agents, automation, and triggers](automation-architecture.md)
+- [Integrations and messaging](integrations-architecture.md)
+- [Clients and device bridges](clients-and-devices.md)
+- [Persistence and migrations](persistence.md)
+- [Development and testing](development.md)

package/docs/automation-architecture.md

@@ -0,0 +1,50 @@
+# Agents, automation, and triggers
+
+Agents, tasks, and runs share a common scope: user ID plus agent ID. A task does
+not create a separate agent context; it invokes the configured agent with
+trigger metadata.
+
+## Agent profiles
+
+The agent manager resolves the selected profile and guarantees a main agent for
+each user. Agent-scoped tables store settings, conversations, memory, runs,
+integration connections, and task ownership.
+
+Orchestrator profiles can delegate work through subagents. Delegated runs keep
+their own execution state while preserving the caller's user and intended
+agent scope.
+
+## Task adapters
+
+The trigger registry loads adapters for:
+
+- recurring and one-time schedules;
+- manual execution;
+- authenticated webhooks;
+- Gmail and Outlook email;
+- Slack and Teams messages;
+- personal WhatsApp messages; and
+- weather events.
+
+Adapters validate and normalize configuration, summarize it for the UI, and
+provide trigger-specific runtime behavior.
+
+## Scheduling and polling
+
+Recurring schedules are registered with `node-cron`. One-time tasks and polled
+integration triggers are checked by runtime pollers. Event-capable integration
+sources can attach listeners when the task runtime starts.
+
+The repository prevents duplicate active executions for the same task and
+records trigger fingerprints so the same external event is not repeatedly
+processed.
+
+## Execution and delivery
+
+The task runtime creates an agent run with trigger context, captures the final
+response, and optionally sends it to a normalized messaging target. Run success
+and delivery success are distinct states.
+
+Notification triggers from the Android client enter through a separate route
+and directly request an agent evaluation; they are not stored schedule
+adapters.

package/docs/automation.md

@@ -1,94 +1,78 @@
-# Automation
+# Automation and triggers
 
-Tasks run on a schedule or integration trigger, use the same tools as chat, and can deliver results through any connected messaging platform.
+Automations run the same agent loop and tools used by chat. They can start on a
+schedule, from a supported account event, or through a webhook, and can deliver
+their result through a configured messaging channel.
 
-## Creating a Task
+## Create a task
 
-Open **Tasks** in the UI and fill in:
+Open **Tasks**, choose the owning agent, select a trigger, and write a
+self-contained instruction. A task can use the agent's model or a task-specific
+override.
 
-| Field | Description |
+The currently implemented trigger families are:
+
+| Trigger | Behavior |
 |---|---|
-| **Name** | Human-readable label |
-| **Cron** | Five-field schedule expression |
-| **Prompt** | Self-contained instruction for the future run |
-| **Enabled** | Active or paused |
-| **Model** | Optional per-task model override |
+| Schedule | Recurring cron expression or one-time timestamp |
+| Gmail | Run when a matching Gmail message is received |
+| Outlook | Run when a matching Outlook message is received |
+| Slack | Run when a matching Slack message is received |
+| Teams | Run when a matching Teams message is received |
+| Personal WhatsApp | Run when a matching personal-account message is received |
+| Weather | Run for configured forecast events such as rain or temperature thresholds |
+| Webhook | Run after an authenticated task webhook request |
 
-## Cron Expressions
+The Android app can also forward device notifications to
+`/api/triggers/notification`. Notification runs are evaluated by the agent and
+are separate from saved tasks.
 
-```
-┌───── minute (0–59)
-│  ┌──── hour (0–23)
-│  │  ┌─── day of month (1–31)
-│  │  │  ┌── month (1–12)
-│  │  │  │  ┌─ day of week (0–7, both 0 and 7 = Sunday)
-│  │  │  │  │
-*  *  *  *  *
+## Schedules
+
+Recurring tasks use five-field cron:
+
+```text
+minute hour day-of-month month day-of-week
 ```
 
-Common patterns:
+Examples:
 
 | Expression | Runs |
 |---|---|
-| `0 9 * * *` | Daily at 9:00 AM |
-| `0 9 * * 1-5` | Weekdays at 9:00 AM |
-| `0 8 * * 1` | Every Monday at 8:00 AM |
-| `0 18 * * 5` | Every Friday at 6:00 PM |
-| `0 9 1 * *` | First of every month at 9:00 AM |
-| `0 */4 * * *` | Every 4 hours |
+| `0 9 * * *` | Every day at 09:00 |
+| `0 9 * * 1-5` | Weekdays at 09:00 |
+| `0 8 * * 1` | Mondays at 08:00 |
 | `*/30 * * * *` | Every 30 minutes |
 
-## Writing Good Task Prompts
+Schedules use the server's configured time context. Confirm the next-run value
+shown in the UI when the server and user are in different time zones.
 
-Prompts run unattended. Be specific about what to check and when to notify — tasks that always send a message become noise, tasks that only notify on a condition are useful.
+## Write unattended instructions
 
-**Daily news digest**
-```
-Search Hacker News for the top 5 stories today. Send me a brief summary of each via Telegram, including the title and link.
-```
+A task prompt must contain enough context to run later without the current chat.
+State what to inspect, what counts as actionable, where to deliver the result,
+and when no message should be sent.
 
-**Price monitor**
-```
-Check the price of Bitcoin and Ethereum on CoinGecko. If either has changed more than 5% in the last 24 hours, send me a Telegram message with the current prices and percentage change. If there are no significant changes, do nothing.
+```text
+Search unread Gmail received since the previous run. Summarize messages that
+need a reply and send the summary to my Telegram chat. Do not send anything
+when no reply is needed.
 ```
 
-**Server health check**
-```
-Run `df -h` and `free -m`. If disk usage on any partition is above 85% or available memory is below 500MB, send me a Telegram alert with the details. Otherwise do nothing.
-```
-
-**Weekly email digest**
-```
-Search my Gmail for unread emails from the last 7 days. Group them by sender domain and summarize the main topics. Send the summary to my Telegram.
-```
+Prefer official integrations or MCP tools over browser automation when both
+can perform the action. Structured tools are easier to restrict and diagnose.
 
-## Tool Access
+## Runs and delivery
 
-Automation can use everything available in chat:
-
-| Capability | Examples |
-|---|---|
-| **Browser** | Navigate, extract content, screenshot, evaluate JavaScript |
-| **CLI** | Shell commands in a persistent terminal |
-| **Files** | Read, write, search host files |
-| **Memory** | Store and retrieve long-term facts |
-| **Messaging** | Send results through any connected platform |
-| **MCP** | Tools from configured remote MCP servers |
-| **Integrations** | Gmail, Calendar, Notion, Slack, and other OAuth tools |
-| **Recordings** | Search and read transcripts |
-| **Health** | Read synced Android Health Connect metrics |
-| **Android** | Control an emulator or device |
-| **Subagents** | Spawn parallel helpers inside a longer run |
-| **Outputs** | Artifacts, images, Mermaid graphs, markdown tables |
-
-Prefer official integrations and MCP tools over browser automation when both can do the job — they are more reliable and easier to audit.
+Open **Runs** to inspect the trigger, tool calls, approvals, output, and error
+for each execution. Delivery requires a configured messaging destination; a
+completed run can still have a delivery error.
 
 ## Safety
 
-NeoAgent runs on your server and can touch real files, messaging surfaces, connected accounts, and browser sessions. Keep prompts narrow.
-
-- Use messaging allowlists to restrict which chats receive automated messages
-- Keep secrets in server config, not in prompts or skill files
-- Prefer read-only checks unless the task explicitly needs to write data
-- Review run history in **Runs** and service logs in **Logs** when behavior is unexpected
-- Browser, CLI, Android, and file tools run on the NeoAgent server — not necessarily your current laptop
+- Start with read-only integration accounts.
+- Keep write, shell, Android, and desktop categories on approval unless the
+  task runs in a controlled environment.
+- Do not put secrets in prompts.
+- Restrict messaging allowlists so untrusted chats cannot trigger an agent.
+- Treat email, web pages, messages, and webhook bodies as untrusted input.