@alfe.ai/gateway 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# @alfe.ai/gateway
+
+Local gateway daemon for Alfe — the always-on control plane for agent integrations.
+
+## Overview
+
+The gateway daemon is a standalone Node.js process that:
+
+- Maintains a persistent WebSocket connection to Alfe cloud (`@alfe/gateway-service` on Fly.io)
+- Exposes a Unix socket at `~/.alfe/gateway.sock` for local plugin IPC
+- Translates between the cloud protocol and local IPC protocol
+- Survives OpenClaw restarts — it's the always-on bridge between cloud and agent
+- Queues commands when plugins are offline (5min TTL)
+
+## Architecture
+
+```
+Alfe Cloud ←—— control WS ——→ @alfe.ai/gateway  (daemon, always running)
+                                     ↕  IPC (~/.alfe/gateway.sock)
+                              @alfe.ai/openclaw    (OpenClaw plugin, Phase 2)
+                                     ↕
+                                OpenClaw process
+```
+
+## Prerequisites
+
+1. Run `alfe login` to configure your API key in `~/.alfe/config.toml`
+2. Node.js 22+
+3. pnpm
+
+## Usage
+
+### Via `alfe` CLI (recommended)
+
+```bash
+# Start daemon (foreground)
+alfe gateway start
+
+# Check status
+alfe gateway status
+
+# Stop daemon
+alfe gateway stop
+
+# Install as system service (auto-start on boot)
+alfe gateway install
+
+# Remove system service
+alfe gateway uninstall
+
+# View logs
+alfe gateway logs
+
+# Full health check
+alfe doctor
+```
+
+### Via standalone binary
+
+```bash
+# Start daemon
+alfe-gateway daemon
+
+# Status
+alfe-gateway status
+
+# Stop
+alfe-gateway stop
+```
+
+## IPC Protocol
+
+Plugins connect to `~/.alfe/gateway.sock` and speak newline-delimited JSON:
+
+### Request (plugin → daemon)
+```json
+{ "type": "req", "id": "uuid", "method": "register", "params": { "name": "my-plugin", "version": "1.0.0", "protocolVersion": 1, "capabilities": ["integrations"] } }
+```
+
+### Response (daemon → plugin)
+```json
+{ "id": "uuid", "ok": true, "payload": { "status": "registered", "daemonVersion": "0.1.0", "protocolVersion": 1 } }
+```
+
+### Event (daemon → plugin)
+```json
+{ "type": "event", "event": "cloud.status", "payload": { "connected": true } }
+```
+
+### Phase 1 Methods
+
+| Direction | Method | Description |
+|-----------|--------|-------------|
+| Daemon→Plugin | `integration.install` | Install an integration |
+| Daemon→Plugin | `integration.remove` | Remove an integration |
+| Daemon→Plugin | `integration.configure` | Update integration config |
+| Daemon→Plugin | `integration.health` | Check integration health |
+| Daemon→Plugin | `integration.activate` | Activate an installed integration |
+| Daemon→Plugin | `integration.deactivate` | Deactivate a running integration |
+| Daemon→Plugin | `integration.list` | List installed integrations |
+| Plugin→Daemon | `register` | Register plugin with daemon |
+| Plugin→Daemon | `status` | Get daemon health status |
+| Plugin→Daemon | `integration.list` | List known integrations |
+| Plugin→Daemon | `integration.report` | Report integration status |
+
+## File Locations
+
+| File | Path |
+|------|------|
+| Config | `~/.alfe/config.toml` |
+| Socket | `~/.alfe/gateway.sock` |
+| PID file | `~/.alfe/gateway.pid` |
+| Logs | `~/.alfe/logs/gateway.log` |
+| launchd plist | `~/Library/LaunchAgents/ai.alfe.gateway.plist` |
+| systemd unit | `~/.config/systemd/user/alfe-gateway.service` |
+
+## Security
+
+- Socket file is `chmod 0600` (owner-only access)
+- PID file prevents multiple daemon instances
+- Secrets pass through in-memory only — never persisted to disk
+- Auth via user's `api_key` from `~/.alfe/config.toml`
+
+## Development
+
+```bash
+# From monorepo root
+pnpm install
+pnpm --filter @alfe.ai/gateway build
+pnpm --filter @alfe.ai/gateway test
+
+# Dev mode (auto-restart on changes)
+pnpm --filter @alfe.ai/gateway dev
+```
+
+## Cloud Protocol
+
+The daemon speaks the following message types with the cloud gateway service:
+
+| Direction | Message | Description |
+|-----------|---------|-------------|
+| Outbound | `SERVICE_REGISTER` | Register daemon with cloud |
+| Inbound | `SERVICE_ACK` | Cloud acknowledges registration |
+| Inbound | `COMMAND` | Cloud sends a command to execute |
+| Outbound | `COMMAND_ACK` | Daemon reports command result |
+| Inbound | `DESIRED_STATE` | Cloud pushes desired integration state |
+| Outbound | `RECONCILIATION_REPORT` | Daemon reports reconciliation results |
+| Inbound | `PING` | Cloud heartbeat |
+| Outbound | `PONG` | Daemon heartbeat response |
+
+See `src/protocol.ts` for full type definitions.
+
+## Completed
+
+- `@alfe.ai/openclaw` plugin connecting via IPC (`packages/openclaw/`)
+- Integration manifest spec (`packages/integration-manifest/`)
+- Integration registry — now DynamoDB-backed via `services/integrations/`
+- Reconciliation engine (`src/reconciliation.ts`) — converges local state to cloud desired state
+
+## Roadmap
+
+- Dashboard integration management (backend wired, UI in progress)
+- Voice migration to integration model (`packages/openclaw-voice/` exists, not yet full integration)

