@geohar/un-bien 0.7.0

package/dist/session/local_config.d.ts

@@ -0,0 +1,67 @@
+export interface LocalConfig {
+    agent_name?: string;
+    /**
+     * If true (default), `/unbien` with no args auto-joins the local UDS
+     * mesh and starts the relay on a fresh terminal. The field name is
+     * historical (plano 21); the UX wording was reworked to "use the relay
+     * on this terminal to connect to the remote mesh (mobile + PCs)". Legacy
+     * configs without this field are treated as `true` for backward compat.
+     */
+    auto_start_relay?: boolean;
+    /**
+     * un-bien remote launch: when true, this machine HONORS `session_launch`
+     * requests from a paired owner (spawn a new pi session). Default FALSE —
+     * remote process spawn is authority-sensitive, so it's strictly opt-in.
+     * Advertised as the `remote_launch` capability only when enabled.
+     */
+    allow_remote_launch?: boolean;
+}
+/**
+ * Normalize a name segment to a mesh-safe token: trim, replace the addressing
+ * separators (`/ : @ #`) and whitespace runs with `-`, collapse repeats, strip
+ * edges. The `@` is included so a sanitized name can never contain the address
+ * separator — `<cwd>@<name>` stays unambiguous on the wire. Returns undefined
+ * when the input isn't a usable non-empty string, sanitizes to empty, or is a
+ * reserved addressing keyword (`broadcast` / `broker`). Used by the broker's
+ * `sanitizeMeshName` to keep the `<nome>` half of a peer address safe to
+ * compose (plan/38).
+ */
+export declare function sanitizeSegment(v: unknown): string | undefined;
+/**
+ * Migrate a persisted `agent_name` to the plan/38 leaf-name model (decision E).
+ * Two legacy shapes get rewritten on read so a pre-fix config never fossilizes a
+ * runtime accident as if it were an explicit choice:
+ *
+ *   - **`#N` collision suffix** — could only have come from a broker/lock
+ *     assignment (the user can't type `#`: `sanitizeSegment` maps it to `-`), so
+ *     a trailing `#<digits>` is stripped and the clean base re-derived.
+ *   - **legacy `parent/folder`** — the old `defaultAgentName` shape; the `/`
+ *     means it predates the leaf-only model, so we keep only the leaf segment.
+ *
+ * Returns the cleaned name, or undefined when nothing usable remains (so the
+ * caller falls back to `defaultAgentName(cwd)`).
+ */
+export declare function migrateAgentName(raw: string): string | undefined;
+/**
+ * True when a local config is available for this cwd — inline via
+ * `UNBIEN_DIRECT_CONFIG`, as `<cwd>/.pi/un-bien/config.json` on disk, or a
+ * machine-wide `defaults` block in the global config. A global default counts
+ * as "configured" so setting it suppresses the first-run wizard and lets
+ * session_start auto-init everywhere (the intent of "I've set the default").
+ */
+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 (plan/38 decision D): the **leaf**
+ * of the cwd, `basename(cwd)`. The cwd now travels as its own address axis
+ * (`<cwd>@<nome>`), so the name no longer needs the `parent/folder` prefix that
+ * used to disambiguate folders — the broker keys peers by `(cwd, nome)`, and a
+ * clean leaf means `#N` almost never fires. Falls back to `"agent"` for a
+ * path with no usable basename (root / empty).
+ */
+export declare function defaultAgentName(cwd: string): string;
+/** Resolves auto_start_relay with backward-compat (undefined → true). */
+export declare function effectiveAutoStartRelay(cfg: LocalConfig): boolean;
+/** Remote launch is OFF unless explicitly enabled (authority-sensitive). */
+export declare function effectiveAllowRemoteLaunch(cfg: LocalConfig): boolean;

