neoagent 3.0.1-beta.2 → 3.0.1-beta.20

package/.env.example

@@ -267,3 +267,22 @@ NEOAGENT_SCREEN_RECORDER_RETENTION_DAYS=7
 
 MESHTASTIC_ENABLED=true
 TELNYX_WEBHOOK_TOKEN=
+
+########################################
+# Stripe billing (optional)
+########################################
+
+# Set to true or 1 to enable the billing system. When disabled (default),
+# no billing routes are exposed and no payment UI is shown anywhere.
+# NEOAGENT_BILLING_ENABLED=false
+
+# Stripe API keys — required when billing is enabled.
+# Use test keys (sk_test_...) during development; live keys in production.
+# STRIPE_SECRET_KEY=sk_test_...
+# STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# Webhook signing secret from your Stripe dashboard (Developers > Webhooks).
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# Length of free trial periods in days (default: 14).
+# BILLING_TRIAL_DAYS=14

package/README.md

@@ -18,6 +18,12 @@
   <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">
+  <a href="https://github.com/NeoLabs-Systems/NeoAgent/releases/latest"><img alt="Android" src="https://img.shields.io/badge/Android-APK-3ddc84?style=flat-square&logo=android&logoColor=white"></a>
+  <a href="https://github.com/NeoLabs-Systems/NeoAgent/releases/latest"><img alt="iOS" src="https://img.shields.io/badge/iOS-coming_soon-lightgrey?style=flat-square&logo=apple&logoColor=white"></a>
+  <a href="https://github.com/NeoLabs-Systems/NeoAgent/releases/latest"><img alt="Windows" src="https://img.shields.io/badge/Windows-EXE-0078d4?style=flat-square&logo=windows&logoColor=white"></a>
+</p>
+
 <p align="center">
   <a href="https://www.producthunt.com/products/neoagent-2?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-neoagent-2" target="_blank" rel="noopener noreferrer"><img alt="NeoAgent - The next-gen self-hosted AI agent that works beyond chat | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1171573&theme=light&t=1781447653039"></a>
 </p>
