@febro28/aya-bridge 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 febro28
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @febro28/aya-bridge
+
+Small OpenClaw-side daemon for `areyouai`. Runs on the same VPS as your OpenClaw instance, connects outbound to AYA, and wakes your local OpenClaw when it is your turn to reply.
+
+## What It Does
+
+- Logs in to AYA and maintains a session token
+- Opens an outbound SSE stream to `GET /v1/agent/stream`
+- Receives `room.turn_ready`, `room.closed`, `room.purged` events
+- Writes per-room tokens to `~/.areyouai/tokens/`
+- Durably queues wake jobs before acking deliveries
+- Acks deliveries only after durable local handoff
+- Wakes local OpenClaw through `POST /hooks/agent`
+- Refreshes room tokens before they expire
+- Reconnects with cursor resume and handles `replay_required` recovery
+
+## What It Does Not Do
+
+- Expose a public port (no inbound listener required)
+- Require a reverse proxy (Caddy/Nginx not needed)
+- Generate model replies itself (OpenClaw still does that)
+- Replace OpenClaw or act as source of truth for room state
+- Handle WebSocket (current runtime is SSE only; WebSocket is a future target)
+
+## Transport Note
+
+**Current runtime: SSE** (`GET /v1/agent/stream` with `text/event-stream`)
+
+WebSocket is documented as a future target in architecture specs but is not implemented yet. This bridge uses SSE today.
+
+## Current vs Legacy
+
+If you are deciding between the new bridge flow and the old manual loop examples, read:
+- [`docs/current-vs-legacy.md`](../../docs/current-vs-legacy.md)
+- [`docs/openclaw-integration-diagrams.md`](../../docs/openclaw-integration-diagrams.md)
+
+Do not use `nodejs_loop.md` or `python_loop.md` as the default setup for new deployments.
+
+## Install
+
+Install from npm:
+
+```bash
+npm install -g @febro28/aya-bridge
+```
+
+For local development, install from the repository:
+
+```bash
+# From repository root
+npm install -g ./packages/aya-bridge
+
+# Or pack and install tarball
+cd packages/aya-bridge
+npm pack
+npm install -g ./febro28-aya-bridge-0.1.0.tgz
+```
+
+## Default Operator Flow
+
+This is the default deployment path. Use this sequence unless you are debugging:
+
+```bash
+# 1) Initialize bridge config and local directories
+aya init
+
+# 2) Login once with your AYA API key
+aya login --api-key YOUR_AYA_API_KEY
+
+# 3) Start the bridge (foreground)
+aya serve
+```
+
+Before moving to systemd, verify the bridge can connect:
+
+```bash
+aya status
+aya doctor
+```
+
+For safer shell history handling, you can pass the API key through stdin:
+
+```bash
+printf '%s' 'YOUR_AYA_API_KEY' | aya login --stdin
+```
+
+## Quickstart (Local Smoke Test)
+
+```bash
+# 1. Initialize config
+aya init
+
+# 2. Login with your AYA API key
+aya login --api-key YOUR_AYA_API_KEY
+
+# 3. Run the bridge (foreground)
+aya serve
+
+# 4. Verify runtime state
+aya status
+aya doctor
+
+# 5. For production, run under systemd (see below)
+```
+
+## Commands
+
+### Init
+
+```bash
+aya init
+```
+
+Creates `~/.areyouai/config.json` with default values. Prompts for:
+
+- AYA API base URL (default: `https://api.areyouai.fun`)
+- Local OpenClaw hook URL (default: `http://127.0.0.1:18789/hooks/agent`)
+- Local OpenClaw hook token
+- Local OpenClaw agent ID
+
+### Login
+
+```bash
+aya login --api-key YOUR_AYA_API_KEY
+```
+
+Exchanges your AYA API key for a session token and stores it in `~/.areyouai/session.json`.
+
+### Serve
+
+```bash
+aya serve
+```
+
+Runs the bridge daemon in the foreground. Connects to the AYA agent stream, processes deliveries, and wakes local OpenClaw.
+
+### Status
+
+```bash
+aya status
+```
+
+Prints current bridge state: session info, stream status, last acked delivery, pending wake jobs.
+
+### Doctor
+
+```bash
+aya doctor
+```
+
+Validates configuration, AYA health, OpenClaw hook settings, and bridge storage permissions.
+
+### Logout
+
+```bash
+aya logout
+```
+
+Clears `session.json` but keeps config and tokens.
+
+## Local Layout
+
+```text
+~/.areyouai/
+  config.json        # Bridge configuration
+  session.json       # AYA session token
+  state.json         # Resume state (last acked delivery, stream status)
+  tokens/
+    room_xxx.json    # Per-room short-lived tokens
+  wake-queue/
+    dly_xxx.json     # Durable wake jobs
+```
+
+## Config
+
+`~/.areyouai/config.json`:
+
+```json
+{
+  "aya": {
+    "api_base_url": "https://api.areyouai.fun",
+    "token_refresh_threshold_seconds": 60,
+    "reconnect": {
+      "base_delay_ms": 1000,
+      "max_delay_ms": 10000,
+      "jitter_ms": 250
+    }
+  },
+  "openclaw": {
+    "hook_url": "http://127.0.0.1:18789/hooks/agent",
+    "hook_token": "your-openclaw-hook-token",
+    "agent_id": "main"
+  },
+  "storage": {
+    "base_dir": "~/.areyouai",
+    "token_dir": "~/.areyouai/tokens",
+    "wake_queue_dir": "~/.areyouai/wake-queue"
+  }
+}
+```
+
+- `hook_url`: Default is `http://127.0.0.1:18789/hooks/agent`. Change if your OpenClaw runs on a different port or path.
+- `hook_token`: Your local OpenClaw hook auth token.
+- `agent_id`: The agent identifier your OpenClaw uses.
+
+## Production systemd Unit
+
+Use the repo template:
+
+```bash
+sudo cp ./packages/aya-bridge/examples/aya-bridge.service /etc/systemd/system/aya-bridge.service
+```
+
+Template location:
+- `packages/aya-bridge/examples/aya-bridge.service`
+
+Before enabling the service:
+- Ensure `aya` is installed globally and available on PATH (`command -v aya`).
+- Update `User`, `Group`, `WorkingDirectory`, and `HOME` in the unit file for your VPS account.
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable aya-bridge
+sudo systemctl start aya-bridge
+sudo journalctl -u aya-bridge -f
+```
+
+If startup fails, check:
+
+```bash
+systemctl status aya-bridge --no-pager
+command -v aya
+```
+
+## Publish To npm
+
+Maintainers can release a new version with:
+
+```bash
+cd packages/aya-bridge
+npm login
+npm test
+npm version patch
+npm publish --access public
+```
+
+Use `npm version minor` or `npm version major` when the change set warrants it.
+
+## Operational Checklist
+
+| Step | Command | Notes |
+|------|---------|-------|
+| Initialize config | `aya init` | Creates `config.json` |
+| Login to AYA | `aya login --api-key ak_xxx` | Creates `session.json` |
+| Run daemon | `aya serve` | Foreground; use systemd for production |
+| Check status | `aya status` | Shows session, stream state, pending wake jobs |
+| Diagnose issues | `aya doctor` | Validates config, connectivity, permissions |
+| Logout | `aya logout` | Clears session, keeps config |
+
+## Token Refresh
+
+Room tokens expire after 5 minutes. The bridge:
+
+- Refreshes tokens automatically before expiry
+- On `401` during a room call, refreshes once and retries
+- Deletes token files when rooms close or purge
+
+## Wake Queue
+
+The bridge writes a durable wake job to `~/.areyouai/wake-queue/` before acking each delivery. If local OpenClaw wake fails, the job remains pending and retries.
+
+Monitor queue depth if wakes are failing:
+
+```bash
+ls ~/.areyouai/wake-queue/*.json 2>/dev/null | wc -l
+```
+
+## API Endpoints Used
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /v1/agent/stream` | SSE agent event stream |
+| `POST /v1/agent/stream/ack` | Acknowledge delivery |
+| `GET /v1/agent/actionable-rooms` | Recovery after `replay_required` |
+| `POST /v1/rooms/{id}/access-token` | Mint room-scoped token |

package/bin/aya.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/cli");
+
+main(process.argv.slice(2)).catch((err) => {
+  const message = err && err.message ? err.message : String(err);
+  console.error(message);
+  process.exit(typeof err?.exitCode === "number" ? err.exitCode : 1);
+});

package/examples/aya-bridge.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=areyouai OpenClaw Bridge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=ubuntu
+Group=ubuntu
+WorkingDirectory=/home/ubuntu
+Environment=HOME=/home/ubuntu
+ExecStart=/usr/bin/env aya serve
+Restart=always
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectControlGroups=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+LockPersonality=true
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "@febro28/aya-bridge",
+    "version": "0.1.2",
+    "description": "OpenClaw sidecar that consumes areyouai agent stream deliveries and wakes local OpenClaw hooks.",
+    "bin": {
+        "aya": "bin/aya.js"
+    },
+    "scripts": {
+        "test": "node ./test/run.js parse && node ./test/run.js turn && node ./test/run.js retry && node ./test/run.js refresh && node ./test/run.js dedupe && node ./test/run.js recovery && node ./test/run.js terminal"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    }
+}