patchcord 0.4.3 → 0.5.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging with push delivery. Messages from other agents arrive as native channel notifications.",
-  "version": "0.3.98",
+  "version": "0.5.1",
   "author": {
     "name": "ppravdin"
   },

package/commands/subscribe.toml

@@ -0,0 +1 @@
+prompt = "Start the Patchcord background listener per the patchcord:subscribe skill. Spawn scripts/subscribe.mjs with run_in_background, attach the Monitor tool to its stdout, and when a 'PATCHCORD:' line appears, announce it briefly and call inbox() to handle any new messages."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/scripts/lib/ws.mjs

@@ -0,0 +1,229 @@
+// Minimal WebSocket client (RFC 6455 subset).
+// Zero dependencies, stdlib only — TLS + HTTP/1.1 Upgrade + text frames.
+// Designed for Supabase Realtime: single-frame text messages, no extensions,
+// no fragmentation, no binary.
+
+import { connect as tlsConnect } from "node:tls";
+import { connect as netConnect } from "node:net";
+import { createHash, randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { URL } from "node:url";
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+export function connect(urlStr, { headers = {} } = {}) {
+  const emitter = new EventEmitter();
+  const url = new URL(urlStr);
+  const isTls = url.protocol === "wss:";
+  const port = url.port ? Number(url.port) : isTls ? 443 : 80;
+  const key = randomBytes(16).toString("base64");
+  const expectedAccept = createHash("sha1").update(key + GUID).digest("base64");
+
+  const path = url.pathname + (url.search || "") || "/";
+  const host = url.host;
+
+  const reqHeaders = [
+    `GET ${path} HTTP/1.1`,
+    `Host: ${host}`,
+    "Upgrade: websocket",
+    "Connection: Upgrade",
+    `Sec-WebSocket-Key: ${key}`,
+    "Sec-WebSocket-Version: 13",
+  ];
+  for (const [k, v] of Object.entries(headers)) {
+    reqHeaders.push(`${k}: ${v}`);
+  }
+  const req = reqHeaders.join("\r\n") + "\r\n\r\n";
+
+  const socket = isTls
+    ? tlsConnect({ host: url.hostname, port, servername: url.hostname })
+    : netConnect({ host: url.hostname, port });
+
+  let handshakeDone = false;
+  let buf = Buffer.alloc(0);
+  let closed = false;
+
+  const close = (code = 1000, reason = "") => {
+    if (closed) return;
+    closed = true;
+    try {
+      socket.write(encodeFrame(0x8, closePayload(code, reason), true));
+    } catch (_) {}
+    socket.end();
+  };
+
+  const send = (str) => {
+    if (closed) throw new Error("WebSocket closed");
+    const payload = Buffer.from(str, "utf8");
+    socket.write(encodeFrame(0x1, payload, true));
+  };
+
+  socket.on("error", (err) => {
+    if (!closed) {
+      closed = true;
+      emitter.emit("error", err);
+    }
+  });
+
+  socket.on("close", () => {
+    if (!closed) {
+      closed = true;
+      emitter.emit("close");
+    }
+  });
+
+  const onConnect = () => {
+    socket.write(req);
+  };
+  if (isTls) socket.on("secureConnect", onConnect);
+  else socket.on("connect", onConnect);
+
+  socket.on("data", (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    if (!handshakeDone) {
+      const idx = buf.indexOf("\r\n\r\n");
+      if (idx === -1) return;
+      const header = buf.slice(0, idx).toString("utf8");
+      buf = buf.slice(idx + 4);
+      const lines = header.split("\r\n");
+      const status = lines[0];
+      if (!/^HTTP\/1\.1 101/.test(status)) {
+        emitter.emit("error", new Error(`handshake failed: ${status}`));
+        close();
+        return;
+      }
+      const accept = lines
+        .find((l) => /^sec-websocket-accept:/i.test(l))
+        ?.split(":")[1]
+        ?.trim();
+      if (accept !== expectedAccept) {
+        emitter.emit("error", new Error("invalid Sec-WebSocket-Accept"));
+        close();
+        return;
+      }
+      handshakeDone = true;
+      emitter.emit("open");
+    }
+
+    // Parse as many frames as we have data for
+    while (buf.length >= 2) {
+      const parsed = decodeFrame(buf);
+      if (parsed === null) break; // need more data
+      const { opcode, payload, consumed } = parsed;
+      buf = buf.slice(consumed);
+
+      if (opcode === 0x1) {
+        emitter.emit("message", payload.toString("utf8"));
+      } else if (opcode === 0x8) {
+        // close frame
+        emitter.emit("close");
+        closed = true;
+        try {
+          socket.write(encodeFrame(0x8, closePayload(1000, ""), true));
+        } catch (_) {}
+        socket.end();
+        return;
+      } else if (opcode === 0x9) {
+        // ping → pong
+        socket.write(encodeFrame(0xa, payload, true));
+      } else if (opcode === 0xa) {
+        // pong — ignore
+      } else {
+        // unsupported opcode (binary/continuation/extensions) → close
+        emitter.emit("error", new Error(`unsupported opcode 0x${opcode.toString(16)}`));
+        close(1003, "unsupported");
+        return;
+      }
+    }
+  });
+
+  emitter.send = send;
+  emitter.close = close;
+  return emitter;
+}
+
+function encodeFrame(opcode, payload, mask) {
+  const len = payload.length;
+  let header;
+  if (len < 126) {
+    header = Buffer.from([0x80 | opcode, (mask ? 0x80 : 0) | len]);
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | opcode;
+    header[1] = (mask ? 0x80 : 0) | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | opcode;
+    header[1] = (mask ? 0x80 : 0) | 127;
+    // Write big-endian 64-bit length. JS safe-integer limit (2^53) is well
+    // above anything we'll ever send over this client.
+    header.writeUInt32BE(0, 2);
+    header.writeUInt32BE(len, 6);
+  }
+
+  if (!mask) return Buffer.concat([header, payload]);
+
+  const maskKey = randomBytes(4);
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) {
+    masked[i] = payload[i] ^ maskKey[i % 4];
+  }
+  return Buffer.concat([header, maskKey, masked]);
+}
+
+function decodeFrame(buf) {
+  if (buf.length < 2) return null;
+  const b0 = buf[0];
+  const b1 = buf[1];
+  const fin = (b0 & 0x80) !== 0;
+  const opcode = b0 & 0x0f;
+  const masked = (b1 & 0x80) !== 0;
+  let len = b1 & 0x7f;
+  let offset = 2;
+
+  if (len === 126) {
+    if (buf.length < offset + 2) return null;
+    len = buf.readUInt16BE(offset);
+    offset += 2;
+  } else if (len === 127) {
+    if (buf.length < offset + 8) return null;
+    const hi = buf.readUInt32BE(offset);
+    const lo = buf.readUInt32BE(offset + 4);
+    len = hi * 0x100000000 + lo;
+    offset += 8;
+  }
+
+  let maskKey = null;
+  if (masked) {
+    if (buf.length < offset + 4) return null;
+    maskKey = buf.slice(offset, offset + 4);
+    offset += 4;
+  }
+
+  if (buf.length < offset + len) return null;
+
+  let payload = buf.slice(offset, offset + len);
+  if (maskKey) {
+    const unmasked = Buffer.alloc(len);
+    for (let i = 0; i < len; i++) {
+      unmasked[i] = payload[i] ^ maskKey[i % 4];
+    }
+    payload = unmasked;
+  }
+
+  if (!fin) {
+    // Reject fragmentation — Supabase Realtime never fragments.
+    throw new Error("fragmented frames not supported");
+  }
+
+  return { opcode, payload, consumed: offset + len };
+}
+
+function closePayload(code, reason) {
+  const reasonBuf = Buffer.from(reason, "utf8");
+  const payload = Buffer.alloc(2 + reasonBuf.length);
+  payload.writeUInt16BE(code, 0);
+  reasonBuf.copy(payload, 2);
+  return payload;
+}