@@ -37,6 +43,10 @@ npm install -g neoagent
 neoagent install
 ```
 
+<p align="center">
+  <a href="https://github.com/NeoLabs-Systems/NeoAgent/releases/latest"><img alt="Download macOS app" src="https://img.shields.io/badge/macOS_app-download-black?style=flat-square&logo=apple&logoColor=white"></a>
+</p>
+
 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.
@@ -51,6 +61,7 @@ service to a network.
 - **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.
 - **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.
 - **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.
+- **SaaS billing is built in and off by default.** Set `NEOAGENT_BILLING_ENABLED=true` to activate Stripe subscriptions, plan management, free trials, and model access restrictions. When disabled, no payment routes or UI appear anywhere. See [Billing](docs/billing.md).
 - **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.
 
 ## 🖥️ Interfaces
@@ -79,6 +90,11 @@ 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.
 
+## 📊 Benchmarks
+
+![NeoAgent benchmark dashboard](static/benchmarks/latest-dashboard.png)
+See [Benchmarking](docs/benchmarking.md) for the reproducibility details and suite coverage.
+
 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)

package/docs/benchmarking.md

@@ -0,0 +1,102 @@
+# Benchmarking
+
+NeoAgent includes an end-to-end benchmark harness that drives the app through
+its authenticated HTTP surface instead of calling internal engine methods
+directly. The harness configures OpenRouter models, submits benchmark tasks,
+collects run events and usage data, and writes normalized result artifacts.
+
+## Latest dashboard
+
+![Latest benchmark dashboard](/benchmarks/latest-dashboard.png)
+
+The generated image is backed by these local outputs:
+
+- `benchmark/results/latest-results.json`
+- `benchmark/results/latest-summary.json`
+- `benchmark/results/latest-summary.md`
+- `static/benchmarks/latest-dashboard.png`
+
+## Commands
+
+```bash
+npm run benchmark:setup
+npm run benchmark:run
+npm run benchmark:report
+```
+
+## Model selection
+
+The benchmark harness is OpenRouter-first. Edit the `OPENROUTER_MODEL_IDS`
+variable in `benchmark/config.js` to pin exact model IDs, or leave it empty to
+use the current cheap-tier OpenRouter models discovered at runtime.
+
+## Benchmark coverage
+
+- `GAIA`, `BrowseComp`, `WebArena`, `VisualWebArena`, and `SWE-bench` are wired
+  as exact public-suite adapters. When their official datasets or external
+  runners are not installed, they are reported as blocked instead of being
+  approximated.
+- `NeoAgent Representative Tasks` runs first-party agent tasks through
+  `/api/agents` and scores them from the persisted run details.
+- `NeoAgent Memory Retrieval` seeds memories over `/api/memory`, recalls them
+  through the app routes, and scores retrieval quality with the same metric
+  code used by the server evaluation module.
+
+## Reproducibility
+
+- Public-suite setup manifests are written under `benchmark/workdir/<suite>/`.
+- The harness uses one benchmark account and persists per-run usage summaries
+  through the existing NeoAgent run detail endpoints.
+- Blocked suites are intentional and explicit. The harness never substitutes a
+  simplified local task and labels it as a public benchmark result.
+
+## Public benchmark prerequisites
+
+### GAIA
+
+- Access to the gated [GAIA dataset](https://huggingface.co/datasets/gaia-benchmark/GAIA).
+- `HF_TOKEN` in the environment.
+- A Python environment with `datasets` installed if you want `benchmark:setup`
+  to export a normalized local cache automatically.
+- Either an exact evaluator wired through
+  `NEOAGENT_BENCHMARK_GAIA_RUNNER` or a repository-local exact runner added to
+  the harness. The current adapter intentionally reports `blocked` until an
+  official evaluator path is configured.
+
+### BrowseComp
+
+- A checkout of [openai/simple-evals](https://github.com/openai/simple-evals),
+  which `benchmark:setup` can clone into `benchmark/workdir/browsecomp/`.
+- Exact BrowseComp case extraction from that repo.
+- An official evaluator command exposed through
+  `NEOAGENT_BENCHMARK_BROWSECOMP_RUNNER`.
+
+### WebArena
+
+- Docker installed and running.
+- The official [WebArena](https://webarena.dev/) environment and task sites.
+- Browser automation dependencies required by the official runner.
+- An exact runner command exposed through
+  `NEOAGENT_BENCHMARK_WEBARENA_RUNNER`.
+
+### VisualWebArena
+
+- Docker installed and running.
+- The official VisualWebArena environment.
+- A vision-capable configured benchmark model.
+- An exact runner command exposed through
+  `NEOAGENT_BENCHMARK_VISUAL_WEBARENA_RUNNER`.
+
+### SWE-bench
+
+- Docker installed and running.
+- A checkout of [SWE-bench](https://github.com/SWE-bench/SWE-bench), which
+  `benchmark:setup` can clone into `benchmark/workdir/swebench/`.
+- The official dataset/runtime and enough disk/network budget for repo/image
+  setup.
+- An exact runner command exposed through
+  `NEOAGENT_BENCHMARK_SWEBENCH_RUNNER`.
+
+On this machine, `docker` is currently missing, so exact `WebArena`,
+`VisualWebArena`, and `SWE-bench` execution remain blocked until Docker and the
+official runners are installed.

package/docs/billing.md

@@ -0,0 +1,224 @@
+# Billing
+
+NeoAgent includes an optional Stripe-based billing system for deployments that
+charge users for access. When disabled — the default — no billing routes are
+exposed, no payment UI is shown, and no payment-related information appears
+anywhere in the application.
+
+## Enable billing
+
+Run the interactive setup wizard:
+
+```bash
+neoagent billing setup
+```
+
+The wizard prompts for your Stripe API keys, webhook secret, and trial length,
+then asks whether to enable billing immediately. Use Stripe test keys
+(`sk_test_...`, `pk_test_...`) during development.
+
+To check the current configuration at any time:
+
+```bash
+neoagent billing        # or: neoagent billing status
+```
+
+To toggle billing without re-running setup:
+
+```bash
+neoagent billing enable    # set NEOAGENT_BILLING_ENABLED=true and restart
+neoagent billing disable   # set NEOAGENT_BILLING_ENABLED=false and restart
+```
+
+When enabled the admin dashboard will show a **Billing** navigation item and
+the `/api/billing/*` endpoints become active.
+
+> **Manual alternative** — you can also set variables directly and restart:
+> ```bash
+> neoagent env set STRIPE_SECRET_KEY sk_live_...
+> neoagent env set STRIPE_PUBLISHABLE_KEY pk_live_...
+> neoagent env set STRIPE_WEBHOOK_SECRET whsec_...
+> neoagent env set NEOAGENT_BILLING_ENABLED true
+> neoagent restart
+> ```
+
+## Subscription plans
+
+Plans are managed in **Admin › Billing › Plans**. Each plan controls:
+
+| Field | Purpose |
+|---|---|
+| Name | Displayed to users in the settings submenu |
+| Price | Stripe price in cents (0 = free) |
+| Billing interval | `month`, `year`, or blank for one-time or free |
+| Stripe Price ID | The `price_...` ID from your Stripe dashboard |
+| 4h token limit | Per-user 4-hour rolling token budget (blank = server default) |
+| Weekly token limit | Per-user 7-day rolling token budget (blank = server default) |
+| Allowed models | Comma-separated model IDs; blank = all models accessible |
+| Features | Marketing feature strings shown on pricing pages |
+
+Token limits are written directly to the user account when a subscription
+becomes active or is updated via webhook. The existing rate-limit enforcement
+in the runtime reads them with no additional configuration.
+
+### Free plan
+
+Create a plan with **Price = 0** to serve as the default for new users. If a
+free plan exists when billing is enabled, every new registration is
+automatically placed on it.
+
+### Model restrictions
+
+If **Allowed models** is non-empty, users on that plan can only use the listed
+model IDs. Models outside the allowlist remain visible in the UI with an
+unavailable status so users understand what upgrading unlocks.
+
+Leave the field blank to allow all configured models on a plan.
+
+## User subscriptions
+
+Users manage their subscription in **Settings › Billing** (Flutter client). From
+there they can:
+
+- View their current plan, status, and next renewal date
+- Upgrade or downgrade through Stripe Checkout
+- Open the Stripe Customer Portal to update a payment method or download invoices
+- Cancel at the end of the current billing period
+
+### Stripe Checkout
+
+When a user selects a paid plan, the server creates a Stripe Checkout session
+and redirects the client to Stripe's hosted payment page. No card data passes
+through NeoAgent.
+
+### Stripe Customer Portal
+
+The Customer Portal is a Stripe-hosted page where users can update their
+payment method, view billing history, and cancel. Configure the portal in your
+[Stripe dashboard](https://dashboard.stripe.com/settings/billing/portal) before
+enabling it.
+
+## Free trials
+
+Enable free trials in **Admin › Billing › Plans** by configuring a Stripe price
+that supports trials, then setting `BILLING_TRIAL_DAYS` to the desired length
+(default: 14 days).
+
+Trials start when a user calls `POST /api/billing/trial` with a plan ID. The
+server runs anti-abuse checks before granting a trial:
+
+| Check | Limit |
+|---|---|
+| IP address | 2 trials per IP per 30 days |
+| Email domain | 3 trials per non-common domain per 30 days |
+| Account age | Account must be at least 1 day old |
+| Device fingerprint | 1 trial per device per 90 days (opaque hash from client) |
+
+The Flutter client is responsible for generating and sending the device
+fingerprint. The server hashes it with SHA-256 before storage — the raw
+fingerprint is never persisted.
+
+## Webhooks
+
+Stripe sends events to `POST /api/billing/webhook`. Register this URL in your
+[Stripe dashboard](https://dashboard.stripe.com/webhooks) under the endpoint
+for your account.
+
+Handled events:
+
+| Event | Effect |
+|---|---|
+| `customer.subscription.created` | Creates a local subscription row |
+| `customer.subscription.updated` | Syncs status, period dates, and token limits |
+| `customer.subscription.deleted` | Marks subscription canceled |
+| `customer.subscription.trial_will_end` | Sends trial-ending email (fires 3 days before) |
+| `invoice.payment_succeeded` | Records payment; sends renewal email on cycle |
+| `invoice.payment_failed` | Records failure; sends payment-failed email |
+
+Events are idempotent — replaying a webhook event produces the same result.
+
+**Required events to enable in Stripe:**
+
+```
+customer.subscription.created
+customer.subscription.updated
+customer.subscription.deleted
+customer.subscription.trial_will_end
+invoice.payment_succeeded
+invoice.payment_failed
+```
+
+### Verifying the webhook locally
+
+Use the Stripe CLI to forward events to a local server during development:
+
+```bash
+stripe listen --forward-to http://localhost:3333/api/billing/webhook
+```
+
+## Email notifications
+
+If [service email](configuration.md#service-email) is configured, users receive
+emails at the following billing events:
+
+| Event | Email |
+|---|---|
+| Trial started | Confirmation with trial end date |
+| Trial ending soon | Reminder 3 days before end |
+| Subscription activated | Welcome to the paid plan |
+| Subscription renewed | Renewal confirmation |
+| Payment failed | Action required with next retry date |
+| Subscription canceled | Cancellation confirmation |
+| Plan changed | Summary of the new plan |
+
+No emails are sent if SMTP is not configured.
+
+## AI context awareness
+
+When billing is enabled, each AI request includes the user's subscription in
+the system prompt:
+
+```
+SUBSCRIPTION: User is on the "Pro" plan, status: active.
+```
+
+Agents and workflows can use this context to adapt their behavior — for
+example, acknowledging feature limitations on a free plan or confirming
+capabilities on a paid one.
+
+## Admin controls
+
+The **Admin › Billing** page provides:
+
+- **Plans**: Create, edit, and deactivate subscription plans
+- **Subscriptions**: Browse all user subscriptions with status filter and
+  pagination; override a user's plan without going through Stripe
+
+Override a user's plan directly from the subscriptions table using the
+**Override** button. This is useful for comped accounts, support escalations,
+or fixing a webhook gap.
+
+## Configuration reference
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `NEOAGENT_BILLING_ENABLED` | `false` | Master on/off switch |
+| `STRIPE_SECRET_KEY` | required | Stripe server-side API key |
+| `STRIPE_PUBLISHABLE_KEY` | required | Stripe client-side key (returned to Flutter) |
+| `STRIPE_WEBHOOK_SECRET` | required | Webhook signing secret from Stripe dashboard |
+| `BILLING_TRIAL_DAYS` | `14` | Free trial length in days |
+
+All variables can be set with `neoagent env set` or added to `~/.neoagent/.env`
+directly. Restart the server after any change.
+
+## Security notes
+
+- NeoAgent stores only Stripe customer IDs and subscription IDs — no card
+  numbers, bank details, or PII beyond what Stripe already holds.
+- Webhook payloads are verified with HMAC-SHA256 using `STRIPE_WEBHOOK_SECRET`
+  before any processing. Requests missing the `stripe-signature` header are
+  rejected with 400.
+- Trial fingerprints are stored as SHA-256 hashes — the raw IP, email domain,
+  and device identifiers are never persisted.
+- All billing routes return 404 when `NEOAGENT_BILLING_ENABLED` is not set,
+  regardless of whether Stripe credentials are present.

package/docs/configuration.md

@@ -97,6 +97,28 @@ reset, email changes, and security notifications.
 | `NEOAGENT_EMAIL_PUBLIC_URL` | Base URL used in email links |
 | `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | Confirmation token lifetime |
 
+## Billing
+
+Billing is disabled by default. Use the interactive wizard to configure it:
+
+```bash
+neoagent billing setup    # guided Stripe key and webhook setup
+neoagent billing          # show current status
+neoagent billing enable   # activate billing and restart
+neoagent billing disable  # deactivate billing and restart
+```
+
+See [Billing](billing.md) for the full setup guide, webhook configuration, and
+plan management.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `NEOAGENT_BILLING_ENABLED` | `false` | Enable the Stripe billing system |
+| `STRIPE_SECRET_KEY` | unset | Stripe server-side API key |
+| `STRIPE_PUBLISHABLE_KEY` | unset | Stripe client-side key (returned to clients) |
+| `STRIPE_WEBHOOK_SECRET` | unset | Webhook signing secret |
+| `BILLING_TRIAL_DAYS` | `14` | Free trial length in days |
+
 ## Isolated runtime
 
 | Variable | Purpose |

package/docs/index.md

@@ -45,6 +45,7 @@ Continue with:
 | [Recordings and health](recordings-and-health.md) | Audio transcription and Health Connect |
 | [Skills and MCP](skills.md) | Reusable instructions and external tool servers |
 | [Operations](operations.md) | Updates, backups, logs, and recovery |
+| [Billing](billing.md) | Stripe subscriptions, plans, trials, and webhooks |
 | [Configuration](configuration.md) | Environment and runtime reference |
 | [Why NeoAgent](why-neoagent.md) | Factual comparison with OpenClaw and Hermes |
 

package/flutter_app/lib/main.dart

@@ -1,6 +1,6 @@
 import 'dart:async';
 import 'dart:convert';
-import 'dart:io' show Platform;
+import 'dart:io' show Directory, File, Platform, Process, ProcessSignal;
 import 'dart:math' as math;
 import 'dart:ui' show ImageFilter;
 
@@ -20,6 +20,7 @@ import 'package:image/image.dart' as img;
 import 'package:mobile_scanner/mobile_scanner.dart';
 import 'package:qr_flutter/qr_flutter.dart';
 import 'package:shared_preferences/shared_preferences.dart';
+import 'package:url_launcher/url_launcher.dart' as url_launcher;
 import 'package:socket_io_client/socket_io_client.dart' as io;
 import 'package:audioplayers/audioplayers.dart';
 import 'package:tray_manager/tray_manager.dart';
@@ -71,7 +72,9 @@ part 'main_security.dart';
 part 'main_model_picker.dart';
 part 'main_operations.dart';
 part 'main_admin.dart';
+part 'main_billing.dart';
 part 'main_unified.dart';
+part 'main_install.dart';
 
 Future<void> main() async {
   await runNeoAgentApp(mode: _appModeFromEnvironment());