@geohar/un-bien 0.7.0

package/dist/session/setup_wizard.d.ts

@@ -0,0 +1,39 @@
+import type { LocalConfig } from "./local_config.js";
+/**
+ * Pi SDK UI surface needed by the wizard. Subset of `ExtensionUIContext` —
+ * declared inline so tests can mock cleanly without dragging the full
+ * ExtensionContext shape.
+ */
+export interface WizardUI {
+    /** Free-text prompt. Returns the entered string, or undefined if cancelled. */
+    input?: (title: string, options?: {
+        defaultValue?: string;
+    }) => Promise<string | undefined>;
+    /** Picker. Returns the picked option, or undefined if cancelled. */
+    select: (title: string, options: string[]) => Promise<string | undefined>;
+    /** Non-blocking notification. Used for inline validation feedback. */
+    notify?: (msg: string, kind: "info" | "warning" | "error") => void;
+}
+export interface WizardDefaults {
+    agent_name: string;
+    use_relay: boolean;
+}
+/**
+ * Runs the 2-question setup wizard. Returns the chosen config on confirm, or
+ * null when the user cancels any prompt.
+ *
+ * Prompts:
+ *   1. Agent name (default: parent/folder of cwd)
+ *   2. Use the relay on this terminal? (yes/no) — gates connection to the
+ *      remote mesh (mobile devices + other PCs over the relay). "No" means
+ *      local-only: this Pi joins the UDS mesh but doesn't open WSS.
+ *   Final: review + confirm "Save and activate?" yes/no
+ *
+ * Daemon mode (run agents 24/7 via systemd/launchd) is intentionally NOT in
+ * the wizard — it's an explicit, separate opt-in via `/unbien install`.
+ *
+ * The local UDS mesh is always single per machine ("local" session) — no
+ * session question. All Pis on the same machine see each other through
+ * the same broker.
+ */
+export declare function runSetupWizard(ui: WizardUI, defaults: WizardDefaults): Promise<LocalConfig | null>;

package/dist/session/setup_wizard.js

@@ -0,0 +1,63 @@
+const YES = "Yes";
+const NO = "No";
+const CANCEL_TOKEN = "__cancel__";
+/**
+ * Runs the 2-question setup wizard. Returns the chosen config on confirm, or
+ * null when the user cancels any prompt.
+ *
+ * Prompts:
+ *   1. Agent name (default: parent/folder of cwd)
+ *   2. Use the relay on this terminal? (yes/no) — gates connection to the
+ *      remote mesh (mobile devices + other PCs over the relay). "No" means
+ *      local-only: this Pi joins the UDS mesh but doesn't open WSS.
+ *   Final: review + confirm "Save and activate?" yes/no
+ *
+ * Daemon mode (run agents 24/7 via systemd/launchd) is intentionally NOT in
+ * the wizard — it's an explicit, separate opt-in via `/unbien install`.
+ *
+ * The local UDS mesh is always single per machine ("local" session) — no
+ * session question. All Pis on the same machine see each other through
+ * the same broker.
+ */
+export async function runSetupWizard(ui, defaults) {
+    const agent_name = await _askText(ui, "Agent name:", defaults.agent_name);
+    if (agent_name === null)
+        return null;
+    ui.notify?.("The relay forwards encrypted messages to the Remote Pi mobile app and other PCs in your mesh. Skip this if you only want a local-only mesh on this machine.", "info");
+    const useRelayChoice = await ui.select("Use the relay on this terminal to connect to the remote mesh (mobile + PCs)?", defaults.use_relay ? [YES, NO] : [NO, YES]);
+    if (!useRelayChoice)
+        return null;
+    const auto_start_relay = useRelayChoice === YES;
+    // Review + confirm
+    const summary = [
+        `  Agent name:    ${agent_name}`,
+        `  Use relay:     ${auto_start_relay ? YES : NO}`,
+    ].join("\n");
+    ui.notify?.(`Summary:\n${summary}`, "info");
+    const confirm = await ui.select("Save and activate?", [YES, NO]);
+    if (confirm !== YES)
+        return null;
+    return { agent_name, auto_start_relay };
+}
+/**
+ * Asks the user for free text. The Pi SDK's `ui.input` does not pre-fill the
+ * field with `defaultValue` (the SDK ignores that option), so we surface the
+ * default in the prompt label and treat an empty submission as "accept the
+ * default" — the standard CLI convention. Falls back to `select` when the
+ * SDK doesn't expose `input` at all.
+ */
+async function _askText(ui, title, defaultValue) {
+    const titleWithHint = `${title} (default: ${defaultValue})`;
+    const raw = ui.input
+        ? await ui.input(titleWithHint, { defaultValue })
+        : await ui.select(titleWithHint, [defaultValue, CANCEL_TOKEN]);
+    if (raw === undefined)
+        return null;
+    if (raw === CANCEL_TOKEN)
+        return null;
+    const trimmed = raw.trim();
+    // Empty submission = accept the default. No re-prompt, no warning — the
+    // user explicitly asked for the default by hitting enter.
+    return trimmed.length > 0 ? trimmed : defaultValue;
+}
+//# sourceMappingURL=setup_wizard.js.map

