@geohar/un-bien 0.7.0

package/dist/protocol/types.d.ts

@@ -0,0 +1,404 @@
+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;
+} | {
+    type: "session_launch";
+    id: string;
+    mode: "tmux" | "rpc";
+    cwd?: string;
+    name?: 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;
+    images?: WireImage[];
+} | {
+    ts: number;
+    type: "agent_message";
+    in_reply_to: string;
+    text: string;
+    usage?: Usage;
+    images?: WireImage[];
+} | {
+    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;
+    protocol_version?: number;
+    capabilities?: 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_reasoning";
+    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;
+    images?: WireImage[];
+} | {
+    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;
+    images?: WireImage[];
+} | {
+    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: "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;
+} | {
+    type: "panel_update";
+    key: string;
+    title: string;
+    icon?: string;
+    data: unknown;
+} | 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" | "session_launch";
+/**
+ * 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;
+}

package/dist/protocol/types.js

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

package/dist/protocol/types.js.map

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

package/dist/rooms.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 App<->Pi `room_id` basis: derived from the stable pi SESSION ID (which is
+ * durable across resume — it lives in the session file header and is reused when
+ * the file is reopened; a fresh session gets a new id). Keying the room on the
+ * session id makes it (a) stable across relay reconnects, so proactive frames
+ * can't drift onto a different room than the session announces, and (b) unique
+ * per chat session, so two same-NAME chats in one folder are distinct. The
+ * display label stays the session's title/name; this is the routing key only.
+ *
+ * 12-char `base64url(sha256(sessionId))` — same shape as `roomIdForCwd`, and it
+ * keeps the raw session id off the wire.
+ */
+export declare function roomIdForSession(sessionId: 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/dist/rooms.js

@@ -0,0 +1,78 @@
+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 App<->Pi `room_id` basis: derived from the stable pi SESSION ID (which is
+ * durable across resume — it lives in the session file header and is reused when
+ * the file is reopened; a fresh session gets a new id). Keying the room on the
+ * session id makes it (a) stable across relay reconnects, so proactive frames
+ * can't drift onto a different room than the session announces, and (b) unique
+ * per chat session, so two same-NAME chats in one folder are distinct. The
+ * display label stays the session's title/name; this is the routing key only.
+ *
+ * 12-char `base64url(sha256(sessionId))` — same shape as `roomIdForCwd`, and it
+ * keeps the raw session id off the wire.
+ */
+export function roomIdForSession(sessionId) {
+    return createHash("sha256")
+        .update(sessionId)
+        .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/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;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,SAAS,CAAC;SACjB,MAAM,CAAC,WAAW,CAAC;SACnB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,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;SACxB,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;SAC3B,MAAM,CAAC,WAAW,CAAC;SACnB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/session/bridge.d.ts

@@ -0,0 +1,37 @@
+import type { Broker } from "./broker.js";
+import { BrokerRemote } from "./broker_remote.js";
+import { PiForwardClient } from "../transport/pi_forward_client.js";
+import type { RelayClient } from "../transport/relay_client.js";
+import { type MeshTopologySnapshot } from "../mesh/siblings.js";
+import type { Ed25519Keypair } from "../pairing/crypto.js";
+/**
+ * Cross-PC mesh bridge composition. Discovery finishes before either transport
+ * half is constructed, and the returned bridge stays dormant until its caller
+ * has re-checked lifecycle ownership and calls `activate()`.
+ */
+export interface AttachBridgeOptions {
+    /** The leader's local Broker (from SessionPeer.localBroker()). */
+    broker: Broker;
+    /** Live relay connection. Caller owns its lifecycle. */
+    relay: RelayClient;
+    /** Relay URL in http(s):// form — for standalone topology discovery. */
+    relayUrl: string;
+    /** This host's Ed25519 identity (machine Pi-key). */
+    keypair: Ed25519Keypair;
+    /** Retained Pi-produced topology. Supplying it bypasses discovery. */
+    topology?: MeshTopologySnapshot;
+    /** Standalone discovery deadline per mesh request. Defaults to 5 seconds. */
+    meshRequestTimeoutMs?: number;
+    /** Diagnostic logger. Defaults to a no-op (avoids TUI leaks). */
+    log?: (msg: string) => void;
+}
+export interface CrossPcBridge {
+    brokerRemote: BrokerRemote;
+    piForward: PiForwardClient;
+    topology: MeshTopologySnapshot;
+    /** Publish the already-built router exactly once. */
+    activate(): void;
+    /** Safe before or after activation; tears down both halves exactly once. */
+    detach(): void;
+}
+export declare function attachCrossPcBridge(opts: AttachBridgeOptions): Promise<CrossPcBridge>;