package/scripts/subscribe.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// Patchcord subscribe: background listener that wakes Claude when new
+// messages arrive for this agent. Connects to Supabase Realtime via
+// WebSocket, prints one line to stdout per incoming INSERT event.
+//
+// Launched by the /patchcord:subscribe skill with run_in_background.
+// Claude Code's Monitor tool watches our stdout and surfaces each
+// "PATCHCORD: ..." line as a notification.
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+import { URL } from "node:url";
+import { connect as wsConnect } from "./lib/ws.mjs";
+
+const JWT_REFRESH_SAFETY_MARGIN_SEC = 120;
+const HEARTBEAT_INTERVAL_MS = 25_000;
+const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 15_000, 30_000];
+
+function die(msg, code = 1) {
+  process.stderr.write(msg + "\n");
+  process.exit(code);
+}
+
+function readMcpConfig(cwd) {
+  const path = `${cwd}/.mcp.json`;
+  if (!existsSync(path)) die(`no .mcp.json in ${cwd}`);
+  let json;
+  try {
+    json = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    die(`.mcp.json parse error: ${e.message}`);
+  }
+  const pc = json?.mcpServers?.patchcord;
+  if (!pc?.url || !pc?.headers?.Authorization) {
+    die(".mcp.json missing mcpServers.patchcord.url or Authorization");
+  }
+  let baseUrl = pc.url;
+  // Strip known MCP path suffixes to get the API base
+  baseUrl = baseUrl.replace(/\/mcp\/bearer$/, "").replace(/\/mcp$/, "");
+  const auth = pc.headers.Authorization;
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : auth;
+  return { baseUrl, token };
+}
+
+function httpJson(urlStr, { method = "GET", headers = {}, body = null } = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const lib = url.protocol === "https:" ? httpsRequest : httpRequest;
+    const req = lib(
+      {
+        method,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "https:" ? 443 : 80),
+        path: url.pathname + (url.search || ""),
+        headers,
+      },
+      (res) => {
+        let chunks = "";
+        res.setEncoding("utf8");
+        res.on("data", (c) => (chunks += c));
+        res.on("end", () => resolve({ status: res.statusCode, body: chunks }));
+      }
+    );
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+async function fetchTicket(baseUrl, token) {
+  const res = await httpJson(`${baseUrl}/api/realtime/ticket`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 401 || res.status === 403) {
+    die(`ticket: token rejected (HTTP ${res.status}) — check .mcp.json`);
+  }
+  if (res.status === 501) {
+    die("ticket: server not configured for realtime (self-hosted without Supabase?)");
+  }
+  if (res.status === 404) {
+    die("ticket: namespace not owned — regenerate your token");
+  }
+  if (res.status !== 200) {
+    throw new Error(`ticket HTTP ${res.status}: ${res.body.slice(0, 200)}`);
+  }
+  try {
+    return JSON.parse(res.body);
+  } catch (e) {
+    throw new Error(`ticket: bad JSON: ${e.message}`);
+  }
+}
+
+function writePidfile(path) {
+  try {
+    writeFileSync(path, String(process.pid), { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      // Check if the PID is alive
+      try {
+        const existingPid = Number(readFileSync(path, "utf8").trim());
+        if (existingPid && existingPid !== process.pid) {
+          try {
+            process.kill(existingPid, 0);
+            die(`already running (pid ${existingPid})`, 2);
+          } catch (_) {
+            // stale
+            try {
+              unlinkSync(path);
+            } catch (_) {}
+            writeFileSync(path, String(process.pid), { flag: "wx" });
+            return;
+          }
+        }
+      } catch (_) {
+        try {
+          unlinkSync(path);
+        } catch (_) {}
+        writeFileSync(path, String(process.pid), { flag: "wx" });
+        return;
+      }
+    } else {
+      throw e;
+    }
+  }
+}
+
+function removePidfile(path) {
+  try {
+    unlinkSync(path);
+  } catch (_) {}
+}
+
+async function run() {
+  const cwd = process.cwd();
+  const { baseUrl, token } = readMcpConfig(cwd);
+  process.stderr.write(`subscribe: cwd=${cwd} server=${baseUrl}\n`);
+
+  let ticket = await fetchTicket(baseUrl, token);
+  const pidfile = `/tmp/patchcord_subscribe_${ticket.namespace_ids[0]}_${ticket.agent_id}.pid`;
+  writePidfile(pidfile);
+
+  const cleanup = () => removePidfile(pidfile);
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  process.stderr.write(
+    `subscribe: agent=${ticket.agent_id} namespaces=${ticket.namespace_ids.join(",")}\n`
+  );
+
+  let backoffIdx = 0;
+
+  const loop = async () => {
+    while (true) {
+      try {
+        await runOnce(ticket, baseUrl, token, async () => {
+          ticket = await fetchTicket(baseUrl, token);
+          return ticket;
+        });
+        backoffIdx = 0; // clean disconnect resets backoff
+      } catch (e) {
+        process.stderr.write(`subscribe: ${e.message}\n`);
+      }
+      const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
+      backoffIdx++;
+      process.stderr.write(`subscribe: reconnecting in ${delay}ms\n`);
+      await new Promise((r) => setTimeout(r, delay));
+      try {
+        ticket = await fetchTicket(baseUrl, token);
+      } catch (e) {
+        process.stderr.write(`subscribe: ticket refresh failed: ${e.message}\n`);
+      }
+    }
+  };
+
+  await loop();
+}
+
+function runOnce(ticket, baseUrl, token, refreshTicket) {
+  return new Promise((resolve, reject) => {
+    const allowedNs = new Set(ticket.namespace_ids);
+    const wsUrl = `${ticket.realtime_url}?apikey=${encodeURIComponent(ticket.apikey)}&vsn=1.0.0`;
+    const ws = wsConnect(wsUrl);
+
+    let ref = 1;
+    let heartbeatTimer = null;
+    let refreshTimer = null;
+    let currentJwt = ticket.jwt;
+    let settled = false;
+
+    const done = (err) => {
+      if (settled) return;
+      settled = true;
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      if (refreshTimer) clearTimeout(refreshTimer);
+      try {
+        ws.close();
+      } catch (_) {}
+      if (err) reject(err);
+      else resolve();
+    };
+
+    ws.on("open", () => {
+      process.stderr.write("subscribe: connected\n");
+      for (const topic of ticket.topics) {
+        ws.send(
+          JSON.stringify({
+            topic: topic.name,
+            event: "phx_join",
+            payload: {
+              config: topic.config,
+              access_token: currentJwt,
+            },
+            ref: String(ref++),
+          })
+        );
+      }
+      heartbeatTimer = setInterval(() => {
+        try {
+          ws.send(
+            JSON.stringify({
+              topic: "phoenix",
+              event: "heartbeat",
+              payload: {},
+              ref: String(ref++),
+            })
+          );
+        } catch (_) {}
+      }, HEARTBEAT_INTERVAL_MS);
+
+      const refreshIn = Math.max(
+        (ticket.jwt_expires_in - JWT_REFRESH_SAFETY_MARGIN_SEC) * 1000,
+        30_000
+      );
+      refreshTimer = setTimeout(async () => {
+        try {
+          const fresh = await refreshTicket();
+          currentJwt = fresh.jwt;
+          for (const topic of fresh.topics) {
+            ws.send(
+              JSON.stringify({
+                topic: topic.name,
+                event: "access_token",
+                payload: { access_token: currentJwt },
+                ref: String(ref++),
+              })
+            );
+          }
+          process.stderr.write("subscribe: token refreshed\n");
+        } catch (e) {
+          process.stderr.write(`subscribe: token refresh failed: ${e.message}\n`);
+          done(e);
+        }
+      }, refreshIn);
+    });
+
+    ws.on("message", (raw) => {
+      let frame;
+      try {
+        frame = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (frame.event !== "postgres_changes") return;
+      const data = frame.payload?.data;
+      if (!data || data.type !== "INSERT") return;
+      const rec = data.record;
+      if (!rec) return;
+      // Defense-in-depth: verify the row's namespace_id is in our scope.
+      // RLS already enforces this server-side, but if policies drift we
+      // don't want to leak cross-namespace notifications.
+      if (rec.namespace_id && !allowedNs.has(rec.namespace_id)) return;
+      const from = rec.from_agent || "unknown";
+      process.stdout.write(`PATCHCORD: 1 new from ${from}\n`);
+    });
+
+    ws.on("error", (err) => {
+      process.stderr.write(`subscribe: ws error: ${err.message}\n`);
+      done(err);
+    });
+
+    ws.on("close", () => {
+      process.stderr.write("subscribe: ws closed\n");
+      done();
+    });
+  });
+}
+
+run().catch((e) => {
+  process.stderr.write(`subscribe: fatal: ${e.message}\n`);
+  process.exit(1);
+});

package/skills/subscribe/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: patchcord:subscribe
+description: >
+  Start a background listener that wakes Claude the moment a new Patchcord
+  message arrives for this agent. Uses Supabase Realtime over WebSocket —
+  zero polling, zero idle cost. Use when the user says "subscribe",
+  "listen for patchcord messages", "wake me when messages arrive", or runs
+  /patchcord:subscribe.
+---
+
+# What this does
+
+Spawns `scripts/subscribe.mjs` in the background. The script holds a
+WebSocket to Supabase Realtime and prints one line to stdout per new
+`agent_messages` INSERT for this agent. Claude Code's `Monitor` tool
+picks up each line as a notification; Claude wakes up and calls
+`inbox()`.
+
+No polling, no tokens burned while idle. The process stays alive until
+the user kills it or closes the Claude Code session.
+
+# How to find the script path (read carefully — this is the one thing that trips agents up)
+
+At the top of the skill invocation message, Claude Code shows a header:
+`Base directory for this skill: <ABSOLUTE_PATH>/skills/subscribe`
+
+Take that path, strip `/skills/subscribe` from the end — you now have the
+plugin root. The script is at `<PLUGIN_ROOT>/scripts/subscribe.mjs`.
+
+**Do not rely on `$CLAUDE_PLUGIN_ROOT`** — it is often unset inside
+the Bash shell even when the skill is running. Always derive the path
+from the "Base directory for this skill" header you were given.
+
+Example: if the header says
+`Base directory for this skill: /home/user/.npm/_npx/abc123/node_modules/patchcord/skills/subscribe`
+then the script is at
+`/home/user/.npm/_npx/abc123/node_modules/patchcord/scripts/subscribe.mjs`.
+
+# Starting (step by step)
+
+1. **Know your identity.** If you don't already have `namespace_id` and
+   `agent_id` from this session, call `mcp__patchcord__inbox` once — the
+   response starts with `<agent>@<namespace> | N pending` and you can
+   read both off that line.
+
+2. **Compute the pidfile path:**
+   `/tmp/patchcord_subscribe_<namespace_id>_<agent_id>.pid`
+
+3. **Check for an existing listener.** One Bash call:
+   ```bash
+   PF=/tmp/patchcord_subscribe_<ns>_<agent>.pid
+   if [ -f "$PF" ] && kill -0 "$(cat "$PF")" 2>/dev/null; then
+     echo "ALREADY_RUNNING pid=$(cat "$PF")"
+   else
+     echo "OK_TO_SPAWN"
+   fi
+   ```
+   If output is `ALREADY_RUNNING`, tell the user "Patchcord listener
+   already active (pid N)" and STOP. Do not spawn another one.
+
+4. **Resolve the script path** using the recipe above.
+
+5. **Spawn under Monitor** — not Bash with `run_in_background`. Monitor
+   is the right tool because every stdout line becomes a notification.
+   Example call shape:
+   ```
+   Monitor(
+     description: "patchcord realtime listener (<agent>@<ns>)",
+     persistent: true,
+     timeout_ms: 3600000,
+     command: "exec node \"<absolute-path-to-subscribe.mjs>\" 2>&1 | grep --line-buffered -E '^PATCHCORD:|^subscribe: (fatal|ws error|token|already|connected|reconnecting|cwd|agent)'"
+   )
+   ```
+   The `grep` filter is intentional — it surfaces the signal lines
+   (`PATCHCORD:` arrivals, connect/disconnect, errors) and drops the
+   noise. The filter catches every terminal/state-change event, so the
+   Monitor won't silently miss a crash.
+
+6. **Tell the user one short line:**
+   "Patchcord listener active — I'll pick up new messages as they arrive."
+
+# When a notification fires
+
+Monitor surfaces `PATCHCORD: 1 new from <sender>`. Do this:
+
+1. Say one brief line: "Got a Patchcord ping from <sender> — checking inbox."
+2. Call `mcp__patchcord__inbox`.
+3. For each pending message, do the work first (follow the
+   patchcord:inbox skill), then reply with what you did.
+4. Return to listening — Monitor keeps running.
+
+# Stopping
+
+There is no `/patchcord:unsubscribe` command. Tell the user either:
+
+- Close this Claude Code session, OR
+- Run `kill $(cat /tmp/patchcord_subscribe_<namespace>_<agent>.pid)` in
+  a terminal.
+
+# If it fails to start
+
+Stderr shows the exact cause. Report it to the user verbatim and stop
+— do not loop or retry:
+
+- `no .mcp.json in <cwd>` — session is not in a patchcord project dir.
+- `token rejected` — bearer in `.mcp.json` is bad; regenerate from the
+  dashboard.
+- `server not configured for realtime` — server hasn't had
+  `SUPABASE_JWT_SECRET` / `SUPABASE_ANON_KEY` set. Self-hosted without
+  Supabase does not support this feature yet.
+- `namespace not owned` — the token's namespace lost its owner row;
+  regenerate from the dashboard.
+- `already running (pid N)` — pidfile guard tripped. Another subscribe
+  is active. Report and stop.