@nexrall/code-core 1.4.59 → 1.4.60

package/dist/agent/peerTransport.js

@@ -0,0 +1,348 @@
+"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._peerTransportInternal = void 0;
+exports.socketPathFor = socketPathFor;
+exports.startPeerInbox = startPeerInbox;
+exports.sendPeerMessage = sendPeerMessage;
+exports.broadcastPeerMessage = broadcastPeerMessage;
+/**
+ * Peer transport — the actual message delivery between two independent
+ * sessions on the same machine, once peerRegistry.ts has let them discover
+ * each other. Mirrors Claude Code's cross-session messaging transport:
+ * same-machine delivery goes over a private Unix domain socket per session,
+ * never through any server — "Message content is not sent to Anthropic
+ * unless the sessions are on different machines."
+ *
+ * ONE ENDPOINT PER SESSION, not a shared broker: `~/.nexrall/peers/<id>.sock`
+ * on macOS/Linux (mode 0600, owner-only), `\\.\pipe\nexrall-peer-<id>` on
+ * Windows (see socketPathFor's own doc comment for why the two need
+ * different safety-check strategies). A sender connects directly to the
+ * RECIPIENT's endpoint, writes one newline-terminated JSON message, and
+ * disconnects — no persistent connection, no broker process to keep alive
+ * or crash-recover.
+ *
+ * SECURITY — this is genuinely adversarial territory, not decoration
+ * -------------------------------------------------------------------
+ * A peer message is the OUTPUT OF ANOTHER LLM CALL, running under whatever
+ * prompted THAT session — treat it as untrusted exactly like fetched web
+ * content (see this repo's own prompt-injection-defense conventions). This
+ * module's job is to make the TRANSPORT itself hard to abuse; the CONTENT
+ * still has to be handled as untrusted data by whoever renders/acts on it
+ * (see loop.ts's renderPeerMessage, once that's wired in Priority 4c/4d):
+ *   - Socket file must not be a SYMLINK (planting a symlink at the expected
+ *     socket path pointing somewhere else is the exact class of bypass
+ *     worktreeEnforcement.ts's git-redirect checks guard against for a
+ *     different resource — same principle, applied here to sockets).
+ *   - Socket file must be owned by the SAME uid as the connecting process
+ *     (`fs.statSync(...).uid === process.getuid()`) — refuses connecting to
+ *     a socket some other user on a shared machine planted at a guessed path.
+ *   - Message size is capped (MAX_MESSAGE_BYTES) so one peer can't wedge
+ *     another's inbox or blow its context window with a single message.
+ *   - A message NEVER carries conversation history or file contents —
+ *     plain text only, matching Claude Code's own "no context, just
+ *     text" design. Context-sharing is what `--resume`/session resume is
+ *     for, not this channel.
+ *   - This module does not interpret message text as a command — no
+ *     slash-command parsing, no execution. It is the receiving session's
+ *     `renderPeerMessage` (loop.ts side, per this module's own doc header
+ *     rationale) that must keep it fenced as untrusted data, never as an
+ *     instruction with the same authority as the actual user.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const net = __importStar(require("net"));
+const MAX_MESSAGE_BYTES = 8 * 1024; // 8 KB — a coordination ping, not a payload channel
+const CONNECT_TIMEOUT_MS = 3000;
+const isWindows = process.platform === 'win32';
+// `struct sockaddr_un`'s `sun_path` field — what a Unix domain socket path
+// actually gets copied into at the OS level — is a FIXED-SIZE buffer: 104
+// bytes on macOS/BSD, 108 on Linux. A path longer than that makes
+// `listen()`/`connect()` fail with EINVAL, and — this is the real bug this
+// constant exists to prevent, caught by a genuinely failing test, not
+// invented defensively — Node's `net.Server` reports that failure ONLY via
+// its `'error'` event, which this module's `startPeerInbox` used to just
+// swallow (`server.on('error', () => {/* best-effort */})`), so the peer
+// would look successfully registered (a socketPath string was returned)
+// while silently never being able to receive a single message. A deep home
+// directory (`~/.nexrall/peers/<16-hex-char-id>.sock`) is enough to exceed
+// this in practice, not just in a test harness using a long os.tmpdir()
+// path — so this is a real production risk, not merely a test artifact.
+// Kept conservatively below the tighter of the two OS limits.
+const MAX_SOCKET_PATH_LENGTH = 100;
+function preferredSocketDir() {
+    return process.env.NEXRALL_PEERS_DIR || path.join(os.homedir(), '.nexrall', 'peers');
+}
+/**
+ * Fallback used ONLY when preferredSocketDir()'s natural path would exceed
+ * MAX_SOCKET_PATH_LENGTH. `/tmp` is short and present on essentially every
+ * POSIX system — the same fallback other Unix-socket-using tools facing
+ * this identical `sockaddr_un` constraint use (tmux, docker compose, etc).
+ * Peer ids are random enough (16 hex chars, minted by registerPeer) that
+ * collisions between unrelated sessions sharing this flat fallback
+ * namespace are not a practical concern.
+ */
+function fallbackSocketDir() {
+    return '/tmp';
+}
+/**
+ * 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.
+ */
+function socketPathFor(peerId) {
+    if (isWindows)
+        return `\\\\.\\pipe\\nexrall-peer-${peerId}`;
+    const preferred = path.join(preferredSocketDir(), `${peerId}.sock`);
+    if (preferred.length <= MAX_SOCKET_PATH_LENGTH)
+        return preferred;
+    return path.join(fallbackSocketDir(), `nexrall-peer-${peerId}.sock`);
+}
+/**
+ * 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.
+ */
+function verifySocketSafety(socketPath) {
+    if (isWindows)
+        return null; // see this function's own doc comment for why
+    let st;
+    try {
+        st = fs.lstatSync(socketPath); // lstat, NOT stat — must inspect the link itself, not what it points to
+    }
+    catch {
+        return 'socket does not exist (peer may have exited)';
+    }
+    if (st.isSymbolicLink()) {
+        return 'refusing to connect: peer socket path is a symlink (possible spoofing attempt)';
+    }
+    if (!st.isSocket()) {
+        return 'refusing to connect: peer socket path is not actually a socket';
+    }
+    if (typeof process.getuid === 'function' && st.uid !== process.getuid()) {
+        return 'refusing to connect: peer socket is owned by a different user';
+    }
+    return null;
+}
+/**
+ * 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.
+ */
+function startPeerInbox(peerId, opts) {
+    const socketPath = socketPathFor(peerId);
+    if (!isWindows) {
+        fs.mkdirSync(path.dirname(socketPath), { recursive: true });
+        // A stale socket file from a previous run of this exact peerId (extremely
+        // unlikely — ids are random — but a crash could theoretically leave one)
+        // would make `server.listen` fail with EADDRINUSE. Safe to remove
+        // unconditionally: peerId is freshly minted per registerPeer() call, so
+        // nothing legitimate could still be listening on it.
+        try {
+            fs.unlinkSync(socketPath);
+        }
+        catch { /* did not exist */ }
+    }
+    // No directory/stale-file handling needed on Windows — named pipes have no
+    // on-disk path component (see socketPathFor's doc comment), and a stale
+    // pipe from a previous instance of this exact random peerId is exactly as
+    // vanishingly unlikely there as the Unix case above.
+    const server = net.createServer((conn) => {
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk.toString('utf-8');
+            if (buf.length > MAX_MESSAGE_BYTES * 2) {
+                // A sender ignoring MAX_MESSAGE_BYTES (or trying to flood) gets cut
+                // off rather than let this session buffer unboundedly.
+                conn.destroy();
+                return;
+            }
+            const nl = buf.indexOf('\n');
+            if (nl === -1)
+                return;
+            const line = buf.slice(0, nl);
+            buf = '';
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed.text === 'string' && typeof parsed.from === 'string' && typeof parsed.fromId === 'string') {
+                    opts.onMessage({
+                        from: parsed.from,
+                        fromId: parsed.fromId,
+                        text: parsed.text.slice(0, MAX_MESSAGE_BYTES),
+                        sentAt: typeof parsed.sentAt === 'number' ? parsed.sentAt : Date.now(),
+                    });
+                }
+            }
+            catch { /* malformed message — drop silently, same as a corrupt network packet */ }
+            conn.end();
+        });
+        conn.on('error', () => { });
+    });
+    server.listen(socketPath, () => {
+        if (isWindows)
+            return; // chmod has no meaning for a named pipe — its access control is the OS's own pipe DACL, not POSIX file mode.
+        // Owner-only permissions — a message channel is exactly the kind of
+        // resource that must not be readable/writable by other users on a
+        // shared machine.
+        try {
+            fs.chmodSync(socketPath, 0o600);
+        }
+        catch { /* best-effort on platforms without POSIX chmod semantics */ }
+    });
+    // See PeerInboxOptions.onError's own comment for why this used to be a
+    // pure no-op (`() => {}`) and why that was a real bug, not a deliberate
+    // simplification: `listen()` failing (EINVAL for an over-length path,
+    // EADDRINUSE, EACCES, ...) used to be indistinguishable from success from
+    // this function's return value alone.
+    server.on('error', (err) => { opts.onError?.(err instanceof Error ? err : new Error(String(err))); });
+    return {
+        socketPath,
+        close() {
+            // `server.close()` itself unlinks the Unix socket file it created via
+            // `listen(path)` — verified directly (Node does this internally, not
+            // merely "documented and trusted"); the explicit unlinkSync below is
+            // therefore belt-and-suspenders for the case where close() fires
+            // asynchronously and a caller inspects the filesystem before that
+            // callback runs, not a correction of a leak. On Windows there is no
+            // socket FILE at all (see socketPathFor's doc comment — a named pipe
+            // is a kernel object), so this unlink is always a harmless no-op
+            // there (ENOENT, swallowed) rather than something that needs its own
+            // platform branch.
+            server.close();
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { /* already gone, or never existed (Windows) */ }
+        },
+    };
+}
+/**
+ * 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.
+ */
+function sendPeerMessage(targetSocketPath, message) {
+    return new Promise((resolve) => {
+        const safetyError = verifySocketSafety(targetSocketPath);
+        if (safetyError) {
+            resolve({ ok: false, error: safetyError });
+            return;
+        }
+        const payload = { ...message, text: message.text.slice(0, MAX_MESSAGE_BYTES), sentAt: Date.now() };
+        const line = JSON.stringify(payload) + '\n';
+        if (Buffer.byteLength(line, 'utf-8') > MAX_MESSAGE_BYTES * 2) {
+            resolve({ ok: false, error: `message too large (max ${MAX_MESSAGE_BYTES} bytes)` });
+            return;
+        }
+        const socket = net.createConnection(targetSocketPath);
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve({ ok: false, error: 'timed out connecting to peer — it may be busy or have just exited' });
+        }, CONNECT_TIMEOUT_MS);
+        socket.on('connect', () => {
+            socket.write(line, (err) => {
+                clearTimeout(timeout);
+                if (err) {
+                    resolve({ ok: false, error: err.message });
+                    return;
+                }
+                socket.end();
+                resolve({ ok: true });
+            });
+        });
+        socket.on('error', (err) => {
+            clearTimeout(timeout);
+            resolve({ ok: false, error: err.message });
+        });
+    });
+}
+/**
+ * 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.
+ */
+async function broadcastPeerMessage(targets, message) {
+    const results = await Promise.all(targets.map(async (t) => {
+        const r = await sendPeerMessage(t.socketPath, message);
+        return { name: t.name, ok: r.ok, error: r.error };
+    }));
+    return results;
+}
+exports._peerTransportInternal = { verifySocketSafety, MAX_MESSAGE_BYTES, CONNECT_TIMEOUT_MS, isWindows };
+//# sourceMappingURL=peerTransport.js.map

package/dist/agent/sharedTasks.d.ts

@@ -0,0 +1,63 @@
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked';
+export interface SharedTask {
+    id: string;
+    content: string;
+    status: TaskStatus;
+    /** Session name/id that currently owns this task (see peer registry, once that lands) — undefined for pending/completed. */
+    claimedBy?: string;
+    /** pid of the process that claimed it — used for the liveness check, same idea as crossProcessLock's stale-lock detection. */
+    claimedByPid?: number;
+    /** IDs of OTHER tasks in this same list that must be `completed` before this one is claimable. */
+    blockedBy?: string[];
+    createdAt: number;
+    updatedAt: number;
+    claimedAt?: number;
+}
+declare function tasksRoot(): string;
+declare function scopeDir(workDir: string): string;
+declare function taskPath(workDir: string, taskId: string): string;
+/** A claimed task whose owning process is gone, or whose claim has gone stale with no update, is treated as abandoned. */
+declare function isClaimAbandoned(task: SharedTask): boolean;
+/** Whether every task ID in `blockedBy` is `completed` — i.e. this task is actually claimable right now. */
+declare function isUnblocked(workDir: string, task: SharedTask): boolean;
+/** List every task registered for `workDir`, newest first isn't guaranteed — sort by createdAt if display order matters to the caller. */
+export declare function listSharedTasks(workDir: string): SharedTask[];
+/** Create a new pending task. `id` auto-generated (short random) unless the caller supplies a stable one (e.g. re-registering from a static plan). */
+export declare function createSharedTask(workDir: string, content: string, opts?: {
+    id?: string;
+    blockedBy?: string[];
+}): SharedTask;
+export type ClaimResult = {
+    ok: true;
+    task: SharedTask;
+} | {
+    ok: false;
+    reason: 'not-found' | 'already-claimed' | 'blocked' | 'not-pending';
+};
+/**
+ * Atomically claim `taskId` for `claimedBy` (a peer/session name). Race-free
+ * against another process calling this at the same instant — see this
+ * module's header comment for exactly why.
+ */
+export declare function claimTask(workDir: string, taskId: string, claimedBy: string): Promise<ClaimResult>;
+/**
+ * Update a task's status. Used for both normal progress (in_progress →
+ * completed) and releasing a claim early (in_progress → pending, e.g. a
+ * session that claimed a task then decided not to do it after all). Also
+ * lock-guarded — a status update racing a claim attempt must not corrupt
+ * either operation's view of the task.
+ */
+export declare function updateSharedTaskStatus(workDir: string, taskId: string, status: TaskStatus, opts?: {
+    claimedBy?: string;
+}): Promise<ClaimResult>;
+export declare const _sharedTasksInternal: {
+    tasksRoot: typeof tasksRoot;
+    scopeDir: typeof scopeDir;
+    taskPath: typeof taskPath;
+    isClaimAbandoned: typeof isClaimAbandoned;
+    isUnblocked: typeof isUnblocked;
+    CLAIM_STALE_MS: number;
+    MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS: number;
+};
+export {};
+//# sourceMappingURL=sharedTasks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharedTasks.d.ts","sourceRoot":"","sources":["../../src/agent/sharedTasks.ts"],"names":[],"mappings":"AA6DA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,4HAA4H;IAC5H,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8HAA8H;IAC9H,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD,iBAAS,SAAS,IAAI,MAAM,CAE3B;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzC;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AA4BD,0HAA0H;AAC1H,iBAAS,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAUnD;AAED,4GAA4G;AAC5G,iBAAS,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAG/D;AAED,0IAA0I;AAC1I,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAW7D;AAED,sJAAsJ;AACtJ,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC/C,UAAU,CAUZ;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+BxG;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACrF,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED,eAAO,MAAM,oBAAoB;;;;;;;;CAAqH,CAAC"}