@herbertgao/pi-extensions 2026.8.2 → 2026.8.3

package/node_modules/remote-pi/dist/protocol/codec.js

@@ -0,0 +1,49 @@
+const SERVER_TYPES = new Set([
+    "pair_ok",
+    "pair_error",
+    "user_input",
+    "queued_message_state",
+    "agent_chunk",
+    "agent_done",
+    "agent_message",
+    "tool_request",
+    "tool_result",
+    "error",
+    "cancelled",
+    "pong",
+    "bye",
+    "session_history",
+    // Plan/57 — interactive extension prompt (ask_user via pi-ask).
+    "extension_ui_request",
+]);
+export class DecodeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DecodeError";
+    }
+}
+export function encodeClient(msg) {
+    return JSON.stringify(msg) + "\n";
+}
+export function decodeServer(line) {
+    let obj;
+    try {
+        obj = JSON.parse(line.trim());
+    }
+    catch (e) {
+        throw new DecodeError("invalid_message", `not JSON: ${e.message}`);
+    }
+    if (!obj ||
+        typeof obj !== "object" ||
+        typeof obj.type !== "string") {
+        throw new DecodeError("invalid_message", "missing 'type'");
+    }
+    const t = obj.type;
+    if (!SERVER_TYPES.has(t)) {
+        throw new DecodeError("unsupported_type", `unknown type: ${t}`);
+    }
+    return obj;
+}
+//# sourceMappingURL=codec.js.map

package/node_modules/remote-pi/dist/protocol/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/protocol/codec.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAwB;IAClD,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,sBAAsB;IACtB,aAAa;IACb,YAAY;IACZ,eAAe;IACf,cAAc;IACd,aAAa;IACb,OAAO;IACP,WAAW;IACX,MAAM;IACN,KAAK;IACL,iBAAiB;IACjB,gEAAgE;IAChE,sBAAsB;CACvB,CAAC,CAAC;AAEH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAElB;IADlB,YACkB,IAA4C,EAC5D,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwC;QAI5D,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,aAAc,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,IACE,CAAC,GAAG;QACJ,OAAO,GAAG,KAAK,QAAQ;QACvB,OAAQ,GAA+B,CAAC,IAAI,KAAK,QAAQ,EACzD,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,CAAC,GAAI,GAA+B,CAAC,IAAc,CAAC;IAC1D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAA0B,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,GAAoB,CAAC;AAC9B,CAAC"}

package/node_modules/remote-pi/dist/protocol/types.d.ts

