@nicknisi/pi-relay 0.1.0 → 0.3.0

package/dist/policy.d.ts

@@ -23,11 +23,13 @@ export declare 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;
     /** Record a successful send so dedupe/rate state stays current. */
-    recordSend(body: string): void;
+    recordSend(body: string, target?: string): void;
 }
 /** Inbound guard: PI_RELAY_INBOUND=refuse drops all peer mail. */
 export declare function inboundAccepts(env?: string | undefined): boolean;

package/dist/policy.js

@@ -20,9 +20,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, unreadBacklog) {
+    check(body, unreadBacklog, target) {
         if (body.length > MAX_BODY_CHARS) {
             return {
                 ok: false,
@@ -36,9 +38,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)
@@ -52,9 +55,9 @@ export class OutboundPolicy {
         return { ok: true };
     }
     /** Record a successful send so dedupe/rate state stays current. */
-    recordSend(body) {
+    recordSend(body, target) {
         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/dist/registry.d.ts

@@ -34,6 +34,22 @@ export declare function ensureRoot(root: string): void;
 export declare function recordPath(root: string, addr: string): string;
 export declare function inboxDir(root: string, addr: string): string;
 export declare function asksDir(root: string, addr: string): string;
+export interface AliasRecord {
+    name: string;
+    addr: string;
+    sessionId: string;
+    claimedAt: number;
+}
+export declare function aliasesDir(root: string): string;
+export declare function aliasPath(root: string, name: string): string;
+export declare function writeAlias(root: string, alias: AliasRecord): void;
+/** Alias names: lowercase alnum start, then alnum/_/-, 1-32 chars. */
+export declare function isValidAliasName(name: string): boolean;
+export declare function readAlias(root: string, name: string): AliasRecord | null;
+export declare function listAliases(root: string): AliasRecord[];
+/** Last-claim-wins: overwrites any prior owner. */
+export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;
+export declare function clearAlias(root: string, name: string): void;
 export declare function writeRecord(root: string, record: SessionRecord): void;
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 /** Read-only listing, oldest first. Never mutates anything. */

package/dist/registry.js

@@ -15,8 +15,8 @@
  * - 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';
+import { assertPathSegment, openRelayRoot, rethrowFilesystemError, RelayDirectoryHandle, RelayFilesystemError, } from './filesystem.js';
 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;
@@ -24,60 +24,222 @@ export function deriveAddr(cwd, sessionId) {
     return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
 export function ensureRoot(root) {
-    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, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.json`);
 }
 export function inboxDir(root, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.inbox`);
 }
 export function asksDir(root, addr) {
+    assertPathSegment(addr, 'relay address');
     return path.join(root, `${addr}.asks`);
 }
-export function writeRecord(root, record) {
-    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 aliasesDir(root) {
+    return path.join(root, 'aliases');
 }
-export function readRecord(root, addr) {
+export function aliasPath(root, name) {
+    assertPathSegment(name, 'relay alias');
+    return path.join(aliasesDir(root), `${name}.json`);
+}
+export function writeAlias(root, alias) {
+    if (!isValidAliasName(alias.name))
+        throw new TypeError(`Invalid relay alias: ${alias.name}`);
+    const relay = openRelayRoot(root, true);
     try {
-        const parsed = JSON.parse(fs.readFileSync(recordPath(root, addr), 'utf8'));
-        if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number') {
-            return parsed;
+        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) {
+    return /^[a-z0-9][a-z0-9_-]{0,31}$/.test(name);
+}
+function readAliasFromDirectory(directory, name) {
+    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;
+    return null;
+}
+export function readAlias(root, name) {
+    // 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) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
+    try {
+        const aliases = relay.openDirectory('aliases');
+        if (aliases === null)
+            return [];
+        try {
+            const out = [];
+            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 {
+    catch (error) {
+        rethrowFilesystemError(error);
+        return [];
+    }
+    finally {
+        relay.close();
+    }
+}
+/** Last-claim-wins: overwrites any prior owner. */
+export function claimAlias(root, name, addr, sessionId) {
+    const alias = { name, addr, sessionId, claimedAt: Date.now() };
+    writeAlias(root, alias);
+    return alias;
+}
+export function clearAlias(root, name) {
+    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, record) {
+    const relay = openRelayRoot(root, true);
+    try {
+        relay.writeFileAtomic(`${record.addr}.json`, JSON.stringify(record, null, 2));
+    }
+    finally {
+        relay.close();
+    }
+}
+function readRecordFromDirectory(directory, addr) {
+    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;
+    return null;
+}
+export function readRecord(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return null;
+    try {
+        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) {
-    let entries;
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
     try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
+        const out = [];
+        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 {
+    catch (error) {
+        rethrowFilesystemError(error);
         return [];
     }
-    const out = [];
-    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);
+    finally {
+        relay.close();
     }
-    return out.sort((a, b) => a.startedAt - b.startedAt);
 }
 function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -98,21 +260,96 @@ export function presenceOf(record, now = Date.now()) {
         return 'offline';
     return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? 'live' : 'stalled';
 }
-function dirHasJson(dir) {
+function dirHasJson(root, name) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return false;
     try {
-        return fs.readdirSync(dir).some((f) => f.endsWith('.json'));
+        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 {
+    catch (error) {
+        rethrowFilesystemError(error);
+        return false;
+    }
+    finally {
+        relay.close();
+    }
+}
+function claimsHaveJson(root, addr) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
         return false;
+    try {
+        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 rmrf(target) {
+function removeClaims(directory, addr) {
+    const claimsName = `${addr}.claims`;
+    const claims = directory.openDirectory(claimsName);
+    if (claims === null)
+        return;
     try {
-        fs.rmSync(target, { recursive: true, force: true });
+        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);
+        }
     }
-    catch {
-        // sweep is best-effort
+    finally {
+        claims.close();
     }
+    directory.removeDirectory(claimsName);
 }
 /**
  * Reclaim dead sessions' files. Rules (mail outranks tidiness):
@@ -131,19 +368,38 @@ export function sweep(root, now = Date.now(), sessionExists) {
     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);
+    }
 }