@yefengr/remote-pi 0.7.0

package/dist/timeline/v2_service.js

@@ -0,0 +1,351 @@
+import { TimelineEventSchema, V2SessionState, MAX_FRAME_BYTES, MAX_FRAGMENT_DECODE_BYTES, } from "../protocol/v2/index.js";
+import { TimelineHistoryPager } from "./history.js";
+export class TimelineV2Service {
+    state;
+    pager;
+    sessionManager;
+    senderRef;
+    runtime;
+    onUserMessage;
+    onCancel;
+    requestChannels = new Map();
+    generationValue;
+    constructor(options) {
+        this.sessionManager = options.sessionManager;
+        this.senderRef = options.senderRef;
+        this.generationValue = options.generation ?? options.sessionManager.getSessionId();
+        this.state = new V2SessionState({ generation: this.generationValue });
+        this.runtime = options.runtime;
+        this.onUserMessage = options.onUserMessage;
+        this.onCancel = options.onCancel;
+        this.pager = new TimelineHistoryPager(this.sessionManager, (manager) => this.runtime.recover(manager), () => this.generationValue);
+    }
+    get generation() {
+        return this.generationValue;
+    }
+    reset(reason) {
+        return this.state.snapshot().channels.map((channel) => ({
+            protocol_version: 2,
+            type: "reset",
+            target_channel_id: channel.channelId,
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            reason,
+        }));
+    }
+    refreshGeneration(next) {
+        if (!next || next === this.generationValue)
+            return false;
+        this.generationValue = next;
+        this.state.setGeneration(next);
+        this.requestChannels.clear();
+        return true;
+    }
+    handle(frame) {
+        switch (frame.type) {
+            case "session_hello":
+                return [this.ready(frame)];
+            case "pair_request":
+                return [this.error(frame.id, "protocol_upgrade_required", "pairing is handled before session_hello")];
+            case "session_sync":
+                return this.handleHistory(frame);
+            case "ping":
+                return this.handlePing(frame);
+            case "cancel":
+                return this.handleCancel(frame);
+            case "user_message":
+                return this.handleUserMessage(frame);
+            case "user_message_observed":
+                return this.handleObserved(frame);
+            case "queued_message_set":
+            case "queued_message_clear":
+            case "approve_tool":
+            case "session_new":
+            case "session_compact":
+            case "model_set":
+            case "thinking_set":
+            case "list_models":
+            case "extension_ui_response":
+                return this.requireReady(frame);
+        }
+    }
+    started(started) {
+        const clientRequestId = started.correlation.clientRequestId;
+        if (!clientRequestId)
+            return [];
+        const request = this.findRecord(clientRequestId);
+        if (!request)
+            return [];
+        this.state.update(request.key, "accepted", { messageId: started.eventId, groupId: started.groupId });
+        const message = {
+            id: started.eventId,
+            group_id: started.groupId,
+            blocks: started.blocks,
+            origin: started.correlation.origin,
+            ...(started.correlation.senderRef ? { sender_ref: started.correlation.senderRef } : {}),
+            delivery: started.correlation.delivery,
+        };
+        return [
+            ...this.direct(request.channelId, {
+                type: "user_message_status",
+                in_reply_to: started.correlation.requestId ?? clientRequestId,
+                session_id: this.sessionManager.getSessionId(),
+                history_generation: this.generation,
+                client_request_id: clientRequestId,
+                status: "accepted",
+                message_id: started.eventId,
+                group_id: started.groupId,
+            }),
+            ...this.direct(request.channelId, {
+                type: "user_message_started",
+                in_reply_to: started.correlation.requestId ?? clientRequestId,
+                session_id: this.sessionManager.getSessionId(),
+                history_generation: this.generation,
+                message,
+            }),
+        ];
+    }
+    commit(clientRequestId, messageId, groupId) {
+        const request = this.findRecord(clientRequestId);
+        if (!request)
+            return [];
+        const record = this.state.update(request.key, "committed", { messageId, groupId });
+        if (!record)
+            return [];
+        return this.direct(request.channelId, {
+            type: "user_message_status",
+            in_reply_to: clientRequestId,
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            client_request_id: clientRequestId,
+            status: "committed",
+            message_id: messageId,
+            ...(groupId ? { group_id: groupId } : {}),
+        });
+    }
+    canDrain(clientRequestId) {
+        return this.findRecord(clientRequestId)?.status === "received";
+    }
+    unknownDelivery(clientRequestId) {
+        const request = this.findRecord(clientRequestId);
+        if (!request)
+            return [];
+        const updated = this.state.rememberUnknownDelivery(request.key);
+        if (!updated)
+            return [];
+        return this.direct(request.channelId, {
+            type: "user_message_status",
+            in_reply_to: clientRequestId,
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            client_request_id: clientRequestId,
+            status: "unknown_delivery",
+        });
+    }
+    partial(partial) {
+        if (partial.session_id !== this.sessionManager.getSessionId() || partial.history_generation !== this.generation)
+            return null;
+        return partial;
+    }
+    publish(event) {
+        return this.publishFrames(event)[0] ?? null;
+    }
+    publishFrames(event) {
+        const parsed = TimelineEventSchema.safeParse(event);
+        if (!parsed.success)
+            return [];
+        const complete = {
+            protocol_version: 2,
+            type: "timeline_event",
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            event: parsed.data,
+        };
+        if (new TextEncoder().encode(JSON.stringify(complete)).byteLength <= MAX_FRAME_BYTES)
+            return [complete];
+        const bytes = new TextEncoder().encode(JSON.stringify(parsed.data));
+        const frames = [];
+        for (let offset = 0, index = 0; offset < bytes.byteLength; offset += MAX_FRAGMENT_DECODE_BYTES, index += 1) {
+            const slice = bytes.slice(offset, offset + MAX_FRAGMENT_DECODE_BYTES);
+            frames.push({
+                protocol_version: 2,
+                type: "timeline_event_fragment",
+                session_id: this.sessionManager.getSessionId(),
+                history_generation: this.generation,
+                event_id: parsed.data.event_id,
+                index,
+                data_base64: Buffer.from(slice).toString("base64"),
+                final: offset + slice.byteLength >= bytes.byteLength,
+            });
+        }
+        return frames;
+    }
+    ready(frame) {
+        this.state.hello(this.senderRef, frame.channel_id);
+        return {
+            protocol_version: 2,
+            type: "session_ready",
+            in_reply_to: frame.id,
+            target_channel_id: frame.channel_id,
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            self_sender_ref: this.senderRef,
+        };
+    }
+    handleHistory(frame) {
+        const error = this.ensureReady(frame);
+        if (error)
+            return [error];
+        return this.pager.sync({
+            requestId: frame.id,
+            targetChannelId: frame.channel_id,
+            before: frame.before,
+            limit: frame.limit,
+        });
+    }
+    handlePing(frame) {
+        const error = this.ensureReady(frame);
+        if (error)
+            return [error];
+        return this.direct(frame.channel_id, { type: "pong", in_reply_to: frame.id });
+    }
+    handleCancel(frame) {
+        const error = this.ensureReady(frame);
+        if (error)
+            return [error];
+        try {
+            if (!(this.onCancel?.(frame.target_id) ?? false)) {
+                return [this.error(frame.id, "internal_error", "no active request to cancel", frame.channel_id)];
+            }
+            return this.direct(frame.channel_id, {
+                type: "cancelled",
+                in_reply_to: frame.id,
+                target_id: frame.target_id,
+            });
+        }
+        catch (cancelError) {
+            const detail = cancelError instanceof Error ? cancelError.message : String(cancelError);
+            return [this.error(frame.id, "internal_error", `cancel failed: ${detail}`, frame.channel_id)];
+        }
+    }
+    handleObserved(frame) {
+        const error = this.ensureReady(frame);
+        if (error)
+            return [error];
+        const record = this.state.getRecord(this.recordKey(frame.client_request_id));
+        if (!record || record.senderRef !== this.senderRef) {
+            return [this.error(frame.id, "invalid_message", "unknown observed request", frame.channel_id)];
+        }
+        this.state.forget(record.key);
+        this.requestChannels.delete(frame.client_request_id);
+        return [];
+    }
+    handleUserMessage(frame) {
+        const error = this.ensureReady(frame);
+        if (error)
+            return [error];
+        const result = this.state.begin({
+            senderRef: this.senderRef,
+            clientRequestId: frame.client_request_id,
+            payload: this.idempotencyPayload(frame),
+        });
+        if (result.kind === "conflict") {
+            return [this.error(frame.id, "invalid_message", "client_request_id payload conflict", frame.channel_id)];
+        }
+        if (result.kind === "replay")
+            return this.replay(frame, result.record);
+        this.requestChannels.set(frame.client_request_id, frame.channel_id);
+        const correlation = frame.streaming_behavior === "steer"
+            ? { origin: "unknown", delivery: "unknown", channelId: frame.channel_id, requestId: frame.id }
+            : {
+                origin: "pwa",
+                delivery: "normal",
+                senderRef: this.senderRef,
+                channelId: frame.channel_id,
+                requestId: frame.id,
+                clientRequestId: frame.client_request_id,
+            };
+        try {
+            const acceptedForDelivery = this.onUserMessage(frame, correlation);
+            if (!acceptedForDelivery)
+                return this.unknownDelivery(frame.client_request_id);
+            if (frame.streaming_behavior === "steer")
+                return this.unknownDelivery(frame.client_request_id);
+            return [this.status(frame, "received")];
+        }
+        catch {
+            return this.unknownDelivery(frame.client_request_id);
+        }
+    }
+    replay(frame, record) {
+        if (record.status === "unknown_delivery")
+            return this.unknownDelivery(frame.client_request_id);
+        if (record.status === "received")
+            return [this.status(frame, "received")];
+        return [this.status(frame, record.status === "committed" ? "committed" : "accepted", record.messageId, record.groupId)];
+    }
+    status(frame, status, messageId, groupId) {
+        return this.direct(frame.channel_id, {
+            type: "user_message_status",
+            in_reply_to: frame.id,
+            session_id: this.sessionManager.getSessionId(),
+            history_generation: this.generation,
+            client_request_id: frame.client_request_id,
+            status,
+            ...(messageId ? { message_id: messageId } : {}),
+            ...(groupId ? { group_id: groupId } : {}),
+        })[0];
+    }
+    requireReady(frame) {
+        const error = this.ensureReady(frame);
+        return [error ?? this.error("id" in frame ? frame.id : "v2", "unsupported_type", "frame is not implemented", "channel_id" in frame ? frame.channel_id : undefined)];
+    }
+    ensureReady(frame) {
+        if (!("channel_id" in frame) || !this.state.get(this.senderRef, frame.channel_id)) {
+            return this.error("id" in frame ? frame.id : "v2", "invalid_channel", "session_hello required", "channel_id" in frame ? frame.channel_id : undefined);
+        }
+        if ("history_generation" in frame && frame.history_generation !== this.generation) {
+            return {
+                protocol_version: 2,
+                type: "reset",
+                target_channel_id: frame.channel_id,
+                session_id: this.sessionManager.getSessionId(),
+                history_generation: this.generation,
+                reason: "generation_changed",
+            };
+        }
+        this.state.touch(this.senderRef, frame.channel_id);
+        return null;
+    }
+    direct(channelId, frame) {
+        return [{ ...frame, protocol_version: 2, target_channel_id: channelId }];
+    }
+    error(inReplyTo, code, message, channelId) {
+        return {
+            protocol_version: 2,
+            type: "protocol_error",
+            ...(channelId ? { target_channel_id: channelId } : {}),
+            in_reply_to: inReplyTo,
+            code,
+            message,
+        };
+    }
+    idempotencyPayload(frame) {
+        return {
+            text: frame.text,
+            images: frame.images ?? [],
+            streaming_behavior: frame.streaming_behavior ?? null,
+        };
+    }
+    recordKey(clientRequestId) {
+        return `${this.generation}\u0000${this.senderRef}\u0000${clientRequestId}`;
+    }
+    findRecord(clientRequestId) {
+        const record = this.state.getRecord(this.recordKey(clientRequestId));
+        const channelId = this.requestChannels.get(clientRequestId);
+        if (!record || !channelId)
+            return undefined;
+        return { ...record, channelId };
+    }
+}
+//# sourceMappingURL=v2_service.js.map