@@ -0,0 +1,393 @@
+export type PairErrorCode = "token_expired" | "token_consumed" | "token_unknown" | "internal_error";
+export type StreamingBehavior = "steer";
+export type QueuedMessageItem = {
+    id: string;
+    text: string;
+    editable: boolean;
+    created_at: number;
+};
+export type ExtensionUiMethod = "select" | "confirm" | "input" | "editor" | "notify";
+export type AskQuestionWireType = "single" | "multi" | "preview";
+export interface AskOptionWire {
+    value: string;
+    label: string;
+    description?: string;
+    /** Preview-pane content (preview questions only). */
+    preview?: string;
+    /** pi-ask addition: option allows freeform custom entry. */
+    freeform?: boolean;
+}
+export interface AskQuestionWire {
+    id: string;
+    label: string;
+    prompt: string;
+    type: AskQuestionWireType;
+    required: boolean;
+    /** pi-ask addition: type actually presented after live toggle / policy. */
+    presentedType?: AskQuestionWireType;
+    /** pi-ask addition: type originally requested by the model. */
+    requestedType?: AskQuestionWireType;
+    options: AskOptionWire[];
+}
+/** Optional pi-ask enrichment on an extension_ui_request — lets the app render
+ *  the full flow (multi/preview/notes) instead of the degraded SDK select. A
+ *  flow maps to ONE request carrying every question; the app renders a
+ *  full-screen modal and submits ONE response with all answers (pi-ask resolves
+ *  a flow in a single submit). When `ask` is absent the SDK method/options
+ *  drive rendering (future generic prompts). */
+export interface AskEnrichmentWire {
+    flow_id: string;
+    tool_call_id: string | null;
+    /** pi-ask RemoteAskSource: "tool" | "answer" | "answer:again" | "ask:replay". */
+    source: string;
+    title: string | null;
+    questions: AskQuestionWire[];
+}
+/** pi-ask RemoteAskAnswer — one question's answered parts.
+ *
+ *  CASING EXCEPTION: inside the `ask` envelope the keys mirror pi-ask's own
+ *  schema VERBATIM (camelCase: `presentedType`, `requestedType`, `customText`,
+ *  `optionNotes`) so the bridge can forward the response to pi-ask's submit
+ *  event without a remap pass. The snake_case convention of this protocol
+ *  applies at the frame level (`flow_id`, `tool_call_id`, `notify_type`). */
+export interface AskAnswerWire {
+    values?: string[];
+    customText?: string;
+    note?: string;
+    optionNotes?: Record<string, string>;
+}
+/** Optional pi-ask enrichment on an extension_ui_response — carries the
+ *  structured answer so multi/preview/notes survive the round-trip. */
+export type AskResponseEnrichmentWire = {
+    flow_id: string;
+    kind: "answer";
+    mode?: "submit" | "elaborate";
+    answers: Record<string, AskAnswerWire>;
+} | {
+    flow_id: string;
+    kind: "cancel";
+};
+/** ServerMessage: interactive extension prompt. Mirrors RpcExtensionUIRequest
+ *  (select/confirm/input/editor/notify). The `ask` envelope is present when the
+ *  prompt originates from a pi-ask flow, carrying the full question schema. */
+export type ExtensionUiRequestWire = {
+    type: "extension_ui_request";
+    id: string;
+    method: "select";
+    title: string;
+    options: string[];
+    ask?: AskEnrichmentWire;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "confirm";
+    title: string;
+    message: string;
+    ask?: AskEnrichmentWire;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "input";
+    title: string;
+    placeholder?: string;
+    ask?: AskEnrichmentWire;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "editor";
+    title: string;
+    prefill?: string;
+    ask?: AskEnrichmentWire;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "notify";
+    message: string;
+    notify_type?: "info" | "warning" | "error";
+};
+/** ClientMessage: response to an extension_ui_request. Mirrors
+ *  RpcExtensionUIResponse (value / confirmed / cancelled). The `ask` envelope
+ *  carries pi-ask's structured answer when the app rendered the rich flow. */
+export type ExtensionUiResponseWire = {
+    type: "extension_ui_response";
+    id: string;
+    value: string;
+    ask?: AskResponseEnrichmentWire;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    confirmed: boolean;
+    ask?: AskResponseEnrichmentWire;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    cancelled: true;
+    ask?: AskResponseEnrichmentWire;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    ask: AskResponseEnrichmentWire;
+};
+export type ClientMessage = {
+    type: "pair_request";
+    id: string;
+    token: string;
+    device_name: string;
+} | {
+    type: "user_message";
+    id: string;
+    text: string;
+    images?: WireImage[];
+    streaming_behavior?: StreamingBehavior;
+} | {
+    type: "queued_message_set";
+    id: string;
+    text: string;
+} | {
+    type: "queued_message_clear";
+    id: string;
+    target_id?: string;
+} | {
+    type: "approve_tool";
+    id: string;
+    tool_call_id: string;
+    decision: "allow" | "deny";
+} | {
+    type: "cancel";
+    id: string;
+    target_id: string;
+} | {
+    type: "ping";
+    id: string;
+} | {
+    type: "session_sync";
+    id: string;
+    limit?: number;
+} | {
+    type: "session_new";
+    id: string;
+} | {
+    type: "session_compact";
+    id: string;
+} | {
+    type: "model_set";
+    id: string;
+    provider: string;
+    model_id: string;
+} | {
+    type: "thinking_set";
+    id: string;
+    level: ThinkingLevel;
+} | {
+    type: "list_models";
+    id: string;
+} | ExtensionUiResponseWire;
+/**
+ * Plan/30 — one inline image attachment on a `user_message`. Mirrors the
+ * SDK's `ImageContent` ({@link https }) split across the wire: `data` is the
+ * base64-encoded (compressed) image bytes, `mime` its content type
+ * (e.g. `"image/jpeg"`). The Pi maps `{ data, mime }` → the SDK's
+ * `{ type:"image", data, mimeType }` before handing it to the model.
+ */
+export interface WireImage {
+    /** Base64-encoded image bytes (compressed app-side). */
+    data: string;
+    /** MIME type, e.g. `"image/jpeg"`. Maps to the SDK's `mimeType`. */
+    mime: string;
+}
+export type Usage = {
+    input_tokens: number;
+    output_tokens: number;
+};
+export type KnownErrorCode = "tool_approval_required" | "invalid_message" | "unsupported_type" | "too_large" | "rate_limited" | "timeout" | "internal_error";
+export type ErrorCode = KnownErrorCode | (string & {});
+export type SessionHistoryEvent = {
+    ts: number;
+    type: "user_input";
+    id: string;
+    text: string;
+    images?: WireImage[];
+} | {
+    ts: number;
+    type: "tool_request";
+    tool_call_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    ts: number;
+    type: "tool_result";
+    tool_call_id: string;
+    result?: unknown;
+    error?: string;
+} | {
+    ts: number;
+    type: "agent_message";
+    in_reply_to: string;
+    text: string;
+    usage?: Usage;
+} | {
+    ts: number;
+    type: "compaction";
+    summary: string;
+    tokens_before: number;
+};
+export type ServerMessage = {
+    type: "pair_ok";
+    in_reply_to: string;
+    session_name: string;
+    session_started_at: number;
+    room_id: string;
+    /**
+     * Plan/27 Wave A: identifies the host coding agent driving this
+     * pi-extension instance. `name` is hardcoded to "Pi coding agent"
+     * today; future Pi forks (Claude Code, OpenCode) populate their own
+     * here. `version` is the pi-extension `package.json` version.
+     * Optional in the wire schema so app-side parsing tolerates older
+     * Pi builds that predate this field — every new pairing emits both.
+     */
+    harness?: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Plan/27 Wave A: `os.hostname()` of the machine the Pi runs on.
+     * App displays it in the device list so the user can distinguish
+     * two paired PCs that happen to share a nickname or sit in the
+     * same project folder.
+     */
+    hostname?: string;
+} | {
+    type: "pair_error";
+    in_reply_to: string;
+    code: PairErrorCode;
+    message: string;
+} | {
+    type: "user_input";
+    id: string;
+    text: string;
+    streaming_behavior?: StreamingBehavior;
+} | {
+    type: "user_message";
+    id: string;
+    text: string;
+    images?: WireImage[];
+    streaming_behavior?: StreamingBehavior;
+} | {
+    type: "queued_message_state";
+    id?: string;
+    text?: string;
+    items?: QueuedMessageItem[];
+} | {
+    type: "steer_consumed";
+    id: string;
+} | {
+    type: "agent_chunk";
+    in_reply_to: string;
+    delta: string;
+} | {
+    type: "agent_done";
+    in_reply_to: string;
+    usage?: Usage;
+} | {
+    type: "agent_message";
+    in_reply_to: string;
+    text: string;
+    usage?: Usage;
+} | {
+    type: "compaction";
+    summary: string;
+    tokens_before: number;
+    ts?: number;
+} | {
+    type: "tool_request";
+    tool_call_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    tool_call_id: string;
+    result?: unknown;
+    error?: string;
+} | {
+    type: "error";
+    in_reply_to?: string;
+    code: ErrorCode;
+    message: string;
+} | {
+    type: "cancelled";
+    in_reply_to: string;
+    target_id: string;
+} | {
+    type: "pong";
+    in_reply_to: string;
+} | {
+    type: "bye";
+    reason: ByeReason;
+} | {
+    type: "session_history";
+    in_reply_to: string;
+    session_started_at: number;
+    events: SessionHistoryEvent[];
+    eos: boolean;
+    truncated: boolean;
+} | {
+    type: "action_ok";
+    in_reply_to: string;
+    action: ActionName;
+} | {
+    type: "action_error";
+    in_reply_to: string;
+    action: ActionName;
+    error: string;
+} | {
+    type: "models_list";
+    in_reply_to: string;
+    models: WireModel[];
+    current?: WireModel;
+} | ExtensionUiRequestWire;
+/**
+ * Plan/28 — Stable names for the typed actions the app can request. Kept
+ * as a closed string union so a switch in either side gets exhaustiveness
+ * checking from the compiler.
+ */
+export type ActionName = "session_new" | "session_compact" | "model_set" | "thinking_set";
+/**
+ * Plan/28 — Mirror of the SDK's `ThinkingLevel` (defined in
+ * `@earendil-works/pi-agent-core/types`). Re-declared locally so the wire
+ * protocol owns its own enum and we don't leak SDK-internal types onto
+ * the app's network surface.
+ *
+ * Note: `"xhigh"` is only honored by select model families — the SDK uses
+ * each `Model.thinkingLevelMap` to decide if the requested level is
+ * supported, falling back to a sensible neighbour when not. The app
+ * surfaces all 6 buttons but can grey out unsupported ones using the
+ * model's metadata if the picker fetches it later.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Plan/28 — Wire shape for one model entry in the app's model picker.
+ *
+ * Subset of the SDK's `Model<Api>` interface — only the fields the app
+ * actually renders. Cost / max-tokens / API class are left off the wire
+ * deliberately; if the app's picker grows to need them, they get added
+ * here and to the handler's mapping in `index.ts` in one diff.
+ */
+export interface WireModel {
+    /** Stable identifier inside the provider's catalog. E.g. `"claude-opus-4-7"`. */
+    id: string;
+    /** Display name for the picker row. E.g. `"Claude Opus 4.7"`. */
+    name: string;
+    /** Provider slug. E.g. `"anthropic"`, `"openai"`. */
+    provider: string;
+    /** Whether the model supports the thinking surface (`reasoning: true`
+     *  in the SDK). Useful so the app can decide whether the thinking
+     *  segmented control should be enabled when this model is selected. */
+    reasoning: boolean;
+    /** Context window in tokens, for display in the picker subtitle. */
+    context_window: number;
+    /** Plan/30: true when the model accepts image input (SDK `Model.input`
+     *  includes `"image"`). The app uses it to enable/disable the attach
+     *  button — a text-only model greys out image attachments. */
+    vision: boolean;
+}
+export type ByeReason = "peer_stop" | "session_replaced" | "shutdown";