package/dist/session/setup_wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup_wizard.js","sourceRoot":"","sources":["../../src/session/setup_wizard.ts"],"names":[],"mappings":"AAwBA,MAAM,GAAG,GAAG,KAAK,CAAC;AAClB,MAAM,EAAE,GAAG,IAAI,CAAC;AAChB,MAAM,YAAY,GAAG,YAAY,CAAC;AAElC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAY,EACZ,QAAwB;IAExB,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,EAAE,EAAE,aAAa,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC1E,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAErC,EAAE,CAAC,MAAM,EAAE,CACT,6JAA6J,EAC7J,MAAM,CACP,CAAC;IACF,MAAM,cAAc,GAAG,MAAM,EAAE,CAAC,MAAM,CACpC,8EAA8E,EAC9E,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAC3C,CAAC;IACF,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,gBAAgB,GAAG,cAAc,KAAK,GAAG,CAAC;IAEhD,mBAAmB;IACnB,MAAM,OAAO,GAAG;QACd,oBAAoB,UAAU,EAAE;QAChC,oBAAoB,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;KAClD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,EAAE,CAAC,MAAM,EAAE,CAAC,aAAa,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEjC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,QAAQ,CACrB,EAAY,EACZ,KAAa,EACb,YAAoB;IAEpB,MAAM,aAAa,GAAG,GAAG,KAAK,cAAc,YAAY,GAAG,CAAC;IAC5D,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK;QAClB,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,EAAE,YAAY,EAAE,CAAC;QACjD,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;IACjE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,GAAG,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,wEAAwE;IACxE,0DAA0D;IAC1D,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;AACrD,CAAC"}

package/dist/session/tools.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SessionPeer } from "./peer.js";
+/**
+ * Registers the native tools the Pi LLM uses to talk to other agents in the
+ * same UDS session (plano 19 transport + plan/25 Wave 0 ACK protocol):
+ *
+ *   - `agent_send`     — unified delivery with broker-level ACK. Returns
+ *                        a status so the LLM can decide whether to retry.
+ *                        For unicast targets the broker auto-replies with
+ *                        `received | busy | denied`. For broadcast/multicast
+ *                        the tool is fire-and-forget (status `sent`).
+ *   - `agent_request`  — **deprecated**. Still works (send + block on reply
+ *                        via `re` correlation) but the LLM should migrate
+ *                        to the event-driven send+inbox pattern. Each call
+ *                        emits a one-shot warning to stderr.
+ *
+ * Reply pattern (new world): when you receive a message you want to answer,
+ * send back another envelope with `re=<original-id>`. The original sender
+ * sees that reply in its inbox during a future turn.
+ *
+ * `getSessionPeer` is a getter (not a captured value) so changes to the
+ * underlying `_sessionPeer` module variable are observed live.
+ */
+export declare function registerAgentTools(pi: ExtensionAPI, getSessionPeer: () => SessionPeer | null): void;

package/dist/session/tools.js

