@geohar/un-bien 0.9.0 → 0.14.0

package/dist/session/received_images.js

@@ -0,0 +1,273 @@
+/**
+ * Received-image preview pipeline.
+ *
+ * Everything the App↔Pi image path needs once an Android `user_message` with
+ * images lands on a PlainPeerChannel: decode + persist the payloads under the
+ * private image cache, emit the metadata-only TUI preview custom message
+ * (deferred while a turn is active), register the TUI renderer for it, and
+ * hand the multimodal content to the agent via sendUserMessage.
+ *
+ * Seam: index.ts (composition root) owns the mutable module state this
+ * pipeline reads (`_pi`, `_myRoomMeta`, the root session record) and the
+ * `_wakeAgent` helper; they are threaded through `ImagePipelineDeps`. This
+ * module MUST NOT import `../index.js` (circular import). The
+ * pending-preview buffer is pipeline-local and lives here in module scope.
+ *
+ * NOT here: `_isPureDataContextMessage` / `_filterInternalMessagesFromContext`
+ * — those are GENERIC context filters (issue #105, pure-data events must not
+ * reach the model) used by the extension registration far beyond the image
+ * path; they stay in index.ts and call `_isReceivedImageContextMessage` below.
+ */
+import { join } from "node:path";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { Box, Container, Image, Text } from "@earendil-works/pi-tui";
+import { IMAGE_PREVIEW_MIME, _imageCacheRootDir, _imageExtension, _safeFilenameToken, _safePreviewPath, _renderablePngPathFromImage, _decodeImagePayload, } from "../image_codec.js";
+/** Custom-message type for the metadata-only TUI preview (un-bien namespace). */
+const UNBIEN_RECEIVED_IMAGE_TYPE = "un-bien:received-image";
+/** Previews parked while a turn is active; flushed on agent_end / stop. */
+const _pendingReceivedImagePreviews = [];
+export function _sendReceivedImagePreviewNow(deps, details) {
+    if (!deps.pi)
+        return;
+    try {
+        deps.pi.sendMessage({
+            customType: UNBIEN_RECEIVED_IMAGE_TYPE,
+            content: "",
+            display: true,
+            details,
+        });
+    }
+    catch {
+        // TUI preview is best-effort; skip on failure.
+    }
+}
+export function _shouldDeferReceivedImagePreview(deps) {
+    return deps.rootState().turnId !== null || deps.myRoomMeta?.working === true;
+}
+export function _sendReceivedImagePreview(deps, details, delivery = "immediate") {
+    if (delivery === "defer" || _shouldDeferReceivedImagePreview(deps)) {
+        _pendingReceivedImagePreviews.push(details);
+        return;
+    }
+    _sendReceivedImagePreviewNow(deps, details);
+}
+export function _flushPendingReceivedImagePreviews(deps) {
+    if (_pendingReceivedImagePreviews.length === 0)
+        return;
+    const pending = _pendingReceivedImagePreviews.splice(0);
+    for (const details of pending)
+        _sendReceivedImagePreviewNow(deps, details);
+}
+/** Drop parked previews without rendering (teardown path — mirrors `_goIdle`). */
+export function clearPendingReceivedImagePreviews() {
+    _pendingReceivedImagePreviews.length = 0;
+}
+export async function _collectReceivedImagePreviews(msg) {
+    if (!msg.images || msg.images.length === 0)
+        return [];
+    const previews = [];
+    const text = typeof msg.text === "string" ? msg.text : "";
+    const dir = _imageCacheRootDir();
+    for (let i = 0; i < msg.images.length; i += 1) {
+        const image = msg.images[i];
+        const mime = typeof image?.mime === "string" ? image.mime : "unknown";
+        if (!image || typeof image.data !== "string") {
+            console.error(`[un-bien] malformed image in message ${msg.id} index=${i}`);
+            previews.push({
+                messageId: msg.id,
+                index: i,
+                mime,
+                ...(text ? { text } : {}),
+                error: "malformed image payload",
+                reason: "missing mime/data payload fields",
+            });
+            continue;
+        }
+        const decoded = _decodeImagePayload(image.data, image.mime);
+        if (!decoded.ok) {
+            console.error(`[un-bien] skipped image id=${msg.id} index=${i}: ${decoded.reason}`);
+            previews.push({
+                messageId: msg.id,
+                index: i,
+                mime: image.mime,
+                ...(text ? { text } : {}),
+                error: "invalid image payload",
+                reason: decoded.reason,
+            });
+            continue;
+        }
+        const ext = _imageExtension(image.mime);
+        if (!ext) {
+            console.error(`[un-bien] unsupported image mime in message ${msg.id} index=${i}: ${image.mime}`);
+            previews.push({
+                messageId: msg.id,
+                index: i,
+                mime: image.mime,
+                ...(text ? { text } : {}),
+                error: "invalid image payload",
+                reason: `unsupported mime: ${image.mime}`,
+            });
+            continue;
+        }
+        const filename = `${_safeFilenameToken(msg.id)}-${i}.${ext}`;
+        const path = join(dir, filename);
+        try {
+            writeFileSync(path, decoded.decoded, { mode: 0o600 });
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                /* best-effort permission hardening */
+            }
+            const previewPath = image.mime === IMAGE_PREVIEW_MIME
+                ? undefined
+                : await _renderablePngPathFromImage(image.data, image.mime, _safePreviewPath(dir, msg.id, i));
+            previews.push({
+                messageId: msg.id,
+                index: i,
+                mime: image.mime,
+                size: decoded.size,
+                path,
+                ...(previewPath ? { previewPath } : {}),
+                ...(text ? { text } : {}),
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(`[un-bien] failed saving image id=${msg.id} index=${i}: ${detail}`);
+            previews.push({
+                messageId: msg.id,
+                index: i,
+                mime: image.mime,
+                ...(text ? { text } : {}),
+                path,
+                error: "failed to save image",
+                reason: detail,
+            });
+        }
+    }
+    return previews;
+}
+export async function _emitReceivedImagePreviews(deps, msg, delivery = "immediate") {
+    const previews = await _collectReceivedImagePreviews(msg);
+    for (const preview of previews)
+        _sendReceivedImagePreview(deps, preview, delivery);
+}
+export function _registerReceivedImageRenderer(pi) {
+    pi.registerMessageRenderer(UNBIEN_RECEIVED_IMAGE_TYPE, (message, _options, theme) => {
+        const details = (message.details ?? {});
+        const path = typeof details.path === "string" ? details.path : "";
+        const previewPath = typeof details.previewPath === "string" ? details.previewPath : "";
+        const mime = typeof details.mime === "string"
+            ? details.mime
+            : "application/octet-stream";
+        const inlineImagePath = previewPath.length > 0
+            ? previewPath
+            : mime === IMAGE_PREVIEW_MIME
+                ? path
+                : "";
+        const size = typeof details.size === "number" ? details.size : undefined;
+        const index = typeof details.index === "number" ? details.index : undefined;
+        const text = typeof details.text === "string" ? details.text.trim() : "";
+        const messageId = typeof details.messageId === "string" ? details.messageId : "unknown";
+        const error = typeof details.error === "string" ? details.error : undefined;
+        const reason = typeof details.reason === "string" ? details.reason : undefined;
+        const label = `📷 Photo from Android (${messageId}${index === undefined ? "" : ` #${index}`})`;
+        const lines = [
+            theme.fg("customMessageLabel", label),
+            theme.fg("customMessageText", `Saved: ${path || "(not saved)"}`),
+        ];
+        if (size !== undefined)
+            lines.push(theme.fg("customMessageText", `Size: ${size} bytes`));
+        if (mime)
+            lines.push(theme.fg("customMessageText", `MIME: ${mime}`));
+        if (error)
+            lines.push(theme.fg("customMessageText", `Error: ${error}`));
+        if (reason)
+            lines.push(theme.fg("customMessageText", `Reason: ${reason}`));
+        if (text)
+            lines.push(theme.fg("customMessageText", `Text: ${text}`));
+        const container = new Container();
+        const metadata = new Box(1, 1, (line) => theme.bg("customMessageBg", line));
+        metadata.addChild(new Text(lines.join("\n")));
+        container.addChild(metadata);
+        if (inlineImagePath && !error) {
+            try {
+                const imageData = readFileSync(inlineImagePath).toString("base64");
+                if (imageData.length > 0) {
+                    const image = new Image(imageData, IMAGE_PREVIEW_MIME, {
+                        fallbackColor: (str) => theme.fg("customMessageText", str),
+                    });
+                    // Keep Kitty image rows out of Box padding/background so pi-tui can
+                    // preserve the empty reserved rows that make inline images visible.
+                    container.addChild(image);
+                }
+            }
+            catch {
+                // Keep the metadata-only fallback on any IO/terminal issue.
+            }
+        }
+        return container;
+    });
+}
+export function _isReceivedImageContextMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.role === "custom" &&
+        message.customType ===
+            UNBIEN_RECEIVED_IMAGE_TYPE);
+}
+export function _contentFromUserMessage(msg) {
+    return msg.images && msg.images.length > 0
+        ? [
+            ...msg.images.map((img) => ({
+                type: "image",
+                data: img.data,
+                mimeType: img.mime,
+            })),
+            { type: "text", text: msg.text },
+        ]
+        : msg.text;
+}
+export async function _deliverImageUserMessage(deps, sender, msg, shouldSteer) {
+    const previewDelivery = shouldSteer ||
+        deps.rootState().turnId !== null ||
+        deps.myRoomMeta?.working === true
+        ? "defer"
+        : "immediate";
+    const emitPreview = async () => {
+        try {
+            await _emitReceivedImagePreviews(deps, msg, previewDelivery);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(`[un-bien] failed emitting image preview id=${msg.id}: ${detail}`);
+        }
+    };
+    if (previewDelivery === "immediate") {
+        await emitPreview();
+    }
+    else {
+        void emitPreview().finally(() => {
+            if (!_shouldDeferReceivedImagePreview(deps))
+                _flushPendingReceivedImagePreviews(deps);
+        });
+    }
+    const previousTurnId = deps.rootState().turnId;
+    const seededTurnId = !shouldSteer || deps.rootState().turnId === null;
+    if (seededTurnId)
+        deps.rootState().turnId = msg.id;
+    const wake = deps.wakeAgent(_contentFromUserMessage(msg), `app user_message id=${msg.id} (+${msg.images?.length ?? 0} image)`, "steer");
+    if (!wake.ok) {
+        if (seededTurnId)
+            deps.rootState().turnId = previousTurnId;
+        sender.send({
+            type: "error",
+            code: "internal_error",
+            in_reply_to: msg.id,
+            message: `Agent rejected incoming message: ${wake.detail}`,
+        });
+        return;
+    }
+}
+//# sourceMappingURL=received_images.js.map

