@nexrall/code-core 1.4.59 → 1.4.60

package/dist/agent/peerRegistry.js

@@ -0,0 +1,238 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._peerRegistryInternal = void 0;
+exports.randomPeerName = randomPeerName;
+exports.registerPeer = registerPeer;
+exports.listPeers = listPeers;
+exports.findPeerByName = findPeerByName;
+/**
+ * Peer registry — lets independent sessions (two CLI windows, CLI + VS Code,
+ * VS Code + Desktop, all on the same machine) DISCOVER each other, mirroring
+ * Claude Code's cross-session messaging discovery mechanism: "Each session
+ * registers itself in files on disk... two sessions can reach each other
+ * only when they can see the same files."
+ *
+ * This module is discovery ONLY — one JSON record per live session, readable
+ * by every other session on the machine. The actual message transport
+ * (Unix socket / named pipe) is a SEPARATE module (peerTransport.ts) that
+ * reads `socketPath` from a record found here. Splitting them mirrors
+ * worktree.ts vs worktreeEnforcement.ts's own split: one module owns "what
+ * exists", another owns "what you're allowed to do with it".
+ *
+ * STORAGE
+ * -------
+ *   ~/.nexrall/peers/<sessionId>.json
+ *
+ * ONE FLAT DIRECTORY, not scoped per-project — unlike sharedTasks.ts (which
+ * scopes by workDir because a task list only makes sense per-project),
+ * discovery is deliberately GLOBAL: Claude Code's own cross-session
+ * messaging works across different projects on the same machine (you can
+ * message a session in an unrelated folder), and there's no reason for
+ * Nexrall Code's peer discovery to be narrower than that. A session that
+ * only wants same-project peers can filter listPeers() by `workDir` itself.
+ *
+ * LIVENESS
+ * --------
+ * A registered peer is considered alive when BOTH:
+ *   - its pid is still running (process.kill(pid, 0))
+ *   - its record was heartbeat-updated within HEARTBEAT_STALE_MS
+ * A session must call `heartbeat()` periodically (see registerPeer's return
+ * value) or its record is treated as dead by every OTHER session's
+ * `listPeers()`, and cleaned up opportunistically by whichever session next
+ * calls listPeers() and notices the staleness (no separate GC daemon needed
+ * — same "GC on next read" pattern crossProcessLock.ts and worktree.ts use
+ * for their own stale state).
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+// A record not heartbeat-updated within this long is treated as dead even if
+// its pid happens to still resolve (e.g. pid reuse by an unrelated process
+// after a crash — the same class of gap crossProcessLock's stale-lock check
+// already documents for the identical reason).
+const HEARTBEAT_STALE_MS = 20000; // 20s — sessions heartbeat every ~10s (see registerPeer)
+const HEARTBEAT_INTERVAL_MS = 10000;
+function peersRoot() {
+    return process.env.NEXRALL_PEERS_DIR || path.join(os.homedir(), '.nexrall', 'peers');
+}
+function recordPath(id) {
+    return path.join(peersRoot(), `${id}.json`);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecordAlive(r) {
+    if (Date.now() - r.updatedAt > HEARTBEAT_STALE_MS)
+        return false;
+    return isPidAlive(r.pid);
+}
+function readRecord(id) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(recordPath(id), 'utf-8'));
+        if (raw && typeof raw.id === 'string' && typeof raw.pid === 'number')
+            return raw;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeRecord(r) {
+    fs.mkdirSync(peersRoot(), { recursive: true });
+    const p = recordPath(r.id);
+    // Atomic write-via-temp-then-rename — same reasoning as sharedTasks.ts's
+    // writeTask: a crash mid-write must never leave a half-written record that
+    // another session's listPeers() then fails to parse.
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(r));
+    fs.renameSync(tmp, p);
+}
+const ADJECTIVES = ['graceful', 'quiet', 'brave', 'calm', 'swift', 'keen', 'bold', 'clear', 'gentle', 'sharp', 'steady', 'curious'];
+const NOUNS = ['unicorn', 'falcon', 'otter', 'harbor', 'meadow', 'ember', 'summit', 'cedar', 'quartz', 'heron', 'lynx', 'delta'];
+/** Generate a readable random peer name, same shape Claude Code uses ("graceful-unicorn"). */
+function randomPeerName() {
+    const a = ADJECTIVES[crypto.randomInt(ADJECTIVES.length)];
+    const n = NOUNS[crypto.randomInt(NOUNS.length)];
+    return `${a}-${n}`;
+}
+/**
+ * Register this session as a discoverable peer. Picks a name automatically
+ * (retrying on collision with a live peer) unless `opts.name` is given and
+ * free. Returns a handle for heartbeating/updating/unregistering — the
+ * caller (CLI/VS Code/Desktop host) owns calling heartbeat() on an interval;
+ * this module does not start its own timer, so it stays trivially testable
+ * and has no surprise background work in environments (like a short-lived
+ * test process) that never want one.
+ */
+function registerPeer(opts) {
+    const id = crypto.randomBytes(8).toString('hex');
+    const takenNames = new Set(listPeers().map((p) => p.name));
+    let name = opts.name?.trim();
+    if (name && takenNames.has(name)) {
+        // Requested name collides with a LIVE peer — disambiguate rather than
+        // silently overwrite/confuse two sessions with the same displayed name.
+        name = `${name}-${id.slice(0, 4)}`;
+    }
+    if (!name) {
+        do {
+            name = randomPeerName();
+        } while (takenNames.has(name));
+    }
+    const now = Date.now();
+    const record = {
+        id, name, pid: process.pid,
+        clientType: opts.clientType,
+        workDir: opts.workDir,
+        socketPath: opts.socketPath,
+        status: 'idle',
+        inbound: opts.inbound ?? 'accept',
+        startedAt: now,
+        updatedAt: now,
+    };
+    writeRecord(record);
+    return {
+        record,
+        heartbeat() {
+            record.updatedAt = Date.now();
+            writeRecord(record);
+        },
+        setStatus(status) {
+            record.status = status;
+            record.updatedAt = Date.now();
+            writeRecord(record);
+        },
+        unregister() {
+            try {
+                fs.unlinkSync(recordPath(id));
+            }
+            catch { /* already gone */ }
+        },
+    };
+}
+/**
+ * List every currently-alive peer on the machine, own-name-first when
+ * `ownId` is given (mirrors Claude Code's `/list-agents` printing the
+ * caller's own name on the first line). Opportunistically removes any
+ * record found to be dead (see this module's header for why no separate
+ * GC process is needed).
+ */
+function listPeers(ownId) {
+    let entries;
+    try {
+        entries = fs.readdirSync(peersRoot());
+    }
+    catch {
+        return [];
+    }
+    const alive = [];
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        const id = name.slice(0, -'.json'.length);
+        const record = readRecord(id);
+        if (!record)
+            continue;
+        if (isRecordAlive(record)) {
+            alive.push(record);
+        }
+        else {
+            // Opportunistic GC — a dead record left behind by a crash (no chance
+            // to call unregister()) shouldn't linger forever cluttering every
+            // future listPeers() call.
+            try {
+                fs.unlinkSync(recordPath(id));
+            }
+            catch { /* raced with another GC — fine */ }
+        }
+    }
+    if (ownId) {
+        alive.sort((a, b) => (a.id === ownId ? -1 : b.id === ownId ? 1 : 0));
+    }
+    return alive;
+}
+/** Find a live peer by name (case-sensitive — names are short readable tokens, not meant to require fuzzy matching). */
+function findPeerByName(name) {
+    return listPeers().find((p) => p.name === name) ?? null;
+}
+exports._peerRegistryInternal = { peersRoot, recordPath, isRecordAlive, HEARTBEAT_STALE_MS, HEARTBEAT_INTERVAL_MS };
+//# sourceMappingURL=peerRegistry.js.map