@@ -0,0 +1,272 @@
+import { Type } from "typebox";
+const NOT_IN_SESSION = "Not in a session. Run /unbien join first";
+const ACK_TIMEOUT_MS = 5_000;
+const LEGACY_REQUEST_TIMEOUT_MS = 30_000;
+const LIST_PEERS_TIMEOUT_MS = 2_000;
+/**
+ * Registers the native tools the Pi LLM uses to talk to other agents in the
+ * same UDS session (plano 19 transport + plan/25 Wave 0 ACK protocol):
+ *
+ *   - `agent_send`     — unified delivery with broker-level ACK. Returns
+ *                        a status so the LLM can decide whether to retry.
+ *                        For unicast targets the broker auto-replies with
+ *                        `received | busy | denied`. For broadcast/multicast
+ *                        the tool is fire-and-forget (status `sent`).
+ *   - `agent_request`  — **deprecated**. Still works (send + block on reply
+ *                        via `re` correlation) but the LLM should migrate
+ *                        to the event-driven send+inbox pattern. Each call
+ *                        emits a one-shot warning to stderr.
+ *
+ * Reply pattern (new world): when you receive a message you want to answer,
+ * send back another envelope with `re=<original-id>`. The original sender
+ * sees that reply in its inbox during a future turn.
+ *
+ * `getSessionPeer` is a getter (not a captured value) so changes to the
+ * underlying `_sessionPeer` module variable are observed live.
+ */
+export function registerAgentTools(pi, getSessionPeer) {
+    const SendParams = Type.Object({
+        to: Type.String({
+            description: "Recipient agent name (e.g. 'backend'), 'broadcast', or array of names. " +
+                "Broadcast/multicast are fire-and-forget; unicast returns an ACK status.",
+        }),
+        body: Type.Unknown({
+            description: "Free-form JSON payload. String or object — your choice.",
+        }),
+        re: Type.Optional(Type.String({
+            description: "Set this to the `id` of an incoming message when you are REPLYING to it. " +
+                "The peer correlates your answer with their original send via this field.",
+        })),
+    });
+    const RequestParams = Type.Object({
+        to: Type.String({
+            description: "Recipient agent name. Must be a single peer (not broadcast).",
+        }),
+        body: Type.Unknown({ description: "Free-form JSON payload to send." }),
+        timeout_ms: Type.Optional(Type.Number({
+            description: "Optional override of the default 30s reply timeout. Per-request.",
+        })),
+    });
+    pi.registerTool({
+        name: "agent_send",
+        label: "Agent Send",
+        description: "Send a message to another Pi agent in the current local session and " +
+            "wait for the broker's delivery ACK. Delivery is reliable: a peer that " +
+            "is mid-turn still receives the message (its harness enqueues it for " +
+            "the next turn), so you never need to retry. Returns one of: `received` " +
+            "(delivered; peer will process it in an upcoming turn), `denied` (peer " +
+            "refused), `timeout` (no ACK in 5s — peer offline / transport error), " +
+            "`sent` (broadcast/multicast — no ACK semantics). Use `re` to mark this " +
+            "message as a reply to an incoming envelope's `id` (correlation only).",
+        promptSnippet: "agent_send({to, body, re?}): unicast → returns {status: received|denied|timeout} (delivery is reliable; no retry-on-busy). Broadcast/multicast → fire-and-forget ({status:'sent'}).",
+        parameters: SendParams,
+        execute: async (_toolCallId, params) => {
+            const peer = getSessionPeer();
+            if (!peer) {
+                const details = {
+                    status: "refused",
+                    ok: false,
+                    error: NOT_IN_SESSION,
+                };
+                return {
+                    content: [{ type: "text", text: NOT_IN_SESSION }],
+                    details,
+                };
+            }
+            const { to, body, re } = params;
+            if (to === peer.address() || to === peer.name()) {
+                const msg = `Refused: cannot agent_send to yourself ("${to}"). Just do the work directly.`;
+                const details = {
+                    status: "refused",
+                    ok: false,
+                    error: msg,
+                };
+                return {
+                    content: [{ type: "text", text: msg }],
+                    details,
+                };
+            }
+            const isUnicast = to !== "broadcast";
+            // Broadcast: fire-and-forget. Broker doesn't ACK multi-target sends.
+            if (!isUnicast) {
+                try {
+                    await peer.send(to, body, re ?? null);
+                    const details = { status: "sent", ok: true };
+                    return {
+                        content: [{ type: "text", text: `Broadcast sent.` }],
+                        details,
+                    };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const details = {
+                        status: "timeout",
+                        ok: false,
+                        error: msg,
+                    };
+                    return {
+                        content: [{ type: "text", text: `Broadcast failed: ${msg}` }],
+                        details,
+                    };
+                }
+            }
+            // Unicast: wait for broker ACK.
+            try {
+                const ack = await peer.sendWithAck(to, body, re ?? null, ACK_TIMEOUT_MS);
+                const ok = ack.status === "received";
+                const details = {
+                    status: ack.status,
+                    ok,
+                    ...(ack.target === undefined ? {} : { target: ack.target }),
+                    ...(ack.error === undefined ? {} : { error: ack.error }),
+                    ...(ack.reason === undefined ? {} : { reason: ack.reason }),
+                };
+                const text = _formatAck(to, ack, re);
+                return { content: [{ type: "text", text }], details };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                const details = {
+                    status: "timeout",
+                    ok: false,
+                    error: msg,
+                };
+                return {
+                    content: [{ type: "text", text: `Failed to send: ${msg}` }],
+                    details,
+                };
+            }
+        },
+    });
+    const ListPeersParams = Type.Object({});
+    pi.registerTool({
+        name: "list_peers",
+        label: "List Peers",
+        description: "Returns the current peer inventory in this session as ADDRESSES of the " +
+            "form `<cwd>@<name>` (cross-PC peers prefixed `<pc>:`). An address is an " +
+            "opaque routing key — pass it to `agent_send`/`agent_request` VERBATIM, " +
+            "never build one by hand. Use BEFORE sending whenever you're unsure who's " +
+            "available, or after a `peer_joined` / `peer_left` notification to refresh " +
+            "your mental model. Resolves in milliseconds — a metadata query to the " +
+            "broker, not a turn of another agent.",
+        promptSnippet: "list_peers(): returns {peers: string[]} of addresses `<cwd>@<name>` (`<pc>:` prefix cross-PC). Echo an address verbatim to agent_send; never compose one. Cheap; call freely.",
+        parameters: ListPeersParams,
+        execute: async (_toolCallId) => {
+            const peer = getSessionPeer();
+            if (!peer) {
+                return {
+                    content: [{ type: "text", text: NOT_IN_SESSION }],
+                    details: { peers: [] },
+                };
+            }
+            try {
+                // Internal use of the request/reply primitive is fine — broker
+                // replies are synthesised in-process (`_handleBrokerMessage`)
+                // without going through `_route`, so they bypass the ACK path.
+                const reply = await peer.request("broker", { type: "list_peers" }, LIST_PEERS_TIMEOUT_MS);
+                const body = reply.body;
+                const peers = Array.isArray(body?.peers)
+                    ? body.peers.filter((p) => typeof p === "string")
+                    : [];
+                // Drop self from the list — the caller is the only one who can't
+                // address itself anyway, so listing it is noise. Peers are ADDRESSES
+                // (plan/38), so filter by address.
+                const selfAddress = peer.address();
+                const filtered = peers.filter((p) => p !== selfAddress);
+                const text = filtered.length === 0 ? "(no peers)" : filtered.join("\n");
+                return {
+                    content: [{ type: "text", text }],
+                    details: { peers: filtered },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `list_peers failed: ${msg}` }],
+                    details: { peers: [] },
+                };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "agent_request",
+        label: "Agent Request (deprecated)",
+        description: "DEPRECATED — prefer `agent_send` + observing your inbox for the " +
+            "reply (correlated by `re=<your-send-id>`). This tool still works: " +
+            "it sends a message and synchronously blocks until the peer replies " +
+            "or the timeout fires. Default 30s. Will be removed in a future " +
+            "release; migrate to the event-driven pattern in the agent-network skill.",
+        promptSnippet: "agent_request({to, body, timeout_ms?}): DEPRECATED synchronous request/reply (blocks current turn). Prefer agent_send + inbox observation.",
+        parameters: RequestParams,
+        execute: async (_toolCallId, params) => {
+            const peer = getSessionPeer();
+            if (!peer) {
+                return {
+                    content: [{ type: "text", text: NOT_IN_SESSION }],
+                    details: { error: NOT_IN_SESSION },
+                };
+            }
+            const { to, body, timeout_ms } = params;
+            if (to === peer.address() || to === peer.name()) {
+                const msg = `Refused: cannot agent_request to yourself ("${to}"). Just do the work directly.`;
+                return {
+                    content: [{ type: "text", text: msg }],
+                    details: { error: msg },
+                };
+            }
+            const timeout = typeof timeout_ms === "number" && timeout_ms > 0
+                ? timeout_ms
+                : LEGACY_REQUEST_TIMEOUT_MS;
+            try {
+                const reply = await peer.request(to, body, timeout);
+                const text = typeof reply.body === "string"
+                    ? reply.body
+                    : JSON.stringify(reply.body);
+                return {
+                    content: [{ type: "text", text }],
+                    details: reply.body,
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Request failed: ${msg}` }],
+                    details: { error: msg },
+                };
+            }
+        },
+    });
+}
+function _formatAck(to, ack, re) {
+    const reSuffix = re ? ` (re=${re})` : "";
+    const errorSuffix = ack.error ? ` (${ack.error})` : "";
+    switch (ack.status) {
+        case "received":
+            return `Delivered to "${to}"${reSuffix} — peer will process it in an upcoming turn.`;
+        case "busy":
+            // plan/34 removed busy-drop: the current broker never returns `busy`. If
+            // we still see it, an OUT-OF-DATE broker leader dropped the message — so
+            // be honest that it was NOT delivered, and point at the fix.
+            return (`NOT delivered — "${to}"${reSuffix} came back BUSY, which only ` +
+                `happens when an out-of-date broker leader dropped the message. ` +
+                `Restart the agent leading the local broker (oldest Pi/unbien process) ` +
+                `to pick up the new build, then resend.`);
+        case "denied":
+            if (ack.reason === "not_authorized") {
+                return (`Relay did not authorize delivery to "${to}"${reSuffix}${errorSuffix}. ` +
+                    `Do not blindly retry; verify authorization first.`);
+            }
+            if (ack.reason === "bad_envelope") {
+                return (`Relay rejected the envelope for "${to}"${reSuffix}${errorSuffix}. ` +
+                    `Do not blindly retry; correct the envelope first.`);
+            }
+            return `"${to}" denied the message${reSuffix}. Do not retry; report to user.`;
+        case "timeout":
+            if (ack.reason === "offline") {
+                return (`Immediate Relay offline transport error for "${to}"${reSuffix}${errorSuffix}; ` +
+                    `reported as timeout without waiting for the ACK deadline.`);
+            }
+            return `No ACK from "${to}" within ${ACK_TIMEOUT_MS}ms${reSuffix} — transport error. Investigate or retry later.`;
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/session/tools.js.map

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

package/dist/session/wizard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal wizard for `/unbien join` with no argument.
+ *
+ * The Pi SDK `ExtensionUIContext.select` accepts a title and string options
+ * and returns the chosen option. Wizard offers existing sessions + an "explicit
+ * create" sentinel. If user picks the sentinel, prompts for a fresh name via
+ * `select`-with-option-other (Pi's "Other" escape hatch). Returns the picked
+ * session name, or null if user cancelled.
+ */
+export interface WizardUI {
+    select(title: string, options: string[]): Promise<string | undefined>;
+}
+export declare function joinWizard(ui: WizardUI, defaultName: string): Promise<string | null>;

package/dist/session/wizard.js

@@ -0,0 +1,20 @@
+import { listSessions, sessionHasSock } from "./global_config.js";
+const CREATE_SENTINEL = "━━━ Create new session ━━━";
+export async function joinWizard(ui, defaultName) {
+    const sessions = listSessions();
+    const liveSessions = sessions.filter(sessionHasSock);
+    const options = [...liveSessions, CREATE_SENTINEL];
+    const picked = await ui.select(liveSessions.length
+        ? "Choose a session to join, or create a new one"
+        : "No active sessions. Create one?", options);
+    if (!picked)
+        return null;
+    if (picked === CREATE_SENTINEL) {
+        // Caller is expected to follow up with a name prompt via ctx.ui.select
+        // (the Pi SDK input dialog). For non-interactive contexts we return the
+        // default name.
+        return defaultName;
+    }
+    return picked;
+}
+//# sourceMappingURL=wizard.js.map

package/dist/session/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.js","sourceRoot":"","sources":["../../src/session/wizard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAelE,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,EAAY,EACZ,WAAmB;IAEnB,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,CAAC,GAAG,YAAY,EAAE,eAAe,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAC5B,YAAY,CAAC,MAAM;QACjB,CAAC,CAAC,+CAA+C;QACjD,CAAC,CAAC,iCAAiC,EACrC,OAAO,CACR,CAAC;IACF,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QAC/B,uEAAuE;QACvE,wEAAwE;QACxE,gBAAgB;QAChB,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/transport/peer_channel.d.ts

@@ -0,0 +1,52 @@
+import type { ClientMessage, ServerMessage } from "../protocol/types.js";
+import { type EnvelopeMessage } from "../session/rpc_envelope.js";
+import type { RelayClient } from "./relay_client.js";
+/** Sink for ServerMessage outbound to the remote app. */
+export interface PeerChannel {
+    send(msg: ServerMessage): void;
+}
+/**
+ * Plaintext PeerChannel backed by a RelayClient WebSocket.
+ *
+ * Usage (after pair_request handshake completes):
+ *   const channel = new PlainPeerChannel(relay, appPeerId, myRoomId, onMsg)
+ *   channel.send(serverMessage)          // base64-encodes JSON, routes via relay
+ *   // incoming relay messages destined for appPeerId are auto-decoded
+ *   // and delivered via onMessage callback
+ *
+ * `myRoomId` is the *local* Pi's room id — sent on every outbound envelope
+ * so the app can correlate which Pi sent it (multi-pi support, plano 17).
+ */
+export declare class PlainPeerChannel implements PeerChannel {
+    private readonly relay;
+    private readonly remotePeerId;
+    private readonly onMessage;
+    /** Route an inbound mesh-envelope ({rpc|evt}, docs/rpc-envelope.md) to the
+     *  new-protocol dispatcher. Absent → the channel ignores envelope frames. */
+    private readonly onRpc?;
+    private readonly _unsubscribe;
+    constructor(relay: RelayClient, remotePeerId: string, 
+    /**
+     * This Pi's room id. Currently NOT injected in the outer envelope
+     * (defensive — relay/app not yet ready). Kept in the constructor for
+     * forward-compat so callers don't need to change again when we re-enable.
+     */
+    myRoomId: string | undefined, onMessage: (msg: ClientMessage) => void, 
+    /** Called when this specific peer connection is considered lost. */
+    _onDisconnect?: () => void, 
+    /** Route an inbound mesh-envelope ({rpc|evt}, docs/rpc-envelope.md) to the
+     *  new-protocol dispatcher. Absent → the channel ignores envelope frames. */
+    onRpc?: ((env: EnvelopeMessage, sender: PlainPeerChannel) => void) | undefined);
+    send(msg: ServerMessage): void;
+    /**
+     * Send an rpc-envelope message (`{ rpc | evt }`, docs/rpc-envelope.md) to the
+     * app. Same base64-into-`ct` outer wire as `send` — the relay stays opaque —
+     * but the inner payload is an `EnvelopeMessage`, not a `ServerMessage`.
+     * Best-effort, mirroring `send`: a relay mid-reconnect must not throw an
+     * uncaught exception out of the SDK event callback that drives it.
+     */
+    sendEnvelope(env: EnvelopeMessage): void;
+    /** Detaches from relay (does not close the relay itself). */
+    detach(): void;
+    private _onLine;
+}

package/dist/transport/peer_channel.js

@@ -0,0 +1,145 @@
+import { UB_KIND, RPC_KIND, EVT_KIND, isEnvelopeFrame, } from "../session/rpc_envelope.js";
+import { envLog } from "../session/debug_log.js";
+/**
+ * Plaintext PeerChannel backed by a RelayClient WebSocket.
+ *
+ * Usage (after pair_request handshake completes):
+ *   const channel = new PlainPeerChannel(relay, appPeerId, myRoomId, onMsg)
+ *   channel.send(serverMessage)          // base64-encodes JSON, routes via relay
+ *   // incoming relay messages destined for appPeerId are auto-decoded
+ *   // and delivered via onMessage callback
+ *
+ * `myRoomId` is the *local* Pi's room id — sent on every outbound envelope
+ * so the app can correlate which Pi sent it (multi-pi support, plano 17).
+ */
+export class PlainPeerChannel {
+    relay;
+    remotePeerId;
+    onMessage;
+    onRpc;
+    _unsubscribe;
+    constructor(relay, remotePeerId, 
+    /**
+     * This Pi's room id. Currently NOT injected in the outer envelope
+     * (defensive — relay/app not yet ready). Kept in the constructor for
+     * forward-compat so callers don't need to change again when we re-enable.
+     */
+    myRoomId, onMessage, 
+    /** Called when this specific peer connection is considered lost. */
+    _onDisconnect, 
+    /** Route an inbound mesh-envelope ({rpc|evt}, docs/rpc-envelope.md) to the
+     *  new-protocol dispatcher. Absent → the channel ignores envelope frames. */
+    onRpc) {
+        this.relay = relay;
+        this.remotePeerId = remotePeerId;
+        this.onMessage = onMessage;
+        this.onRpc = onRpc;
+        const listener = (line) => this._onLine(line);
+        relay.on("message", listener);
+        this._unsubscribe = () => relay.off("message", listener);
+        void _onDisconnect;
+        void myRoomId; // intentionally unused — see send() comment
+    }
+    // ── PeerChannel interface ──────────────────────────────────────────────────
+    send(msg) {
+        const ct = Buffer.from(JSON.stringify(msg)).toString("base64");
+        // NOTE: `room` removed from the outer envelope until relay (W1.A) + app
+        // (W1.C) accept the field. Multi-Pi multiplexing already works via
+        // `room_id`/`room_meta` in the WS-level `hello` — outer routing stays by
+        // `peer` alone. Re-add the field once downstream is ready.
+        const outer = { peer: this.remotePeerId, ct };
+        // Best-effort delivery. The relay WS can be mid-reconnect (idle/NAT drop, or
+        // a session_new/session-replacement teardown) when we push a server→app frame
+        // — notably the action_ok/action_error ack a handler emits right after
+        // newSession. `relay.send` throws "relay: not connected" in that window; since
+        // this runs inside an async SDK event callback, letting it propagate becomes an
+        // uncaughtException that kills the whole pi process. The relay auto-reconnects
+        // and the app re-syncs via session_sync, so a dropped frame is recoverable — a
+        // crash is not. Mirrors RelayClient.sendControl's no-op-when-closed policy.
+        try {
+            this.relay.send(JSON.stringify(outer));
+        }
+        catch {
+            /* relay down — drop this frame; reconnect + session_sync will recover */
+        }
+    }
+    /**
+     * Send an rpc-envelope message (`{ rpc | evt }`, docs/rpc-envelope.md) to the
+     * app. Same base64-into-`ct` outer wire as `send` — the relay stays opaque —
+     * but the inner payload is an `EnvelopeMessage`, not a `ServerMessage`.
+     * Best-effort, mirroring `send`: a relay mid-reconnect must not throw an
+     * uncaught exception out of the SDK event callback that drives it.
+     */
+    sendEnvelope(env) {
+        // Stamp the wrapper kind + timestamp at the single outbound choke.
+        const wire = {
+            ...env,
+            // Namespace stamp: each plane stamps its REAL type — ub-plane -> "ub",
+            // evt -> "evt", rpc (the spine / default) -> "rpc". Legacy "env" is no
+            // longer stamped (still accepted on read one transition).
+            type: env.type ??
+                (env.ub !== undefined
+                    ? UB_KIND
+                    : env.evt !== undefined
+                        ? EVT_KIND
+                        : RPC_KIND),
+            ts: env.ts ?? Date.now(),
+        };
+        const ct = Buffer.from(JSON.stringify(wire)).toString("base64");
+        const outer = { peer: this.remotePeerId, ct };
+        try {
+            this.relay.send(JSON.stringify(outer));
+        }
+        catch {
+            /* relay down — drop this frame; reconnect + session_sync will recover */
+        }
+    }
+    /** Detaches from relay (does not close the relay itself). */
+    detach() {
+        this._unsubscribe();
+    }
+    // ── Incoming line from relay ────────────────────────────────────────────────
+    _onLine(line) {
+        let outer;
+        try {
+            outer = JSON.parse(line);
+        }
+        catch {
+            return; // malformed line
+        }
+        if (outer.peer !== this.remotePeerId)
+            return;
+        if (!outer.ct)
+            return;
+        let plaintext;
+        try {
+            plaintext = Buffer.from(outer.ct, "base64").toString("utf8");
+        }
+        catch {
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(plaintext);
+        }
+        catch {
+            return;
+        }
+        if (!msg || typeof msg !== "object")
+            return;
+        const obj = msg;
+        envLog(`inbound<-${this.remotePeerId.slice(0, 8)}: type=${String(obj.type)} rpc=${obj.rpc !== undefined} evt=${obj.evt !== undefined}`);
+        // Mesh-envelope inbound (any plane, real-typed or legacy "env" or bare
+        // field-presence) routes to the envelope dispatcher, NOT the stock
+        // ClientMessage switch. Shared predicate with index.ts's reconnect guard so
+        // they can't drift; the dispatcher branches by plane (rpc vs ub) itself.
+        if (isEnvelopeFrame(obj)) {
+            this.onRpc?.(obj, this);
+            return;
+        }
+        if (typeof obj.type !== "string")
+            return;
+        this.onMessage(msg);
+    }
+}
+//# sourceMappingURL=peer_channel.js.map