@opengeni/react 0.52.1 → 1.0.1

package/src/hooks/use-terminal-stream.ts

@@ -7,7 +7,16 @@ import {
   ttydResizeFrame,
   TtydServerCommand,
 } from "@opengeni/sdk";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  decodeStreamFrame,
+  decodeStreamOpenAck,
+  encodeStreamFrame,
+  encodeStreamOpen,
+  type RelayChannel,
+  STREAM_KIND_PTY,
+  STREAM_ROLE_CLIENT,
+} from "../lib/relay-wire";
 
 /** The ttyd connection lifecycle as surfaced to the component. */
 export type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
@@ -22,6 +31,9 @@ export type UseTerminalStreamOptions = {
   onOutput?: ((data: string) => void) | undefined;
   /** Called when ttyd sends a SET_WINDOW_TITLE frame. */
   onTitle?: ((title: string) => void) | undefined;
+  /** Requests a fresh negotiated terminal grant after an unexpected transport
+   * failure. Intentional disconnects and effect cleanup never call it. */
+  onReconnectNeeded?: (() => void) | undefined;
   /** Initial PTY size to seed the ttyd auth frame + first resize. */
   initialCols?: number | undefined;
   initialRows?: number | undefined;
@@ -47,6 +59,58 @@ export type UseTerminalStreamResult = {
 // input rather than ever executing a truncated shell command.
 export const MAX_PENDING_TERMINAL_INPUT_CODE_UNITS = 64 * 1024;
 const TERMINAL_CONNECT_EXPIRY_SKEW_MS = 5_000;
+const TERMINAL_RECONNECT_INITIAL_MS = 100;
+const TERMINAL_RECONNECT_MAX_MS = 3_000;
+const RELAY_TAG_OPEN = 1;
+const RELAY_TAG_OPEN_ACK = 2;
+const RELAY_TAG_FRAME = 3;
+
+function relayDatagram(tag: number, body: Uint8Array): ArrayBuffer {
+  const bytes = new Uint8Array(body.length + 1);
+  bytes[0] = tag;
+  bytes.set(body, 1);
+  return bytes.buffer;
+}
+
+function relayChannelFromUrl(url: string): RelayChannel {
+  const endpoint = new URL(url);
+  const channel: RelayChannel = {
+    channelId: endpoint.searchParams.get("channel") ?? "",
+    workspaceId: endpoint.searchParams.get("ws") ?? "",
+    agentId: endpoint.searchParams.get("agent") ?? "",
+    kind: STREAM_KIND_PTY,
+    port: Number(endpoint.searchParams.get("port") ?? "0"),
+  };
+  if (
+    !channel.channelId ||
+    !channel.workspaceId ||
+    !channel.agentId ||
+    !Number.isSafeInteger(channel.port) ||
+    channel.port <= 0
+  ) {
+    throw new Error("terminal relay endpoint is incomplete");
+  }
+  return channel;
+}
+
+function sendRelayInput(
+  socket: WebSocket,
+  channel: RelayChannel,
+  sequence: bigint,
+  data: string,
+): void {
+  socket.send(
+    relayDatagram(
+      RELAY_TAG_FRAME,
+      encodeStreamFrame({
+        channelId: channel.channelId,
+        seq: sequence.toString(),
+        data: new TextEncoder().encode(data),
+        producedAtMs: String(Date.now()),
+      }),
+    ),
+  );
+}
 
 /** A bearer must remain valid long enough to finish a new websocket handshake.
  * Existing open sockets are unaffected: this is evaluated only when the
@@ -55,7 +119,12 @@ export function terminalStreamCredentialUsable(
   capability: Pick<TerminalCapability, "transport" | "url" | "expiresAt"> | null | undefined,
   nowMs = Date.now(),
 ): boolean {
-  if (capability?.transport !== "pty-ws" || !capability.url) return false;
+  if (
+    (capability?.transport !== "pty-ws" && capability?.transport !== "relay-pty") ||
+    !capability.url
+  ) {
+    return false;
+  }
   if (!capability.expiresAt) return true;
   const expiresAt = Date.parse(capability.expiresAt);
   return Number.isFinite(expiresAt) && expiresAt > nowMs + TERMINAL_CONNECT_EXPIRY_SKEW_MS;
@@ -100,12 +169,21 @@ function closeSocket(socket: WebSocket | null): void {
  * SSR-safe: the socket open lives in `useEffect`, so a server render is a no-op.
  */
 export function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult {
-  const { capability, onOutput, onTitle, initialCols, initialRows } = options;
+  const { capability, onOutput, onTitle, onReconnectNeeded, initialCols, initialRows } = options;
   const [status, setStatus] = useState<TerminalStreamStatus>("closed");
+  const [reconnectGeneration, setReconnectGeneration] = useState(0);
   const wsRef = useRef<WebSocket | null>(null);
   const pendingInputRef = useRef("");
   const socketFailedRef = useRef(false);
   const socketAuthenticatedRef = useRef(false);
+  const relayChannelRef = useRef<RelayChannel | null>(null);
+  const relayIdentityRef = useRef<string | null>(null);
+  const relayInputSequenceRef = useRef(0n);
+  const relayOutputSequenceRef = useRef(0n);
+  const reconnectAttemptRef = useRef(0);
+  const credentialIdentityRef = useRef<string | null>(null);
+  const refreshRequestedRef = useRef(false);
+  const intentionalCloseRef = useRef<WeakSet<WebSocket>>(new WeakSet());
   // Latest size, so a resize() before the socket opens is replayed on open, and a
   // reconnect seeds the right geometry.
   const sizeRef = useRef<{ cols: number; rows: number }>({
@@ -116,26 +194,43 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
   // render (the parent passes fresh closures each time).
   const onOutputRef = useRef(onOutput);
   const onTitleRef = useRef(onTitle);
+  const onReconnectNeededRef = useRef(onReconnectNeeded);
   onOutputRef.current = onOutput;
   onTitleRef.current = onTitle;
+  onReconnectNeededRef.current = onReconnectNeeded;
 
   const transport = capability?.transport ?? null;
   const url = capability?.url ?? null;
   const token = capability?.token ?? null;
   const expiresAt = capability?.expiresAt ?? null;
+  const transportRef = useRef(transport);
+  transportRef.current = transport;
 
   useEffect(() => {
     // SSR / no WebSocket / not a live pty-ws cell: stay closed; the caller falls
     // back to the Channel-A read-only firehose.
     if (typeof window === "undefined" || typeof WebSocket === "undefined") return;
-    if (transport !== "pty-ws") {
+    const relay = transport === "relay-pty";
+    if (transport !== "pty-ws" && !relay) {
       // A transport downgrade is a real semantic boundary. Do not replay input
       // captured for a PTY if this surface later changes back from firehose mode.
       pendingInputRef.current = "";
       socketAuthenticatedRef.current = false;
+      relayIdentityRef.current = null;
+      relayInputSequenceRef.current = 0n;
+      relayOutputSequenceRef.current = 0n;
+      reconnectAttemptRef.current = 0;
+      credentialIdentityRef.current = null;
+      refreshRequestedRef.current = false;
       setStatus("closed");
       return;
     }
+    const credentialIdentity = `${transport}\u0000${url ?? ""}\u0000${token ?? ""}\u0000${expiresAt ?? ""}`;
+    if (credentialIdentityRef.current !== credentialIdentity) {
+      credentialIdentityRef.current = credentialIdentity;
+      reconnectAttemptRef.current = 0;
+      refreshRequestedRef.current = false;
+    }
     // A changed/cleared credential is a new connection attempt boundary. It may
     // receive input while its exact grant is pending even if the prior socket
     // failed; the unchanged failed identity remains fenced because this effect
@@ -150,18 +245,42 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     }
     if (!terminalStreamCredentialUsable({ transport, url, expiresAt })) {
       // A descriptor from an older rolling server may still carry a bearer that
-      // aged out before this surface mounted. Wait for the exact fresh grant.
+      // aged out before this surface mounted. Ask once for the exact fresh grant.
       setStatus("closed");
+      if (!refreshRequestedRef.current) {
+        refreshRequestedRef.current = true;
+        onReconnectNeededRef.current?.();
+      }
       return;
     }
 
     let disposed = false;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
     let socket: WebSocket;
+    let relayChannel: RelayChannel | null = null;
+    const relayOutputDecoder = new TextDecoder();
     setStatus("connecting");
     try {
-      // The ttyd "tty" subprotocol is REQUIRED — ttyd rejects a handshake without
-      // it. The scoped token is already in the tunnel `url`.
-      socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
+      if (relay) {
+        relayChannel = relayChannelFromUrl(url);
+        const relayIdentity = [
+          relayChannel.workspaceId,
+          relayChannel.agentId,
+          relayChannel.port,
+          relayChannel.channelId,
+        ].join("\u0000");
+        if (relayIdentityRef.current !== relayIdentity) {
+          relayIdentityRef.current = relayIdentity;
+          relayInputSequenceRef.current = 0n;
+          relayOutputSequenceRef.current = 0n;
+        }
+        relayChannelRef.current = relayChannel;
+        socket = new WebSocket(url);
+      } else {
+        // The ttyd "tty" subprotocol is REQUIRED — ttyd rejects a handshake without
+        // it. The scoped token is already in the tunnel `url`.
+        socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
+      }
     } catch {
       socketFailedRef.current = true;
       setStatus("error");
@@ -170,8 +289,54 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     socket.binaryType = "arraybuffer";
     wsRef.current = socket;
 
+    const requestFreshGrant = () => {
+      if (disposed || refreshRequestedRef.current || intentionalCloseRef.current.has(socket))
+        return;
+      refreshRequestedRef.current = true;
+      onReconnectNeededRef.current?.();
+    };
+
+    const scheduleTransportReconnect = () => {
+      if (disposed || reconnectTimer !== null || intentionalCloseRef.current.has(socket)) return;
+      if (refreshRequestedRef.current) return;
+      if (!terminalStreamCredentialUsable({ transport, url, expiresAt })) {
+        requestFreshGrant();
+        return;
+      }
+      const attempt = reconnectAttemptRef.current++;
+      const delay = Math.min(
+        TERMINAL_RECONNECT_INITIAL_MS * 2 ** Math.min(attempt, 8),
+        TERMINAL_RECONNECT_MAX_MS,
+      );
+      setStatus("connecting");
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        if (!disposed) setReconnectGeneration((generation) => generation + 1);
+      }, delay);
+    };
+
     socket.onopen = () => {
       if (disposed) return;
+      if (relay && relayChannel) {
+        try {
+          socket.send(
+            relayDatagram(
+              RELAY_TAG_OPEN,
+              encodeStreamOpen({
+                channel: relayChannel,
+                token: token ?? "",
+                role: STREAM_ROLE_CLIENT,
+                resumeFromSeq: relayOutputSequenceRef.current.toString(),
+              }),
+            ),
+          );
+        } catch {
+          socketFailedRef.current = false;
+          setStatus("connecting");
+          closeSocket(socket);
+        }
+        return;
+      }
       // ttyd's required first frame: the auth message (empty token — the gate is
       // the tunnel url + scoped stream token, not a ttyd -c credential), seeded
       // with the current PTY geometry. Then an explicit resize to be safe.
@@ -186,16 +351,62 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
         }
         socketAuthenticatedRef.current = true;
       } catch {
-        socketFailedRef.current = true;
-        setStatus("error");
+        socketFailedRef.current = false;
+        setStatus("connecting");
         closeSocket(socket);
         return;
       }
       setStatus("open");
+      reconnectAttemptRef.current = 0;
+      refreshRequestedRef.current = false;
     };
 
     socket.onmessage = (ev: MessageEvent) => {
       if (disposed) return;
+      if (relay) {
+        if (!(ev.data instanceof ArrayBuffer) || !relayChannel) return;
+        const bytes = new Uint8Array(ev.data);
+        if (bytes.length < 1) return;
+        const tag = bytes[0];
+        const body = bytes.subarray(1);
+        if (tag === RELAY_TAG_OPEN_ACK) {
+          try {
+            const ack = decodeStreamOpenAck(body);
+            if (!ack.accepted) throw new Error(ack.error?.message ?? "terminal relay rejected");
+            reconnectAttemptRef.current = 0;
+            refreshRequestedRef.current = false;
+            socketAuthenticatedRef.current = true;
+            if (pendingInputRef.current.length > 0) {
+              sendRelayInput(
+                socket,
+                relayChannel,
+                relayInputSequenceRef.current++,
+                pendingInputRef.current,
+              );
+              pendingInputRef.current = "";
+            }
+            setStatus("open");
+          } catch {
+            socketFailedRef.current = true;
+            setStatus("error");
+            requestFreshGrant();
+            closeSocket(socket);
+          }
+        } else if (tag === RELAY_TAG_FRAME && socketAuthenticatedRef.current) {
+          try {
+            const frame = decodeStreamFrame(body);
+            const sequence = BigInt(frame.seq);
+            if (sequence < relayOutputSequenceRef.current) return;
+            relayOutputSequenceRef.current = sequence + 1n;
+            if (frame.data.length > 0) {
+              onOutputRef.current?.(relayOutputDecoder.decode(frame.data, { stream: true }));
+            }
+          } catch {
+            // Ignore one malformed frame; the live PTY remains usable.
+          }
+        }
+        return;
+      }
       const { command, payload } = decodeFrame(ev.data as string | ArrayBuffer);
       switch (command) {
         case TtydServerCommand.OUTPUT:
@@ -212,20 +423,28 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
 
     socket.onerror = () => {
       if (!disposed) {
-        socketFailedRef.current = true;
-        setStatus("error");
+        // A network/relay outage is retryable with the same credential and PTY.
+        // Keep accepting bounded input while the transport comes back.
+        socketFailedRef.current = false;
+        setStatus("connecting");
+        closeSocket(socket);
       }
     };
     socket.onclose = () => {
       if (wsRef.current === socket) wsRef.current = null;
       socketAuthenticatedRef.current = false;
-      if (!disposed) setStatus(socketFailedRef.current ? "error" : "closed");
+      if (!disposed) {
+        if (socketFailedRef.current) setStatus("error");
+        else scheduleTransportReconnect();
+      }
     };
 
     return () => {
       disposed = true;
       wsRef.current = null;
       socketAuthenticatedRef.current = false;
+      relayChannelRef.current = null;
+      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
       // Drop handlers so an in-flight close/error doesn't mutate state post-unmount.
       socket.onopen = null;
       socket.onmessage = null;
@@ -235,52 +454,66 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     };
     // A url/token change (rotation) re-runs this effect → close old, open new.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [transport, url, token, expiresAt]);
+  }, [transport, url, token, expiresAt, reconnectGeneration]);
 
-  return useMemo<UseTerminalStreamResult>(() => {
-    const write = (data: string) => {
-      const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
-        try {
+  const write = useCallback((data: string) => {
+    const currentTransport = transportRef.current;
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
+      try {
+        const relayChannel = relayChannelRef.current;
+        if (currentTransport === "relay-pty" && relayChannel) {
+          sendRelayInput(ws, relayChannel, relayInputSequenceRef.current++, data);
+        } else {
           ws.send(ttydInputFrame(data));
-        } catch {
-          socketFailedRef.current = true;
-          setStatus("error");
-          closeSocket(ws);
-        }
-      } else if (transport === "pty-ws" && !socketFailedRef.current) {
-        const nextSize = pendingInputRef.current.length + data.length;
-        if (nextSize > MAX_PENDING_TERMINAL_INPUT_CODE_UNITS) {
-          pendingInputRef.current = "";
-          socketFailedRef.current = true;
-          setStatus("error");
-          closeSocket(ws);
-          return;
         }
-        pendingInputRef.current += data;
+      } catch {
+        socketFailedRef.current = false;
+        setStatus("connecting");
+        closeSocket(ws);
       }
-    };
-    const resize = (cols: number, rows: number) => {
-      if (cols <= 0 || rows <= 0) return;
-      sizeRef.current = { cols, rows };
-      const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
-        try {
-          ws.send(ttydResizeFrame(cols, rows));
-        } catch {
-          // socket raced closed — geometry is replayed on the next open.
-        }
+    } else if (
+      (currentTransport === "pty-ws" || currentTransport === "relay-pty") &&
+      !socketFailedRef.current
+    ) {
+      const nextSize = pendingInputRef.current.length + data.length;
+      if (nextSize > MAX_PENDING_TERMINAL_INPUT_CODE_UNITS) {
+        pendingInputRef.current = "";
+        socketFailedRef.current = true;
+        setStatus("error");
+        closeSocket(ws);
+        return;
       }
-    };
-    const disconnect = () => {
-      const ws = wsRef.current;
-      wsRef.current = null;
-      pendingInputRef.current = "";
-      socketFailedRef.current = false;
-      socketAuthenticatedRef.current = false;
-      setStatus("closed");
-      closeSocket(ws);
-    };
+      pendingInputRef.current += data;
+    }
+  }, []);
+  const resize = useCallback((cols: number, rows: number) => {
+    if (cols <= 0 || rows <= 0) return;
+    sizeRef.current = { cols, rows };
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
+      try {
+        // Self-hosted relay PTYs carry raw input/output frames. Resize remains
+        // an out-of-band control operation; do not send ttyd framing into them.
+        if (transportRef.current === "pty-ws") ws.send(ttydResizeFrame(cols, rows));
+      } catch {
+        // socket raced closed — geometry is replayed on the next open.
+      }
+    }
+  }, []);
+  const disconnect = useCallback(() => {
+    const ws = wsRef.current;
+    wsRef.current = null;
+    pendingInputRef.current = "";
+    socketFailedRef.current = false;
+    socketAuthenticatedRef.current = false;
+    relayChannelRef.current = null;
+    setStatus("closed");
+    if (ws) intentionalCloseRef.current.add(ws);
+    closeSocket(ws);
+  }, []);
+
+  return useMemo<UseTerminalStreamResult>(() => {
     return { connected: status === "open", status, write, resize, disconnect };
-  }, [status, transport]);
+  }, [status, write, resize, disconnect]);
 }

package/src/index.ts

@@ -175,6 +175,8 @@ export type {
   UseEnvironmentsOptions,
   UseEnvironmentsResult,
 } from "./hooks/use-environments";
+export { useChannels } from "./hooks/use-channels";
+export type { UseChannelsOptions, UseChannelsResult } from "./hooks/use-channels";
 export { useRigs, useRig, useRigVersions, useRigChanges } from "./hooks/use-rigs";
 export type {
   UseRigsOptions,
@@ -543,6 +545,12 @@ export type {
   UseCodexAccountsOptions,
   UseCodexAccountsResult,
 } from "./hooks/use-codex-accounts";
+export { useSuperGrokAccounts } from "./hooks/use-supergrok-accounts";
+export type {
+  SuperGrokAccountsClientLike,
+  UseSuperGrokAccountsOptions,
+  UseSuperGrokAccountsResult,
+} from "./hooks/use-supergrok-accounts";
 
 // Sandbox helpers
 export { gitFileDiffToPatch } from "./lib/git-patch";

package/src/interaction.ts

@@ -4,17 +4,40 @@ export type {
   EmbeddedBrowserInteractionClientLike,
   EmbeddedComputerInteractionClientLike,
   EmbeddedInteractionClientLike,
+  EmbeddedInterventionClientLike,
 } from "./client";
 export {
   useEmbeddedBrowserInteraction,
   useEmbeddedComputerInteraction,
   useEmbeddedInteraction,
+  useEmbeddedInterventions,
 } from "./session-context";
 export type {
   EmbeddedBrowserInteractionClientOverride,
   EmbeddedComputerInteractionClientOverride,
   EmbeddedInteractionClientOverride,
+  EmbeddedInterventionClientOverride,
 } from "./session-context";
+export { useNetworkRoutes } from "./hooks/use-network-routes";
+export type {
+  NetworkRoutesClient,
+  UseNetworkRoutesOptions,
+  UseNetworkRoutesResult,
+} from "./hooks/use-network-routes";
+export { useSiteAuthConnections } from "./hooks/use-site-auth-connections";
+export type {
+  SiteAuthConnectionsClient,
+  UseSiteAuthConnectionsOptions,
+  UseSiteAuthConnectionsResult,
+} from "./hooks/use-site-auth-connections";
+export { useAuthRuns } from "./hooks/use-auth-runs";
+export type { AuthRunsClient, UseAuthRunsOptions, UseAuthRunsResult } from "./hooks/use-auth-runs";
+export { useInteractionInterventions } from "./hooks/use-interaction-interventions";
+export type {
+  InteractionInterventionsClient,
+  UseInteractionInterventionsOptions,
+  UseInteractionInterventionsResult,
+} from "./hooks/use-interaction-interventions";
 export { useAttachedBrowsers } from "./hooks/use-attached-browsers";
 export type {
   AttachedBrowsersClient,
@@ -38,6 +61,13 @@ export type {
   UseBrowserSessionOptions,
   UseBrowserSessionResult,
 } from "./hooks/use-browser-session";
+export { useBrowserDownloads } from "./hooks/use-browser-downloads";
+export type {
+  BrowserDownloadsClient,
+  BrowserDownloadSaveOptions,
+  UseBrowserDownloadsOptions,
+  UseBrowserDownloadsResult,
+} from "./hooks/use-browser-downloads";
 export { useBrowserFrameStream } from "./hooks/use-browser-frame-stream";
 export type {
   BrowserFrameConnectionState,

package/src/lib/host-platform.ts

@@ -0,0 +1,10 @@
+export type InteractionHostPlatform = "mac" | "other";
+
+/** Physical client platform. Remote input adapters use this only to identify
+ * the user's primary shortcut modifier; the target platform is resolved
+ * separately. */
+export function interactionHostPlatform(): InteractionHostPlatform {
+  if (typeof navigator === "undefined") return "other";
+  const platform = navigator.platform || navigator.userAgent;
+  return /Mac|iPhone|iPad|iPod/u.test(platform) ? "mac" : "other";
+}

package/src/lib/relay-wire.ts

@@ -1,5 +1,5 @@
 // Minimal HAND-MIRROR of the relay stream wire messages the desktop frame client
-// needs (`StreamOpen` encode; `StreamOpenAck` + `StreamFrame` decode). It exists
+// needs (`StreamOpen`/`StreamClose` encode; `StreamOpenAck` + `StreamFrame` decode). It exists
 // because the publish-closure guard (scripts/publish-closure-guard.ts) forbids
 // `@opengeni/react` from depending on `@opengeni/agent-proto` — the published SDK
 // closure may only reach `@opengeni/sdk` among `@opengeni/*` packages. So, exactly
@@ -13,16 +13,21 @@
 //   StreamOpenAck: accepted=1(bool), error=2(AgentError msg), resumeFromSeq=3
 //   AgentError:    code=1, message=2, retryable=3, detail=4  (we read only message)
 //   StreamFrame:   channelId=1, seq=2, data=3(bytes), producedAtMs=4  (we read only data)
+//   StreamClose:   channelId=1, reason=2(int32), message=3
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 
 /** `StreamKind.STREAM_KIND_DESKTOP` (agent-proto enum value). */
 export const STREAM_KIND_DESKTOP = 2;
+/** `StreamKind.STREAM_KIND_PTY` (agent-proto enum value). */
+export const STREAM_KIND_PTY = 1;
 /** `StreamKind.STREAM_KIND_BROWSER` (agent-proto enum value). */
 export const STREAM_KIND_BROWSER = 3;
 /** `StreamKind.STREAM_KIND_COMPUTER` (agent-proto enum value). */
 export const STREAM_KIND_COMPUTER = 4;
 /** `StreamRole.STREAM_ROLE_CLIENT` (agent-proto enum value). */
 export const STREAM_ROLE_CLIENT = 2;
+/** `StreamCloseReason.STREAM_CLOSE_REASON_NORMAL`. */
+export const STREAM_CLOSE_REASON_NORMAL = 1;
 
 export interface RelayChannel {
   channelId: string;
@@ -58,6 +63,35 @@ export function encodeStreamOpen(message: RelayStreamOpen): Uint8Array {
   return writer.finish();
 }
 
+/** Encode an intentional viewer detach. Transport loss omits this message so
+ * reconnect/resume remains available. */
+export function encodeStreamClose(message: {
+  channelId: string;
+  reason: number;
+  message: string;
+}): Uint8Array {
+  const writer = new BinaryWriter();
+  if (message.channelId !== "") writer.uint32(10).string(message.channelId);
+  if (message.reason !== 0) writer.uint32(16).int32(message.reason);
+  if (message.message !== "") writer.uint32(26).string(message.message);
+  return writer.finish();
+}
+
+/** Encode a viewer→agent PTY input `StreamFrame`. */
+export function encodeStreamFrame(message: {
+  channelId: string;
+  seq: string;
+  data: Uint8Array;
+  producedAtMs: string;
+}): Uint8Array {
+  const writer = new BinaryWriter();
+  if (message.channelId !== "") writer.uint32(10).string(message.channelId);
+  if (message.seq !== "0") writer.uint32(16).uint64(message.seq);
+  if (message.data.length > 0) writer.uint32(26).bytes(message.data);
+  if (message.producedAtMs !== "0") writer.uint32(32).uint64(message.producedAtMs);
+  return writer.finish();
+}
+
 /** The only `AgentError` field we surface from a rejected ack. */
 function decodeAgentErrorMessage(reader: BinaryReader, length: number): { message?: string } {
   const end = reader.pos + length;
@@ -99,13 +133,18 @@ export function decodeStreamOpenAck(bytes: Uint8Array): {
   return error !== undefined ? { accepted, error } : { accepted };
 }
 
-/** Decode a `StreamFrame`, extracting only the `data` (framebuffer PNG) bytes. */
-export function decodeStreamFrame(bytes: Uint8Array): { data: Uint8Array } {
+/** Decode the sequence plus `data` from a `StreamFrame`. */
+export function decodeStreamFrame(bytes: Uint8Array): { seq: string; data: Uint8Array } {
   const reader = new BinaryReader(bytes);
   const end = reader.len;
+  let seq = "0";
   let data = new Uint8Array(0);
   while (reader.pos < end) {
     const tag = reader.uint32();
+    if (tag >>> 3 === 2 && tag === 16) {
+      seq = reader.uint64().toString();
+      continue;
+    }
     if (tag >>> 3 === 3 && tag === 26) {
       // Copy into a fresh ArrayBuffer-backed view: BinaryReader.bytes() returns
       // `Uint8Array<ArrayBufferLike>` (a view into the message buffer), which both
@@ -116,5 +155,5 @@ export function decodeStreamFrame(bytes: Uint8Array): { data: Uint8Array } {
     if ((tag & 7) === 4 || tag === 0) break;
     reader.skip(tag & 7);
   }
-  return { data };
+  return { seq, data };
 }

package/src/lib/terminal-capability.ts

@@ -5,6 +5,6 @@ import type { TerminalCapability } from "@opengeni/sdk";
  * real-PTY backend reports sse-events until the just-in-time grant warms it. */
 export function terminalCanAcquirePty(cell: TerminalCapability | null | undefined): boolean {
   if (!cell?.ptyCapable) return false;
-  if (cell.transport === "pty-ws") return true;
+  if (cell.transport === "pty-ws" || cell.transport === "relay-pty") return true;
   return cell.reason === "lease_cold" || cell.reason === "not_provisioned";
 }