@nicknisi/pi-relay 0.0.0

package/mailbox.ts

@@ -0,0 +1,227 @@
+/**
+ * Letter transport for the relay mailbox. Pi-free.
+ *
+ * Guarantees (each pinned by a test):
+ * - A reader never sees half a letter: writers rename into place; readers
+ *   only look at `*.json`.
+ * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
+ *   the caller handles it.
+ * - A corrupt letter is discarded on read, so it cannot poison every drain.
+ * - Consumption is the receipt: the sender learns "delivered" only when the
+ *   letter actually disappeared from the target's inbox.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { asksDir, inboxDir } from './registry.js';
+
+export type LetterKind = 'message' | 'ask' | 'reply' | 'cancel';
+
+export interface Letter {
+  id: string;
+  from: { addr: string; name: string; cwd: string };
+  kind: LetterKind;
+  body: string;
+  replyTo?: string;
+  ts: number;
+}
+
+export const MAX_BODY_CHARS = 32 * 1024;
+
+function letterFileName(letter: Letter): string {
+  return `${letter.ts}-${letter.id.slice(0, 6)}.json`;
+}
+
+/** Atomic deposit: write to a tmp sibling, then rename into place. */
+export function deposit(root: string, toAddr: string, letter: Letter): void {
+  const dir = inboxDir(root, toAddr);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const name = letterFileName(letter);
+  const tmp = path.join(dir, `${name}.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, JSON.stringify(letter), { mode: 0o600 });
+  fs.renameSync(tmp, path.join(dir, name));
+}
+
+/**
+ * Take every letter in the inbox, oldest first. Each letter is unlinked as
+ * it is read — before parsing — so it can never be delivered twice. The
+ * tradeoff: a drained letter that is never delivered would be lost, so the
+ * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ */
+export function drain(root: string, addr: string): Letter[] {
+  const dir = inboxDir(root, addr);
+  let names: string[];
+  try {
+    names = fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.json'))
+      .sort();
+  } catch {
+    return [];
+  }
+  const out: Letter[] = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    try {
+      fs.unlinkSync(file);
+    } catch {
+      continue; // another drainer took it
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.id === 'string' && typeof parsed.body === 'string') {
+        out.push(parsed as Letter);
+      }
+    } catch {
+      // corrupt letter — discarded, cannot fail future drains
+    }
+  }
+  return out;
+}
+
+export function unreadCount(root: string, addr: string): number {
+  try {
+    return fs.readdirSync(inboxDir(root, addr)).filter((f) => f.endsWith('.json')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Watch an inbox for new mail. fs.watch with a 3s poll fallback (watch can
+ * miss events). The callback is expected to drain; it must tolerate empty.
+ * Returns an unwatch function. Timer/watcher are unref'd so they never keep
+ * a process alive.
+ */
+export function watchInbox(root: string, addr: string, onMail: () => void): () => void {
+  const dir = inboxDir(root, addr);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let watcher: fs.FSWatcher | undefined;
+  try {
+    watcher = fs.watch(dir, () => onMail());
+    watcher.unref();
+  } catch {
+    // poll-only fallback
+  }
+  const poll = setInterval(onMail, 3000);
+  poll.unref();
+  return () => {
+    watcher?.close();
+    clearInterval(poll);
+  };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Consumption receipt: after depositing to a LIVE target, wait briefly for
+ * the letter to vanish. 'delivered' means the receiver's drainer took it —
+ * stronger than any transport ack.
+ */
+export async function awaitReceipt(
+  root: string,
+  toAddr: string,
+  letter: Letter,
+  timeoutMs = 1500,
+): Promise<'delivered' | 'queued'> {
+  const file = path.join(inboxDir(root, toAddr), letterFileName(letter));
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!fs.existsSync(file)) return 'delivered';
+    await sleep(100);
+  }
+  return fs.existsSync(file) ? 'queued' : 'delivered';
+}
+
+// ── Ask tracking ─────────────────────────────────────────────────────────
+// Received asks live at <addr>.asks/<askId>.json until we reply; our
+// outgoing asks live at <addr>.asks/out-<askId>.json until a reply/cancel
+// arrives or we time out.
+
+export interface OutAsk {
+  askId: string;
+  toAddr: string;
+  body: string;
+  ts: number;
+}
+
+function asksPath(root: string, addr: string, askId: string): string {
+  return path.join(asksDir(root, addr), `${askId}.json`);
+}
+
+function outAskPath(root: string, addr: string, askId: string): string {
+  return path.join(asksDir(root, addr), `out-${askId}.json`);
+}
+
+function writeJson0600(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+export function trackIncomingAsk(root: string, addr: string, letter: Letter): void {
+  writeJson0600(asksPath(root, addr, letter.id), letter);
+}
+
+export function trackOutgoingAsk(root: string, addr: string, out: OutAsk): void {
+  writeJson0600(outAskPath(root, addr, out.askId), out);
+}
+
+export function readIncomingAsk(root: string, addr: string, askId: string): Letter | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(asksPath(root, addr, askId), 'utf8'));
+    return parsed && typeof parsed.id === 'string' ? (parsed as Letter) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readOutgoingAsk(root: string, addr: string, askId: string): OutAsk | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(outAskPath(root, addr, askId), 'utf8'));
+    return parsed && typeof parsed.toAddr === 'string' ? (parsed as OutAsk) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove both sides of an ask id (incoming and/or outgoing). Idempotent. */
+export function clearAsk(root: string, addr: string, askId: string): void {
+  for (const file of [asksPath(root, addr, askId), outAskPath(root, addr, askId)]) {
+    try {
+      fs.unlinkSync(file);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/** Asks we have received and not yet answered, oldest first. */
+export function pendingAsks(root: string, addr: string): Letter[] {
+  let names: string[];
+  try {
+    names = fs
+      .readdirSync(asksDir(root, addr))
+      .filter((f) => f.endsWith('.json') && !f.startsWith('out-'))
+      .sort();
+  } catch {
+    return [];
+  }
+  const out: Letter[] = [];
+  for (const name of names) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(asksDir(root, addr), name), 'utf8'));
+      if (parsed && typeof parsed.id === 'string') out.push(parsed as Letter);
+    } catch {
+      // skip corrupt entry
+    }
+  }
+  return out;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nicknisi/pi-relay",
+  "version": "0.0.0",
+  "description": "Brokerless session-to-session messaging for pi — a file mailbox that outlives the process, with ask/reply coordination. Formerly @nicknisi/pi-intercom.",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/nicknisi/pi-extensions/tree/main/packages/relay#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicknisi/pi-extensions.git",
+    "directory": "packages/relay"
+  },
+  "files": [
+    "dist",
+    "index.ts",
+    "registry.ts",
+    "mailbox.ts",
+    "policy.ts",
+    "format.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "typebox": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/policy.ts

@@ -0,0 +1,75 @@
+/**
+ * Loop-breaking and inbound policy. Pi-free.
+ *
+ * A loop between two agents must terminate independently of what either
+ * model decides: repeats, rate, and backlog are all capped here, at the
+ * transport, not in the prompts.
+ */
+
+import { MAX_BODY_CHARS } from './mailbox.js';
+
+export const DEDUPE_WINDOW_MS = 10_000;
+export const RATE_LIMIT_MAX = 8;
+export const RATE_LIMIT_WINDOW_MS = 30_000;
+export const BACKLOG_CAP = 50;
+
+export type OutboundVerdict = { ok: true } | { ok: false; reason: string };
+
+export class OutboundPolicy {
+  private readonly sentAt: number[] = [];
+  private readonly recentBodies = new Map<string, number>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /**
+   * Gate one outbound letter. `unreadBacklog` is the target's current
+   * unread count (report 0 when the target is idle — an idle agent has by
+   * definition worked through what it was handed).
+   */
+  check(body: string, unreadBacklog: number): OutboundVerdict {
+    if (body.length > MAX_BODY_CHARS) {
+      return {
+        ok: false,
+        reason: `Message is ${body.length} chars; cap is ${MAX_BODY_CHARS}. Send a summary and a path, not a payload.`,
+      };
+    }
+    if (unreadBacklog >= BACKLOG_CAP) {
+      return {
+        ok: false,
+        reason: `Peer has ${unreadBacklog} unread messages (cap ${BACKLOG_CAP}); wait for it to drain.`,
+      };
+    }
+    const now = this.now();
+    const lastSame = this.recentBodies.get(body);
+    if (lastSame !== undefined && now - lastSame < DEDUPE_WINDOW_MS) {
+      return { ok: false, reason: 'Identical message sent less than 10s ago — dropped to break loops.' };
+    }
+    const windowStart = now - RATE_LIMIT_WINDOW_MS;
+    while (this.sentAt.length > 0 && this.sentAt[0]! < windowStart) this.sentAt.shift();
+    if (this.sentAt.length >= RATE_LIMIT_MAX) {
+      return {
+        ok: false,
+        reason: `Rate limited: ${RATE_LIMIT_MAX} messages per ${RATE_LIMIT_WINDOW_MS / 1000}s per session.`,
+      };
+    }
+    return { ok: true };
+  }
+
+  /** Record a successful send so dedupe/rate state stays current. */
+  recordSend(body: string): void {
+    this.sentAt.push(this.now());
+    this.recentBodies.set(body, this.now());
+    // bound the dedupe map
+    if (this.recentBodies.size > 200) {
+      const cutoff = this.now() - DEDUPE_WINDOW_MS;
+      for (const [key, ts] of this.recentBodies) {
+        if (ts < cutoff) this.recentBodies.delete(key);
+      }
+    }
+  }
+}
+
+/** Inbound guard: PI_RELAY_INBOUND=refuse drops all peer mail. */
+export function inboundAccepts(env: string | undefined = process.env.PI_RELAY_INBOUND): boolean {
+  return env !== 'refuse';
+}

package/registry.ts

@@ -0,0 +1,163 @@
+/**
+ * Session registry for the relay mailbox: who is around, where, and
+ * whether they're reachable. Pi-free — importable from tests without pi's
+ * loader.
+ *
+ * Design (from pi-peer's ARCHITECTURE.md):
+ * - An address belongs to a CONVERSATION, not a process: hash of cwd + pi
+ *   session id, so a resumed session (`pi -c`) answers to the same address
+ *   and two sessions on one directory never share an inbox.
+ * - A record outlives the process that wrote it — that's what makes a
+ *   session addressable while it's down (mail waits on disk).
+ * - Presence is a pid PLUS a heartbeat: pid alone can't tell wedged from
+ *   healthy (and pids get reused); heartbeat alone can't tell crash from
+ *   pause.
+ * - Listing has NO side effects: reading the directory never deletes.
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface SessionRecord {
+  addr: string;
+  sessionId: string;
+  name: string;
+  cwd: string;
+  pid: number;
+  startedAt: number;
+  lastSeenAt: number;
+  status: 'idle' | 'working';
+  offline?: boolean;
+}
+
+export type Presence = 'live' | 'stalled' | 'offline';
+
+export const HEARTBEAT_STALE_MS = 45_000;
+/** A mailbox holding undelivered mail is kept this long after last contact. */
+export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
+
+export function deriveAddr(cwd: string, sessionId: string): string {
+  return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
+}
+
+export function ensureRoot(root: string): void {
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(root, 0o700);
+  } catch {
+    // best-effort on filesystems that support modes
+  }
+}
+
+export function recordPath(root: string, addr: string): string {
+  return path.join(root, `${addr}.json`);
+}
+
+export function inboxDir(root: string, addr: string): string {
+  return path.join(root, `${addr}.inbox`);
+}
+
+export function asksDir(root: string, addr: string): string {
+  return path.join(root, `${addr}.asks`);
+}
+
+export function writeRecord(root: string, record: SessionRecord): void {
+  ensureRoot(root);
+  const file = recordPath(root, record.addr);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+export function readRecord(root: string, addr: string): SessionRecord | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(recordPath(root, addr), 'utf8'));
+    if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number') {
+      return parsed as SessionRecord;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read-only listing, oldest first. Never mutates anything. */
+export function listRecords(root: string): SessionRecord[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: SessionRecord[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const record = readRecord(root, entry.name.slice(0, -'.json'.length));
+    if (record) out.push(record);
+  }
+  return out.sort((a, b) => a.startedAt - b.startedAt);
+}
+
+function pidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but isn't ours — still alive
+    return (err as NodeJS.ErrnoException)?.code === 'EPERM';
+  }
+}
+
+export function presenceOf(record: SessionRecord, now: number = Date.now()): Presence {
+  if (record.offline) return 'offline';
+  if (!pidAlive(record.pid)) return 'offline';
+  return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? 'live' : 'stalled';
+}
+
+function dirHasJson(dir: string): boolean {
+  try {
+    return fs.readdirSync(dir).some((f) => f.endsWith('.json'));
+  } catch {
+    return false;
+  }
+}
+
+function rmrf(target: string): void {
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+  } catch {
+    // sweep is best-effort
+  }
+}
+
+/**
+ * Reclaim dead sessions' files. Rules (mail outranks tidiness):
+ * - a running session is never touched;
+ * - a mailbox holding undelivered mail is kept for SWEEP_MAIL_KEEP_MS;
+ * - an offline but resumable session keeps its record (its address — new
+ *   mail must remain deliverable while it's down);
+ * - only an empty mailbox of a session that can no longer be resumed is
+ *   discarded promptly.
+ *
+ * `sessionExists(sessionId)` reports whether pi can still resume the
+ * session (its session file is present). When omitted, every offline
+ * session is treated as resumable (the conservative choice).
+ */
+export function sweep(root: string, now: number = Date.now(), sessionExists?: (sessionId: string) => boolean): void {
+  for (const record of listRecords(root)) {
+    if (presenceOf(record, now) !== 'offline') continue;
+    const hasMail = dirHasJson(inboxDir(root, record.addr)) || dirHasJson(asksDir(root, record.addr));
+    const expired = now - record.lastSeenAt >= SWEEP_MAIL_KEEP_MS;
+    if (hasMail && !expired) continue;
+    if (!expired && (sessionExists?.(record.sessionId) ?? true)) continue;
+    rmrf(inboxDir(root, record.addr));
+    rmrf(asksDir(root, record.addr));
+    try {
+      fs.unlinkSync(recordPath(root, record.addr));
+    } catch {
+      // already gone
+    }
+  }
+}