@fitchmultz/pi-subagents 0.46.1 → 0.47.0

package/dist/pi-intercom/bridge-mailbox.js

@@ -0,0 +1,324 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { isRecord } from "../shared/unknown.js";
+import { normalizeMessage, normalizeSessionInfo } from "./types.js";
+import { Fault, INBOX_BYTES, INBOX_COUNT, fingerprint as certificateFingerprint, label, } from "./bridge-protocol.js";
+export function stateDirectory(value) {
+    if (value === undefined) {
+        return;
+    }
+    const path = label(value, "stateDir", 4096);
+    const stat = lstatSync(path);
+    if (!isAbsolute(path) ||
+        !stat.isDirectory() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o777) !== 0o700) {
+        throw new Error("stateDir must be an absolute owned directory with mode 0700, not a symlink.");
+    }
+    return realpathSync(path);
+}
+function privateFile(path, create = false) {
+    const flags = create ? constants.O_RDWR | constants.O_CREAT : constants.O_RDONLY;
+    const fd = openSync(path, flags | constants.O_NOFOLLOW, 0o600);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() ||
+            stat.uid !== process.getuid?.() ||
+            (stat.mode & 0o777) !== 0o600 ||
+            stat.nlink !== 1) {
+            throw new Error("Mailbox files must be owned regular files with mode 0600 and one link.");
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function database(stateDir, fingerprint) {
+    stateDirectory(stateDir);
+    const path = join(stateDir, `${certificateFingerprint(fingerprint)}.sqlite`);
+    privateFile(path, true);
+    for (const suffix of ["-journal", "-wal", "-shm"]) {
+        try {
+            lstatSync(`${path}${suffix}`);
+        }
+        catch (error) {
+            if (isRecord(error) && error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+        privateFile(`${path}${suffix}`);
+    }
+    const db = new DatabaseSync(path, { enableDoubleQuotedStringLiterals: false });
+    try {
+        db.exec(`
+      PRAGMA journal_mode=DELETE;
+      PRAGMA synchronous=FULL;
+      PRAGMA secure_delete=ON;
+      PRAGMA cache_size=-1024;
+      PRAGMA busy_timeout=1000;
+      CREATE TABLE IF NOT EXISTS mailbox (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE,
+        envelope TEXT,
+        bytes INTEGER NOT NULL,
+        ask INTEGER NOT NULL,
+        receivedAt INTEGER NOT NULL,
+        acked INTEGER NOT NULL DEFAULT 0,
+        notified INTEGER NOT NULL DEFAULT 1
+      );
+      CREATE INDEX IF NOT EXISTS unread ON mailbox(sequence) WHERE acked=0;
+      CREATE INDEX IF NOT EXISTS asks ON mailbox(ask) WHERE ask=1 AND acked=0;
+      CREATE INDEX IF NOT EXISTS notifications ON mailbox(sequence) WHERE notified=0;
+      CREATE TABLE IF NOT EXISTS losses (
+        singleton INTEGER PRIMARY KEY CHECK(singleton=1),
+        count INTEGER NOT NULL
+      );
+      INSERT OR IGNORE INTO losses VALUES(1, 0);
+    `);
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+function decode(value) {
+    const raw = typeof value === "string" ? JSON.parse(value) : undefined;
+    const from = isRecord(raw) ? normalizeSessionInfo(raw.from) : null;
+    const message = isRecord(raw) ? normalizeMessage(raw.message) : null;
+    if (!from || !message) {
+        throw new Fault(507, "mailbox_storage_failed", "Stored mailbox entry is invalid.");
+    }
+    return { from, message };
+}
+/** Persistent payloads leave only ID tombstones after acknowledgement, preventing replay resurrection. */
+export class Mailbox {
+    db;
+    entries = new Map();
+    bytes = 0;
+    sequence = 0;
+    failure;
+    admissionFailed = false;
+    notifications;
+    constructor(stateDir, fingerprint, notifications = false) {
+        try {
+            this.db = stateDir === undefined ? undefined : database(stateDir, fingerprint);
+        }
+        catch {
+            throw new Fault(507, "mailbox_storage_failed", "Cannot open private mailbox storage.");
+        }
+        this.notifications = notifications;
+    }
+    get persistent() {
+        return this.db !== undefined;
+    }
+    stored(action) {
+        if (this.failure) {
+            throw this.failure;
+        }
+        try {
+            return action();
+        }
+        catch (error) {
+            throw error instanceof Fault
+                ? error
+                : new Fault(507, "mailbox_storage_failed", "Mailbox storage operation failed.");
+        }
+    }
+    add(envelope) {
+        if (!this.db) {
+            return this.addVolatile(envelope);
+        }
+        const db = this.db;
+        return this.stored(() => {
+            try {
+                const payload = JSON.stringify(envelope);
+                const inserted = db
+                    .prepare("INSERT OR IGNORE INTO mailbox(id,envelope,bytes,ask,receivedAt,notified) VALUES(?,?,?,?,?,?)")
+                    .run(envelope.message.id, payload, Buffer.byteLength(payload), envelope.message.expectsReply === true ? 1 : 0, Date.now(), this.notifications ? 0 : 1);
+                this.admissionFailed = false;
+                return inserted.changes === 0 ? "duplicate" : "stored";
+            }
+            catch {
+                this.admissionFailed = true;
+                try {
+                    db.prepare("UPDATE losses SET count=MIN(count+1,9007199254740991) WHERE singleton=1").run();
+                }
+                catch {
+                    this.failure = new Fault(507, "mailbox_storage_failed", "Mailbox admission and loss recording failed; loss count is not durable.", { lossRecorded: false });
+                    throw this.failure;
+                }
+                return "lost";
+            }
+        });
+    }
+    addVolatile(envelope) {
+        if (this.entries.has(envelope.message.id)) {
+            return "duplicate";
+        }
+        const bytes = Buffer.byteLength(JSON.stringify(envelope));
+        if (this.entries.size >= INBOX_COUNT || this.bytes + bytes > INBOX_BYTES) {
+            return "lost";
+        }
+        this.entries.set(envelope.message.id, {
+            ...envelope,
+            bytes,
+            sequence: ++this.sequence,
+            receivedAt: Date.now(),
+            acked: 0,
+        });
+        this.bytes += bytes;
+        return "stored";
+    }
+    get(id) {
+        if (!this.db) {
+            return this.entries.get(id);
+        }
+        const db = this.db;
+        return this.stored(() => {
+            const row = db.prepare("SELECT envelope FROM mailbox WHERE id=? AND acked=0").get(id);
+            return row ? decode(row.envelope) : undefined;
+        });
+    }
+    remove(id) {
+        if (this.db) {
+            const db = this.db;
+            this.stored(() => db
+                .prepare("UPDATE mailbox SET acked=1, envelope=CASE WHEN notified=1 THEN NULL ELSE envelope END, bytes=CASE WHEN notified=1 THEN 0 ELSE bytes END WHERE id=?")
+                .run(id));
+            return;
+        }
+        const entry = this.entries.get(id);
+        if (entry) {
+            this.bytes -= entry.bytes;
+            this.entries.delete(id);
+        }
+    }
+    ack(ids) {
+        const acked = [];
+        const retained = [];
+        for (const id of ids) {
+            const entry = this.get(id);
+            if (entry?.message.expectsReply === true) {
+                // Durable consumer intake owns the primary wake; keep only the reply obligation here.
+                this.notificationAccepted(id);
+                retained.push(id);
+            }
+            else if (entry) {
+                this.remove(id);
+                acked.push(id);
+            }
+        }
+        return { acked, retained };
+    }
+    page(after, limit) {
+        return this.readPage(after, limit, false);
+    }
+    pendingNotifications(after = 0, limit = INBOX_COUNT) {
+        return this.readPage(after, limit, true);
+    }
+    notificationAccepted(id) {
+        const db = this.db;
+        if (db) {
+            this.stored(() => db
+                .prepare("UPDATE mailbox SET notified=1, envelope=CASE WHEN acked=1 THEN NULL ELSE envelope END, bytes=CASE WHEN acked=1 THEN 0 ELSE bytes END WHERE id=?")
+                .run(id));
+        }
+    }
+    readPage(after, limit, notifications) {
+        if (!Number.isSafeInteger(after) ||
+            after < 0 ||
+            !Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > INBOX_COUNT) {
+            throw new Fault(400, "invalid_input", "Invalid mailbox page bounds.");
+        }
+        return this.stored(() => {
+            const candidates = this.candidates(after, limit, notifications);
+            const messages = [];
+            let bytes = 0;
+            let cursor = after;
+            let hasMore = false;
+            for (const candidate of candidates) {
+                const row = indexRow(candidate);
+                if (messages.length === limit || (messages.length > 0 && bytes + row.bytes > INBOX_BYTES)) {
+                    hasMore = true;
+                    break;
+                }
+                const envelope = decode(isRecord(candidate) && typeof candidate.envelope === "string"
+                    ? candidate.envelope
+                    : JSON.stringify(candidate));
+                messages.push(notifications
+                    ? { ...envelope, receivedAt: row.receivedAt, acknowledged: row.acked === 1 }
+                    : envelope);
+                bytes += row.bytes;
+                cursor = row.sequence;
+            }
+            return { messages, nextCursor: String(cursor), hasMore };
+        });
+    }
+    candidates(after, limit, notifications) {
+        if (this.db) {
+            return this.db
+                .prepare(`SELECT sequence,bytes,receivedAt,acked,envelope FROM mailbox WHERE ${notifications ? "notified=0" : "acked=0"} AND sequence>? ORDER BY sequence LIMIT ?`)
+                .iterate(after, limit + 1);
+        }
+        return notifications
+            ? []
+            : [...this.entries.values()].filter((entry) => entry.sequence > after).slice(0, limit + 1);
+    }
+    status(volatileLosses) {
+        const db = this.db;
+        const lostMessages = db
+            ? this.stored(() => db.prepare("SELECT count FROM losses WHERE singleton=1").get()?.count)
+            : volatileLosses;
+        if (typeof lostMessages !== "number") {
+            throw new Fault(507, "mailbox_storage_failed", "Stored loss counter is invalid.");
+        }
+        return {
+            lostMessages,
+            overflow: lostMessages > 0,
+            storageError: this.persistent && lostMessages > 0,
+        };
+    }
+    presence() {
+        const db = this.db;
+        if (!db) {
+            return {
+                pendingAsks: [...this.entries.values()].filter((entry) => entry.message.expectsReply === true).length,
+                acceptsAsks: this.entries.size < INBOX_COUNT && this.bytes < INBOX_BYTES,
+            };
+        }
+        return this.stored(() => {
+            const pendingAsks = db
+                .prepare("SELECT COUNT(*) AS count FROM mailbox WHERE ask=1 AND acked=0")
+                .get()?.count;
+            if (typeof pendingAsks !== "number") {
+                throw new Fault(507, "mailbox_storage_failed", "Stored ask counter is invalid.");
+            }
+            return { pendingAsks, acceptsAsks: !this.admissionFailed };
+        });
+    }
+    close() {
+        this.db?.close();
+        const discarded = this.entries.size;
+        this.entries.clear();
+        this.bytes = 0;
+        return discarded;
+    }
+}
+function indexRow(row) {
+    if (!isRecord(row)) {
+        throw new Fault(507, "mailbox_storage_failed", "Stored mailbox index is invalid.");
+    }
+    const { sequence, bytes, receivedAt, acked } = row;
+    if (typeof sequence !== "number" ||
+        typeof bytes !== "number" ||
+        typeof receivedAt !== "number" ||
+        typeof acked !== "number") {
+        throw new Fault(507, "mailbox_storage_failed", "Stored mailbox index is invalid.");
+    }
+    return { sequence, bytes, receivedAt, acked };
+}

package/dist/pi-intercom/bridge-presence.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { isRecord } from "../shared/unknown.js";
+import { readBridgeFile, writeBridgeJson } from "./bridge-files.js";
+import { log } from "./bridge-protocol.js";
+export class PersistentPresence {
+    registrations = new Map();
+    stopped = false;
+    timer;
+    running;
+    owner;
+    constructor(owner) {
+        this.owner = owner;
+        for (const identity of owner.clients().values()) {
+            this.restore(identity);
+        }
+    }
+    path(fingerprint) {
+        return join(this.owner.stateDir, `presence-${fingerprint}.json`);
+    }
+    restore(identity) {
+        try {
+            const value = JSON.parse(readBridgeFile(this.path(identity.fingerprint256), true, 8192).toString("utf8"));
+            if (isRecord(value) &&
+                value.fingerprint === identity.fingerprint256 &&
+                value.name === identity.name &&
+                value.cwd === identity.cwd &&
+                typeof value.expires === "number" &&
+                Number.isFinite(value.expires) &&
+                value.expires > Date.now()) {
+                this.registrations.set(identity.fingerprint256, {
+                    fingerprint: identity.fingerprint256,
+                    name: identity.name,
+                    cwd: identity.cwd,
+                    expires: value.expires,
+                });
+            }
+        }
+        catch {
+            // An absent/invalid saved registration never grants a certificate identity.
+        }
+    }
+    authenticated(identity, expires) {
+        const previous = this.registrations.get(identity.fingerprint256);
+        if (previous?.expires === expires &&
+            previous.name === identity.name &&
+            previous.cwd === identity.cwd) {
+            return;
+        }
+        const registration = {
+            fingerprint: identity.fingerprint256,
+            name: identity.name,
+            cwd: identity.cwd,
+            expires,
+        };
+        writeBridgeJson(this.path(identity.fingerprint256), registration);
+        this.registrations.set(identity.fingerprint256, registration);
+        this.start();
+    }
+    start() {
+        if (!this.stopped && !this.running) {
+            clearTimeout(this.timer);
+            this.timer = setTimeout(() => {
+                this.running = this.maintain().finally(() => {
+                    this.running = undefined;
+                    if (!this.stopped) {
+                        this.timer = setTimeout(() => this.start(), 15000);
+                    }
+                });
+            }, 0);
+        }
+    }
+    async maintain() {
+        for (const registration of this.registrations.values()) {
+            if (this.stopped) {
+                return;
+            }
+            const identity = this.owner.clients().get(registration.fingerprint);
+            if (!identity ||
+                identity.name !== registration.name ||
+                identity.cwd !== registration.cwd ||
+                registration.expires <= Date.now()) {
+                this.registrations.delete(registration.fingerprint);
+                continue;
+            }
+            try {
+                // Each identity has one connection attempt; preserve the native broker's spawn safeguards.
+                // oxlint-disable-next-line no-await-in-loop
+                await this.owner.connect(identity, registration.expires);
+            }
+            catch {
+                log("presence_retry", { name: identity.name, result: "broker_unavailable" });
+            }
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        await this.running;
+    }
+}

package/dist/pi-intercom/bridge-routes.js

@@ -21,16 +21,39 @@ export function routeFor(req) {
         Object.keys(req.headers).some((key) => key.startsWith("sec-fetch-"))) {
         throw new Fault(403, "browser_forbidden", "Browser access is not supported.");
     }
-    const route = `${req.method ?? ""} ${req.url ?? ""}`;
+    const route = `${req.method ?? ""} ${(req.url ?? "").split("?")[0]}`;
     if (!isRoute(route)) {
         throw new Fault(404, "not_found", "Unknown method or path.");
     }
+    if (req.url?.includes("?") === true && route !== "GET /v1/inbox") {
+        throw new Fault(400, "invalid_input", "Only inbox accepts query parameters.");
+    }
+    checkGetBody(req);
+    return route;
+}
+function checkGetBody(req) {
     if (req.method === "GET" &&
         (req.headers["transfer-encoding"] !== undefined ||
             (req.headers["content-length"] !== undefined && req.headers["content-length"] !== "0"))) {
         throw new Fault(400, "invalid_input", "GET requests must not have a body.");
     }
-    return route;
+}
+function inboxQuery(req) {
+    const url = req.url ?? "";
+    const separator = url.indexOf("?");
+    const query = new URLSearchParams(separator === -1 ? "" : url.slice(separator + 1));
+    if ([...query.keys()].some((key) => !["after", "limit"].includes(key) || query.getAll(key).length !== 1)) {
+        throw new Fault(400, "invalid_input", "Unknown or repeated inbox query parameter.");
+    }
+    const after = query.get("after") ?? "0";
+    const limit = query.get("limit") ?? String(INBOX_COUNT);
+    if (!/^(0|[1-9]\d{0,15})$/.test(after) ||
+        !Number.isSafeInteger(Number(after)) ||
+        !/^[1-9]\d{0,2}$/.test(limit) ||
+        Number(limit) > INBOX_COUNT) {
+        throw new Fault(400, "invalid_input", "after must be a nonnegative safe integer cursor; limit must be 1..256.");
+    }
+    return { route: "GET /v1/inbox", after: Number(after), limit: Number(limit) };
 }
 function timeout(value) {
     const ms = value === undefined ? ASK_TIMEOUT : value;
@@ -43,10 +66,11 @@ export async function operationFor(req, route, signal) {
     const input = req.method === "POST" ? object(await body(req, signal), fields[route]) : {};
     switch (route) {
         case "GET /v1/list":
-        case "GET /v1/inbox":
         case "POST /v1/register":
         case "GET /v1/sessions":
             return { route };
+        case "GET /v1/inbox":
+            return inboxQuery(req);
         case "POST /v1/start":
             return { route, name: label(input.name, "session name", 64).trim() };
         case "POST /v1/stop":