package/dist/timeline/v2_service.js.map

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

package/dist/transport/peer_channel.d.ts

@@ -0,0 +1,57 @@
+import type { ClientMessage, ServerMessage } from "../protocol/types.js";
+import { type ClientFrame, type ServerFrame } from "../protocol/v2/index.js";
+import type { RelayClient } from "./relay_client.js";
+/** Sink for ServerMessage outbound to the remote app. */
+export interface PeerChannel {
+    send(msg: ServerMessage): void;
+}
+export interface V2Channel {
+    getPeerId(): string;
+    sendV2(msg: ServerFrame): void;
+    detach(): 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 V2PeerChannel implements V2Channel {
+    private readonly relay;
+    private readonly remotePeerId;
+    private readonly onMessage;
+    private readonly unsubscribe;
+    constructor(relay: RelayClient, remotePeerId: string, onMessage: (msg: ClientFrame) => void);
+    getPeerId(): string;
+    sendV2(msg: ServerFrame): void;
+    detach(): void;
+    private onLine;
+}
+/** @deprecated Protocol v1 test helper. Production uses V2PeerChannel. */
+export declare class PlainPeerChannel implements PeerChannel {
+    private readonly relay;
+    private readonly remotePeerId;
+    private readonly onMessage;
+    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);
+    /** Authenticated Owner peer id used as a server-derived sender reference. */
+    getPeerId(): string;
+    send(msg: ServerMessage): void;
+    /** Detaches from relay (does not close the relay itself). */
+    detach(): void;
+    private _onLine;
+}