package/node_modules/remote-pi/dist/protocol/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/node_modules/remote-pi/dist/protocol/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/protocol/types.ts"],"names":[],"mappings":""}

package/node_modules/remote-pi/dist/rooms.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic room id derived from a cwd. Two Pi processes in the same
+ * directory produce the same id; different cwds produce different ids
+ * (with cryptographic-strength collision resistance). Symlinks are resolved
+ * via `realpath` so `/a` and `/symlink-to-a` map to the same room.
+ *
+ * Format: first 12 chars of base64url(sha256(realpath)).
+ */
+export declare function roomIdForCwd(cwd: string): string;
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export declare function roomIdFor(cwd: string, name?: string): string;

package/node_modules/remote-pi/dist/rooms.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { defaultAgentName } from "./session/local_config.js";
+/**
+ * Deterministic room id derived from a cwd. Two Pi processes in the same
+ * directory produce the same id; different cwds produce different ids
+ * (with cryptographic-strength collision resistance). Symlinks are resolved
+ * via `realpath` so `/a` and `/symlink-to-a` map to the same room.
+ *
+ * Format: first 12 chars of base64url(sha256(realpath)).
+ */
+export function roomIdForCwd(cwd) {
+    let target;
+    try {
+        target = realpathSync(cwd);
+    }
+    catch {
+        // cwd doesn't exist (unlikely in production) — fallback to raw path.
+        target = cwd;
+    }
+    return createHash("sha256").update(target).digest("base64url").slice(0, 12);
+}
+/**
+ * THE single derivation of the App↔Pi `room_id` (plan/41) — keyed by
+ * `(cwd, name)` so several agents in the SAME folder get distinct rooms (the
+ * app then renders one tile per agent instead of merging them into one).
+ *
+ * Default-preserving: when `name` is absent OR equals `defaultAgentName(cwd)`
+ * (an agent with no custom `agent_name`), it returns the LEGACY `roomIdForCwd`
+ * EXACTLY — so a single unnamed agent's existing conversation is NOT re-keyed
+ * on upgrade. A custom or `#N`-suffixed name → a name-scoped id (same formula
+ * the cwd-lock uses).
+ *
+ * Using the ASSIGNED leaf name (the broker's `#N` on collision) disambiguates
+ * even two unnamed agents: the 1st stays `folder` (== default → legacy room),
+ * the 2nd becomes `folder#2` (≠ default → name-scoped room).
+ *
+ * INVARIANT: every callsite that derives the App↔Pi room for the same agent
+ * MUST go through this function — otherwise the app would pair on a room the
+ * Pi never announces.
+ */
+export function roomIdFor(cwd, name) {
+    if (!name || name === defaultAgentName(cwd))
+        return roomIdForCwd(cwd);
+    let target;
+    try {
+        target = realpathSync(cwd);
+    }
+    catch {
+        target = cwd;
+    }
+    // NUL separator (U+0000): impossible in a POSIX path and stripped from any
+    // sanitized name, so the cwd/name boundary is unambiguous.
+    const sep = String.fromCharCode(0);
+    return createHash("sha256").update(target + sep + name).digest("base64url").slice(0, 12);
+}
+//# sourceMappingURL=rooms.js.map

