@nicknisi/pi-relay 0.0.0

package/dist/mailbox.js

@@ -0,0 +1,194 @@
+/**
+ * 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 const MAX_BODY_CHARS = 32 * 1024;
+function letterFileName(letter) {
+    return `${letter.ts}-${letter.id.slice(0, 6)}.json`;
+}
+/** Atomic deposit: write to a tmp sibling, then rename into place. */
+export function deposit(root, toAddr, letter) {
+    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, addr) {
+    const dir = inboxDir(root, addr);
+    let names;
+    try {
+        names = fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const file = path.join(dir, name);
+        let raw;
+        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);
+            }
+        }
+        catch {
+            // corrupt letter — discarded, cannot fail future drains
+        }
+    }
+    return out;
+}
+export function unreadCount(root, addr) {
+    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, addr, onMail) {
+    const dir = inboxDir(root, addr);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let watcher;
+    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) => 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, toAddr, letter, timeoutMs = 1500) {
+    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';
+}
+function asksPath(root, addr, askId) {
+    return path.join(asksDir(root, addr), `${askId}.json`);
+}
+function outAskPath(root, addr, askId) {
+    return path.join(asksDir(root, addr), `out-${askId}.json`);
+}
+function writeJson0600(file, value) {
+    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, addr, letter) {
+    writeJson0600(asksPath(root, addr, letter.id), letter);
+}
+export function trackOutgoingAsk(root, addr, out) {
+    writeJson0600(outAskPath(root, addr, out.askId), out);
+}
+export function readIncomingAsk(root, addr, askId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(asksPath(root, addr, askId), 'utf8'));
+        return parsed && typeof parsed.id === 'string' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readOutgoingAsk(root, addr, askId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(outAskPath(root, addr, askId), 'utf8'));
+        return parsed && typeof parsed.toAddr === 'string' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remove both sides of an ask id (incoming and/or outgoing). Idempotent. */
+export function clearAsk(root, addr, askId) {
+    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, addr) {
+    let names;
+    try {
+        names = fs
+            .readdirSync(asksDir(root, addr))
+            .filter((f) => f.endsWith('.json') && !f.startsWith('out-'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    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);
+        }
+        catch {
+            // skip corrupt entry
+        }
+    }
+    return out;
+}

package/dist/policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export declare const DEDUPE_WINDOW_MS = 10000;
+export declare const RATE_LIMIT_MAX = 8;
+export declare const RATE_LIMIT_WINDOW_MS = 30000;
+export declare const BACKLOG_CAP = 50;
+export type OutboundVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare class OutboundPolicy {
+    private readonly now;
+    private readonly sentAt;
+    private readonly recentBodies;
+    constructor(now?: () => number);
+    /**
+     * 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;
+    /** Record a successful send so dedupe/rate state stays current. */
+    recordSend(body: string): void;
+}
+/** Inbound guard: PI_RELAY_INBOUND=refuse drops all peer mail. */
+export declare function inboundAccepts(env?: string | undefined): boolean;

package/dist/policy.js

@@ -0,0 +1,71 @@
+/**
+ * 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 class OutboundPolicy {
+    now;
+    sentAt = [];
+    recentBodies = new Map();
+    constructor(now = Date.now) {
+        this.now = 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, unreadBacklog) {
+        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) {
+        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 = process.env.PI_RELAY_INBOUND) {
+    return env !== 'refuse';
+}

package/dist/registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+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 declare const HEARTBEAT_STALE_MS = 45000;
+/** A mailbox holding undelivered mail is kept this long after last contact. */
+export declare const SWEEP_MAIL_KEEP_MS: number;
+export declare function deriveAddr(cwd: string, sessionId: string): string;
+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 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. */
+export declare function listRecords(root: string): SessionRecord[];
+export declare function presenceOf(record: SessionRecord, now?: number): Presence;
+/**
+ * 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 declare function sweep(root: string, now?: number, sessionExists?: (sessionId: string) => boolean): void;

package/dist/registry.js

@@ -0,0 +1,149 @@
+/**
+ * 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 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, 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
+    }
+}
+export function recordPath(root, addr) {
+    return path.join(root, `${addr}.json`);
+}
+export function inboxDir(root, addr) {
+    return path.join(root, `${addr}.inbox`);
+}
+export function asksDir(root, addr) {
+    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 readRecord(root, addr) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(recordPath(root, addr), 'utf8'));
+        if (parsed && typeof parsed.addr === 'string' && typeof parsed.pid === 'number') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read-only listing, oldest first. Never mutates anything. */
+export function listRecords(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        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);
+    }
+    return out.sort((a, b) => a.startedAt - b.startedAt);
+}
+function pidAlive(pid) {
+    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?.code === 'EPERM';
+    }
+}
+export function presenceOf(record, now = Date.now()) {
+    if (record.offline)
+        return 'offline';
+    if (!pidAlive(record.pid))
+        return 'offline';
+    return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? 'live' : 'stalled';
+}
+function dirHasJson(dir) {
+    try {
+        return fs.readdirSync(dir).some((f) => f.endsWith('.json'));
+    }
+    catch {
+        return false;
+    }
+}
+function rmrf(target) {
+    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, 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 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
+        }
+    }
+}

package/dist/relay.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Relay mechanism tests — tmp dirs, no pi imports. The suite is the
+ * specification: each case pins a guarantee from the design.
+ */
+export {};