aegis-arun 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Aegis — Terminal Agent Runtime
+
+Aegis (`aegis`, also `arun`) is a Rust terminal agent runtime. It connects to supported model providers, runs tools through permission-filtered capabilities, and records task progress and evidence in a durable SQLite event log. You can follow work in the terminal, steer an active task, and inspect its results without handing control to a provider CLI.
+
+## Get started
+
+Launch `aegis` or `arun` with no arguments to open the interactive terminal. Choose a provider, sign in or configure a compatible custom endpoint, select a model, review workspace access, and describe the task. Aegis creates and follows the task for you; you do not need to enter run or attach commands.
+
+ChatGPT and Grok use Aegis-owned direct HTTP flows. Browser approval is the recommended desktop sign-in flow; a device-code option is available for remote or headless terminals. Custom endpoints use an OpenAI-compatible interface. Claude subscription sign-in is pending. See [provider status and evidence](docs/direct-providers.md) and [browser sign-in boundaries](docs/browser-signin.md).
+
+For a source build and advanced CLI use:
+
+```powershell
+cargo build --release
+target/release/arun login chatgpt
+target/release/arun run "Inspect this repository" --provider chatgpt
+```
+
+The npm package `aegis-arun@0.2.0` is published on npm. Install it globally and launch either command:
+
+```sh
+npm install --global aegis-arun
+aegis
+```
+
+The package supports Windows x64 and Linux x64/arm64; macOS is unsupported. Published packages download a platform-specific runtime. Local native builds require Node 20+ and Rust. See [npm publishing](docs/npm-publishing.md) for package and release details.
+
+## Working in the terminal
+
+The interactive interface keeps ordinary terminal scrollback rather than taking over an alternate screen. It shows readable tool activity and results, supports steering an active task from the composer, and provides searchable menus and keyboard controls. Use `/` for the command catalog; F1 explains keyboard controls. Set `NO_COLOR=1` to disable colors or `AEGIS_REDUCED_MOTION=1` to reduce animation. See [terminal behavior and verification](docs/terminal-ui.md).
+
+Aegis asks when intent or a decision is unclear. An unanswered question blocks dependent work, while independent work can continue. Ctrl+C interrupts active work; Ctrl+D detaches from a task. F3 opens saved tasks and recovery choices, and F5 starts a fresh conversation without deleting task history. Advanced users can inspect tasks with commands such as `arun status <run-id>`, `arun replay <run-id>`, `arun artifacts <run-id>`, and `arun metrics <run-id>`.
+
+## Permissions and evidence
+
+Workspace reads and search are available by default. Writes require permission; command execution is disabled unless a specific program and locally available container image are granted. Process workers use a network-disabled container with a read-only root filesystem and resource limits. Images are not pulled implicitly during task execution. Trusted-host MCP servers are an explicit exception and are not sandboxed. See [runtime contracts](docs/contracts.md) for details.
+
+Task completion is not established by a model's claim alone. Successful operations produce evidence artifacts; explicit user requirements are tracked separately and need current-revision evidence. Interrupted operations with uncertain external effects are paused for reconciliation rather than blindly replayed. Independent completion checks can be configured, but their availability and scope should be reviewed for each project. See [task controls and proof boundaries](docs/control-surface.md).
+
+Aegis records provider-reported usage when available and labels missing or estimated measurements rather than treating them as exact. Deadlines and resource limits still apply; there is no task-level model-turn or token cap. Metrics are measurements, not a guarantee of provider billing accuracy or task efficiency.
+
+## Build and validate
+
+```powershell
+cargo test
+cargo test --test docker -- --ignored
+```
+
+The ignored Docker test requires a running Docker daemon and the local `node:22-alpine` image. The npm package smoke test is run after building the native binary with `npm run build:native`, then `npm run test:package`. These checks do not establish live inference, hosted sign-in, or interactive UI quality. Review [verification notes](docs/verification.md) for dated observations and known gaps.
+
+## Further documentation
+
+- [Current provider evidence and remaining work](docs/direct-providers.md)
+- [Terminal UI behavior](docs/terminal-ui.md)
+- [Task controls and evidence boundaries](docs/control-surface.md)
+- [Runtime contracts](docs/contracts.md)
+- [Saved-chat continuation](docs/saved-chat-continuation.md)
+- [npm release process](docs/npm-publishing.md)
+- [Windows local setup](relay/local/README.md)
+
+Aegis is under active development. Provider compatibility, account access, packaging, and verification status can change; consult the linked evidence notes rather than assuming every documented path has been independently validated.