package/dist/agent/peerTransport.d.ts

@@ -0,0 +1,122 @@
+export interface PeerMessage {
+    /** The sending peer's name (from peerRegistry.ts), for display + as a reply target. */
+    from: string;
+    /** The sending peer's id — used internally to look up a reply address; not meant for display. */
+    fromId: string;
+    text: string;
+    sentAt: number;
+}
+/**
+ * Where this peer's transport endpoint lives.
+ *
+ * macOS/Linux: a real file at `~/.nexrall/peers/<id>.sock` — a Unix domain
+ * socket, backed by an actual filesystem entry `verifySocketSafety` can
+ * `lstat` and validate — UNLESS that path would exceed
+ * MAX_SOCKET_PATH_LENGTH, in which case fallbackSocketDir() is used instead
+ * (see its own doc comment).
+ *
+ * Windows: `\\.\pipe\nexrall-peer-<id>` — a NAMED PIPE, which lives in the
+ * NT kernel object namespace, NOT the regular NTFS filesystem tree. There is
+ * no directory to create and no on-disk file for `fs.lstatSync` to inspect
+ * (see verifySocketSafety's Windows branch for what this means for the
+ * safety checks), and no `sockaddr_un`-style length limit either — Windows
+ * named pipe paths have a much larger practical limit, so no fallback logic
+ * applies there. `net.createServer().listen(path)` / `net.createConnection
+ * (path)` both accept this exact path form natively — no separate Windows
+ * API surface needed, Node's own `net` module dispatches to named pipes
+ * automatically when the path matches this pattern.
+ */
+export declare function socketPathFor(peerId: string): string;
+/**
+ * Validate that `socketPath` is safe to connect to BEFORE connecting —
+ * see this module's header for exactly which bypass this closes. Returns an
+ * error string on failure, null when safe to proceed.
+ *
+ * WINDOWS CAVEAT: named pipes are kernel objects, not filesystem entries, so
+ * `fs.lstatSync` (what the symlink/uid checks below are built on) does not
+ * apply to them — there is no on-disk path component for a symlink to spoof
+ * in the first place, so that specific attack class does not carry over.
+ * The uid-ownership check has no direct equivalent from plain Node `net`
+ * either (that would require reading the pipe's Windows security descriptor
+ * via a native call, which this module deliberately does not add). The
+ * actual safety boundary on Windows is therefore the OS's own named-pipe
+ * ACL (set by whoever created it, defaulting to the creating user + admins)
+ * plus the connection attempt itself failing cleanly (ENOENT/EACCES) for a
+ * pipe that does not exist or is not accessible — handled by sendPeerMessage's
+ * own error path, not by a pre-check here. This is a genuinely weaker
+ * guarantee than the Unix path's explicit checks, called out here rather
+ * than silently assumed equivalent.
+ */
+declare function verifySocketSafety(socketPath: string): string | null;
+export interface PeerInboxOptions {
+    /** Called for each message as it arrives — see loop.ts's drainInbox usage, once wired. */
+    onMessage: (msg: PeerMessage) => void;
+    /**
+     * Called if the underlying listen() call itself fails (e.g. EINVAL from a
+     * socket path exceeding the OS's sockaddr_un length limit — see
+     * MAX_SOCKET_PATH_LENGTH's own comment for why this used to fail
+     * completely silently). Optional: a caller that omits this still gets a
+     * peer that LOOKS registered but can never actually receive a message,
+     * same as before this callback existed — but now at least has the option
+     * to find out and surface it (e.g. log it, or skip registering the peer
+     * record's socketPath at all so senders get a clear "not reachable" error
+     * up front instead of a silent black hole).
+     */
+    onError?: (err: Error) => void;
+}
+export interface PeerInbox {
+    socketPath: string;
+    close(): void;
+}
+/**
+ * Start listening for incoming peer messages on this session's own
+ * socket/pipe. Unix domain socket on macOS/Linux, named pipe on Windows —
+ * see socketPathFor's own doc comment for the platform split. Not tested
+ * against a real Windows machine (dev/CI for this repo runs macOS/Linux);
+ * the implementation follows Node's own documented cross-platform `net`
+ * behavior for named-pipe paths, but treat the Windows path as less
+ * battle-tested than the Unix one until it has run on real Windows.
+ */
+export declare function startPeerInbox(peerId: string, opts: PeerInboxOptions): PeerInbox;
+export interface SendPeerMessageResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Send a message to a peer at `targetSocketPath`. Fire-and-forget from the
+ * caller's perspective (resolves once the write completes or fails) — there
+ * is no delivery receipt, matching Claude Code's own "best effort" framing
+ * for cross-session messaging.
+ */
+export declare function sendPeerMessage(targetSocketPath: string, message: Omit<PeerMessage, 'sentAt'>): Promise<SendPeerMessageResult>;
+export interface BroadcastTarget {
+    name: string;
+    socketPath: string;
+}
+export interface BroadcastResult {
+    name: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Send the SAME message to every target in `targets`, in parallel. Each
+ * target gets its own independent sendPeerMessage call — one unreachable or
+ * slow peer cannot block or fail delivery to the others (no partial-failure
+ * cascade, no head-of-line blocking on a single slow socket).
+ *
+ * Deliberately a thin fan-out over the existing single-target
+ * sendPeerMessage rather than a new wire-level primitive: broadcast is a
+ * CALLER-SIDE concept (send to N addresses), not a transport-level one —
+ * there is no multicast socket underneath this, just N ordinary point-to-
+ * point sends, which keeps every security check (verifySocketSafety, size
+ * caps) shared with the single-message path instead of duplicated.
+ */
+export declare function broadcastPeerMessage(targets: BroadcastTarget[], message: Omit<PeerMessage, 'sentAt'>): Promise<BroadcastResult[]>;
+export declare const _peerTransportInternal: {
+    verifySocketSafety: typeof verifySocketSafety;
+    MAX_MESSAGE_BYTES: number;
+    CONNECT_TIMEOUT_MS: number;
+    isWindows: boolean;
+};
+export {};
+//# sourceMappingURL=peerTransport.d.ts.map

package/dist/agent/peerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peerTransport.d.ts","sourceRoot":"","sources":["../../src/agent/peerTransport.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAwCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmB7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,0FAA0F;IAC1F,SAAS,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IACtC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,SAAS,CA8EhF;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAkChC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,GACnC,OAAO,CAAC,eAAe,EAAE,CAAC,CAQ5B;AAED,eAAO,MAAM,sBAAsB;;;;;CAA2E,CAAC"}