package/node_modules/remote-pi/dist/rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../src/rooms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAa;IAClD,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,gBAAgB,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IACtE,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IACD,2EAA2E;IAC3E,2DAA2D;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/node_modules/remote-pi/dist/session/address.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mesh addressing for plan/35 (malha direta). An "agent" ≡ a cwd (cwd_lock
+ * guarantees at most one Pi per folder), so the folder *is* the address:
+ *
+ *   - **local**  → an absolute path on this machine. A local peer is reached by
+ *     `POST`ing its inbox socket directly (see `apiSockPath`).
+ *   - **remote** → `<label>:/path`, where `<label>` names a sibling machine
+ *     (resolved to a pubkey via `mesh_versions`/siblings in Wave C) and `/path`
+ *     is the folder on that machine. Routed cross-PC through the relay.
+ *
+ * The address an agent passes is ALWAYS the absolute folder path; the `.sock`
+ * file itself lives OUTSIDE the cwd (decisão fixada — "Transporte local"). The
+ * folder is hashed to the file name, so the mapping is deterministic and both
+ * the inbox (its own socket) and a sender (the peer's socket) land on the same
+ * file without coordinating.
+ *
+ * Wave 0 only *parses* what it is handed — contacts (known routes) live in the
+ * agent's context/CLAUDE.md (decisão Q5), not in an allowlist module. The
+ * `<label>→pubkey` resolution and remote send arrive in Wave C; here we keep
+ * the parser and the local route→socket mapping.
+ */
+export type Address = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "remote";
+    label: string;
+    path: string;
+};
+export declare class AddressError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parses a mesh address. A `:` separates a remote `<label>` from its `/path`;
+ * with no `:` the whole string is a local absolute path (decisão fixada:
+ * "Sem ':' → local"). Both the local path and the remote path must be
+ * absolute — the folder is the canonical route.
+ */
+export declare function parseAddress(raw: string): Address;
+/**
+ * The inbox socket path for a folder. Single source of truth shared by the
+ * inbox server (its own socket) and the send client (a local peer's socket).
+ *
+ * `~/.pi/remote-pi/socks/<roomId>.sock`, where `roomId = roomIdForCwd(folder)`
+ * (`sha256(realpath(folder))[:12]` — the same hash `cwd_lock` uses). The folder
+ * is the address; the hash is only the file name. `realpath` canonicalization
+ * means `/a` and a symlink to `/a` map to the same socket.
+ */
+export declare function apiSockPath(folderPath: string): string;

