@nicknisi/pi-relay 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -17,6 +17,8 @@
   "files": [
     "dist",
     "index.ts",
+    "core.ts",
+    "filesystem.ts",
     "registry.ts",
     "mailbox.ts",
     "policy.ts",
@@ -27,18 +29,34 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
     }
   },
   "dependencies": {
+    "koffi": "^3.1.4",
     "typebox": "^1.1.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
   "pi": {
     "extensions": [
       "./index.ts"
     ]
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.ts"
   }
 }

package/policy.ts

@@ -24,9 +24,11 @@ export class OutboundPolicy {
   /**
    * 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).
+   * definition worked through what it was handed). `target` scopes the
+   * identical-body dedupe to a single peer (loop-breaking) so a broadcast
+   * of one body to N peers is not deduped after the first.
    */
-  check(body: string, unreadBacklog: number): OutboundVerdict {
+  check(body: string, unreadBacklog: number, target?: string): OutboundVerdict {
     if (body.length > MAX_BODY_CHARS) {
       return {
         ok: false,
@@ -40,9 +42,10 @@ export class OutboundPolicy {
       };
     }
     const now = this.now();
-    const lastSame = this.recentBodies.get(body);
+    const dedupeKey = `${body}\u0000${target ?? ''}`;
+    const lastSame = this.recentBodies.get(dedupeKey);
     if (lastSame !== undefined && now - lastSame < DEDUPE_WINDOW_MS) {
-      return { ok: false, reason: 'Identical message sent less than 10s ago — dropped to break loops.' };
+      return { ok: false, reason: 'Identical message to the same peer 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();
@@ -56,9 +59,9 @@ export class OutboundPolicy {
   }
 
   /** Record a successful send so dedupe/rate state stays current. */
-  recordSend(body: string): void {
+  recordSend(body: string, target?: string): void {
     this.sentAt.push(this.now());
-    this.recentBodies.set(body, this.now());
+    this.recentBodies.set(`${body}\u0000${target ?? ''}`, this.now());
     // bound the dedupe map
     if (this.recentBodies.size > 200) {
       const cutoff = this.now() - DEDUPE_WINDOW_MS;

package/registry.ts

@@ -16,8 +16,14 @@
  */
 
 import * as crypto from 'node:crypto';
-import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {
+  assertPathSegment,
+  openRelayRoot,
+  rethrowFilesystemError,
+  RelayDirectoryHandle,
+  RelayFilesystemError,
+} from './filesystem.js';
 
 export interface SessionRecord {
   addr: string;
@@ -42,61 +48,210 @@ export function deriveAddr(cwd: string, sessionId: string): string {
 }
 
 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
-  }
+  const directory = openRelayRoot(root, true)!;
+  directory.close();
 }
 
 export function recordPath(root: string, addr: string): string {
+  assertPathSegment(addr, 'relay address');
   return path.join(root, `${addr}.json`);
 }
 
 export function inboxDir(root: string, addr: string): string {
+  assertPathSegment(addr, 'relay address');
   return path.join(root, `${addr}.inbox`);
 }
 
 export function asksDir(root: string, addr: string): string {
+  assertPathSegment(addr, 'relay address');
   return path.join(root, `${addr}.asks`);
 }
 
+// ── Claimable aliases ────────────────────────────────────────────────────
+// Durable, human-readable names (@ci, @dotfiles) that point at a session
+// address. Last-claim-wins: `claimAlias` overwrites unconditionally. The
+// alias outlives the process and survives restart (persisted on disk, not
+// runtime-only); it is swept when the owning session's record is reaped.
+
+export interface AliasRecord {
+  name: string; // stored without the leading @
+  addr: string;
+  sessionId: string;
+  claimedAt: number;
+}
+
+export function aliasesDir(root: string): string {
+  return path.join(root, 'aliases');
+}
+
+export function aliasPath(root: string, name: string): string {
+  assertPathSegment(name, 'relay alias');
+  return path.join(aliasesDir(root), `${name}.json`);
+}
+
+export function writeAlias(root: string, alias: AliasRecord): void {
+  if (!isValidAliasName(alias.name)) throw new TypeError(`Invalid relay alias: ${alias.name}`);
+  const relay = openRelayRoot(root, true)!;
+  try {
+    const aliases = relay.openDirectory('aliases', true)!;
+    try {
+      aliases.writeFileAtomic(`${alias.name}.json`, JSON.stringify(alias, null, 2));
+    } finally {
+      aliases.close();
+    }
+  } finally {
+    relay.close();
+  }
+}
+
+/** Alias names: lowercase alnum start, then alnum/_/-, 1-32 chars. */
+export function isValidAliasName(name: string): boolean {
+  return /^[a-z0-9][a-z0-9_-]{0,31}$/.test(name);
+}
+
+function readAliasFromDirectory(directory: RelayDirectoryHandle, name: string): AliasRecord | null {
+  const raw = directory.readFile(`${name}.json`);
+  if (raw === null) return null;
+  const parsed = JSON.parse(raw);
+  if (parsed && typeof parsed.name === 'string' && typeof parsed.addr === 'string') return parsed as AliasRecord;
+  return null;
+}
+
+export function readAlias(root: string, name: string): AliasRecord | null {
+  // The name can come from LLM-controlled tool input — never let it reach
+  // the filesystem unvalidated (e.g. '@../../../../tmp/x').
+  if (!isValidAliasName(name)) return null;
+  const relay = openRelayRoot(root);
+  if (relay === null) return null;
+  try {
+    const aliases = relay.openDirectory('aliases');
+    if (aliases === null) return null;
+    try {
+      return readAliasFromDirectory(aliases, name);
+    } catch (error) {
+      rethrowFilesystemError(error);
+      return null;
+    } finally {
+      aliases.close();
+    }
+  } finally {
+    relay.close();
+  }
+}
+
+export function listAliases(root: string): AliasRecord[] {
+  const relay = openRelayRoot(root);
+  if (relay === null) return [];
+  try {
+    const aliases = relay.openDirectory('aliases');
+    if (aliases === null) return [];
+    try {
+      const out: AliasRecord[] = [];
+      for (const entry of aliases.readDirectory()) {
+        if (!entry.name.endsWith('.json')) continue;
+        if (entry.isSymbolicLink()) throw new RelayFilesystemError(`Refusing symlinked relay alias: ${entry.name}`);
+        if (!entry.isFile()) continue;
+        try {
+          const alias = readAliasFromDirectory(aliases, entry.name.slice(0, -'.json'.length));
+          if (alias) out.push(alias);
+        } catch (error) {
+          rethrowFilesystemError(error);
+        }
+      }
+      return out.sort((a, b) => a.claimedAt - b.claimedAt);
+    } finally {
+      aliases.close();
+    }
+  } catch (error) {
+    rethrowFilesystemError(error);
+    return [];
+  } finally {
+    relay.close();
+  }
+}
+
+/** Last-claim-wins: overwrites any prior owner. */
+export function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord {
+  const alias: AliasRecord = { name, addr, sessionId, claimedAt: Date.now() };
+  writeAlias(root, alias);
+  return alias;
+}
+
+export function clearAlias(root: string, name: string): void {
+  if (!isValidAliasName(name)) return;
+  const relay = openRelayRoot(root);
+  if (relay === null) return;
+  try {
+    const aliases = relay.openDirectory('aliases');
+    if (aliases === null) return;
+    try {
+      aliases.unlinkFile(`${name}.json`);
+    } catch (error) {
+      rethrowFilesystemError(error);
+      // deletion remains best-effort for ordinary I/O failures
+    } finally {
+      aliases.close();
+    }
+  } finally {
+    relay.close();
+  }
+}
+
 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);
+  const relay = openRelayRoot(root, true)!;
+  try {
+    relay.writeFileAtomic(`${record.addr}.json`, JSON.stringify(record, null, 2));
+  } finally {
+    relay.close();
+  }
+}
+
+function readRecordFromDirectory(directory: RelayDirectoryHandle, addr: string): SessionRecord | null {
+  const raw = directory.readFile(`${addr}.json`);
+  if (raw === null) return null;
+  const parsed = JSON.parse(raw);
+  if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number') return parsed as SessionRecord;
+  return null;
 }
 
 export function readRecord(root: string, addr: string): SessionRecord | null {
+  assertPathSegment(addr, 'relay address');
+  const relay = openRelayRoot(root);
+  if (relay === null) return 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 readRecordFromDirectory(relay, addr);
+  } catch (error) {
+    rethrowFilesystemError(error);
     return null;
+  } finally {
+    relay.close();
   }
 }
 
 /** Read-only listing, oldest first. Never mutates anything. */
 export function listRecords(root: string): SessionRecord[] {
-  let entries: fs.Dirent[];
+  const relay = openRelayRoot(root);
+  if (relay === null) return [];
   try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch {
+    const out: SessionRecord[] = [];
+    for (const entry of relay.readDirectory()) {
+      if (!entry.name.endsWith('.json')) continue;
+      if (entry.isSymbolicLink()) throw new RelayFilesystemError(`Refusing symlinked relay record: ${entry.name}`);
+      if (!entry.isFile()) continue;
+      try {
+        const record = readRecordFromDirectory(relay, entry.name.slice(0, -'.json'.length));
+        if (record) out.push(record);
+      } catch (error) {
+        rethrowFilesystemError(error);
+      }
+    }
+    return out.sort((a, b) => a.startedAt - b.startedAt);
+  } catch (error) {
+    rethrowFilesystemError(error);
     return [];
+  } finally {
+    relay.close();
   }
-  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 {
@@ -116,22 +271,82 @@ export function presenceOf(record: SessionRecord, now: number = Date.now()): Pre
   return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? 'live' : 'stalled';
 }
 
-function dirHasJson(dir: string): boolean {
+function dirHasJson(root: string, name: string): boolean {
+  const relay = openRelayRoot(root);
+  if (relay === null) return false;
   try {
-    return fs.readdirSync(dir).some((f) => f.endsWith('.json'));
-  } catch {
+    const directory = relay.openDirectory(name);
+    if (directory === null) return false;
+    try {
+      return directory.readDirectory().some((entry) => {
+        if (!entry.name.endsWith('.json')) return false;
+        if (entry.isSymbolicLink()) throw new RelayFilesystemError(`Refusing symlinked relay entry: ${entry.name}`);
+        return entry.isFile();
+      });
+    } finally {
+      directory.close();
+    }
+  } catch (error) {
+    rethrowFilesystemError(error);
     return false;
+  } finally {
+    relay.close();
   }
 }
 
-function rmrf(target: string): void {
+function claimsHaveJson(root: string, addr: string): boolean {
+  const relay = openRelayRoot(root);
+  if (relay === null) return false;
   try {
-    fs.rmSync(target, { recursive: true, force: true });
-  } catch {
-    // sweep is best-effort
+    const claims = relay.openDirectory(`${addr}.claims`);
+    if (claims === null) return false;
+    try {
+      for (const entry of claims.readDirectory()) {
+        if (entry.isSymbolicLink()) throw new RelayFilesystemError(`Refusing symlinked relay claim: ${entry.name}`);
+        if (!entry.isDirectory()) continue;
+        const claim = claims.openDirectory(entry.name);
+        if (claim === null) continue;
+        try {
+          if (
+            claim.readDirectory().some((file) => {
+              if (!file.name.endsWith('.json')) return false;
+              if (file.isSymbolicLink()) {
+                throw new RelayFilesystemError(`Refusing symlinked claimed letter: ${file.name}`);
+              }
+              return file.isFile();
+            })
+          ) {
+            return true;
+          }
+        } finally {
+          claim.close();
+        }
+      }
+      return false;
+    } finally {
+      claims.close();
+    }
+  } finally {
+    relay.close();
   }
 }
 
+function removeClaims(directory: RelayDirectoryHandle, addr: string): void {
+  const claimsName = `${addr}.claims`;
+  const claims = directory.openDirectory(claimsName);
+  if (claims === null) return;
+  try {
+    for (const entry of claims.readDirectory()) {
+      if (entry.isSymbolicLink()) throw new RelayFilesystemError(`Refusing symlinked relay claim: ${entry.name}`);
+      if (!entry.isDirectory()) continue;
+      claims.removeDirectory(entry.name);
+    }
+  } finally {
+    claims.close();
+  }
+  directory.removeDirectory(claimsName);
+}
+
 /**
  * Reclaim dead sessions' files. Rules (mail outranks tidiness):
  * - a running session is never touched;
@@ -148,16 +363,34 @@ function rmrf(target: string): void {
 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 hasMail =
+      dirHasJson(root, `${record.addr}.inbox`) ||
+      dirHasJson(root, `${record.addr}.asks`) ||
+      claimsHaveJson(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
+    const relay = openRelayRoot(root);
+    if (relay !== null) {
+      try {
+        relay.removeDirectory(`${record.addr}.inbox`);
+        relay.removeDirectory(`${record.addr}.asks`);
+        removeClaims(relay, record.addr);
+        try {
+          relay.unlinkFile(`${record.addr}.json`);
+        } catch (error) {
+          rethrowFilesystemError(error);
+          // deletion remains best-effort for ordinary I/O failures
+        }
+      } finally {
+        relay.close();
+      }
     }
   }
+  // Aliases are swept when the owning session dies: an alias whose record
+  // was just reaped (or never existed) is reclaimed. A resumable-but-offline
+  // session keeps its record, so it keeps its alias too.
+  for (const alias of listAliases(root)) {
+    if (readRecord(root, alias.addr) === null) clearAlias(root, alias.name);
+  }
 }