package/bin/aegis.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { ensureNative } from '../scripts/install.mjs';
+import { fileURLToPath } from 'node:url';
+import { whatsappCommand } from '../scripts/whatsapp-cli.mjs';
+
+async function run(executable, args) {
+  const child = spawn(executable, args, { stdio: 'inherit', windowsHide: true });
+  const handlers = new Map(['SIGINT', 'SIGTERM'].map(signal => [signal, () => { if (!child.killed) child.kill(signal); }]));
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  try {
+    return await new Promise((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', (code, signal) => resolve(signal ? 1 : code ?? 1));
+    });
+  } finally {
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  }
+}
+
+try {
+  const executable = process.env.ARUN_BINARY || await ensureNative();
+  const args = process.argv.slice(2);
+  if (args[0] === 'whatsapp') {
+    process.exitCode = await whatsappCommand(args.slice(1), executable);
+  } else if (args[0] === 'pc') {
+    if (!args[1] || ['help', '--help', '-h'].includes(args[1])) {
+      console.log('aegis pc enable --trusted-host [--workspace <directory>]\nGrants files, PowerShell and desktop tools to new tasks in that workspace.\naegis pc status');
+    } else if (args[1] === 'status' && args.length === 2) {
+      process.exitCode = await run(executable, ['mcp', 'list']);
+    } else if (args[1] === 'enable') {
+      process.exitCode = await run(process.execPath, [fileURLToPath(new URL('../scripts/windows-host-install.mjs', import.meta.url)), '--aegis', executable, ...args.slice(2)]);
+    } else {
+      throw new Error('Usage: aegis pc enable --trusted-host [--workspace <directory>] | status');
+    }
+  } else {
+    process.exitCode = await run(executable, args);
+  }
+} catch (error) {
+  console.error('aegis: ' + error.message);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,18 @@
-{
-  "name": "aegis-arun",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "aegis-arun",
+  "version": "0.2.0",
+  "description": "A durable terminal agent with direct account sign-in and custom endpoints",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": { "node": ">=20" },
+  "bin": { "aegis": "bin/aegis.mjs", "arun": "bin/aegis.mjs" },
+  "files": ["bin", "scripts/install.mjs", "scripts/platform.mjs", "scripts/windows-host.mjs", "scripts/windows-host.ps1", "scripts/windows-host-install.mjs", "scripts/whatsapp-cli.mjs", "relay/local", "vendor", "README.md"],
+  "scripts": {
+    "postinstall": "node scripts/install.mjs",
+    "build:native": "node scripts/build-native.mjs",
+    "test:package": "node scripts/package-smoke.mjs",
+    "test": "node --test tests/npm/*.test.mjs"
+  },
+  "repository": { "type": "git", "url": "https://github.com/aleksandarkolev-st/aegis.git" },
+  "keywords": ["agent", "terminal", "runtime", "codex", "claude", "grok"]
+}

package/relay/README.md

@@ -0,0 +1,177 @@
+# Aegis cloud relay
+
+This standalone Rust service connects messaging channels to Aegis through a channel-neutral `MessagingChannel` contract. The relay core owns identity, pairing, routing, notification delivery, and receipts. Evolution is the only live adapter today and implements that contract for WhatsApp. The metadata schema also reserves an iMessage channel identity, but no iMessage adapter is implemented or tested here; it remains an optional macOS-only integration.
+
+The relay does not run code or make tool decisions. A channel adapter normalizes inbound text into a small typed command on a per-installation JetStream subject. Aegis connects outbound to NATS over TLS, consumes only its own command subject, and publishes its allowlisted remote events. The active channel adapter renders those events for destinations paired to the same actor.
+
+## Stored data
+
+PostgreSQL contains eight metadata tables: users, installations, channel_bindings, pairing_tokens, delivery_receipts, notification_preferences, task_conversations, and outbound_echoes. Conversation rows bind a group to one owner's task. Echo rows retain digests only: a short body reservation covers send/webhook races, and a returned provider message ID digest prevents delayed self-account echoes for 30 days. Channel identity is stored independently of provider names.
+
+- Pairing codes are random 256-bit values. PostgreSQL stores their SHA-256 hashes and 5-minute expiry; redemption is atomic and one time.
+- Each installation belongs to one relay user and can register multiple actor IDs. Pairing metadata keeps one current token row per actor; actor IDs are unique across installations and cannot be moved to another installation.
+- Inbound webhook receipts keep only channel, sender ID, provider message ID, target installation/binding, disposition, and status for 30 days. They prevent provider retries from publishing commands twice or retrying a consumed pairing code.
+- Outbound receipts keep channel, event/binding IDs, status, attempt count, provider message ID, and timestamps for 90 days.
+- Missing notification preferences enable state changes (task_started, approval_required, blocked, completed, failed, and reply) and suppress routine progress. Progress can be explicitly enabled per channel with the admin preference endpoint.
+- No message text, repository data, model context, provider credential, shell output, or event transcript is written to PostgreSQL or application logs.
+- JetStream command and event streams use file storage, WorkQueue retention, and a 64 MiB cap with an explicit discard-oldest policy. Commands have a 15-minute maximum age; events have a 24-hour maximum age. Acknowledged items are removed from the work queue. Pending payloads, including normalized command text and reply text, remain only in this bounded NATS queue until acknowledgement or expiry; they are not copied into PostgreSQL or application logs. The relay updates existing stream configuration at startup, so an existing event stream receives the 24-hour policy too. An event can be retained for up to one day while the relay is offline if NATS remains available and the stream stays below 64 MiB; reaching the byte cap can evict older events sooner.
+
+The AegisEvent schema accepts only task_started, progress, approval_required, blocked, completed, failed, and reply. Every event must include a valid actor_id. Unknown fields such as shell output or repository context are rejected. Approval events include a display_detail of at most 512 bytes with only the capability and bounded target, plus the challenge expiry; these are never persisted or logged. Expired approval notifications are acknowledged and dropped. reply_text is accepted only for a reply event and is capped at 4 KiB.
+
+## Remote commands
+
+The default adapter accepts direct incoming text and paired-owner messages in known task groups. Explicit self-account mode accepts only the linked owner's own self-chat and own messages in those groups. The local Windows setup remains inert until the linked owner is confirmed. Unrelated groups, other contacts in self-account mode, outbound reply echoes, status events, media-only messages, malformed sender IDs, and unauthenticated webhooks are ignored or rejected. Message text is line-ending normalized and capped at 8 KiB. It is never logged.
+
+An unpaired number can redeem a one-time code with either exact form: `/pair <code>` or `AEGIS <code>`. The command name is case-insensitive for the `AEGIS` form; the code must be one exact 43-character token with no trailing text. Pairing codes are consumed once. These prefixes are reserved for pairing and are not forwarded as ordinary messages.
+
+| WhatsApp text | Typed command |
+| --- | --- |
+| /help, /goal, /models, /settings and the terminal catalog | slash (executed locally by authenticated Aegis) |
+| Ordinary text or /message <text> | message |
+| /tasks or /list_tasks | list_tasks |
+| /status | status |
+| /result [task-id] | result |
+| /evidence [task-id] | evidence |
+| /details [task-id] | details |
+| /pause | pause |
+| /resume | resume |
+| /cancel [task-id] | cancel |
+| /select_task <task-id> or /use <task-id> | select_task |
+| /approve_once <challenge-id> | approve_once |
+| /deny <challenge-id> | deny |
+
+`/result [alias]` is available only after a task reaches a terminal state. It returns the saved final summary, bounded to 2 KiB and marked as verified, unverified, or not verified based on the recorded task state. `/evidence [alias]` returns at most eight receipts that are referenced by verified explicit obligations and belong to the current workspace revision. Each row contains only a safe capability name, a 12-character hash prefix, and byte count; artifact contents, paths, command arguments, stdout, and previews are never returned. Conversational answers have no evidence receipts.
+
+Approval commands carry the challenge ID. There is no /approve alias. IDs are restricted to 128 ASCII letters, digits, underscores, hyphens, or periods.
+
+Each command envelope includes installation_id, actor_id, stable envelope_id and request_id, issued/expiry timestamps, source channel/sender/message IDs, and the typed command. Commands expire after five minutes. Retries reuse stable IDs and set JetStream's Nats-Msg-Id. Event envelopes include installation_id, actor_id, challenge_id, display_detail, and reply_text; nullable event-specific fields are null when unused. The relay restricts fan-out to the matching paired destination.
+
+Relay-to-Aegis authentication uses TLS and separate NATS users with subject permissions. The relay authenticates as `aegis-relay`; each device authenticates as `aegis-<canonical lowercase installation UUID>` with its own password. Aegis validates the installation, expiry, typed command, and envelope actor_id against its local actor-to-run mapping before dispatch. No actor HMAC key is sent to or shared with the relay. Each Aegis event carries actor_id from the local actor-to-run scope; before delivery, the relay selects only active bindings for the same installation, actor, and active channel adapter. A phone paired to another actor on the same installation cannot receive that event.
+
+The relay's `relay-whatsapp-delivery` durable pull consumer is supervised independently from HTTP serving. A JetStream pull error or end-of-stream drops the current pull stream, waits with exponential backoff from 1 to 30 seconds, then gets or creates the same durable consumer and resumes pending events. The backoff resets after a consumer stays connected for at least a minute. Unacknowledged events remain eligible for redelivery until acknowledged or removed by the event stream's one-day/64 MiB limits.
+
+## NATS principal provisioning
+
+Provision NATS users separately from HTTP channel pairing. The admin pairing route does not issue NATS credentials. Use a current supported NATS server with the named, single-filter consumer create API (introduced in 2.9). Replace any server-wide `authorization.token` configuration with an explicit user list. Generate a distinct random password for the relay and for every installation, and store production server passwords as bcrypt hashes or use an equivalent external provisioning system. Retain TLS. Rotate or revoke an installation's NATS user independently of channel pairing when its device credential is compromised.
+
+The legacy names `NATS_AUTH_TOKEN` and `--nats-token-env` now identify **user passwords**, not NATS token authentication. The relay reads its password from `NATS_AUTH_TOKEN`. Aegis stores only the environment variable name in `remote.json`; its daemon reads the installation password from that variable. Neither client accepts a username override or falls back to shared token authentication.
+
+For installation `I`, substitute its canonical lowercase hyphenated UUID and set `C` to `aegis-I`. Its NATS user is `C`. Give it precisely these publish permissions:
+
+```text
+aegis.events.I
+$JS.API.CONSUMER.INFO.AEGIS_COMMANDS.C
+$JS.API.CONSUMER.CREATE.AEGIS_COMMANDS.C.aegis.commands.I
+$JS.API.CONSUMER.MSG.NEXT.AEGIS_COMMANDS.C
+$JS.ACK.AEGIS_COMMANDS.C.*.*.*.*.*
+```
+
+Give it only `_INBOX.aegis.device.I.>` as a subscribe permission. Aegis sets `_INBOX.aegis.device.I` as its custom inbox prefix. Pull messages and API/publish replies arrive through those inboxes; no direct subscription to the command subject or stream-info permission is needed. Before pulling, the daemon checks the returned consumer's stream, name, durable name, exact command filter, pull mode, and explicit acknowledgement policy. An existing consumer with different authority fails closed.
+
+Give `aegis-relay` precisely these publish permissions:
+
+```text
+aegis.commands.*
+$JS.API.STREAM.CREATE.AEGIS_COMMANDS
+$JS.API.STREAM.UPDATE.AEGIS_COMMANDS
+$JS.API.STREAM.CREATE.AEGIS_EVENTS
+$JS.API.STREAM.UPDATE.AEGIS_EVENTS
+$JS.API.STREAM.INFO.AEGIS_EVENTS
+$JS.API.CONSUMER.INFO.AEGIS_EVENTS.relay-whatsapp-delivery
+$JS.API.CONSUMER.CREATE.AEGIS_EVENTS.relay-whatsapp-delivery.aegis.events.*
+$JS.API.CONSUMER.MSG.NEXT.AEGIS_EVENTS.relay-whatsapp-delivery
+$JS.ACK.AEGIS_EVENTS.relay-whatsapp-delivery.*.*.*.*.*
+```
+
+Give the relay only `_INBOX.aegis.relay.>` as a subscribe permission; its custom inbox prefix is `_INBOX.aegis.relay`. The relay also checks the returned durable consumer's scope and acknowledgement policy before pulling. Allow lists deny subjects outside the list. Do not add unrestricted users, broad `$JS.API.>` or `$JS.ACK.>` grants, shared `_INBOX.>` subscriptions, `allow_responses`, unfiltered `CONSUMER.CREATE` endpoints, or legacy `CONSUMER.DURABLE.CREATE` endpoints. In particular, a device grant for a consumer name without the exact filter suffix would let it request a different filter in the payload. The filtered endpoint checks the payload against the filter in its subject and rejects multiple filters. See the [NATS consumer API implementation](https://github.com/nats-io/nats-server/blob/v2.12.0/server/jetstream_api.go#L4286) and [authentication documentation](https://docs.nats.io/learn/security/authentication-basics).
+
+These ACK grants cover the standalone server configuration here. If deploying JetStream domains or cross-account routing that changes ACK subjects, scope the additional emitted ACK format to the same stream and consumer, and configure the matching API prefix as required by that topology. Do not broaden an ACK grant to compensate for a topology mismatch. Administrative inspection, cleanup, and credential provisioning should use a separate trusted operator principal; devices and the relay are not granted consumer-delete permissions.
+
+The shared `AEGIS_COMMANDS` and `AEGIS_EVENTS` streams isolate message access through these permissions, but **do not isolate availability or storage quotas**. One device's event flood can fill the shared 64 MiB event stream and evict another device's pending events. Deploy per-installation streams with exact subjects and separate limits, or per-installation JetStream accounts, when that boundary is required; those deployments also need corresponding relay consumer lifecycle changes.
+
+## WhatsApp delivery guarantee
+
+Outbound WhatsApp delivery is **at-least-once**, not exactly-once. Aegis event IDs and per-destination PostgreSQL receipts suppress retries after the relay commits a successful delivery receipt. The current Evolution `sendText` DTO has no provider idempotency-key field ([controller](https://github.com/evolution-foundation/evolution-api/blob/main/src/api/controllers/sendMessage.controller.ts), [DTO](https://github.com/evolution-foundation/evolution-api/blob/main/src/api/dto/sendMessage.dto.ts)), so a send that Evolution accepts before the relay receives its response or commits the receipt is ambiguous. Retrying that event can send a duplicate WhatsApp message. The relay passes stable event IDs to the provider interface for adapters that support idempotency, but Evolution cannot use them for provider-side deduplication.
+
+## HTTP routes
+
+- GET /healthz returns ok.
+- POST /admin/v1/installations requires Authorization: Bearer RELAY_ADMIN_TOKEN. JSON body:
+
+      {"actor_id":"local-actor-id","installation_id":"<optional canonical Aegis UUID>"}
+
+  The relay creates the user and installation if needed, then returns a 5-minute pairing code once. Under the trusted admin bearer principal, an existing installation UUID identifies that installation's user; additional actor IDs can be provisioned under the same installation. Re-provisioning the same installation/actor pair rotates its one-time code and keeps the user, installation, and actor binding scope. An actor ID already owned by another installation is rejected with 409. The relay admin bearer is the trusted bootstrap authority for this single deployment; it is not an end-user credential.
+- POST /admin/v1/installations/{installation_id}/notifications/{event_kind} requires the admin bearer token and JSON {"enabled":false} (or true); this compatibility route changes WhatsApp preferences.
+- POST /admin/v1/installations/{installation_id}/channels/{channel}/notifications/{event_kind} changes preferences for `whatsapp` or the reserved `imessage` identity.
+- POST /admin/v1/installations/{installation_id}/bindings/revoke requires the admin bearer token and JSON {"actor_id":"local-actor-id","sender_id":"+4915112345678"}. It deactivates only the WhatsApp binding matching those values and consumes any unused pairing code for that actor on the installation.
+- POST /admin/v1/installations/{installation_id}/channels/{channel}/bindings/revoke applies the same sender-specific operation to one channel.
+- POST /admin/v1/installations/{installation_id}/actors/{actor_id}/bindings/revoke requires the admin bearer token and no request body. It idempotently consumes any unused pairing code and deactivates every channel binding for exactly that actor and installation. It returns 204 even if nothing is currently paired, so the local daemon can use it as best-effort cloud cleanup after disabling the actor locally.
+- POST /v1/webhooks/whatsapp/evolution authenticates before interpreting the message JSON. It accepts either a dedicated x-aegis-webhook-token header, or an HMAC signature in x-aegis-timestamp and x-aegis-signature. The signature is v1= plus base64url-no-pad HMAC-SHA256 over timestamp, a period, and the raw body; it expires after five minutes. Use a dedicated webhook secret separate from the Evolution API key.
+
+Configure Evolution's webhook to send x-aegis-webhook-token. If it cannot set custom webhook headers, place a trusted HTTPS ingress adapter in front that validates provider authentication and adds this dedicated header. Do not expose the webhook route without authentication.
+
+## Environment
+
+Required variables:
+
+| Variable | Purpose |
+| --- | --- |
+| DATABASE_URL | PostgreSQL URL. Production should use sslmode=verify-full. |
+| NATS_URL | tls://host:port; plaintext NATS is rejected. |
+| NATS_AUTH_TOKEN | Password for the fixed `aegis-relay` NATS user, at least 32 characters. Keep it in a secret manager. |
+| NATS_TLS_ROOT_CERT | Optional PEM CA path for a private NATS certificate authority. |
+| RELAY_ADMIN_TOKEN | Admin API bearer secret, at least 32 characters. |
+| EVOLUTION_BASE_URL | HTTPS Evolution API base URL. HTTP is allowed only for localhost development. |
+| EVOLUTION_INSTANCE | Evolution instance name. |
+| EVOLUTION_API_KEY | Evolution outbound API credential; held in process configuration only. |
+| EVOLUTION_WEBHOOK_SECRET | Dedicated webhook token/HMAC secret, at least 32 characters. |
+| RELAY_BIND_ADDR | Defaults to 127.0.0.1:8787. |
+
+In production, bind the process to a private interface and expose the webhook through an HTTPS reverse proxy with request limits and authentication. Do not expose a plaintext or unauthenticated NATS listener. Database initialization creates the eight metadata tables above.
+
+## Local services and smoke test
+
+Local Compose binds PostgreSQL and NATS to loopback only. NATS uses TLS, the relay user, and two devices with exact installation permissions; its test certificate is generated locally and is not committed. PostgreSQL plaintext is allowed only with RELAY_ALLOW_INSECURE_LOCAL_DATABASE=true and a localhost or Compose-service database host.
+
+Compose requires `NATS_AUTH_TOKEN` for the relay password and the following complete values for each device. Use prefix `AEGIS_NATS_DEVICE_` for the first device and `AEGIS_NATS_DEVICE2_` for the second; substitute `I` and `C` as described above. NATS config variables do not interpolate UUIDs inside subject strings, so provide each full subject rather than a UUID placeholder. There are no shared-token or wildcard-device defaults.
+
+| Variable suffix | Value |
+| --- | --- |
+| USERNAME | `aegis-I` |
+| PASSWORD | Unique device password, separate from `NATS_AUTH_TOKEN` |
+| EVENT_SUBJECT | `aegis.events.I` |
+| CONSUMER_INFO | `$JS.API.CONSUMER.INFO.AEGIS_COMMANDS.C` |
+| CONSUMER_CREATE | `$JS.API.CONSUMER.CREATE.AEGIS_COMMANDS.C.aegis.commands.I` |
+| CONSUMER_NEXT | `$JS.API.CONSUMER.MSG.NEXT.AEGIS_COMMANDS.C` |
+| ACK | `$JS.ACK.AEGIS_COMMANDS.C.*.*.*.*.*` |
+| INBOX | `_INBOX.aegis.device.I.>` |
+
+Derive these values from the installation identity before starting NATS. Supply the first device's password to its daemon under the environment variable named by `--nats-token-env`. Treat the inputs as operator configuration: setting a wildcard where an exact subject is specified would weaken the boundary.
+
+For the four `$JS...` values, include double quote characters around the full value in the environment variable (for example, `"$JS.API.CONSUMER.INFO.AEGIS_COMMANDS.C"`). NATS parses environment variable values as config text; these quotes keep `$JS` literal, and are removed before the subject permission is applied.
+
+From the repository root in PowerShell, run:
+
+    .\relay\dev\start-local.ps1
+
+It starts Postgres and NATS, exports development-only settings, and runs the relay. The local webhook listens only on 127.0.0.1:8787; external webhook traffic still needs HTTPS.
+
+The fake-adapter smoke tests need no provider account, database, or NATS. They exercise the channel-neutral relay core and local Aegis authority with fixtures; they do not represent a live iMessage adapter:
+
+    cargo test --manifest-path relay/Cargo.toml --test local_smoke
+
+Or run .\relay\scripts\smoke.ps1. Provider parsing and webhook authentication have fixture-based unit tests.
+
+### Pair an Aegis installation
+
+After the relay is running and Aegis has a locally saved provider/model profile, set the local development credentials in a separate PowerShell session and pair the installation:
+
+    $env:AEGIS_RELAY_ADMIN_TOKEN = "local-development-admin-token-not-for-production"
+    $env:AEGIS_NATS_TOKEN = $env:AEGIS_NATS_DEVICE_PASSWORD
+    aegis remote pair --relay-admin-url http://127.0.0.1:8787 --admin-token-env AEGIS_RELAY_ADMIN_TOKEN --nats-url tls://localhost:4422 --nats-token-env AEGIS_NATS_TOKEN --nats-root-cert .\relay\dev\certs\nats.crt
+
+Send the one-time `/pair <code>` command printed by Aegis from the WhatsApp number to bind. Then check `aegis remote status` and keep `aegis remote run` running while you use the relay. Pairing stores no credential values; Aegis reads them from the named environment variables. Supply the device password in this session before running the daemon. These sample credentials are for local development only. Configure Evolution with a valid account, HTTPS endpoint, API key, and webhook authentication before expecting WhatsApp messages to reach the local relay.
+
+To exercise PostgreSQL pairing rotation, actor-scoped binding lookup, and durable inbound dedupe against the local database, run .\relay\scripts\db-smoke.ps1. It starts only the loopback-bound Postgres service and runs the optional integration test.
+
+For the isolated cross-process end-to-end check, run .\relay\scripts\e2e-smoke.ps1. It builds the real Aegis binary, starts a temporary PostgreSQL and TLS JetStream Compose project on loopback ports, exercises the Aegis pairing CLI and remote daemon through the relay HTTP router, and tears down only that uniquely named test project and its volumes. The fake WhatsApp adapter avoids provider credentials; this verifies the local relay path, not delivery through a live Evolution account.

package/relay/local/README.md

@@ -0,0 +1,47 @@
+# Local WhatsApp setup on Windows
+
+This persistent stack uses Evolution API **2.3.7**, Redis, separate PostgreSQL databases for Evolution and relay metadata, and TLS NATS. Evolution runs in Docker Desktop; the real relay and installed Aegis run on Windows. The development smoke fixtures are separate.
+
+From the Aegis workspace, run:
+
+```powershell
+aegis whatsapp init
+aegis whatsapp start
+aegis whatsapp create-instance
+aegis whatsapp qr
+```
+
+Open the printed local `whatsapp-qr.html` path. On the phone hosting the relay account, open **WhatsApp → Settings → Linked devices → Link a device** and scan. No account is linked by the setup commands alone.
+
+For your existing single WhatsApp account, enable `self-account` after linking. It reads the linked owner from Evolution and enables only your own self-DM and own messages in known task groups. It refuses to activate before the account reports a connected owner. Then run `pair` to generate the five-minute Aegis pairing code and send it in **Message yourself**:
+
+```powershell
+aegis whatsapp self-account
+aegis whatsapp pair
+aegis whatsapp daemon
+aegis whatsapp status
+```
+
+After sending the code to yourself, run `daemon`. Replies are protected against being mistaken for new self-account commands. Task groups accept only their paired owner's messages and route to the exact task; unrelated groups are ignored. The default adapter mode remains available for deployments with a separate relay account.
+
+Send `/help` in WhatsApp for the terminal command catalog, `/goal <task>` to start work, and `/new` in self-chat before a separate task. Interactive terminal pickers become text choices and explicit reviews in WhatsApp. Group creation with only the linked owner is still unverified; a failed request leaves that task controllable in self-chat.
+
+To grant files, native PowerShell and desktop applications to new workspace tasks, run `aegis pc enable --trusted-host`. It registers the included Windows MCP server and exact tool grants. Choose your model and reasoning in local settings, or use `/model gpt-6.1-sol` and `/reasoning high` for future remote tasks. Remote host operations still use Aegis's exact approval gates.
+
+`webhook` re-registers the authenticated inbound route. `stop` stops owned Windows processes and Docker services while retaining sessions and volumes. `start` resumes the infrastructure and relay; run `daemon` again if paired. A Windows restart requires these start commands. Aegis still applies its local permissions and approval gates to remote requests.
+
+Use `-Workspace <directory>` for another workspace, `-AegisBinary <installed arun.exe>` and `-RelayBinary <aegis-relay.exe>` if native executable discovery is unavailable. Bundled relay executables are used before the repository Cargo fallback. Initial setup reads the installed executable's real workspace identity. Re-running `init` preserves credentials; deleting state or Docker volumes is not an upgrade procedure.
+
+## Local data and network
+
+Random credentials, certificate/private key, process identity records, private logs and QR artifacts live in the Git-ignored `.arun/local-remote` directory. Its Windows ACL grants only the current user and SYSTEM, including inherited files. Compose container environment values remain visible to Docker administrators.
+
+Published ports bind to `127.0.0.1`. Redis and Evolution's PostgreSQL have no host ports. Evolution uses `host.docker.internal` to reach the loopback Windows relay; webhook setup verifies this route before registration. NATS permits only the relay principal and the exact local device's command consumer, event subject and private inbox. The local relay PostgreSQL connection uses the explicit loopback plaintext exception; NATS always uses TLS.
+
+Evolution keeps its authentication/session data in persistent Docker volumes. Message/contact/chat/history database persistence and verbose webhook logs are disabled. This does not establish a live delivery guarantee: phone linking and an actual incoming/outgoing WhatsApp exchange must be verified after scanning.
+
+## Version and API references
+
+The image tag follows Evolution's [2.3.7 official deployment configuration](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/Docker/swarm/evolution_api_v2.yaml). Storage/log switches follow its [versioned environment example](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/.env.example). Instance creation and QR retrieval use the [versioned instance routes](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/src/api/routes/instance.router.ts). The webhook uses `MESSAGES_UPSERT`, `byEvents=false`, and a custom `x-aegis-webhook-token` header, supported by the [versioned webhook controller](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/src/api/integrations/event/webhook/webhook.controller.ts).
+
+Task group creation uses `POST /group/create/{instance}` with the deterministic task subject and your phone as the participant. Evolution's [2.3.7 group schema](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/src/validate/group.schema.ts) requires at least one participant; an empty array is invalid. The [Baileys adapter](https://github.com/evolution-foundation/evolution-api/blob/2.3.7/src/api/integrations/channel/whatsapp/whatsapp.baileys.service.ts) passes the resolved participants to WhatsApp group creation. Creating a group with the linked owner must still be verified against the actual linked account; a failed or ambiguous creation is reported in the task's DM rather than silently claiming a group exists.

package/relay/local/compose.yaml

@@ -0,0 +1,132 @@
+services:
+  relay-postgres:
+    image: postgres:17.6-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: aegis_relay
+      POSTGRES_USER: relay
+      POSTGRES_PASSWORD: ${RELAY_DATABASE_PASSWORD:?Run local-remote.ps1 init}
+      POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256
+    ports:
+      - "127.0.0.1:${RELAY_DATABASE_PORT}:5432"
+    volumes:
+      - relay-postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: [CMD-SHELL, "pg_isready -U relay -d aegis_relay"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+
+  evolution-postgres:
+    image: postgres:17.6-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: evolution
+      POSTGRES_USER: evolution
+      POSTGRES_PASSWORD: ${EVOLUTION_DATABASE_PASSWORD:?Run local-remote.ps1 init}
+      POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256
+    volumes:
+      - evolution-postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: [CMD-SHELL, "pg_isready -U evolution -d evolution"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+
+  redis:
+    image: redis:7.4.5-alpine
+    restart: unless-stopped
+    command: [redis-server, --appendonly, "yes"]
+    volumes:
+      - redis:/data
+    healthcheck:
+      test: [CMD, redis-cli, ping]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+
+  nats:
+    image: nats:2.12.0-alpine
+    restart: unless-stopped
+    command: [-c, /etc/nats/nats-server.conf]
+    environment:
+      NATS_AUTH_TOKEN: ${NATS_AUTH_TOKEN}
+      AEGIS_NATS_DEVICE_USERNAME: ${AEGIS_NATS_DEVICE_USERNAME}
+      AEGIS_NATS_DEVICE_PASSWORD: ${AEGIS_NATS_DEVICE_PASSWORD}
+      AEGIS_NATS_DEVICE_EVENT_SUBJECT: ${AEGIS_NATS_DEVICE_EVENT_SUBJECT}
+      AEGIS_NATS_DEVICE_CONSUMER_INFO: ${AEGIS_NATS_DEVICE_CONSUMER_INFO}
+      AEGIS_NATS_DEVICE_CONSUMER_CREATE: ${AEGIS_NATS_DEVICE_CONSUMER_CREATE}
+      AEGIS_NATS_DEVICE_CONSUMER_NEXT: ${AEGIS_NATS_DEVICE_CONSUMER_NEXT}
+      AEGIS_NATS_DEVICE_ACK: ${AEGIS_NATS_DEVICE_ACK}
+      AEGIS_NATS_DEVICE_INBOX: ${AEGIS_NATS_DEVICE_INBOX}
+    ports:
+      - "127.0.0.1:${NATS_PORT}:4222"
+    volumes:
+      - ./nats-server.conf:/etc/nats/nats-server.conf:ro
+      - ${LOCAL_REMOTE_DIR}/nats-certs:/run/certs:ro
+      - jetstream:/data/jetstream
+    healthcheck:
+      test: [CMD-SHELL, "nc -z 127.0.0.1 4222"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+
+  evolution:
+    image: evoapicloud/evolution-api:v2.3.7
+    restart: unless-stopped
+    depends_on:
+      evolution-postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${EVOLUTION_PORT}:8080"
+    volumes:
+      - evolution-instances:/evolution/instances
+    environment:
+      SERVER_URL: http://localhost:${EVOLUTION_PORT}
+      AUTHENTICATION_API_KEY: ${EVOLUTION_API_KEY}
+      AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES: "false"
+      DATABASE_PROVIDER: postgresql
+      DATABASE_CONNECTION_URI: postgresql://evolution:${EVOLUTION_DATABASE_PASSWORD}@evolution-postgres:5432/evolution?schema=public
+      DATABASE_CONNECTION_CLIENT_NAME: aegis_local
+      DATABASE_SAVE_DATA_INSTANCE: "true"
+      DATABASE_SAVE_DATA_NEW_MESSAGE: "false"
+      DATABASE_SAVE_MESSAGE_UPDATE: "false"
+      DATABASE_SAVE_DATA_CONTACTS: "false"
+      DATABASE_SAVE_DATA_CHATS: "false"
+      DATABASE_SAVE_DATA_LABELS: "false"
+      DATABASE_SAVE_DATA_HISTORIC: "false"
+      DATABASE_SAVE_IS_ON_WHATSAPP: "false"
+      CACHE_REDIS_ENABLED: "true"
+      CACHE_REDIS_URI: redis://redis:6379/0
+      CACHE_REDIS_PREFIX_KEY: aegis_local
+      CACHE_REDIS_SAVE_INSTANCES: "false"
+      CACHE_LOCAL_ENABLED: "false"
+      TELEMETRY_ENABLED: "false"
+      LOG_LEVEL: ERROR,WARN
+      LOG_BAILEYS: error
+      WEBHOOK_GLOBAL_ENABLED: "false"
+      CONFIG_SESSION_PHONE_CLIENT: Aegis
+      CONFIG_SESSION_PHONE_NAME: Chrome
+      DEL_INSTANCE: "false"
+      OPENAI_ENABLED: "false"
+      CHATWOOT_ENABLED: "false"
+      TYPEBOT_ENABLED: "false"
+      N8N_ENABLED: "false"
+      DIFY_ENABLED: "false"
+      EVOAI_ENABLED: "false"
+      S3_ENABLED: "false"
+    healthcheck:
+      test: [CMD, node, -e, "fetch('http://127.0.0.1:8080/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 5s
+      timeout: 4s
+      start_period: 30s
+      retries: 30
+
+volumes:
+  relay-postgres:
+  evolution-postgres:
+  redis:
+  jetstream:
+  evolution-instances: