remote-pi 0.1.0

package/dist/session/broker.js

@@ -0,0 +1,206 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { parse, serialize, uuidv7, EnvelopeError } from "./envelope.js";
+const BROKER_NAME = "broker";
+export class Broker {
+    peers = new Map();
+    auditPath;
+    onRouted;
+    server;
+    constructor(opts) {
+        this.server = opts.server;
+        this.auditPath = opts.auditPath;
+        this.onRouted = opts.onRouted;
+        this.server.on("connection", (socket) => this._handleConnection(socket));
+    }
+    /** Peers currently registered. Snapshot, safe to read. */
+    peerNames() {
+        return [...this.peers.keys()];
+    }
+    async close() {
+        for (const p of this.peers.values())
+            p.socket.destroy();
+        this.peers.clear();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+    }
+    // ── connection lifecycle ──────────────────────────────────────────────────
+    _handleConnection(socket) {
+        const conn = { name: "", socket, buf: "" };
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => this._onData(conn, chunk));
+        socket.on("close", () => this._onClose(conn));
+        socket.on("error", () => { });
+    }
+    _onData(conn, chunk) {
+        conn.buf += chunk;
+        let nl;
+        while ((nl = conn.buf.indexOf("\n")) >= 0) {
+            const line = conn.buf.slice(0, nl);
+            conn.buf = conn.buf.slice(nl + 1);
+            if (!line)
+                continue;
+            void this._handleLine(conn, line);
+        }
+    }
+    async _handleLine(conn, line) {
+        // Unregistered conn must send a `register` control message first.
+        if (!conn.name) {
+            this._handleRegister(conn, line);
+            return;
+        }
+        // Already registered — must be a regular envelope.
+        let env;
+        try {
+            env = parse(line);
+        }
+        catch (e) {
+            if (e instanceof EnvelopeError)
+                return; // malformed; drop silently
+            throw e;
+        }
+        // Force `from` to the registered name (security: peer can't spoof).
+        env.from = conn.name;
+        await this._route(env);
+    }
+    _handleRegister(conn, line) {
+        let req;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed ||
+                typeof parsed !== "object" ||
+                parsed.type !== "register" ||
+                typeof parsed.name !== "string") {
+                conn.socket.destroy();
+                return;
+            }
+            req = parsed;
+        }
+        catch {
+            conn.socket.destroy();
+            return;
+        }
+        const assigned = this._uniqueName(req.name);
+        conn.name = assigned;
+        this.peers.set(assigned, conn);
+        const ack = { type: "register_ack", name_assigned: assigned };
+        try {
+            conn.socket.write(JSON.stringify(ack) + "\n");
+        }
+        catch { /* peer hung up */ }
+        // Notify others (peer_joined broadcast).
+        this._broadcastSystem({ type: "peer_joined", name: assigned }, assigned);
+    }
+    _uniqueName(requested) {
+        if (!this.peers.has(requested))
+            return requested;
+        for (let n = 2; n < 1000; n++) {
+            const candidate = `${requested}#${n}`;
+            if (!this.peers.has(candidate))
+                return candidate;
+        }
+        throw new Error(`name space exhausted for ${requested}`);
+    }
+    _onClose(conn) {
+        if (!conn.name)
+            return;
+        this.peers.delete(conn.name);
+        this._broadcastSystem({ type: "peer_left", name: conn.name }, conn.name);
+    }
+    // ── routing ───────────────────────────────────────────────────────────────
+    async _route(env) {
+        // Special handling for messages addressed to the broker itself.
+        if (env.to === BROKER_NAME) {
+            this._handleBrokerMessage(env);
+            return;
+        }
+        const targets = this._resolveTargets(env);
+        const delivered = [];
+        const line = serialize(env);
+        for (const targetName of targets) {
+            const peer = this.peers.get(targetName);
+            if (!peer)
+                continue;
+            try {
+                peer.socket.write(line);
+                delivered.push(targetName);
+            }
+            catch {
+                // peer dropped mid-write — close handler will fire
+            }
+        }
+        if (this.auditPath)
+            await this._appendAudit(env, delivered);
+        this.onRouted?.(env, delivered);
+    }
+    _resolveTargets(env) {
+        if (env.to === "broadcast") {
+            return this.peerNames().filter((n) => n !== env.from);
+        }
+        if (Array.isArray(env.to)) {
+            return env.to.filter((n) => n !== env.from);
+        }
+        // Unicast: drop self-loops too. The skill warns "useless" but the LLM
+        // might still try (especially with deceiving `re` reply chains). A
+        // self-loop has no upside and risks unbounded message ↔ inject ↔ message
+        // cycles when the inbound injector tells the LLM "reply with re=…".
+        if (env.to === env.from)
+            return [];
+        return [env.to];
+    }
+    _handleBrokerMessage(env) {
+        const body = env.body;
+        if (!body || typeof body !== "object")
+            return;
+        if (body.type === "list_peers") {
+            const reply = {
+                from: BROKER_NAME,
+                to: env.from,
+                id: uuidv7(),
+                re: env.id,
+                body: { type: "list_peers_reply", peers: this.peerNames() },
+            };
+            const peer = this.peers.get(env.from);
+            if (peer) {
+                try {
+                    peer.socket.write(serialize(reply));
+                }
+                catch { /* ignored */ }
+            }
+        }
+    }
+    _broadcastSystem(body, excludeName) {
+        for (const [name, peer] of this.peers) {
+            if (name === excludeName)
+                continue;
+            const env = {
+                from: BROKER_NAME,
+                to: name,
+                id: uuidv7(),
+                re: null,
+                body,
+            };
+            try {
+                peer.socket.write(serialize(env));
+            }
+            catch { /* ignored */ }
+        }
+    }
+    async _appendAudit(env, delivered) {
+        if (!this.auditPath)
+            return;
+        const line = JSON.stringify({
+            ts: Date.now(),
+            from: env.from,
+            to: env.to,
+            id: env.id,
+            re: env.re,
+            delivered,
+        }) + "\n";
+        try {
+            await mkdir(dirname(this.auditPath), { recursive: true });
+            await appendFile(this.auditPath, line, "utf8");
+        }
+        catch { /* audit best-effort */ }
+    }
+}
+//# sourceMappingURL=broker.js.map