package/dist/session/local_config.js

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { loadConfig } from "../config.js";
+const LOCAL_DIR = ".pi/un-bien";
+const LOCAL_FILE = "config.json";
+/**
+ * Escape hatch: when set, carries the WHOLE local config as inline JSON,
+ * bypassing the on-disk `config.json`. For CI/ops/daemons that inject config
+ * via env instead of writing a file — mirrors `UNBIEN_RELAY` for the relay
+ * URL. Takes precedence over the file; an unset/empty/unparseable value falls
+ * back to the file (never fatal).
+ */
+const DIRECT_CONFIG_ENV = "UNBIEN_DIRECT_CONFIG";
+function pathFor(cwd) {
+    return join(cwd, LOCAL_DIR, LOCAL_FILE);
+}
+/**
+ * Normalize a name segment to a mesh-safe token: trim, replace the addressing
+ * separators (`/ : @ #`) and whitespace runs with `-`, collapse repeats, strip
+ * edges. The `@` is included so a sanitized name can never contain the address
+ * separator — `<cwd>@<name>` stays unambiguous on the wire. Returns undefined
+ * when the input isn't a usable non-empty string, sanitizes to empty, or is a
+ * reserved addressing keyword (`broadcast` / `broker`). Used by the broker's
+ * `sanitizeMeshName` to keep the `<nome>` half of a peer address safe to
+ * compose (plan/38).
+ */
+export function sanitizeSegment(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const token = v
+        .trim()
+        .replace(/[/:@#\s]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!token)
+        return undefined;
+    if (token.toLowerCase() === "broadcast" || token.toLowerCase() === "broker")
+        return undefined;
+    return token;
+}
+/**
+ * Migrate a persisted `agent_name` to the plan/38 leaf-name model (decision E).
+ * Two legacy shapes get rewritten on read so a pre-fix config never fossilizes a
+ * runtime accident as if it were an explicit choice:
+ *
+ *   - **`#N` collision suffix** — could only have come from a broker/lock
+ *     assignment (the user can't type `#`: `sanitizeSegment` maps it to `-`), so
+ *     a trailing `#<digits>` is stripped and the clean base re-derived.
+ *   - **legacy `parent/folder`** — the old `defaultAgentName` shape; the `/`
+ *     means it predates the leaf-only model, so we keep only the leaf segment.
+ *
+ * Returns the cleaned name, or undefined when nothing usable remains (so the
+ * caller falls back to `defaultAgentName(cwd)`).
+ */
+export function migrateAgentName(raw) {
+    // Legacy `parent/folder` (or any path-ish value) → keep the trailing segment.
+    const leaf = raw.includes("/") ? raw.slice(raw.lastIndexOf("/") + 1) : raw;
+    // Drop a runtime collision suffix a pre-fix build may have frozen into config.
+    const clean = leaf.replace(/#\d+$/, "").trim();
+    return clean.length > 0 ? clean : undefined;
+}
+/**
+ * Parse a raw JSON string into a LocalConfig, surfacing only known fields.
+ * Returns null when the input isn't a usable JSON object. Legacy `session_name`
+ * from pre-refactor configs is silently dropped — the local UDS mesh is now
+ * always a single fixed session, so the field has no meaning.
+ */
+function parseLocalConfig(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const src = parsed;
+    const cfg = {};
+    if (typeof src["agent_name"] === "string") {
+        // Migrate on read (plan/38 decision E): strip a frozen `#N` and the legacy
+        // `parent/folder` shape so neither fossilizes as an explicit name.
+        const migrated = migrateAgentName(src["agent_name"]);
+        if (migrated)
+            cfg.agent_name = migrated;
+    }
+    if (typeof src["auto_start_relay"] === "boolean")
+        cfg.auto_start_relay = src["auto_start_relay"];
+    if (typeof src["allow_remote_launch"] === "boolean")
+        cfg.allow_remote_launch = src["allow_remote_launch"];
+    return cfg;
+}
+/** Inline config from `UNBIEN_DIRECT_CONFIG`, when set + parseable; else null. */
+function directConfig() {
+    const raw = process.env[DIRECT_CONFIG_ENV];
+    if (!raw || raw.trim().length === 0)
+        return null;
+    return parseLocalConfig(raw);
+}
+/**
+ * Machine-wide fallback for local-config fields, from the `defaults` block of
+ * the global `~/.pi/un-bien/config.json` (see `UnBienConfig.defaults`). Lets
+ * you pin a default once instead of dropping a `config.json` into every repo.
+ * Returns an empty object when no `defaults` block is present, so the whole
+ * feature is inert (and every path below identical to before) unless opted in.
+ */
+function globalLocalDefaults() {
+    const d = loadConfig().defaults;
+    const cfg = {};
+    if (d && typeof d.auto_start_relay === "boolean")
+        cfg.auto_start_relay = d.auto_start_relay;
+    return cfg;
+}
+/**
+ * True when a local config is available for this cwd — inline via
+ * `UNBIEN_DIRECT_CONFIG`, as `<cwd>/.pi/un-bien/config.json` on disk, or a
+ * machine-wide `defaults` block in the global config. A global default counts
+ * as "configured" so setting it suppresses the first-run wizard and lets
+ * session_start auto-init everywhere (the intent of "I've set the default").
+ */
+export function localConfigExists(cwd) {
+    return (directConfig() !== null ||
+        existsSync(pathFor(cwd)) ||
+        Object.keys(globalLocalDefaults()).length > 0);
+}
+export function loadLocalConfig(cwd) {
+    // Layering (later wins): global `defaults` < per-cwd file / inline env. The
+    // inline `UNBIEN_DIRECT_CONFIG` still takes precedence over the on-disk
+    // file; an unset/empty/malformed env falls through to it. Any field left
+    // unset by the winning source inherits the global default.
+    const defaults = globalLocalDefaults();
+    const direct = directConfig();
+    if (direct)
+        return { ...defaults, ...direct };
+    const p = pathFor(cwd);
+    if (!existsSync(p))
+        return { ...defaults };
+    try {
+        return {
+            ...defaults,
+            ...(parseLocalConfig(readFileSync(p, "utf8")) ?? {}),
+        };
+    }
+    catch {
+        return { ...defaults };
+    }
+}
+export function saveLocalConfig(cwd, patch) {
+    const p = pathFor(cwd);
+    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;
+    // Best-effort persistence: a read-only config.json is a legitimate deployment
+    // (NixOS/Home Manager symlink into the immutable Nix store, read-only root,
+    // EPERM). The name/config sync is cosmetic — it must NEVER crash the pi
+    // process with an uncaughtException. `saveLocalConfig` is reached via
+    // fire-and-forget async paths (`void _syncNameFromPi()` from `turn_start` /
+    // `session_start`), so a sync throw from `mkdirSync`/`writeFileSync` sails
+    // past the runner's per-handler try/catch and takes down pi. Guard both fs
+    // calls together so a partial attempt can't throw past the caller.
+    try {
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify(next, null, 2));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[un-bien] could not persist local config ${p}: ${message}`);
+    }
+}
+/**
+ * Default agent name when none is configured (plan/38 decision D): the **leaf**
+ * of the cwd, `basename(cwd)`. The cwd now travels as its own address axis
+ * (`<cwd>@<nome>`), so the name no longer needs the `parent/folder` prefix that
+ * used to disambiguate folders — the broker keys peers by `(cwd, nome)`, and a
+ * clean leaf means `#N` almost never fires. Falls back to `"agent"` for a
+ * path with no usable basename (root / empty).
+ */
+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;
+}
+/** Remote launch is OFF unless explicitly enabled (authority-sensitive). */
+export function effectiveAllowRemoteLaunch(cfg) {
+    return cfg.allow_remote_launch === true;
+}
+//# 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":"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"}

package/dist/session/mesh_node.d.ts

@@ -0,0 +1,116 @@
+import { SessionPeer, type AckResult } from "./peer.js";
+import type { Envelope } from "./envelope.js";
+import type { Broker } from "./broker.js";
+import { RelayClient } from "../transport/relay_client.js";
+import type { Ed25519Keypair } from "./../pairing/crypto.js";
+import type { MeshTopologySnapshot } from "../mesh/siblings.js";
+/**
+ * MeshNode is the composition point for the local UDS mesh plus the optional
+ * cross-PC Relay bridge. Topology is retained independently from the current
+ * role, Relay, Broker, or bridge publication lifecycle.
+ */
+/** Self-managed-relay bridge config (MCP path). */
+export interface MeshSelfRelayBridge {
+    /** Relay URL in http(s):// form (converted to ws(s):// internally). */
+    relayUrl: string;
+    /** cwd — derives the relay room id and the room_meta. */
+    cwd: string;
+    /** Display name for room_meta. Defaults to the assigned mesh name. */
+    sessionName?: string;
+    /** Advanced/test override; production defaults to five seconds per request. */
+    meshRequestTimeoutMs?: number;
+}
+export interface MeshNodeOptions {
+    /** UDS broker socket path (e.g. ~/.pi/un-bien/sessions/local/broker.sock). */
+    sockPath: string;
+    /** Requested mesh name (broker may add a #N collision suffix). */
+    name: string;
+    cwd?: string;
+    takeoverExisting?: boolean;
+    auditPath?: string;
+    /** Self-managed relay bridge — brought up if this node leads. */
+    bridge?: MeshSelfRelayBridge;
+    /** Diagnostic logger. Defaults to a no-op (avoids leaking into TUIs). */
+    log?: (msg: string) => void;
+}
+export type { AckResult } from "./peer.js";
+export declare class MeshNode {
+    private readonly peer_;
+    private readonly log;
+    private latestTopology;
+    private topologyRevision;
+    private bridgeGeneration;
+    private bridgeAttachInFlight;
+    private bridgeAttachQueued;
+    private closed;
+    private closeInFlight;
+    private activeBridge;
+    private relay;
+    private relayOwned;
+    private relayCloseHandler;
+    private brokerRemote;
+    private piForward;
+    private keypair;
+    private bridgeParams;
+    private reconnectWired;
+    private readonly closedOwnedRelays;
+    /** Self-managed relay reconnect state. Injected Relay reconnect is host-owned. */
+    private relayReconnectTimer;
+    private relayBackoffIdx;
+    private static readonly RELAY_RECONNECT_BACKOFFS_MS;
+    constructor(opts: MeshNodeOptions);
+    /** Join (or lead) the mesh. Resolves with the assigned name. */
+    connect(): Promise<string>;
+    /** Attach an externally-owned Relay. MeshNode never closes this Relay. */
+    attachBridge(opts: {
+        relay: RelayClient;
+        relayUrl: string;
+        keypair?: Ed25519Keypair;
+        meshRequestTimeoutMs?: number;
+    }): Promise<void>;
+    /** Retain a canonical immutable topology independently from bridge state. */
+    setTopology(snapshot: MeshTopologySnapshot): void;
+    hasTopology(): boolean;
+    /** Forget bridge parameters and tear down publication, retaining topology. */
+    detachBridge(): void;
+    private _assertOpen;
+    private _wireReconnect;
+    private _onReconnect;
+    /** One serialized attach loop. Newer generations are drained before exit. */
+    private _requestBridge;
+    private _attemptBridge;
+    private _attemptIsStale;
+    private _relayIsClosed;
+    private _removeMarker;
+    private _closeOwnedRelay;
+    private _teardownPublishedBridge;
+    private _onSelfRelayClosed;
+    private _clearRelayReconnectTimer;
+    private _scheduleRelayReconnect;
+    private _attemptRelayReconnect;
+    /** Announce the local peer set to siblings (Pi broker peer_joined/left). */
+    onLocalPeersChanged(local: string[]): void;
+    /** True when the cross-PC relay bridge is active (this node is leader). */
+    hasBridge(): boolean;
+    /** The underlying SessionPeer — for consumers that need it directly (tools). */
+    peer(): SessionPeer;
+    /** Fire-and-forget send. `to` may be a name, `<pc>:<name>`, or "broadcast". */
+    send(to: string | string[], body: unknown, re?: string | null): Promise<void>;
+    /** Unicast send + await broker ACK (received/busy/denied/timeout). */
+    sendWithAck(to: string, body: unknown, re?: string | null, timeoutMs?: number): Promise<AckResult>;
+    /** Send + await the first reply whose `re` matches the outbound id. */
+    request(to: string, body: unknown, timeoutMs?: number): Promise<Envelope>;
+    /** Subscribe to inbound envelopes. Returns an unsubscribe fn. */
+    onMessage(handler: (env: Envelope) => void): () => void;
+    /** Subscribe to post-failover reconnects. Returns an unsubscribe fn. */
+    onReconnect(handler: () => void): () => void;
+    /** Assigned clean mesh name (after any #N collision suffix). */
+    name(): string;
+    /** Canonical mesh address (`[<pc>:]<cwd>@<nome>`) — echo, never compose. */
+    address(): string;
+    rename(newName: string): Promise<string>;
+    currentRole(): "leader" | "follower";
+    localBroker(): Broker | null;
+    listPeers(timeoutMs?: number): Promise<string[]>;
+    close(): Promise<void>;
+}