package/dist/bin/gateway.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/gateway.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { a as installService, d as SOCKET_PATH, h as LOG_FILE, i as checkExistingDaemon, n as queryDaemonHealth, o as stopExistingDaemon, r as startDaemon, s as uninstallService, t as formatHealthReport } from "../health.js";
+import { spawn } from "node:child_process";
+//#region bin/gateway.ts
+/**
+* Alfe Gateway CLI — manages the local daemon.
+*
+* Commands:
+*   daemon    - Run the daemon in foreground (used by service managers)
+*   start     - Start the daemon (background via service manager, or foreground fallback)
+*   stop      - Stop a running daemon
+*   restart   - Restart the daemon
+*   status    - Show daemon status
+*   install   - Install as a system service (launchd/systemd)
+*   uninstall - Remove the system service
+*   logs      - Tail daemon logs
+*/
+const command = process.argv[2];
+async function main() {
+	switch (command) {
+		case "daemon":
+			await startDaemon();
+			break;
+		case "start": {
+			const existingPid = await checkExistingDaemon();
+			if (existingPid) {
+				console.log(`Daemon already running (PID ${String(existingPid)})`);
+				process.exit(0);
+			}
+			console.log("Starting Alfe Gateway Daemon...");
+			await startDaemon();
+			break;
+		}
+		case "stop":
+			if (await stopExistingDaemon()) console.log("Daemon stopped");
+			else console.log("Daemon is not running");
+			break;
+		case "restart":
+			if (await stopExistingDaemon()) {
+				console.log("Stopped existing daemon");
+				await new Promise((r) => setTimeout(r, 500));
+			}
+			console.log("Starting Alfe Gateway Daemon...");
+			await startDaemon();
+			break;
+		case "status":
+			try {
+				const health = await queryDaemonHealth(SOCKET_PATH);
+				console.log("\nAlfe Gateway Status\n");
+				console.log(formatHealthReport(health));
+				console.log();
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.log(`\nAlfe Gateway Status\n`);
+				console.log(`  Gateway daemon      ✗  ${message}`);
+				console.log();
+				process.exit(1);
+			}
+			break;
+		case "install":
+			try {
+				const result = await installService();
+				console.log(result);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.error(`Install failed: ${message}`);
+				process.exit(1);
+			}
+			break;
+		case "uninstall":
+			try {
+				const result = await uninstallService();
+				console.log(result);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.error(`Uninstall failed: ${message}`);
+				process.exit(1);
+			}
+			break;
+		case "logs":
+			console.log(`Tailing ${LOG_FILE}\n`);
+			try {
+				spawn("tail", ["-f", LOG_FILE], { stdio: "inherit" }).on("error", () => {
+					console.error(`Cannot tail log file: ${LOG_FILE}`);
+					process.exit(1);
+				});
+			} catch {
+				console.error(`Log file not found: ${LOG_FILE}`);
+				process.exit(1);
+			}
+			break;
+		default:
+			console.log(`
+Alfe Gateway Daemon
+
+Usage: alfe-gateway <command>
+
+Commands:
+  daemon      Run daemon in foreground (for service managers)
+  start       Start the daemon
+  stop        Stop the daemon
+  restart     Restart the daemon
+  status      Show daemon and connection status
+  install     Install as system service (launchd/systemd)
+  uninstall   Remove system service
+  logs        Tail daemon logs
+
+Examples:
+  alfe-gateway start       # Start daemon
+  alfe-gateway status      # Check status
+  alfe-gateway install     # Auto-start on boot
+`);
+			if (command) {
+				console.error(`Unknown command: ${command}`);
+				process.exit(1);
+			}
+	}
+}
+main().catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	console.error("Fatal error:", message);
+	process.exit(1);
+});
+//#endregion
+export {};