package/dist/transport/peer_channel.js

@@ -0,0 +1,170 @@
+import { decodeClientFrameV2, encodeServerFrameV2, } from "../protocol/v2/index.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 V2PeerChannel {
+    relay;
+    remotePeerId;
+    onMessage;
+    unsubscribe;
+    constructor(relay, remotePeerId, onMessage) {
+        this.relay = relay;
+        this.remotePeerId = remotePeerId;
+        this.onMessage = onMessage;
+        const listener = (line) => this.onLine(line);
+        relay.on("message", listener);
+        this.unsubscribe = () => relay.off("message", listener);
+    }
+    getPeerId() {
+        return this.remotePeerId;
+    }
+    sendV2(msg) {
+        const ct = Buffer.from(encodeServerFrameV2(msg)).toString("base64");
+        try {
+            this.relay.send(JSON.stringify({ peer: this.remotePeerId, ct }));
+        }
+        catch {
+            // Reconnect plus authoritative history recovers dropped formal events.
+        }
+    }
+    detach() {
+        this.unsubscribe();
+    }
+    onLine(line) {
+        let outer;
+        try {
+            outer = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (outer.peer !== this.remotePeerId || !outer.ct)
+            return;
+        try {
+            const plaintext = Buffer.from(outer.ct, "base64").toString("utf8");
+            this.onMessage(decodeClientFrameV2(plaintext));
+        }
+        catch {
+            // Strict v2 boundary. A parseable legacy/invalid request receives an upgrade
+            // error; malformed bytes without an id cannot be safely targeted.
+            try {
+                const raw = JSON.parse(Buffer.from(outer.ct, "base64").toString("utf8"));
+                const id = typeof raw.id === "string" ? raw.id : undefined;
+                const channelId = typeof raw.channel_id === "string" ? raw.channel_id : undefined;
+                if (id) {
+                    this.sendV2({
+                        protocol_version: 2,
+                        type: "protocol_error",
+                        ...(channelId ? { target_channel_id: channelId } : {}),
+                        in_reply_to: id,
+                        code: "protocol_upgrade_required",
+                        message: "Protocol v2 is required",
+                    });
+                }
+            }
+            catch {
+                // Ignore malformed outer payloads.
+            }
+        }
+    }
+}
+/** @deprecated Protocol v1 test helper. Production uses V2PeerChannel. */
+export class PlainPeerChannel {
+    relay;
+    remotePeerId;
+    onMessage;
+    _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) {
+        this.relay = relay;
+        this.remotePeerId = remotePeerId;
+        this.onMessage = onMessage;
+        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 ──────────────────────────────────────────────────
+    /** Authenticated Owner peer id used as a server-derived sender reference. */
+    getPeerId() {
+        return this.remotePeerId;
+    }
+    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 */
+        }
+    }
+    /** 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" ||
+            typeof msg.type !== "string") {
+            return;
+        }
+        this.onMessage(msg);
+    }
+}
+//# sourceMappingURL=peer_channel.js.map

package/dist/transport/peer_channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer_channel.js","sourceRoot":"","sources":["../../src/transport/peer_channel.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GAGpB,MAAM,yBAAyB,CAAC;AA+BjC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IAIL;IACA;IACA;IALF,WAAW,CAAa;IAEzC,YACmB,KAAkB,EAClB,YAAoB,EACpB,SAAqC;QAFrC,UAAK,GAAL,KAAK,CAAa;QAClB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,cAAS,GAAT,SAAS,CAA4B;QAEtD,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,GAAgB;QACrB,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,EAA0B,CAAC,CAAC,CAAC;QAC3F,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;QACzE,CAAC;IACH,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;IAEO,MAAM,CAAC,IAAY;QACzB,IAAI,KAAoB,CAAC;QACzB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,EAAE;YAAE,OAAO;QAC1D,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnE,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,6EAA6E;YAC7E,kEAAkE;YAClE,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAA4B,CAAC;gBACpG,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC3D,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;gBAClF,IAAI,EAAE,EAAE,CAAC;oBACP,IAAI,CAAC,MAAM,CAAC;wBACV,gBAAgB,EAAE,CAAC;wBACnB,IAAI,EAAE,gBAAgB;wBACtB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACtD,WAAW,EAAE,EAAE;wBACf,IAAI,EAAE,2BAA2B;wBACjC,OAAO,EAAE,yBAAyB;qBACnC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,gBAAgB;IAIR;IACA;IAOA;IAXF,YAAY,CAAa;IAE1C,YACmB,KAAkB,EAClB,YAAoB;IACrC;;;;OAIG;IACH,QAA4B,EACX,SAAuC;IACxD,oEAAoE;IACpE,aAA0B;QAVT,UAAK,GAAL,KAAK,CAAa;QAClB,iBAAY,GAAZ,YAAY,CAAQ;QAOpB,cAAS,GAAT,SAAS,CAA8B;QAIxD,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACzD,KAAK,aAAa,CAAC;QACnB,KAAK,QAAQ,CAAC,CAAE,4CAA4C;IAC9D,CAAC;IAED,8EAA8E;IAE9E,6EAA6E;IAC7E,SAAS;QACP,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,IAAI,CAAC,GAAkB;QACrB,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC/D,wEAAwE;QACxE,mEAAmE;QACnE,yEAAyE;QACzE,2DAA2D;QAC3D,MAAM,KAAK,GAAkB,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,CAAC;QAC7D,6EAA6E;QAC7E,8EAA8E;QAC9E,uEAAuE;QACvE,+EAA+E;QAC/E,gFAAgF;QAChF,+EAA+E;QAC/E,+EAA+E;QAC/E,4EAA4E;QAC5E,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;QAC3E,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,MAAM;QACJ,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED,+EAA+E;IAEvE,OAAO,CAAC,IAAY;QAC1B,IAAI,KAAoB,CAAC;QACzB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkB,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,iBAAiB;QAC3B,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QAC7C,IAAI,CAAC,KAAK,CAAC,EAAE;YAAE,OAAO;QAEtB,IAAI,SAAiB,CAAC;QACtB,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QAED,IAAI,GAAY,CAAC;QACjB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QAED,IACE,CAAC,GAAG;YACJ,OAAO,GAAG,KAAK,QAAQ;YACvB,OAAQ,GAA+B,CAAC,IAAI,KAAK,QAAQ,EACzD,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAoB,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/transport/pi_forward_client.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from "node:events";
+import type { RelayClient } from "./relay_client.js";
+import type { Envelope } from "../session/envelope.js";
+/** Outbound API + inbound listener for Pi↔Pi envelope forwarding via relay. */
+export interface PiForwardClientEvents {
+    /**
+     * Emitted whenever the relay delivers a `pi_envelope_in` frame addressed
+     * to this Pi. `fromPc` is the verified Pi-pubkey of the sender (relay
+     * authoritative — defense against spoofed `envelope.from`).
+     */
+    envelope: [env: Envelope, fromPc: string];
+}
+export declare class PiForwardClient extends EventEmitter {
+    private readonly relay;
+    private readonly onRelayMessage;
+    private detached;
+    constructor(relay: RelayClient);
+    /**
+     * Pack `env` in a `pi_envelope` frame addressed to `toPc` and send via
+     * the relay WS. Best-effort: if the relay is not connected, the call is
+     * silently dropped. The caller (broker_remote) handles the timeout via
+     * its outstanding-ACK map — a missing ACK from the destination wrapper
+     * surfaces as `status: "timeout"` upstream regardless.
+     */
+    sendEnvelopeToPi(toPc: string, env: Envelope): void;
+    /** Stop listening to the relay. Call from `_goIdle` / shutdown. */
+    detach(): void;
+    private _handleLine;
+}