package/dist/session/received_images.js.map

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

package/dist/session/relay_lifecycle.d.ts

@@ -0,0 +1,219 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Ed25519Keypair } from "../pairing/crypto.js";
+import type { SelfRevoke } from "../mesh/self_revoke.js";
+import type { MeshTopologySnapshot } from "../mesh/siblings.js";
+import type { ClientMessage, ServerMessage, ThinkingLevel } from "../protocol/types.js";
+import { RelayClient } from "../transport/relay_client.js";
+import { PlainPeerChannel } from "../transport/peer_channel.js";
+import type { MeshNode } from "./mesh_node.js";
+import { type EnvelopeMessage } from "./rpc_envelope.js";
+import type { CommandDeps } from "../commands/deps.js";
+/**
+ * The seam between index.ts (composition root) and the relay lifecycle +
+ * owner-management code.
+ *
+ * Same shape as `CommandDeps`: index.ts owns every piece of mutable module
+ * state this code touches; it reaches it only through accessor closures /
+ * function references on this object. Members are added exactly as the moved
+ * code requires them — nothing speculative. Mutable state written here is a
+ * get/set pair; state only read is `readonly`.
+ */
+export interface RelayLifecycleDeps {
+    /** Remote state machine: `idle` → `started` (`paired` is derived). */
+    state: "idle" | "started";
+    /** Live relay WS connection, null when off. */
+    relay: RelayClient | null;
+    /** URL used by the current relay connection (http(s):// canonical form). */
+    relayUrl: string | null;
+    /** Shortid of the most recently attached peer (UX hint only). */
+    peerShort: string;
+    /** Auto-listener dispose fn for the current relay connection. */
+    stopAutoListener: (() => void) | null;
+    /** SelfRevoke topology producer for the relay path. */
+    selfRevoke: SelfRevoke | null;
+    /** Epoch guarding the SelfRevoke producer identity. */
+    selfRevokeEpoch: number;
+    /** Producer epoch that last published a verified topology. */
+    selfRevokeTopologyReadyEpoch: number;
+    /** Last topology snapshot published by the producer. */
+    selfRevokeTopology: MeshTopologySnapshot | null;
+    /** Root replacement authority epoch (session replacements). */
+    rootLifecycleGeneration: number;
+    /** Connected owner channels, keyed by canonical owner pubkey. */
+    readonly activePeers: Map<string, PlainPeerChannel>;
+    /** Local UDS mesh node, null when not joined. */
+    readonly meshNode: MeshNode | null;
+    /** Cached Ed25519 identity of this connect cycle. */
+    readonly cachedEd25519: Ed25519Keypair | null;
+    /** THE App↔Pi room id for the current chat session. */
+    readonly myRoomId: string | null;
+    /** Room meta hello payload persisted for reconnect replay. */
+    readonly myRoomMeta: {
+        name: string;
+        cwd: string;
+        model?: string;
+        thinking?: ThinkingLevel;
+        working?: boolean;
+        sessionId?: string;
+    } | null;
+    /** Epoch ms the state machine entered 'started'. */
+    readonly sessionStartedAt: number | null;
+    /** Current session's cwd (sessionManager.getCwd(); process.cwd() fallback). */
+    sessionCwd(): string;
+    /** Set by session_shutdown; blocks listener authority until rearm. */
+    readonly disposed: boolean;
+    /** The ROOT session's ExtensionAPI (never a subagent child's). */
+    readonly pi: ExtensionAPI | null;
+    /** The root session's pi sessionId, null pre-sessionManager. */
+    readonly rootSessionId: string | null;
+    /** The `/unbien` command seam index.ts builds (`_cmdStart` for relay:on). */
+    readonly commandDeps: CommandDeps;
+    /** The ROOT session's state record (turn teardown + sessionId reads). */
+    rootState(): {
+        turnId: string | null;
+        sessionManager?: {
+            getSessionId(): string;
+        } | null;
+    };
+    /** Test-visible state: `idle` | `started` | derived `paired`. */
+    getState(): "idle" | "started" | "paired";
+    /** Repaint the footer status line from current state. */
+    refreshFooter(ctx?: {
+        ui?: {
+            setStatus?: unknown;
+            setTitle?: unknown;
+        };
+    } | null): void;
+    /** ctx.ui.notify that never throws (stale-ctx safe). */
+    safeNotify(message: string, level?: "info" | "warning" | "error", preferred?: {
+        ui?: unknown;
+    } | null): void;
+    /** Reads peers.json and refreshes the global-pairings cache + footer. */
+    refreshPairingsCache(): void;
+    /** Friendly (configured or derived) agent name for a cwd. */
+    displayName(cwd: string): string;
+    /** Attach the cross-PC bridge once relay + leader are both up. */
+    attachBridgeIfReady(): void;
+    /** Stock ClientMessage router (ping / cancel / pre-attach paths). */
+    routeClientMessageFrom(sender: PlainPeerChannel, msg: ClientMessage, ctx: Pick<ExtensionContext, "abort">): void;
+    /** Envelope-carried pi RpcCommand router. */
+    routeRpcCommandFrom(sender: PlainPeerChannel, env: EnvelopeMessage): void;
+    /** un-bien plane (session_sync / session_launch) router. */
+    routeUnBienPlaneFrom(sender: PlainPeerChannel, env: EnvelopeMessage): void;
+    /** Always-fresh ctx (session_start ctx preferred over captured ones). */
+    liveCtx(): {
+        ui?: unknown;
+    } | null;
+    /** Fallback ctx when no live ctx exists (notify/abort no-ops). */
+    readonly noopCtx: {
+        ui: {
+            notify(): void;
+        };
+        abort(): void;
+    };
+    /** Rename this agent (mesh + relay room) — control `rename:<name>`. */
+    renameAgent(newName: string): Promise<void>;
+}
+/** 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 = "\0un-bien-ctrl:";
+/** 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
+ *  `un-bien:relay-state` custom message (see `_emitRelayState`). */
+export type RelayConnectivity = "connected" | "reconnecting" | "disconnected";
+/** Relay-lifecycle generation (module-local). index.ts bumps it on
+ *  session_shutdown and fronts it through the CommandDeps get/set pair. */
+export declare function _getRelayLifecycleGeneration(): number;
+/** @see _getRelayLifecycleGeneration */
+export declare function _setRelayLifecycleGeneration(value: number): void;
+/** Pending reconnect timer (module-local) — the test-hooks reconnect probe. */
+export declare function _getReconnectTimer(): ReturnType<typeof setTimeout> | null;
+/** Returns true when at least one owner is attached. Derived `paired` UX. */
+export declare function _anyPeerActive(deps: RelayLifecycleDeps): boolean;
+/** Broadcast for the extension_ui bridge. The bridge only ever emits
+ *  `extension_ui_request`, sent ENVELOPE-ONLY as a `{rpc}` frame (the wire
+ *  shape mirrors the SDK rpc contract 1:1). No stock fallback. */
+export declare function _uiBroadcast(deps: RelayLifecycleDeps, msg: ServerMessage): void;
+/** Broadcast for the panel bridge. The bridge only ever emits `panel_update`,
+ *  forwarded ENVELOPE-ONLY as `{evt:{channel:"panel", data}}` (the {evt} plane);
+ *  the app folds it into its panel store. No stock fallback. */
+export declare function _panelBroadcast(deps: RelayLifecycleDeps, msg: ServerMessage): void;
+/** Fan an rpc-envelope frame out to every attached peer (base64 ct via each
+ *  channel) — the single owner-fanout path for `{ rpc | evt }` messages. */
+export declare function _broadcastEnvelope(deps: RelayLifecycleDeps, env: EnvelopeMessage): void;
+/**
+ * Teardown-path variant of `_broadcastEnvelope`: awaits each channel's ws
+ * send-completion (frame handed to the socket) — bounded by `timeoutMs` so a
+ * wedged socket can never hang a shutdown. The `session_shutdown` broadcast
+ * MUST use this: its handler tears the relay down immediately after, and a
+ * fire-and-forget send only beats `close()` by incidental FIFO luck.
+ */
+export declare function _broadcastEnvelopeFlushed(deps: RelayLifecycleDeps, env: EnvelopeMessage, timeoutMs?: number): Promise<void>;
+/** Detaches a single owner's channel + removes it from the map. Used by
+ *  `_onPeerDisconnect`, `_cmdRevoke`, and the SelfRevoke callback. */
+export declare function _detachPeerChannel(deps: RelayLifecycleDeps, appPeerId: string): void;
+/**
+ * Full teardown: stop listener, detach channel, close relay → idle.
+ */
+export declare function _goIdle(deps: RelayLifecycleDeps): void;
+/**
+ * Called when the relay WS closes unexpectedly (network drop, relay restart,
+ * etc.). Does a **partial** teardown — keeps `_sessionStartedAt`, `_messageBuffer`,
+ * `_relayUrl`, `_cachedEd25519`, `_peerShort` so the session can resume on
+ * reconnect — and schedules an `_attemptReconnect`.
+ *
+ * Peer (app) reconnect after a successful relay reconnect is handled by the
+ * existing auto-listener via `peers.json` lookup, so we don't need to track
+ * the prior peer here; we just go back to `started` and wait.
+ */
+export declare function _onRelayClose(deps: RelayLifecycleDeps, closedRelay: RelayClient): void;
+/** Current relay connectivity, derived from `_state` + `_relay`. */
+export declare function _relayStatus(deps: RelayLifecycleDeps): RelayConnectivity;
+/**
+ * Emit the `un-bien:relay-state` custom message so an RPC client (Cockpit)
+ * can render a relay on/off indicator. Pure data (`display:false`) — never
+ * shown in the transcript. De-duped on the connectivity value; pass
+ * `force=true` to answer an explicit `relay:status` query regardless.
+ */
+export declare function _emitRelayState(deps: RelayLifecycleDeps, force?: boolean): void;
+/** Minimal ctx for relay start/stop driven by a control message (no command
+ *  ctx is available in the `input` hook). cwd matches the daemon's launch dir,
+ *  so the derived relay room is identical to the one `_cmdStart` first used. */
+export declare function _controlCtx(): Pick<ExtensionContext, "ui" | "cwd">;
+/**
+ * `ui.notify` for headless contexts (daemon auto-init + control channel). There
+ * is no TUI, and the RPC client (Cockpit) already gets everything it needs via
+ * structured events (`un-bien:relay-state`, `un-bien:name-assigned`,
+ * room_meta) — so routine INFO chatter would just pollute the client's captured
+ * stderr. We drop info and forward only warnings/errors (kept for the
+ * supervisor's journal / genuine failures). The interactive Pi keeps its normal
+ * footer/notify path — this only affects headless ctxs.
+ */
+export declare function _headlessUi(): {
+    notify: (msg: string, type?: "info" | "warning" | "error") => void;
+};
+/**
+ * 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(deps: RelayLifecycleDeps, 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(deps: RelayLifecycleDeps, appPeerId?: string): void;
+export declare function _installAutoListener(deps: RelayLifecycleDeps, relay: RelayClient): () => void;