@alfe.ai/gateway 0.9.5 → 0.9.6

package/README.md

@@ -1,6 +1,7 @@
 # @alfe.ai/gateway
 
-Local gateway daemon for Alfe — the always-on control plane for agent integrations.
+Local gateway daemon for Alfe — the always-on control plane between an agent VM,
+its runtime, and Alfe cloud.
 
 ## Overview
 
@@ -8,23 +9,24 @@ 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)
+- Reconciles integrations and state-shaped runtime config from full cloud snapshots
+- Supervises the selected runtime (`openclaw`, `hermes`, or `claude-code`)
+- Hosts the local AI proxy and MCP bundler
+- Survives runtime restarts and reports lifecycle/health back to cloud
 
 ## Architecture
 
 ```
-Alfe Cloud ←—— control WS ——→ @alfe.ai/gateway  (daemon, always running)
-                                     ↕  IPC (~/.alfe/gateway.sock)
-                              @alfe.ai/openclaw    (OpenClaw plugin, Phase 2)
-                                     ↕
-                                OpenClaw process
+Alfe Cloud ←—— control WS ——→ @alfe.ai/gateway (daemon)
+                                     ├── runtime supervisor → OpenClaw/Hermes/Claude host
+                                     ├── integration reconciliation
+                                     ├── local AI proxy + MCP bundler
+                                     └── IPC (~/.alfe/gateway.sock) ← runtime plugins/CLI
 ```
 
 ## Prerequisites
 
-1. Run `alfe login` to configure your API key in `~/.alfe/config.toml`
+1. Run `alfe setup` (or managed provisioning) to configure agent identity
 2. Node.js 22+
 3. pnpm
 
@@ -58,8 +60,8 @@ alfe doctor
 ### Via standalone binary
 
 ```bash
-# Start daemon
-alfe-gateway daemon
+# Start daemon in foreground
+alfe-gateway start
 
 # Status
 alfe-gateway status
@@ -79,7 +81,7 @@ Plugins connect to `~/.alfe/gateway.sock` and speak newline-delimited JSON:
 
 ### Response (daemon → plugin)
 ```json
-{ "id": "uuid", "ok": true, "payload": { "status": "registered", "daemonVersion": "0.1.0", "protocolVersion": 1 } }
+{ "id": "uuid", "ok": true, "payload": { "status": "registered", "daemonVersion": "<current CLI version>", "protocolVersion": 1 } }
 ```
 
 ### Event (daemon → plugin)
@@ -87,21 +89,21 @@ Plugins connect to `~/.alfe/gateway.sock` and speak newline-delimited JSON:
 { "type": "event", "event": "cloud.status", "payload": { "connected": true } }
 ```
 
-### Phase 1 Methods
+### Current 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 |
+| Daemon→Plugin | `runtime.activity` | Probe whether a chat turn is in flight before a planned restart |
 | 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 |
+| Plugin→Daemon | `mcp.list_tools` / `mcp.call_tool` | Inspect or invoke bundled MCP tools |
+| Plugin→Daemon | `mcp.list_servers` / `mcp.add_server` / `mcp.remove_server` | Manage local MCP servers |
+
+IPC is owner-only, newline-delimited JSON. Requests must contain non-empty
+`id`/`method` fields and an object `params`; individual messages are capped at
+1 MiB.
 
 ## File Locations
 
@@ -113,13 +115,15 @@ Plugins connect to `~/.alfe/gateway.sock` and speak newline-delimited JSON:
 | Logs | `~/.alfe/logs/gateway.log` |
 | launchd plist | `~/Library/LaunchAgents/ai.alfe.gateway.plist` |
 | systemd unit | `~/.config/systemd/user/alfe-gateway.service` |
+| managed systemd environment | `~/.alfe/gateway.env` (or `/etc/alfe/gateway.env` for root) |
 
 ## 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`
+- PID ownership is verified against the live process command before signals are sent
+- Managed systemd credentials are stored in an owner-only (`0600`) environment file, not the unit text
+- Credential fragments are never logged
+- Auth uses the agent API key from managed environment or `~/.alfe/config.toml`
 
 ## Development
 
@@ -128,6 +132,8 @@ Plugins connect to `~/.alfe/gateway.sock` and speak newline-delimited JSON:
 pnpm install
 pnpm --filter @alfe.ai/gateway build
 pnpm --filter @alfe.ai/gateway test
+pnpm --filter @alfe.ai/gateway lint
+pnpm --filter @alfe.ai/gateway typecheck
 
 # Dev mode (auto-restart on changes)
 pnpm --filter @alfe.ai/gateway dev
@@ -145,22 +151,15 @@ The daemon speaks the following message types with the cloud gateway service:
 | Outbound | `COMMAND_ACK` | Daemon reports command result |
 | Inbound | `DESIRED_STATE` | Cloud pushes desired integration state |
 | Outbound | `RECONCILIATION_REPORT` | Daemon reports reconciliation results |
+| Outbound | `COMMANDS_AVAILABLE` | Daemon advertises integration commands |
 | 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)
+`DESIRED_STATE` is an atomic, deletion-capable snapshot. The daemon validates
+every nested entry and rejects the entire frame when one row is malformed or
+duplicated. It also skips all mutation if local integration state cannot be
+read. See `src/protocol.ts`, `src/reconciliation.ts`, and `DEVELOPING.md` for the
+full contracts.
 
 ## Links