package/node_modules/remote-pi/dist/session/address.js

@@ -0,0 +1,58 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { roomIdForCwd } from "../rooms.js";
+export class AddressError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AddressError";
+    }
+}
+/**
+ * Parses a mesh address. A `:` separates a remote `<label>` from its `/path`;
+ * with no `:` the whole string is a local absolute path (decisão fixada:
+ * "Sem ':' → local"). Both the local path and the remote path must be
+ * absolute — the folder is the canonical route.
+ */
+export function parseAddress(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        throw new AddressError("empty address");
+    const colon = trimmed.indexOf(":");
+    if (colon === -1) {
+        if (!isAbsolute(trimmed)) {
+            throw new AddressError(`local address must be an absolute path: ${trimmed}`);
+        }
+        return { kind: "local", path: trimmed };
+    }
+    const label = trimmed.slice(0, colon);
+    const path = trimmed.slice(colon + 1);
+    if (!label)
+        throw new AddressError(`remote address missing label: ${trimmed}`);
+    if (!path)
+        throw new AddressError(`remote address missing path: ${trimmed}`);
+    if (!isAbsolute(path)) {
+        throw new AddressError(`remote address path must be absolute: ${trimmed}`);
+    }
+    return { kind: "remote", label, path };
+}
+/** Directory holding inbox sockets, resolved at call time (not module load) so
+ *  tests can redirect it via `REMOTE_PI_HOME` — the same override `cwd_lock`
+ *  honors. Kept OUT of the cwd: `sun_path` is capped at 104 chars on macOS
+ *  (EINVAL at ≥105), so a socket nested inside a deep cwd would overflow. */
+function socksDir() {
+    const root = process.env["REMOTE_PI_HOME"] || homedir();
+    return join(root, ".pi", "remote-pi", "socks");
+}
+/**
+ * The inbox socket path for a folder. Single source of truth shared by the
+ * inbox server (its own socket) and the send client (a local peer's socket).
+ *
+ * `~/.pi/remote-pi/socks/<roomId>.sock`, where `roomId = roomIdForCwd(folder)`
+ * (`sha256(realpath(folder))[:12]` — the same hash `cwd_lock` uses). The folder
+ * is the address; the hash is only the file name. `realpath` canonicalization
+ * means `/a` and a symlink to `/a` map to the same socket.
+ */
+export function apiSockPath(folderPath) {
+    return join(socksDir(), `${roomIdForCwd(folderPath)}.sock`);
+}
+//# sourceMappingURL=address.js.map

package/node_modules/remote-pi/dist/session/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/session/address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4B3C,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,YAAY,CAAC,eAAe,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,YAAY,CAAC,2CAA2C,OAAO,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,YAAY,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAC;IAC/E,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,YAAY,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,YAAY,CAAC,yCAAyC,OAAO,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzC,CAAC;AAED;;;6EAG6E;AAC7E,SAAS,QAAQ;IACf,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,OAAO,EAAE,CAAC;IACxD,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC9D,CAAC"}