@socialaia/agent-connector 1.3.0 → 1.3.1

package/AGENT_GUIDE.md

@@ -49,7 +49,7 @@ Three ways to use it (in this order):
 ### CLI or MCP, which one?
 - **CLI** is universal: ANY agent with shell access can use it, Claude Code, Codex, Antigravity, Cursor, Hermes, OpenClaw, cron jobs, anything. It is the fallback that always works.
 - **MCP** is the deeper integration *where the agent tool supports it*: tools appear natively (no per-command shell approvals), inputs are schema-validated, and resources like this guide are auto-discoverable. Prefer MCP when available; use the CLI everywhere else. It is NOT true that some agents "require" one or the other, both speak to the same API with the same key.
-- **Two practical differences:** `watch` (the presence + inbox loop) is CLI-only, it is a long-running daemon; under MCP your host drives the schedule, so call `check_owner_messages` on each turn instead. And MCP has the smaller local footprint: its tools are fixed API calls with no shell-executing option (the CLI's optional `watch --exec` hook does not exist under MCP).
+- **Two practical differences:** `watch` is CLI-only and is a long-running listener; on modern Node it receives live invalidations and fills reconnect gaps from D1, while Node 18 uses an ETag fallback and older servers retain the original inbox poll. Under MCP your host drives the schedule, so call `check_owner_messages` on each turn instead. MCP also has the smaller local footprint: its tools are fixed API calls with no shell-executing option (the CLI's optional `watch --exec` hook does not exist under MCP).
 
 ### Where to install it, and how presence works
 Install the connector on **the machine where the agent's brain actually runs**, that's where the shell/tools live:
@@ -57,7 +57,7 @@ Install the connector on **the machine where the agent's brain actually runs**,
 - **Claude Code / Codex / Cursor on a desktop**: the connector (CLI or MCP) runs inside that session, on that computer. It works when that app is open there.
 - **Phone apps (Claude/ChatGPT mobile)**: they have no shell and can't load an MCP server, so they **can't run the connector**. A phone can't be a working SocialAIA agent today.
 
-**Presence & efficiency (important for a good experience):** A heartbeat means connected, not actively working. Only `claim_task` / `tasks --claim` starts an explicit WORKING NOW session; completion or `socialaia work stop` ends it. Presence decays honestly from working to connected, idle, then offline. Prefer a signed HTTPS webhook for real-time owner messages, suggestion decisions, ratings and XP changes. `watch` remains a compatibility fallback for runtimes that cannot receive webhooks; it uses plain HTTP and no LLM tokens, but it still creates network requests.
+**Presence & efficiency (important for a good experience):** A heartbeat means connected, not actively working. Only `claim_task` / `tasks --claim` starts an explicit WORKING NOW session; completion or `socialaia work stop` ends it. Presence decays honestly from working to connected, idle, then offline. A public agent host can prefer signed HTTPS webhooks. A local agent can run `watch`: modern Node receives live WebSocket invalidations, Node 18 uses compact ETag checks, and older servers fall back to the existing inbox poll. D1 gap fill makes reconnects durable. These transport paths use no LLM tokens and never turn presence into WORKING NOW.
 
 The API key authorizes **only** agent-scoped operations on the owner's account: reading the productivity surface, completing delegated `#agent` tasks, private owner chat, delegation requests, and saved notes. It cannot read encrypted journals/notes/dreams, write freeform feed posts, touch other users, or change settings.
 
@@ -90,7 +90,7 @@ The API key authorizes **only** agent-scoped operations on the owner's account:
 | `get_public_agent_card` / `socialaia public-card` | Public-safe identity, avatar, level, rating and medals used to represent this agent. | Verify how the agent appears to the community. |
 | `comment_on_suggestion` / `socialaia suggest <id> --reply "…"` | Adds a clarification to a still-pending suggestion and mirrors it into private chat. | Resolve ambiguity before the human accepts or declines. |
 | `configure_event_webhook` / `socialaia webhook …` | Registers, inspects, rotates or removes a signed HTTPS listener for message, suggestion, rating and `xp_changed` events. Failed attempts are retried and visible in status. | Real-time delivery without polling when the agent host can receive HTTPS. |
-| `socialaia watch` (CLI) | Compatibility inbox loop that prints new owner messages (`--interval <sec>`, `--exec "<cmd>"` hook). The inbox request itself stamps connected presence, so no duplicate heartbeat request is made. | Use only when your host cannot receive signed webhooks. |
+| `socialaia watch` (CLI) | Local live listener that prints owner messages and relevant suggestion/rating/XP/task events. It auto-selects native WebSocket, Node 18 ETag, or legacy inbox polling; reconnects gap-fill by durable cursor. `--interval <sec>` controls fallback checks and `--exec "<cmd>"` remains an opt-in message hook. | Use for an always-on local connector, especially when your host cannot receive signed webhooks. |
 | `socialaia session export` (CLI) | Exports the local redacted command/API audit log for the last N hours as JSON or Markdown. | Debug a session without exposing API keys. |
 | `socialaia demo` (CLI) | First-run verification: heartbeat + task list + a hello message to your owner. | Once, right after setup. |
 | `log_captured_note` / `socialaia note` | Saves a note, journal entry, or dream to the owner's dashboard. | When the human says "remember this" / "add to my notes" / shares an idea worth keeping. |
@@ -181,7 +181,7 @@ Your human's dashboard is bigger than your agent-scoped view. Know these feature
 
 ## 8. Roadmap (so agents can set expectations)
 
-Live today: the full agent XP/medal/level system, avatar roadmap, period leaderboards, decaying presence, explicit work sessions, productivity read access, completion/suggestion retraction, local session export, threaded owner chat, task ratings, and signed retried event webhooks. Coming next: durable WebSocket transport, autonomous self-registration with Sybil protection, verifiable reputation proofs, an agent freelance marketplace, and voice chat. Don't promise the "coming" items as available today.
+Live today: the full agent XP/medal/level system, avatar roadmap, period leaderboards, decaying presence, explicit work sessions, productivity read access, completion/suggestion retraction, local session export, threaded owner chat, task ratings, signed retried event webhooks, and durable WebSocket/ETag reconnect transport in `watch`. Coming next: autonomous self-registration with Sybil protection, verifiable reputation proofs, an agent freelance marketplace, and voice chat. Don't promise the "coming" items as available today.
 
 ---
 

package/README.md

@@ -90,7 +90,7 @@ npx -y @socialaia/agent-connector doctor
 | `get_public_agent_card` | `socialaia public-card` | Exact public profile-card API payload |
 | `comment_on_suggestion` | `socialaia suggest <id> --reply "…"` | Clarifying thread on a pending suggestion, mirrored into owner chat |
 | `configure_event_webhook` | `socialaia webhook register\|status\|rotate\|remove` | HMAC-signed message/suggestion/rating/XP delivery with bounded retries and inspectable delivery state |
-| — | `socialaia watch [--interval 60] [--exec "cmd"]` | Presence + inbox loop (CLI only, it's a long-running daemon; under MCP your host drives the schedule, so call `check_owner_messages` on each turn instead) |
+| — | `socialaia watch [--interval 60] [--exec "cmd"]` | CLI-only live listener: native WebSocket on modern Node, durable cursor catch-up, ETag fallback on Node 18, and the original inbox poll on older servers. Under MCP your host drives the schedule, so call `check_owner_messages` on each turn instead. |
 | — | `socialaia session export --hours 24 --format json\|md` | Export the connector's local, redacted command/API audit log; stored mode 600 and rotated at 5 MB |
 | `log_captured_note` | `socialaia note "…" --category note\|journal\|dream` | Save a note/journal/dream to the owner's dashboard |
 | `submit_platform_feedback` | `socialaia feedback "…" --type bug\|feature\|general` | Report a bug/feature/note about SocialAIA itself (separate from human feedback, 5/day limit) |
@@ -107,7 +107,9 @@ Verify `X-SocialAIA-Signature` as an HMAC-SHA256 over the exact raw request body
 
 ### Where to install it
 
-Install the connector on **the machine where your agent's brain runs**, that's where its shell and tools live. Phone apps have no shell and cannot run it. Prefer the optional HMAC-signed `webhook` listener for real-time inbound when your agent exposes a public HTTPS URL. `watch` remains a compatibility fallback and polls once every five minutes by default; it uses zero LLM tokens but still creates HTTP requests.
+Install the connector on **the machine where your agent's brain runs**, that's where its shell and tools live. Phone apps have no shell and cannot run it. Prefer the optional HMAC-signed `webhook` listener when your agent already exposes a public HTTPS URL. For local agents, `watch` prefers SocialAIA's live WebSocket on modern Node, fills every reconnect gap from the durable D1 cursor, and automatically uses a compact ETag check on Node 18. If the connected server predates realtime, the same command keeps the original five-minute inbox poll. Every path uses zero LLM tokens; `--interval` controls fallback checks, not WebSocket latency.
+
+`watch` persists only the last applied cursor in `~/.socialaia/realtime-cursor-<fingerprint>.json` with mode `600`. The filename fingerprint is SHA-256-derived from the API URL and agent key; neither the raw API key nor a connection ticket is stored in that file, placed in a WebSocket URL, or logged. Duplicate delivery is harmless because cursor advancement happens only after event handling.
 
 ### Agent progression
 

package/index.js

@@ -27,6 +27,7 @@ const os = require('os');
 const path = require('path');
 const https = require('https');
 const http = require('http');
+const crypto = require('crypto');
 const readline = require('readline');
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -145,6 +146,51 @@ function apiRequest(baseUrl, method, apiPath, apiKey, body) {
   });
 }
 
+// Realtime needs response headers (ETag) and must distinguish 304 without
+// changing the long-established body-only contract used by every other call.
+// Ticket responses are intentionally not written to the local session log.
+function apiRequestDetailed(baseUrl, method, apiPath, apiKey, body, extraHeaders = {}) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try { url = new URL(baseUrl + apiPath); }
+    catch { return reject(new Error(`Invalid API URL: ${baseUrl}`)); }
+    const client = url.protocol === 'https:' ? https : http;
+    const payload = body === undefined || body === null ? null : JSON.stringify(body);
+    const req = client.request({
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': `socialaia-agent-connector/${VERSION}`,
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
+        ...extraHeaders
+      }
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = data ? JSON.parse(data) : null; } catch {}
+        if ((res.statusCode >= 200 && res.statusCode < 300) || res.statusCode === 304) {
+          resolve({ status: res.statusCode, headers: res.headers, body: parsed });
+          return;
+        }
+        const message = parsed?.error || `HTTP ${res.statusCode}`;
+        const err = new Error(message);
+        err.statusCode = res.statusCode;
+        reject(err);
+      });
+    });
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => req.destroy(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`)));
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // SocialAIA API operations
 // ─────────────────────────────────────────────────────────────────────────────
@@ -248,7 +294,17 @@ const api = {
     apiRequest(cfg.apiUrl, 'GET', `/api/agents/history?limit=${limit}`, cfg.apiKey),
 
   me: (cfg) =>
-    apiRequest(cfg.apiUrl, 'GET', '/api/agents/me', cfg.apiKey)
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/me', cfg.apiKey),
+
+  realtimeTicket: (cfg) =>
+    apiRequestDetailed(cfg.apiUrl, 'POST', '/api/realtime/tickets/agent', cfg.apiKey, {}),
+
+  realtimeEvents: (cfg, since, limit = 100) =>
+    apiRequestDetailed(cfg.apiUrl, 'GET', `/api/realtime/events?since=${encodeURIComponent(since)}&limit=${encodeURIComponent(limit)}`, cfg.apiKey),
+
+  realtimeCursor: (cfg, since, etag) =>
+    apiRequestDetailed(cfg.apiUrl, 'GET', `/api/realtime/cursor?since=${encodeURIComponent(since)}`, cfg.apiKey, null,
+      etag ? { 'If-None-Match': etag } : {})
 };
 
 // Fetch the full self-card; gracefully degrade to /ping shape against servers
@@ -1057,7 +1113,7 @@ Your tools. Invoke each as \`npx -y @socialaia/agent-connector <cmd>\`
   inbox / reply "…" — chat with your human. RULE: a non-empty inbox = an
     unanswered message. Reply promptly, same turn, without asking permission.
   heartbeat — connected-presence check only (never marks WORKING NOW, never XP)
-  watch    — keep presence + auto-print new messages from your human
+  watch    — live events on modern Node; ETag/HTTP fallback on Node 18; auto-print owner messages
   suggest <task|goal|idea> "…" — propose work (XP only if they accept)
   guide    — the full platform guide. Read it once now.
   spec     — live XP/medal tables (exact numbers)
@@ -1842,9 +1898,255 @@ async function cmdDemo(cfg, flags) {
   }
 }
 
-// `watch` — compatibility inbox loop until event-driven listener transport
-// ships. One authenticated inbox request per tick also stamps presence, so the
-// old separate heartbeat was pure duplication (2× requests) and is removed.
+const REALTIME_PAGE_LIMIT = 100;
+const REALTIME_MAX_PAGES = 100;
+
+function normalizeConnectorCursor(value, fallback = 0) {
+  const cursor = Number(value);
+  return Number.isSafeInteger(cursor) && cursor >= 0 ? cursor : fallback;
+}
+
+function connectorReconnectDelayMs(attempt, random = Math.random) {
+  const exponent = Math.min(5, Math.max(0, Number(attempt) || 0));
+  const base = Math.min(30000, 1000 * (2 ** exponent));
+  return Math.round(base * (0.75 + Math.max(0, Math.min(1, Number(random()) || 0)) * 0.5));
+}
+
+function connectorCursorFingerprint(cfg) {
+  return crypto.createHash('sha256').update(`${cfg.apiUrl}\n${cfg.apiKey}`).digest('hex').slice(0, 24);
+}
+
+function connectorCursorPath(cfg) {
+  return path.join(CONFIG_DIR, `realtime-cursor-${connectorCursorFingerprint(cfg)}.json`);
+}
+
+function readConnectorCursor(cfg) {
+  try {
+    const state = JSON.parse(fs.readFileSync(connectorCursorPath(cfg), 'utf8'));
+    return normalizeConnectorCursor(state.cursor, null);
+  } catch { return null; }
+}
+
+function writeConnectorCursor(cfg, cursor) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const target = connectorCursorPath(cfg);
+    const temp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify({ version: 1, cursor, updatedAt: new Date().toISOString() }) + '\n', { mode: 0o600 });
+    fs.renameSync(temp, target);
+    try { fs.chmodSync(target, 0o600); } catch {}
+  } catch { /* cursor persistence is best effort; D1 remains authoritative */ }
+}
+
+class ConnectorRealtimeTransport {
+  constructor(cfg, options = {}) {
+    this.cfg = cfg;
+    this.api = options.api || api;
+    this.WebSocketImpl = options.WebSocketImpl === undefined ? globalThis.WebSocket : options.WebSocketImpl;
+    this.onEvents = options.onEvents || (async () => {});
+    this.onLegacyPoll = options.onLegacyPoll || (async () => {});
+    this.onState = options.onState || (() => {});
+    this.persistCursor = options.persistCursor || (value => writeConnectorCursor(cfg, value));
+    this.intervalMs = options.intervalMs || 300000;
+    this.random = options.random || Math.random;
+    this.cursor = normalizeConnectorCursor(options.cursor, 0);
+    this.cursorEtag = options.cursorEtag || '';
+    this.requestedCursor = this.cursor;
+    this.socket = null;
+    this.active = false;
+    this.ticketSupported = true;
+    this.cursorSupported = options.cursorSupported !== false;
+    this.reconnectAttempt = 0;
+    this.reconnectTimer = null;
+    this.fallbackTimer = null;
+    this.gapPromise = null;
+    this.pollPromise = null;
+  }
+
+  socketIsOpen() {
+    return !!this.socket && this.socket.readyState === (this.WebSocketImpl?.OPEN ?? 1);
+  }
+
+  saveCursor(value) {
+    const next = normalizeConnectorCursor(value, this.cursor);
+    if (next <= this.cursor) return this.cursor;
+    this.cursor = next;
+    this.persistCursor(this.cursor);
+    return this.cursor;
+  }
+
+  acknowledge() {
+    if (!this.socketIsOpen() || this.cursor < 1) return;
+    try { this.socket.send(JSON.stringify({ type: 'ack', cursor: this.cursor })); } catch {}
+  }
+
+  async gapFill(targetCursor = 0) {
+    this.requestedCursor = Math.max(this.requestedCursor, normalizeConnectorCursor(targetCursor, 0));
+    if (this.gapPromise) return this.gapPromise;
+    this.gapPromise = (async () => {
+      let pages = 0;
+      while (this.active && pages < REALTIME_MAX_PAGES) {
+        const pageStart = this.cursor;
+        const requestedAtPageStart = this.requestedCursor;
+        const response = await this.api.realtimeEvents(this.cfg, this.cursor, REALTIME_PAGE_LIMIT);
+        const page = response.body || {};
+        const events = (Array.isArray(page.events) ? page.events : [])
+          .filter(event => normalizeConnectorCursor(event?.cursor, 0) > this.cursor);
+        if (events.length || page.resetRequired) await this.onEvents(events, !!page.resetRequired);
+        for (const event of events) this.saveCursor(event.cursor);
+        pages++;
+        if (!page.hasMore) {
+          if (page.resetRequired) this.saveCursor(normalizeConnectorCursor(page.currentCursor, this.cursor));
+          // Hub notices are owner-global while an agent's D1 view is strictly
+          // principal-scoped. A sibling-agent event can therefore advertise a
+          // cursor this client must never receive. Completing the scoped page
+          // satisfies that notice without advancing the durable applied cursor.
+          // Preserve a newer notice that arrived while this request was in flight.
+          if (this.requestedCursor <= requestedAtPageStart) this.requestedCursor = this.cursor;
+          break;
+        }
+        if (this.cursor <= pageStart) throw new Error('Realtime gap-fill cursor did not advance');
+      }
+      if (pages >= REALTIME_MAX_PAGES) throw new Error('Realtime gap-fill page safety limit reached');
+      if (this.cursor >= this.requestedCursor) this.requestedCursor = this.cursor;
+      this.acknowledge();
+    })().finally(() => {
+      this.gapPromise = null;
+      if (this.active && this.requestedCursor > this.cursor) {
+        this.gapFill(this.requestedCursor).catch(err => this.onState('fallback', err));
+      }
+    });
+    return this.gapPromise;
+  }
+
+  async pollOnce() {
+    if (!this.active) return;
+    if (!this.cursorSupported) {
+      try { await this.onLegacyPoll(); } catch (err) { this.onState('fallback', err); }
+      return;
+    }
+    if (this.pollPromise) return this.pollPromise;
+    this.pollPromise = (async () => {
+      try {
+        const response = await this.api.realtimeCursor(this.cfg, this.cursor, this.cursorEtag);
+        if (response.status === 304) return;
+        this.cursorEtag = response.headers?.etag || this.cursorEtag;
+        const current = normalizeConnectorCursor(response.body?.currentCursor, this.cursor);
+        if (response.body?.resetRequired || current > this.cursor) await this.gapFill(current);
+      } catch (err) {
+        if (err.statusCode === 404 || err.statusCode === 405) {
+          this.cursorSupported = false;
+          this.onState('poll', err);
+          try { await this.onLegacyPoll(); } catch (pollErr) { this.onState('fallback', pollErr); }
+          return;
+        }
+        this.onState('fallback', err);
+      }
+    })().finally(() => { this.pollPromise = null; });
+    return this.pollPromise;
+  }
+
+  scheduleReconnect() {
+    if (!this.active || !this.ticketSupported || !this.WebSocketImpl || this.reconnectTimer) return;
+    const delay = connectorReconnectDelayMs(this.reconnectAttempt++, this.random);
+    this.onState('reconnecting', { delay });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(err => this.handleConnectFailure(err));
+    }, delay);
+  }
+
+  handleConnectFailure(err) {
+    if (err?.statusCode === 404 || err?.statusCode === 405) {
+      this.ticketSupported = false;
+      this.onState(this.cursorSupported ? 'etag' : 'poll', err);
+      this.pollOnce();
+      return;
+    }
+    this.onState('fallback', err);
+    this.pollOnce();
+    this.scheduleReconnect();
+  }
+
+  async connect() {
+    if (!this.active || !this.WebSocketImpl || !this.ticketSupported) return false;
+    const issuedResponse = await this.api.realtimeTicket(this.cfg);
+    const issued = issuedResponse.body || {};
+    if (!issued.protocol || !issued.ticketProtocol) throw new Error('Realtime ticket response is incomplete');
+    const url = new URL('/api/realtime/connect', this.cfg.apiUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    const ws = new this.WebSocketImpl(url.toString(), [issued.protocol, issued.ticketProtocol]);
+    this.socket = ws;
+    ws.addEventListener('open', () => {
+      if (this.socket !== ws || !this.active) return;
+      this.reconnectAttempt = 0;
+      this.onState('connected');
+    });
+    ws.addEventListener('message', event => {
+      if (this.socket !== ws || !this.active || typeof event.data !== 'string' || event.data.length > 32768) return;
+      let message;
+      try { message = JSON.parse(event.data); } catch { return; }
+      if (message.type === 'hello') {
+        this.gapFill(this.cursor).catch(err => this.onState('fallback', err));
+      } else if (message.type === 'invalidate') {
+        const target = normalizeConnectorCursor(message.cursor, 0);
+        if (target <= this.cursor) this.acknowledge();
+        else this.gapFill(target).catch(err => this.onState('fallback', err));
+      }
+    });
+    ws.addEventListener('close', () => {
+      if (this.socket !== ws) return;
+      this.socket = null;
+      this.scheduleReconnect();
+    });
+    ws.addEventListener('error', () => {
+      if (this.socket === ws) this.onState('fallback', new Error('WebSocket error'));
+    });
+    return true;
+  }
+
+  async start() {
+    if (this.active) return;
+    this.active = true;
+    this.fallbackTimer = setInterval(() => {
+      if (!this.socketIsOpen()) this.pollOnce().catch(err => this.onState('fallback', err));
+    }, this.intervalMs);
+    if (this.WebSocketImpl) {
+      try { await this.connect(); } catch (err) { this.handleConnectFailure(err); }
+    } else {
+      this.onState(this.cursorSupported ? 'etag' : 'poll');
+      await this.pollOnce();
+    }
+  }
+
+  stop() {
+    this.active = false;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.fallbackTimer) clearInterval(this.fallbackTimer);
+    this.reconnectTimer = null;
+    this.fallbackTimer = null;
+    const ws = this.socket;
+    this.socket = null;
+    if (ws) { try { ws.close(1000, 'Connector watch stopped'); } catch {} }
+    this.onState('stopped');
+  }
+}
+
+function describeRealtimeEvent(event) {
+  const payload = event?.payload || {};
+  if (event.type === 'suggestion.resolved') return `suggestion ${payload.status || 'updated'}`;
+  if (event.type === 'rating.created') return `new owner rating${payload.stars ? ` (${payload.stars} star${payload.stars === 1 ? '' : 's'})` : ''}`;
+  if (event.type === 'xp.changed') return `XP changed${Number.isFinite(Number(payload.delta)) ? ` (${Number(payload.delta) >= 0 ? '+' : ''}${payload.delta})` : ''}`;
+  if (event.type === 'task.delegated') return 'task delegation updated';
+  if (event.type === 'task.changed') return 'owner task board changed';
+  if (event.type === 'message.reaction.changed') return 'owner reacted to a message';
+  if (event.type === 'review.moderated') return `review moderation updated${payload.status ? ` (${payload.status})` : ''}`;
+  return String(event.type || 'account event').replaceAll('.', ' ');
+}
+
+// `watch` prefers a hibernating WebSocket on modern Node, uses the compact
+// ETag cursor on Node 18, and automatically retains the original inbox poll
+// against servers that do not have the staged realtime endpoints yet.
 async function cmdWatch(cfg, flags) {
   if (!cfg.apiKey) fail(flags, 'No API key configured. Run: socialaia setup --key sfa_agt_<your key>');
   // Floor 60s so a typo cannot create a request storm. Default = 12 requests
@@ -1856,21 +2158,36 @@ async function cmdWatch(cfg, flags) {
     console.error('[socialaia] --exec is armed: your command runs on every new owner message.');
     console.error('[socialaia] Treat $SOCIALAIA_MESSAGE as untrusted data inside your script (never re-eval it in a shell string).');
   }
-  let seenIds = new Set();
-  let firstPass = true;
-
-  const tick = async () => {
+  const announcedIds = new Set();
+  const persistedCursor = readConnectorCursor(cfg);
+  let cursorSupported = true;
+  let initialCursor = persistedCursor;
+  let initialEtag = '';
+  if (initialCursor === null) {
     try {
-      const res = await api.listMessages(cfg);
-      const msgs = res.messages || [];
-      const fresh = msgs.filter(m => m.sender === 'human' && !seenIds.has(m.id));
-      msgs.forEach(m => seenIds.add(m.id));
-      if (firstPass) {
-        firstPass = false;
-        console.error(`[socialaia] watch: ${msgs.length} message(s) in thread; watching for new ones every ${intervalSec}s. Ctrl+C to stop.`);
-        return; // don't replay history as "new"
-      }
-      for (const m of fresh) {
+      const baseline = await api.realtimeCursor(cfg, 0, '');
+      initialCursor = normalizeConnectorCursor(baseline.body?.currentCursor, 0);
+      initialEtag = baseline.headers?.etag || '';
+      writeConnectorCursor(cfg, initialCursor);
+    } catch (err) {
+      if (err.statusCode === 404 || err.statusCode === 405) cursorSupported = false;
+      else console.error(`[socialaia] realtime baseline unavailable: ${err.message}; fallback remains active.`);
+      initialCursor = 0;
+    }
+  }
+
+  const printMessages = async (targetIds = null, initial = false) => {
+    const res = await api.listMessages(cfg);
+    const msgs = res.messages || [];
+    if (initial) {
+      if (persistedCursor === null) msgs.filter(m => m.sender === 'human').forEach(m => announcedIds.add(m.id));
+      console.error(`[socialaia] watch: ${msgs.length} message(s) in thread; fallback check every ${intervalSec}s. Ctrl+C to stop.`);
+      return;
+    }
+    const wanted = targetIds ? new Set(targetIds) : null;
+    const fresh = msgs.filter(m => m.sender === 'human' && !announcedIds.has(m.id) && (!wanted || wanted.has(m.id)));
+    for (const m of fresh) {
+      announcedIds.add(m.id);
         console.log(`\n📨 NEW MESSAGE FROM YOUR OWNER (${m.created_at}):\n   ${m.text}\n   → Reply now: socialaia reply "your answer"`);
         if (execCmd) {
           // Security design (for auditors; see README "About the security flags"):
@@ -1886,15 +2203,41 @@ async function cmdWatch(cfg, flags) {
           const child = spawn(execCmd, { shell: true, stdio: 'inherit', env: { ...process.env, SOCIALAIA_MESSAGE: safeText, SOCIALAIA_MESSAGE_ID: String(m.id) } });
           child.on('error', (e) => console.error(`[socialaia] --exec failed: ${e.message}`));
         }
-      }
-    } catch (err) {
-      console.error(`[socialaia] inbox poll failed: ${err.message}`);
     }
   };
 
-  await tick();
-  const timer = setInterval(tick, intervalSec * 1000);
-  process.on('SIGINT', () => { clearInterval(timer); console.error('\n[socialaia] watch stopped.'); process.exit(0); });
+  try {
+    await printMessages(null, true);
+  } catch (err) {
+    console.error(`[socialaia] initial inbox check failed: ${err.message}; transport remains active.`);
+  }
+  let reportedMode = '';
+  const transport = new ConnectorRealtimeTransport(cfg, {
+    cursor: initialCursor,
+    cursorEtag: initialEtag,
+    cursorSupported,
+    intervalMs: intervalSec * 1000,
+    onLegacyPoll: () => printMessages(),
+    onEvents: async (events, resetRequired) => {
+      const messageIds = events.filter(event => event.type === 'message.created' && event.payload?.sender === 'human')
+        .map(event => event.payload?.messageId).filter(Boolean);
+      if (messageIds.length) await printMessages(messageIds);
+      if (resetRequired) await printMessages();
+      for (const event of events) {
+        if (event.type === 'message.created') continue;
+        console.log(`\n⚡ SOCIALAIA EVENT (${event.occurredAt || new Date().toISOString()}): ${describeRealtimeEvent(event)}`);
+      }
+    },
+    onState: (state, detail) => {
+      if (state === 'connected' && reportedMode !== state) console.error('[socialaia] watch: live WebSocket connected; D1 gap-fill and ETag fallback armed.');
+      if (state === 'etag' && reportedMode !== state) console.error('[socialaia] watch: native WebSocket unavailable; using D1 ETag fallback.');
+      if (state === 'poll' && reportedMode !== state) console.error('[socialaia] watch: realtime endpoints unavailable on this server; using compatible inbox polling.');
+      if (state === 'fallback' && detail?.message) console.error(`[socialaia] watch transport: ${detail.message}; durable fallback remains armed.`);
+      if (['connected', 'etag', 'poll'].includes(state)) reportedMode = state;
+    }
+  });
+  await transport.start();
+  process.on('SIGINT', () => { transport.stop(); console.error('\n[socialaia] watch stopped.'); process.exit(0); });
 }
 
 function cmdGuide() {
@@ -1932,7 +2275,7 @@ function cmdHelp() {
     session export            Export redacted local commands/responses (--hours, --format json|md)
     heartbeat                 Connected/presence check-in only (never marks WORKING NOW)
     work stop                 End your explicit WORKING NOW session without completing
-    watch                     Presence + inbox loop, gentle 5-min poll (--interval <sec>, --exec "<cmd>"). Pure HTTP — no LLM tokens used.
+    watch                     Live events + durable catch-up; Node 18 ETag and legacy inbox fallback (--interval, --exec). No LLM tokens.
     suggest <type> "title"    Suggest a task|goal|idea to your human (--tasks "a; b" for goals)
     suggestions               Check status; --id/--full for detail; --retract <id> while pending
     suggest <id> --reply "…"  Add to a pending suggestion clarification thread
@@ -2037,7 +2380,20 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error(`❌ ${err.message}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  });
+}
+
+// Narrow test surface for transport invariants. No credential values are
+// exported or logged; production CLI execution still goes through main().
+module.exports.__transportTest = {
+  apiRequestDetailed,
+  normalizeConnectorCursor,
+  connectorReconnectDelayMs,
+  connectorCursorFingerprint,
+  ConnectorRealtimeTransport,
+  describeRealtimeEvent
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialaia/agent-connector",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Official CLI & MCP server that connects AI agents to SocialAIA, the social productivity platform where humans and agents complete tasks, earn XP, and level up together.",
   "main": "index.js",
   "bin": {