package/dist/session/broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../../src/session/broker.ts"],"names":[],"mappings":"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"}

package/dist/session/envelope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 5-field envelope for the agent-network local protocol (plano 19).
+ * Serialized as JSONL (one JSON object per line) over UDS streams.
+ */
+export interface Envelope {
+    from: string;
+    to: string | string[];
+    id: string;
+    re: string | null;
+    body: unknown;
+}
+/**
+ * Generates a UUID v7 — time-ordered, monotonically increasing within the
+ * same millisecond. Format:
+ *   <48-bit ts ms><4-bit ver=7><12-bit rand><2-bit var=10><62-bit rand>
+ */
+export declare function uuidv7(): string;
+export declare class EnvelopeError extends Error {
+    constructor(message: string);
+}
+export declare function serialize(env: Envelope): string;
+export declare function parse(line: string): Envelope;
+/** Convenience: builds an envelope with id auto-generated. */
+export declare function envelope(from: string, to: string | string[], body: unknown, re?: string | null): Envelope;

package/dist/session/envelope.js

@@ -0,0 +1,89 @@
+import { randomBytes } from "node:crypto";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Generates a UUID v7 — time-ordered, monotonically increasing within the
+ * same millisecond. Format:
+ *   <48-bit ts ms><4-bit ver=7><12-bit rand><2-bit var=10><62-bit rand>
+ */
+export function uuidv7() {
+    const ts = Date.now();
+    const rand = randomBytes(10);
+    // Encode 48-bit timestamp into bytes 0-5.
+    const buf = Buffer.alloc(16);
+    buf[0] = (ts / 2 ** 40) & 0xff;
+    buf[1] = (ts / 2 ** 32) & 0xff;
+    buf[2] = (ts / 2 ** 24) & 0xff;
+    buf[3] = (ts / 2 ** 16) & 0xff;
+    buf[4] = (ts / 2 ** 8) & 0xff;
+    buf[5] = ts & 0xff;
+    rand.copy(buf, 6);
+    // Set version (7) in upper nibble of byte 6.
+    buf[6] = (buf[6] & 0x0f) | 0x70;
+    // Set variant (10) in upper two bits of byte 8.
+    buf[8] = (buf[8] & 0x3f) | 0x80;
+    const hex = buf.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+export class EnvelopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvelopeError";
+    }
+}
+export function serialize(env) {
+    return JSON.stringify(env) + "\n";
+}
+export function parse(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch (e) {
+        throw new EnvelopeError(`not JSON: ${e.message}`);
+    }
+    if (!raw || typeof raw !== "object") {
+        throw new EnvelopeError("not an object");
+    }
+    const o = raw;
+    if (typeof o["from"] !== "string" || o["from"].length === 0) {
+        throw new EnvelopeError("from must be non-empty string");
+    }
+    const to = o["to"];
+    if (typeof to !== "string" && !Array.isArray(to)) {
+        throw new EnvelopeError("to must be string or array");
+    }
+    if (typeof to === "string" && to.length === 0) {
+        throw new EnvelopeError("to must be non-empty");
+    }
+    if (Array.isArray(to)) {
+        if (to.length === 0)
+            throw new EnvelopeError("to[] must not be empty");
+        for (const t of to) {
+            if (typeof t !== "string" || t.length === 0) {
+                throw new EnvelopeError("to[] entries must be non-empty strings");
+            }
+        }
+    }
+    if (typeof o["id"] !== "string" || !UUID_RE.test(o["id"])) {
+        throw new EnvelopeError("id must be UUID");
+    }
+    const re = o["re"];
+    if (re !== null && (typeof re !== "string" || !UUID_RE.test(re))) {
+        throw new EnvelopeError("re must be null or UUID");
+    }
+    if (!("body" in o)) {
+        throw new EnvelopeError("body required");
+    }
+    return {
+        from: o["from"],
+        to: to,
+        id: o["id"],
+        re: re,
+        body: o["body"],
+    };
+}
+/** Convenience: builds an envelope with id auto-generated. */
+export function envelope(from, to, body, re = null) {
+    return { from, to, id: uuidv7(), re, body };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/session/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/session/envelope.ts"],"names":[],"mappings":"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"}

package/dist/session/global_config.d.ts

@@ -0,0 +1,14 @@
+/** Ensures the new subdirs exist inside the existing ~/.pi/remote/. */
+export declare function ensureGlobalDirs(): void;
+/** Path to the UDS socket for a named session. */
+export declare function sessionSockPath(name: string): string;
+/** Path to the audit log for a named session. */
+export declare function sessionAuditPath(name: string): string;
+/** Path to the session metadata JSON. */
+export declare function sessionMetaPath(name: string): string;
+export declare function sessionsDir(): string;
+export declare function skillsDir(): string;
+/** Lists discovered session names from disk. */
+export declare function listSessions(): string[];
+/** Heuristic: a session has an existing broker.sock file. */
+export declare function sessionHasSock(name: string): boolean;

package/dist/session/global_config.js

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const HOME_PI_REMOTE = join(homedir(), ".pi", "remote");
+const SESSIONS_DIR = join(HOME_PI_REMOTE, "sessions");
+const SKILLS_DIR = join(HOME_PI_REMOTE, "skills");
+/** Ensures the new subdirs exist inside the existing ~/.pi/remote/. */
+export function ensureGlobalDirs() {
+    mkdirSync(SESSIONS_DIR, { recursive: true });
+    mkdirSync(SKILLS_DIR, { recursive: true });
+}
+/** Path to the UDS socket for a named session. */
+export function sessionSockPath(name) {
+    return join(SESSIONS_DIR, name, "broker.sock");
+}
+/** Path to the audit log for a named session. */
+export function sessionAuditPath(name) {
+    return join(SESSIONS_DIR, name, "audit.jsonl");
+}
+/** Path to the session metadata JSON. */
+export function sessionMetaPath(name) {
+    return join(SESSIONS_DIR, name, "session.json");
+}
+export function sessionsDir() {
+    return SESSIONS_DIR;
+}
+export function skillsDir() {
+    return SKILLS_DIR;
+}
+/** Lists discovered session names from disk. */
+export function listSessions() {
+    ensureGlobalDirs();
+    try {
+        return readdirSync(SESSIONS_DIR).filter((entry) => {
+            try {
+                return statSync(join(SESSIONS_DIR, entry)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Heuristic: a session has an existing broker.sock file. */
+export function sessionHasSock(name) {
+    return existsSync(sessionSockPath(name));
+}
+//# sourceMappingURL=global_config.js.map

package/dist/session/global_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global_config.js","sourceRoot":"","sources":["../../src/session/global_config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AACxD,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;AACtD,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;AAElD,uEAAuE;AACvE,MAAM,UAAU,gBAAgB;IAC9B,SAAS,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,YAAY;IAC1B,gBAAgB,EAAE,CAAC;IACnB,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YAChD,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YAC3D,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,KAAK,CAAC;YAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/session/leader_election.d.ts

@@ -0,0 +1,16 @@
+import { Server, Socket } from "node:net";
+export type ElectionResult = {
+    role: "leader";
+    server: Server;
+} | {
+    role: "follower";
+    socket: Socket;
+};
+/**
+ * UDS-based leader election. Tries to connect to `sockPath`; on failure, tries
+ * to bind. If both lose the race (EADDRINUSE on bind, ECONNREFUSED on connect),
+ * cleans up stale sock file and retries with jittered backoff.
+ *
+ * Returns the role + the live handle (server for leader, socket for follower).
+ */
+export declare function joinOrLead(sockPath: string): Promise<ElectionResult>;

package/dist/session/leader_election.js

@@ -0,0 +1,78 @@
+import { createConnection, createServer } from "node:net";
+import { existsSync, lstatSync, unlinkSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+const MAX_ATTEMPTS = 20;
+const BASE_BACKOFF_MS = 30;
+const JITTER_MS = 70;
+const PROBE_TIMEOUT_MS = 500;
+/**
+ * UDS-based leader election. Tries to connect to `sockPath`; on failure, tries
+ * to bind. If both lose the race (EADDRINUSE on bind, ECONNREFUSED on connect),
+ * cleans up stale sock file and retries with jittered backoff.
+ *
+ * Returns the role + the live handle (server for leader, socket for follower).
+ */
+export async function joinOrLead(sockPath) {
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        if (existsSync(sockPath)) {
+            const sock = await _tryConnect(sockPath);
+            if (sock)
+                return { role: "follower", socket: sock };
+            _removeStaleSock(sockPath);
+        }
+        const server = await _tryBind(sockPath);
+        if (server)
+            return { role: "leader", server };
+        await delay(BASE_BACKOFF_MS + Math.random() * JITTER_MS);
+    }
+    throw new Error(`leader election failed after ${MAX_ATTEMPTS} attempts: ${sockPath}`);
+}
+function _tryConnect(sockPath) {
+    return new Promise((resolve) => {
+        const sock = createConnection({ path: sockPath });
+        let settled = false;
+        const settle = (val) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (!val)
+                sock.destroy();
+            resolve(val);
+        };
+        const timer = setTimeout(() => settle(null), PROBE_TIMEOUT_MS);
+        sock.once("connect", () => settle(sock));
+        sock.once("error", () => settle(null));
+    });
+}
+function _tryBind(sockPath) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        let settled = false;
+        const settle = (val) => {
+            if (settled)
+                return;
+            settled = true;
+            if (!val) {
+                try {
+                    server.close();
+                }
+                catch { /* ignored */ }
+            }
+            resolve(val);
+        };
+        server.once("error", () => settle(null));
+        server.listen(sockPath, () => settle(server));
+    });
+}
+function _removeStaleSock(sockPath) {
+    try {
+        const stat = lstatSync(sockPath);
+        if (stat.isSocket())
+            unlinkSync(sockPath);
+    }
+    catch {
+        // ENOENT or not-a-socket — nothing to clean up.
+    }
+}
+//# sourceMappingURL=leader_election.js.map

package/dist/session/leader_election.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader_election.js","sourceRoot":"","sources":["../../src/session/leader_election.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAM7B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,YAAY,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;YACzC,IAAI,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACpD,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAE9C,MAAM,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,gCAAgC,YAAY,cAAc,QAAQ,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB;IACnC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,GAAkB,EAAE,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC,GAAG;gBAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,QAAgB;IAChC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,GAAkB,EAAE,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,IAAI,CAAC;oBAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,QAAQ,EAAE;YAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC"}

package/dist/session/local_config.d.ts

@@ -0,0 +1,18 @@
+export interface LocalConfig {
+    agent_name?: string;
+    session_name?: string;
+    /**
+     * If true (default), `/remote-pi` with no args auto-joins the session and
+     * starts the relay on a fresh terminal. Added in plano 21. Legacy configs
+     * without this field are treated as `true` for backward compatibility.
+     */
+    auto_start_relay?: boolean;
+}
+/** Returns true when `<cwd>/.pi/remote-pi/config.json` exists on disk. */
+export declare function localConfigExists(cwd: string): boolean;
+export declare function loadLocalConfig(cwd: string): LocalConfig;
+export declare function saveLocalConfig(cwd: string, patch: Partial<LocalConfig>): void;
+/** Default agent name when none is configured: basename of cwd. */
+export declare function defaultAgentName(cwd: string): string;
+/** Resolves auto_start_relay with backward-compat (undefined → true). */
+export declare function effectiveAutoStartRelay(cfg: LocalConfig): boolean;

package/dist/session/local_config.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+const LOCAL_DIR = ".pi/remote-pi";
+const LOCAL_FILE = "config.json";
+function pathFor(cwd) {
+    return join(cwd, LOCAL_DIR, LOCAL_FILE);
+}
+/** Returns true when `<cwd>/.pi/remote-pi/config.json` exists on disk. */
+export function localConfigExists(cwd) {
+    return existsSync(pathFor(cwd));
+}
+export function loadLocalConfig(cwd) {
+    const p = pathFor(cwd);
+    if (!existsSync(p))
+        return {};
+    try {
+        const raw = readFileSync(p, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export function saveLocalConfig(cwd, patch) {
+    const p = pathFor(cwd);
+    mkdirSync(dirname(p), { recursive: true });
+    const current = loadLocalConfig(cwd);
+    const next = { ...current, ...patch };
+    // Always persist auto_start_relay explicitly (default true) so future reads
+    // never need to guess. Backward-compat: legacy files without the field
+    // are treated as true on read; we lock that intent in on first save.
+    if (typeof next.auto_start_relay !== "boolean")
+        next.auto_start_relay = true;
+    writeFileSync(p, JSON.stringify(next, null, 2));
+}
+/** Default agent name when none is configured: basename of cwd. */
+export function defaultAgentName(cwd) {
+    return basename(cwd) || "agent";
+}
+/** Resolves auto_start_relay with backward-compat (undefined → true). */
+export function effectiveAutoStartRelay(cfg) {
+    return cfg.auto_start_relay !== false;
+}
+//# sourceMappingURL=local_config.js.map

package/dist/session/local_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local_config.js","sourceRoot":"","sources":["../../src/session/local_config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,SAAS,GAAG,eAAe,CAAC;AAClC,MAAM,UAAU,GAAG,aAAa,CAAC;AAajC,SAAS,OAAO,CAAC,GAAW;IAC1B,OAAO,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACrD,OAAO,MAAqB,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,KAA2B;IACtE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,IAAI,GAAgB,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;IACnD,4EAA4E;IAC5E,uEAAuE;IACvE,qEAAqE;IACrE,IAAI,OAAO,IAAI,CAAC,gBAAgB,KAAK,SAAS;QAAE,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAC7E,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,uBAAuB,CAAC,GAAgB;IACtD,OAAO,GAAG,CAAC,gBAAgB,KAAK,KAAK,CAAC;AACxC,CAAC"}