remote-pi-app 0.7.1

package/dist/extension_ui_bridge.js

@@ -0,0 +1,341 @@
+// Plan/57 — Bridge @eko24ive/pi-ask clarification flows to the paired app over
+// the extension_ui_request/response contract.
+//
+// pi-ask (when installed) runs ask_user in the Pi TUI on the desktop AND emits
+// a same-process event contract on `pi.events` (docs/remote-events.md):
+//
+//   @eko24ive/pi-ask:started      { flowId, toolCallId?, source, title?, questions[] }
+//   @eko24ive/pi-ask:submit       { requestId, flowId, response }   // we emit this
+//   @eko24ive/pi-ask:submit-result{ requestId, flowId, ok, error? } // pi-ask emits
+//   @eko24ive/pi-ask:completed    { flowId, result }
+//
+// This module subscribes to those events and translates them into the SDK's
+// extension_ui_request/response wire shapes (mirrored from
+// `pi --mode rpc`'s RpcExtensionUIRequest/Response) so the mobile app renders
+// ask_user natively. pi-ask's richer schema rides in an optional `ask` envelope.
+//
+// Inert when pi-ask is absent: no events fire, nothing breaks. ask_user without
+// pi-ask doesn't exist, so this bridge is strictly opt-in.
+const PI_ASK_STARTED = "@eko24ive/pi-ask:started";
+const PI_ASK_COMPLETED = "@eko24ive/pi-ask:completed";
+const PI_ASK_SUBMIT = "@eko24ive/pi-ask:submit";
+const PI_ASK_SUBMIT_RESULT = "@eko24ive/pi-ask:submit-result";
+/** Drop a flow from `activeFlows` if pi-ask never resolves it (e.g. a flow
+ *  disposed on session_shutdown — pi-ask does not emit `completed` for those).
+ *  Bounds memory; generous vs. a human answer time. */
+const FLOW_TTL_MS = 10 * 60 * 1000;
+/**
+ * Wire pi-ask's event contract to the relay's extension_ui_request/response
+ * frames. Returns `null` only if the SDK exposes no usable `events` bus (defensive
+ * — modern Pi always has one); callers stay null-safe.
+ */
+export function createExtensionUiBridge(pi, broadcast) {
+    const eventsRaw = pi.events;
+    if (!eventsRaw ||
+        typeof eventsRaw.on !== "function" ||
+        typeof eventsRaw.emit !== "function") {
+        return null;
+    }
+    // Assign to a freshly-typed const so the narrowed (non-undefined) type is
+    // preserved inside nested closures below (TS re-widens the raw capture).
+    const events = eventsRaw;
+    // flowId → flow. Kept so a label-only (degraded) response can map back to the
+    // option value, and so completed/submit-result can be tolerated if they arrive
+    // after the app already answered.
+    const activeFlows = new Map();
+    // Per-flow TTL timers (FLOW_TTL_MS). pi-ask disposes flows on session_shutdown
+    // WITHOUT emitting `completed`, so without this the `activeFlows` map would
+    // leak one entry per abandoned flow. Bounded, defensive.
+    const flowTimers = new Map();
+    function clearFlowTtl(flowId) {
+        const t = flowTimers.get(flowId);
+        if (t !== undefined) {
+            clearTimeout(t);
+            flowTimers.delete(flowId);
+        }
+    }
+    function armFlowTtl(flowId) {
+        clearFlowTtl(flowId);
+        flowTimers.set(flowId, setTimeout(() => {
+            if (!activeFlows.delete(flowId))
+                return; // already resolved
+            flowTimers.delete(flowId);
+            // Tell the app the bridge forgot this flow instead of stranding its
+            // modal silently: a matching WARNING notify keeps the modal open with
+            // a retry hint. Rich clients can still retry (the response carries
+            // flow_id and pi-ask's flow may still be pending on the desktop);
+            // degraded clients at least get closure.
+            broadcast({
+                type: "extension_ui_request",
+                id: flowId,
+                method: "notify",
+                message: "Clarification expired on the bridge — retry or answer on desktop.",
+                notify_type: "warning",
+            });
+        }, FLOW_TTL_MS));
+    }
+    const unsubStarted = events.on(PI_ASK_STARTED, (raw) => {
+        const event = parseStartedEvent(raw);
+        if (!event)
+            return;
+        const flow = {
+            flowId: event.flowId,
+            toolCallId: event.toolCallId ?? null,
+            source: event.source ?? "tool",
+            title: event.title ?? null,
+            questions: event.questions,
+        };
+        activeFlows.set(flow.flowId, flow);
+        armFlowTtl(flow.flowId);
+        broadcast(requestForFlow(flow));
+    });
+    const unsubCompleted = events.on(PI_ASK_COMPLETED, (raw) => {
+        const e = raw;
+        if (!e || e.version !== 1 || typeof e.flowId !== "string")
+            return;
+        const flowId = e.flowId;
+        clearFlowTtl(flowId);
+        activeFlows.delete(flowId);
+        // Same id as the originating request (the flowId). The app treats a `notify`
+        // whose id matches an open interactive request as "that flow resolved —
+        // dismiss it". Covers the non-submitting owner in a multi-owner setup.
+        broadcast({
+            type: "extension_ui_request",
+            id: flowId,
+            method: "notify",
+            message: "Clarification resolved.",
+        });
+    });
+    // submit-result is per-request feedback. On error (invalid answer / flow
+    // gone) surface a warning so the submitting owner can retry. The notify reuses
+    // the flowId as its id (same as the originating request) so the app correlates
+    // it to its open modal; notify_type "warning" distinguishes it from the
+    // `completed` dismiss (same id, absent/other notify_type). Success is covered
+    // by `completed`, so ok is a no-op here.
+    const unsubResult = events.on(PI_ASK_SUBMIT_RESULT, (raw) => {
+        const e = raw;
+        if (!e || e.version !== 1 || e.ok === true)
+            return;
+        const message = typeof e.message === "string"
+            ? e.message
+            : typeof e.error === "string"
+                ? e.error
+                : "Clarification answer was not accepted.";
+        const flowId = typeof e.flowId === "string"
+            ? e.flowId
+            : activeFlows.size === 1
+                // Defensive: pi-ask always carries flowId. If it's ever absent, an
+                // unambiguous single active flow is a safe attribution; with zero or
+                // several, the warning is uncorrelatable and the app ignores
+                // unmatched notifies — drop it instead of broadcasting a random id
+                // no client can act on.
+                ? activeFlows.keys().next().value
+                : undefined;
+        if (!flowId)
+            return;
+        broadcast({
+            type: "extension_ui_request",
+            id: flowId,
+            method: "notify",
+            message,
+            notify_type: "warning",
+        });
+    });
+    function respond(msg) {
+        const ask = msg.ask;
+        // Explicit cancel — with or without the ask envelope. A strict client
+        // (no envelope) only carries the request id, which IS the flowId by this
+        // bridge's contract; confirm via activeFlows before trusting it.
+        if (("cancelled" in msg && msg.cancelled === true) ||
+            (ask !== undefined && ask.kind === "cancel")) {
+            const flowId = ask?.flow_id ?? (activeFlows.has(msg.id) ? msg.id : null);
+            if (!flowId)
+                return;
+            emitSubmit(msg.id, flowId, { kind: "cancel" });
+            return;
+        }
+        // Rich path: the ask envelope carries the structured answer (option values).
+        if (ask !== undefined && ask.kind === "answer") {
+            emitSubmit(msg.id, ask.flow_id, {
+                kind: "answer",
+                mode: ask.mode,
+                answers: ask.answers,
+            });
+            return;
+        }
+        // Degraded path: a response without the ask envelope (e.g. a generic client
+        // that rendered only the SDK `select`). Map the chosen label back to the
+        // option value for the flow's first question.
+        const flow = activeFlows.get(msg.id);
+        if (!flow || flow.questions.length === 0)
+            return;
+        const question = flow.questions[0];
+        if (!question)
+            return;
+        const label = "value" in msg ? String(msg.value) : "";
+        // NB: pi-ask's schema doesn't forbid duplicate labels — on a collision the
+        // first match wins. Inherent ambiguity of a label-only (degraded) client.
+        const match = question.options.find((o) => o.label === label);
+        const answers = {
+            [question.id]: match
+                ? { values: [match.value] }
+                : label
+                    ? { customText: label }
+                    : {},
+        };
+        emitSubmit(msg.id, flow.flowId, {
+            kind: "answer",
+            mode: "submit",
+            answers,
+        });
+    }
+    function emitSubmit(requestId, flowId, response) {
+        try {
+            events.emit(PI_ASK_SUBMIT, {
+                version: 1,
+                requestId,
+                flowId,
+                response,
+            });
+        }
+        catch {
+            // pi-ask not installed or bus gone — nothing useful to do; the flow will
+            // either resolve locally (desktop TUI) or time out on its own.
+        }
+    }
+    return {
+        respond,
+        // Insertion order = the order the flows opened, so a client replaying more
+        // than one renders them oldest-first. pi-ask resolves one flow at a time in
+        // practice, so this is a defensive detail rather than a live case.
+        pendingRequests: () => [...activeFlows.values()].map(requestForFlow),
+        dispose() {
+            unsubStarted();
+            unsubCompleted();
+            unsubResult();
+            for (const t of flowTimers.values())
+                clearTimeout(t);
+            flowTimers.clear();
+            activeFlows.clear();
+        },
+    };
+}
+/** Build the single extension_ui_request that represents a whole ask flow. */
+function requestForFlow(flow) {
+    const first = flow.questions[0];
+    const title = flow.title ?? first?.prompt ?? "Clarification";
+    const options = first ? first.options.map((o) => o.label) : [];
+    const ask = {
+        flow_id: flow.flowId,
+        tool_call_id: flow.toolCallId,
+        source: flow.source,
+        title: flow.title,
+        questions: flow.questions,
+    };
+    // A pure-text question (pi-ask allows an empty options array) degrades to
+    // `input` — a strict client renders a text field instead of an empty select.
+    if (options.length === 0) {
+        return {
+            type: "extension_ui_request",
+            // One request per flow → reuse the flowId as the correlation id. The
+            // app's response carries the same id (and ask.flow_id) for routing.
+            id: flow.flowId,
+            method: "input",
+            title,
+            placeholder: first?.prompt,
+            ask,
+        };
+    }
+    return {
+        type: "extension_ui_request",
+        // One request per flow → reuse the flowId as the correlation id. The app's
+        // response carries the same id (and ask.flow_id) so the bridge can route.
+        id: flow.flowId,
+        method: "select",
+        title,
+        options,
+        ask,
+    };
+}
+function parseStartedEvent(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (raw.version !== 1)
+        return null;
+    if (typeof raw.flowId !== "string")
+        return null;
+    if (!Array.isArray(raw.questions))
+        return null;
+    const questions = [];
+    for (const q of raw.questions) {
+        const parsed = parseQuestion(q);
+        if (!parsed)
+            return null;
+        questions.push(parsed);
+    }
+    if (questions.length === 0)
+        return null;
+    return {
+        flowId: raw.flowId,
+        toolCallId: asString(raw.toolCallId),
+        source: asString(raw.source),
+        title: asString(raw.title),
+        questions,
+    };
+}
+function parseQuestion(value) {
+    if (!isRecord(value))
+        return null;
+    if (typeof value.id !== "string" || typeof value.prompt !== "string")
+        return null;
+    if (!Array.isArray(value.options))
+        return null;
+    const options = [];
+    for (const o of value.options) {
+        const opt = parseOption(o);
+        if (!opt)
+            return null;
+        options.push(opt);
+    }
+    // Empty options is valid: pi-ask's schema has no minItems — a question can be
+    // pure text (custom answer only). The request degrades to `input` upstream.
+    return {
+        id: value.id,
+        label: typeof value.label === "string" ? value.label : value.prompt,
+        prompt: value.prompt,
+        type: asQuestionType(value.type) ?? "single",
+        required: value.required === true,
+        presentedType: asQuestionType(value.presentedType),
+        requestedType: asQuestionType(value.requestedType),
+        options,
+    };
+}
+function parseOption(value) {
+    if (!isRecord(value))
+        return null;
+    // pi-ask's schema marks value/label Optional on input, but a started event
+    // always carries resolved values. Be lenient: fall back label→value.
+    const val = typeof value.value === "string" ? value.value : asString(value.label);
+    const label = typeof value.label === "string" ? value.label : val;
+    if (!val || !label)
+        return null;
+    return {
+        value: val,
+        label,
+        description: asString(value.description),
+        preview: asString(value.preview),
+        freeform: value.freeform === true ? true : undefined,
+    };
+}
+function asQuestionType(value) {
+    return value === "single" || value === "multi" || value === "preview"
+        ? value
+        : undefined;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=extension_ui_bridge.js.map

package/dist/extension_ui_bridge.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * pi-extension — remote-pi slash commands + AgentBridge wiring
+ *
+ * Exported as ExtensionFactory (default export) to be loaded by Pi SDK:
+ *   pi -e $(pwd)/dist/index.js
+ *
+ * State machine:  idle → started → paired
+ *   /remote-pi start   connects to relay (idle → started)
+ *   /remote-pi pair    shows QR for new peers (started, async → paired via auto-listener)
+ *   /remote-pi stop    closes everything (any → idle)
+ *
+ * Pairing (post plano 06 — sem Noise XX):
+ *   App envia inner `pair_request` (id, token, device_name) sobre canal opaco.
+ *   Pi valida o token via qrSession.consumeToken, salva peer em peers.json
+ *   {name, remote_epk, paired_at} e responde com `pair_ok` (ou `pair_error`).
+ *   `ct` é base64(JSON.stringify(inner)) — sem cifra, sem MAC.
+ *
+ * Reconexão de peer conhecido:
+ *   Se uma mensagem chega em estado `started` vinda de um epk presente em
+ *   peers.json, o auto-listener promove direto pra `paired` sem novo
+ *   pair_request, criando o PlainPeerChannel e roteando a mensagem.
+ *
+ * Architecture note — why we don't use AgentBridge directly here:
+ *   AgentBridge.beforeToolCallHook is designed to be passed to createAgentSession().
+ *   Inside an extension Pi already owns the AgentSession, so we can't re-bind
+ *   beforeToolCall after the fact. The equivalent is pi.on("tool_call", …) which
+ *   fires BEFORE execution and supports { block: true }.
+ *   AgentBridge (src/session/agent_bridge.ts) remains the tested, mockable unit
+ *   for integration tests.
+ */
+import type { ExtensionContext, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ClientMessage, SessionHistoryEvent } from "./protocol/types.js";
+import { PlainPeerChannel } from "./transport/peer_channel.js";
+export type RemoteState = "idle" | "started";
+/** Relay connectivity as seen by an RPC client (Cockpit). Derived from
+ *  `_state` + `_relay`: "disconnected" = relay off (idle); "connected" = live
+ *  WS; "reconnecting" = was on, WS dropped, retrying. Surfaced via the
+ *  `remote-pi:relay-state` custom message (see `_emitRelayState`). */
+export type RelayConnectivity = "connected" | "reconnecting" | "disconnected";
+/** Sentinel prefix for a transparent control message an RPC client sends on the
+ *  `prompt` channel (stdin). The `input` hook intercepts it, runs the action,
+ *  and swallows it (`action:"handled"`) so it never becomes an LLM turn or a
+ *  transcript entry. Starts with NUL so it can't collide with real user input
+ *  and doesn't begin with "/" (which would route to the command parser). */
+export declare const CTRL_PREFIX = "\0remote-pi-ctrl:";
+type BufferMsg = {
+    role: "user" | "assistant" | "toolResult" | string;
+    content?: unknown;
+    timestamp?: number;
+    toolCallId?: string;
+    toolName?: string;
+    isError?: boolean;
+    usage?: {
+        input?: number;
+        output?: number;
+    };
+    /** Plan/32: pre-compaction token count, set on the synthetic
+     *  `role:"compaction"` marker pushed in `session_compact`. */
+    tokensBefore?: number;
+};
+type MeshEnvelope = {
+    id: string;
+    from: string;
+    re: string | null;
+    body: unknown;
+};
+/** Test-only override of the message buffer. */
+/**
+ * Test-only: emulate what `/remote-pi` does on the returning-user path
+ * (join the local mesh, then start the relay) without touching the FS for
+ * a `localConfigExists()` lookup. Lets tests bring the relay up without
+ * mocking the wizard or the local config storage.
+ *
+ * Typed loosely to accept any ctx shape with `ui.notify` + `cwd` — the
+ * unit tests use minimal mocks that don't satisfy the full
+ * `ExtensionContext` interface.
+ */
+export declare function _connectForTest(ctx: unknown): Promise<void>;
+/** Test-only: tear everything down (mirrors `/remote-pi stop`). */
+export declare function _stopForTest(ctx: unknown): Promise<void>;
+/** Test-only: read/reset the `_disposed` flag. Production clears it only when
+ *  a host reuses this module for a replacement session; tests share one module
+ *  across cases, so they also reset it to avoid cross-test pollution. */
+export declare function _getDisposedForTest(): boolean;
+export declare function _setDisposedForTest(v: boolean): void;
+/** Test-only: reset the once-per-session auto-init gate so session_start re-runs it. */
+export declare function _resetAutoInitedForTest(): void;
+/** Test-only: set the auto-init gate for lifecycle replacement tests. */
+export declare function _setAutoInitedForTest(value: boolean): void;
+/** Test-only: true when this instance holds a live local-mesh node. */
+export declare function _hasMeshNodeForTest(): boolean;
+/** Test-only: drive the current real SelfRevoke producer through one sweep. */
+export declare function _checkSelfRevokeForTest(): Promise<void>;
+/** Test-only: the effective (possibly `#N`-suffixed) name the cwd-lock reserved. */
+export declare function _getLockedNameForTest(): string | null;
+/** Test-only: release + clear the cwd lock (the lock normally survives stop). */
+export declare function _resetCwdLockForTest(): void;
+/**
+ * Test-only: relay-only startup, no UDS mesh join. Replaces the old
+ * `remote-pi relay start` handler that some tests captured to bring up
+ * the relay in isolation (e.g. ping/pong tests that don't care about the
+ * agent-network broker).
+ */
+export declare function _startRelayForTest(ctx: unknown): Promise<void>;
+/** Test-only: public marker for canceled-keypair cache regression checks. */
+export declare function _getCachedPublicKeyForTest(): string | null;
+export declare function _setMessageBufferForTest(msgs: unknown[]): void;
+/** Test-only accessor: returns a defensive copy of the buffer. */
+export declare function _getMessageBufferForTest(): unknown[];
+/** Test-only override of session started timestamp. */
+export declare function _setSessionStartedAtForTest(ts: number | null): void;
+/** Test-only: reset the cached model name (between tests). */
+export declare function _setCurrentModelForTest(name: string | undefined): void;
+/** Test-only: read the active turn id used for plain `cancel` routing. */
+export declare function _getCurrentTurnIdForTest(): string | null;
+export declare function _getPendingSteerIdsForTest(text: string): string[];
+/** Test-only: override the bound AgentSession so a spy can capture the
+ *  content handed to `sendUserMessage` (plan/30 multimodal ingest). */
+export declare function _setPiForTest(pi: unknown): void;
+/** Test-only: exposes pending reconnect timer state. */
+export declare function _hasPendingReconnect(): boolean;
+/**
+ * Public state-snapshot helper. Returns the derived UX state, not the raw
+ * `_state` enum: the W2D refactor collapsed the internal machine to
+ * `idle | started` and made `paired` a derived metric
+ * (`_activePeers.size > 0`). Tests and the footer keep the three-state
+ * mental model via this getter.
+ */
+export declare function _getState(): "idle" | "started" | "paired";
+/** Test-only: number of owners currently attached via PlainPeerChannel. */
+export declare function _getActivePeerCountForTest(): number;
+/** Test-only: true if a specific peer (base64 std) has an attached channel. */
+export declare function _hasActivePeerForTest(appPeerIdStd: string): boolean;
+/**
+ * Handle a transparent control command from an RPC client (Cockpit), received
+ * as a `CTRL_PREFIX`-tagged input the `input` hook swallowed. Toggles the relay
+ * WITHOUT leaving the local mesh (relay-only: `_cmdStart` up / `_goIdle` down),
+ * then emits the fresh state. `relay:status` just re-emits (no change) so the
+ * client can sync its button after (re)attaching to the RPC stream.
+ */
+export declare function _handleControl(cmd: string): Promise<void>;
+/**
+ * Per-owner disconnect callback. Fires when one specific owner's channel
+ * detaches (e.g. relay told us the peer is gone). Other owners' channels
+ * keep running — relay stays "started".
+ *
+ * Exported so tests can trigger the disconnect path for a specific peer.
+ *
+ * Backward-compat: a no-arg call (legacy tests / pre-W2D callers) falls
+ * back to detaching the most recently attached peer, mirroring the old
+ * singleton semantics.
+ */
+export declare function _onPeerDisconnect(appPeerId?: string): void;
+declare const extension: ExtensionFactory;
+export default extension;
+/** Test-only entry point for verifying mesh-to-agent delivery semantics. */
+export declare function _deliverMeshMessageToAgentForTest(env: MeshEnvelope): void;
+export declare function _routeClientMessageFrom(sender: PlainPeerChannel, msg: ClientMessage, ctx: Pick<ExtensionContext, "abort">): void;
+/**
+ * Backward-compatible shim for legacy callers + tests that didn't track
+ * a specific sender channel. Routes to the most recently attached owner,
+ * mirroring the pre-W2D singleton behavior.
+ */
+export declare function routeClientMessage(msg: ClientMessage, ctx: Pick<ExtensionContext, "abort">): void;
+/**
+ * Maps SDK AgentMessage[] (UserMessage / AssistantMessage / ToolResultMessage)
+ * into the flat SessionHistoryEvent[] shape consumed by the app.
+ *
+ * Caveats (see report): in_reply_to of agent_message is the *last* user_input
+ * id seen in a linear scan — fine for typical conversational flow but not
+ * a perfect reconstruction of multi-turn ordering when tools interleave.
+ * Stable id for user_input is `sync_<timestamp>`.
+ */
+export declare function _mapAgentMessagesToEvents(messages: BufferMsg[]): SessionHistoryEvent[];
+/**
+ * `remote-pi restart-supervisor` — restarts the `pi-supervisord` PROCESS
+ * (not the daemons). The supervisor is a long-running Node process with no
+ * hot-reload, so after a `dist` rebuild the old code keeps running until the
+ * process is restarted. The Cockpit "Restart supervisor" button shells out to
+ * this; the OS-specific restart lives here so the app stays cross-platform.
+ *
+ * Restarting the supervisor re-spawns every daemon as a side effect. Exits 0
+ * on success, non-zero on failure (the Cockpit detects failure by exit code).
+ */
+/** One step of a restart sequence. `ignoreFailure` steps (e.g. `schtasks /End`
+ *  when the task isn't running) don't abort the sequence. */
+export interface RestartStep {
+    cmd: string;
+    args: string[];
+    ignoreFailure?: boolean;
+}
+/** Pure: the OS command sequence that restarts the supervisor service, or null
+ *  when the platform isn't supported. Most platforms are 1 step; Windows is 2
+ *  (`schtasks /End` then `/Run`). Exported for tests. */
+export declare function _restartSupervisorCommand(platform: NodeJS.Platform, uid: number): RestartStep[] | null;
+/**
+ * Read-only probe of the local UDS broker for the mesh roster, backing
+ * `remote-pi peers`. Opens a raw connection to `sockPath`, sends a single
+ * unregistered `list_peers` request, and resolves with the peer names from the
+ * broker's reply (local UDS peers + cross-PC `<pc>:<peer>` entries).
+ *
+ * The probe deliberately does NOT register as a peer: the broker answers
+ * observer probes without assigning a name or broadcasting peer_joined/left
+ * (see Broker._tryObserverProbe), so a shell query never perturbs the mesh —
+ * no phantom peer flashes in anyone's roster, local or cross-PC.
+ *
+ * Resolves null when no broker is reachable (connection refused / no socket
+ * file — i.e. no Pi or daemon is leading the mesh on this machine), or on
+ * timeout, so the caller can print an "offline" message instead of an empty
+ * roster.
+ */
+export declare function probeListPeers(sockPath: string, timeoutMs?: number): Promise<string[] | null>;