@opengeni/sdk 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,6 +36,7 @@
   },
   "devDependencies": {
     "@opengeni/contracts": "workspace:*",
+    "@opengeni/deployment": "workspace:*",
     "tsup": "^8.5.0",
     "typescript": "^6.0.3",
     "zod": "^4.2.1"

package/src/client.ts

@@ -52,9 +52,46 @@ import type {
   SessionEvent,
   SessionGoal,
   SessionTurn,
+  // Stream surfacing (Phase 5): capability negotiation + viewer lifecycle + config.
+  SessionCapabilities,
+  AttachViewerRequest,
+  AttachViewerResponse,
+  AcknowledgeStreamRequest,
+  AcknowledgeStreamResponse,
+  ViewerHeartbeatRequest,
+  ViewerHeartbeatResponse,
+  // Channel-A structured services (P4.4).
+  FsListRequest,
+  FsListResponse,
+  FsReadRequest,
+  FsReadResponse,
+  FsWriteRequest,
+  FsWriteResponse,
+  FsDeleteRequest,
+  FsDeleteResponse,
+  FsMoveRequest,
+  FsMoveResponse,
+  FsMkdirRequest,
+  FsMkdirResponse,
+  GitStatusRequest,
+  GitStatusResponse,
+  GitDiffRequest,
+  GitDiffResponse,
+  GitLogRequest,
+  GitLogResponse,
+  GitShowRequest,
+  GitShowResponse,
+  TerminalExecRequest,
+  TerminalExecResponse,
+  PtyOpenRequest,
+  PtyOpenResponse,
+  PtyWriteRequest,
+  PtyResizeRequest,
+  PtyCloseRequest,
   ToolRef,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
+  UpdateSessionRequest,
   UpdateSessionTurnRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,
@@ -129,6 +166,10 @@ export class OpenGeniClient {
     return await this.requestJson<Session>("GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}`);
   }
 
+  async updateSession(workspaceId: string, sessionId: string, request: UpdateSessionRequest): Promise<Session> {
+    return await this.requestJson<Session>("PATCH", `/v1/workspaces/${workspaceId}/sessions/${sessionId}`, request);
+  }
+
   async listSessions(workspaceId: string, options: { limit?: number } = {}): Promise<Session[]> {
     return await this.requestJson<Session[]>("GET", `/v1/workspaces/${workspaceId}/sessions`, undefined, {
       ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
@@ -403,6 +444,144 @@ export class OpenGeniClient {
     return await this.requestJson<CompactSessionContextResult>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/compact`, {});
   }
 
+  // --- Channel-A structured services (P4.4) ------------------------------------
+  // FileSystem (Pierre tree), Git (Pierre diff), Terminal (exec + PTY). Each is a
+  // synchronous API-direct point query; the fs.changed/git.changed/terminal.pty.*
+  // notifications + the PTY output stream arrive on the existing event SSE.
+
+  /** FileSystem: list a directory tree (feeds the Pierre file tree). */
+  async fsList(workspaceId: string, sessionId: string, request: FsListRequest = {}): Promise<FsListResponse> {
+    return await this.requestJson<FsListResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`, request);
+  }
+
+  /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
+  async fsRead(workspaceId: string, sessionId: string, request: FsReadRequest): Promise<FsReadResponse> {
+    return await this.requestJson<FsReadResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`, request);
+  }
+
+  /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
+  async fsWrite(workspaceId: string, sessionId: string, request: FsWriteRequest): Promise<FsWriteResponse> {
+    return await this.requestJson<FsWriteResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/write`, request);
+  }
+
+  /** FileSystem: delete a path (emits fs.changed). */
+  async fsDelete(workspaceId: string, sessionId: string, request: FsDeleteRequest): Promise<FsDeleteResponse> {
+    return await this.requestJson<FsDeleteResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/delete`, request);
+  }
+
+  /** FileSystem: move/rename a path (emits fs.changed; 409 if destination exists and overwrite is false). */
+  async fsMove(workspaceId: string, sessionId: string, request: FsMoveRequest): Promise<FsMoveResponse> {
+    return await this.requestJson<FsMoveResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/move`, request);
+  }
+
+  /** FileSystem: create a directory (emits fs.changed; recursive defaults to true). */
+  async fsMkdir(workspaceId: string, sessionId: string, request: FsMkdirRequest): Promise<FsMkdirResponse> {
+    return await this.requestJson<FsMkdirResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/mkdir`, request);
+  }
+
+  /** Git: working-tree/index status (the Pierre file-status feed). */
+  async gitStatus(workspaceId: string, sessionId: string, request: GitStatusRequest = {}): Promise<GitStatusResponse> {
+    return await this.requestJson<GitStatusResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`, request);
+  }
+
+  /** Git: structured diff hunks (the Pierre diff feed). */
+  async gitDiff(workspaceId: string, sessionId: string, request: GitDiffRequest = {}): Promise<GitDiffResponse> {
+    return await this.requestJson<GitDiffResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`, request);
+  }
+
+  /** Git: commit log. */
+  async gitLog(workspaceId: string, sessionId: string, request: GitLogRequest = {}): Promise<GitLogResponse> {
+    return await this.requestJson<GitLogResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/log`, request);
+  }
+
+  /** Git: show a commit (diff vs first parent) or fetch a raw blob at a ref. */
+  async gitShow(workspaceId: string, sessionId: string, request: GitShowRequest): Promise<GitShowResponse> {
+    return await this.requestJson<GitShowResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/show`, request);
+  }
+
+  /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
+  async terminalExec(workspaceId: string, sessionId: string, request: TerminalExecRequest): Promise<TerminalExecResponse> {
+    return await this.requestJson<TerminalExecResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/exec`, request);
+  }
+
+  /** Terminal: open an interactive PTY. Output streams on the event SSE as
+   *  terminal.pty.output.delta; drive it with terminalPtyWrite. */
+  async terminalPtyOpen(workspaceId: string, sessionId: string, request: PtyOpenRequest = {}): Promise<PtyOpenResponse> {
+    return await this.requestJson<PtyOpenResponse>("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty`, request);
+  }
+
+  /** Terminal: send stdin to an open PTY (output rides A1). */
+  async terminalPtyWrite(workspaceId: string, sessionId: string, request: PtyWriteRequest): Promise<void> {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/write`, request);
+  }
+
+  /** Terminal: resize an open PTY. */
+  async terminalPtyResize(workspaceId: string, sessionId: string, request: PtyResizeRequest): Promise<void> {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/resize`, request);
+  }
+
+  /** Terminal: close an open PTY (idempotent). */
+  async terminalPtyClose(workspaceId: string, sessionId: string, request: PtyCloseRequest): Promise<void> {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/close`, request);
+  }
+
+  // --- Stream surfacing: capability negotiation + viewer lifecycle (Phase 5) ---
+  // The capability doc is the single source of UI truth (degradation is always a
+  // value, never a crash). The desktop pixel plane (Channel B) is gated behind an
+  // un-redacted-acknowledgment + a viewer holder; the structured terminal/files/
+  // git surfaces (Channel A) ride the methods above and the event SSE.
+
+  /** Read the negotiated capability doc for a session WITHOUT acquiring a viewer
+   *  holder (no warm, no spawn). Drives capability-gated rendering: which
+   *  surfaces mount, the per-surface unavailability reasons, and the lease
+   *  liveness the client polls on while `cold`/`warming`. The desktop URL/token
+   *  are minted in-process only when the box is warm AND the principal has
+   *  acknowledged the un-redacted plane. */
+  async getStreamCapabilities(workspaceId: string, sessionId: string): Promise<SessionCapabilities> {
+    return await this.requestJson<SessionCapabilities>(
+      "GET", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`);
+  }
+
+  /** Record the calling principal's acknowledgment of the un-redacted desktop
+   *  pixel plane (and, when the box is shared, the shared-exposure disclosure).
+   *  The desktop viewer-attach path returns 409 until this is recorded. */
+  async acknowledgeStream(
+    workspaceId: string, sessionId: string, request: AcknowledgeStreamRequest = {},
+  ): Promise<AcknowledgeStreamResponse> {
+    return await this.requestJson<AcknowledgeStreamResponse>(
+      "POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities/acknowledge`, request);
+  }
+
+  /** Attach a viewer holder (refcounted liveness — keeps the box warm while
+   *  watched/used), spinning the box up in-process when cold, and mint the scoped
+   *  direct-to-provider URLs for the requested plane(s). `request.desktop:true`
+   *  opts into the un-redacted pixel plane and mints the noVNC URL — that plane
+   *  alone throws `OpenGeniApiError(409)` when the un-redacted/shared
+   *  acknowledgment is missing (the consent gate). A terminal-only attach
+   *  (`desktop` omitted/false) warms the box + mints the pty-ws terminal cell with
+   *  NO consent gate. An omitted `viewerId` mints a fresh one. */
+  async attachViewer(
+    workspaceId: string, sessionId: string, request: AttachViewerRequest = {},
+  ): Promise<AttachViewerResponse> {
+    return await this.requestJson<AttachViewerResponse>(
+      "POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers`, request);
+  }
+
+  /** Heartbeat a viewer holder (Channel-A app-level liveness). A closed laptop
+   *  stops sending these → the reaper drops the holder within ~90s. Echoes
+   *  `leaseEpoch` so a superseded epoch is rejected (`alive:false` → re-attach). */
+  async heartbeatViewer(
+    workspaceId: string, sessionId: string, viewerId: string, request: ViewerHeartbeatRequest,
+  ): Promise<ViewerHeartbeatResponse> {
+    return await this.requestJson<ViewerHeartbeatResponse>(
+      "POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}/heartbeat`, request);
+  }
+
+  /** Detach a viewer (delete this holder; idempotent delete-my-row). */
+  async detachViewer(workspaceId: string, sessionId: string, viewerId: string): Promise<void> {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}`);
+  }
+
   // --- Access + workspaces -----------------------------------------------------
 
   /**
@@ -670,6 +849,17 @@ export class OpenGeniClient {
     );
   }
 
+  /**
+   * Delete a document from a base. Removes the document row and its indexed
+   * chunks while leaving the uploaded file asset available for other uses.
+   */
+  async deleteDocument(workspaceId: string, baseId: string, documentId: string): Promise<void> {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}`,
+    );
+  }
+
   async searchDocuments(
     workspaceId: string,
     baseId: string,

package/src/desktop.ts

@@ -0,0 +1,152 @@
+// Zero-dependency desktop (noVNC) transport contract.
+//
+// The actual `@novnc/novnc` RFB import is a browser-only DOM dependency and
+// lives in `@opengeni/react` (lazily imported, SSR-safe). The framework-agnostic
+// SDK ships only the transport CONTRACT: a URL assembler, the minimal RFB
+// surface the component drives, the connection state machine, and the
+// rotation/fence reducers — all pure and unit-testable, with no DOM and no deps.
+//
+// Channel A (terminal-as-events, files, git) needs NO new transport here: those
+// are event projections + the synchronous fs/git/terminal point queries on
+// `OpenGeniClient`. Only the desktop pixel plane (Channel B, direct-to-provider)
+// needs this.
+
+import type { DesktopStreamCapability, StreamUrlRotatedPayload } from "./types";
+
+/**
+ * Translate the negotiated desktop capability into the WebSocket URL the noVNC
+ * RFB client connects to. The scoped provider token is ALREADY embedded in the
+ * minted `url` (Modal tunnel host, Blaxel `bl_preview_token`, Daytona signed
+ * preview) by `session.resolveExposedPort(6080)` — we do NOT append `cap.token`
+ * as a query param (that double-auth was an adversarial-review bug: the box runs
+ * `-nopw` in v1, so the RFB password is meaningless and the real auth is the
+ * tunnel token in the host). We only normalize the scheme to `ws`/`wss` and, when
+ * the minted URL points at a `vnc.html` viewer page, rewrite it to the
+ * websockify socket path noVNC actually dials.
+ */
+export function desktopSocketUrl(cap: Pick<DesktopStreamCapability, "url">): string {
+  if (!cap.url) {
+    throw new Error("desktop capability has no url (transport is null)");
+  }
+  const u = new URL(cap.url);
+  // https → wss, http → ws (noVNC dials a WebSocket, not the HTTP viewer page).
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  // A minted `…/vnc.html` (or `…/vnc_lite.html`) viewer page → the websockify
+  // socket the page itself would open (`…/websockify`). A bare host/path with no
+  // viewer page is already the socket path; leave it untouched.
+  if (/\/vnc(_lite)?\.html$/.test(u.pathname)) {
+    u.pathname = u.pathname.replace(/\/vnc(_lite)?\.html$/, "/websockify");
+    u.search = "";
+    u.hash = "";
+  }
+  return u.toString();
+}
+
+/**
+ * The minimal RFB surface the React component drives. Lets tests (and 3rd
+ * parties swapping noVNC for a WebRTC client in v3) provide a fake without the
+ * DOM. Matches `@novnc/novnc`'s RFB constructor + lifecycle.
+ */
+export interface DesktopRfbLike {
+  viewOnly: boolean;
+  scaleViewport: boolean;
+  /**
+   * 1:1 viewport clipping. We always drive this FALSE: with clipping on, noVNC
+   * paints the framebuffer pixel-for-pixel and scrolls/crops to the container
+   * (the "zoomed in" look). FALSE lets `scaleViewport` shrink the 1280x800 frame
+   * to fit the panel (aspect-preserved). Declared so the hook can pin it instead
+   * of relying on noVNC's default — `scaleViewport=true` forces clip off
+   * internally, but a stale/partial state on reconnect could leave it on.
+   */
+  clipViewport: boolean;
+  addEventListener(
+    type: "connect" | "disconnect" | "securityfailure",
+    cb: (e?: unknown) => void,
+  ): void;
+  removeEventListener?: (
+    type: "connect" | "disconnect" | "securityfailure",
+    cb: (e?: unknown) => void,
+  ) => void;
+  disconnect(): void;
+}
+
+export type DesktopRfbFactory = (
+  target: HTMLElement,
+  url: string,
+  opts: { credentials?: { password?: string | undefined } | undefined },
+) => DesktopRfbLike;
+
+export type DesktopConnectionState =
+  | "idle"
+  | "negotiating"
+  | "connecting"
+  | "connected"
+  | "rotating"
+  | "reconnecting"
+  | "error"
+  | "ended";
+
+export type DesktopStreamEvent =
+  | { type: "negotiated" }
+  | { type: "connected" }
+  | { type: "disconnected" }
+  | { type: "rotate" }
+  | { type: "fail" }
+  | { type: "abort" };
+
+/**
+ * Pure reducer for the desktop connection lifecycle. The component owns the RFB
+ * object + DOM; this owns the transitions so they are unit-testable. Mirrors the
+ * Channel-A stream reducer discipline.
+ */
+export function nextDesktopState(
+  current: DesktopConnectionState,
+  ev: DesktopStreamEvent,
+): DesktopConnectionState {
+  switch (ev.type) {
+    case "negotiated":
+      return "connecting";
+    case "connected":
+      return "connected";
+    case "rotate":
+      return current === "connected" ? "rotating" : current;
+    case "disconnected":
+      // A deliberate teardown (ended) stays ended; everything else reconnects.
+      return current === "ended" ? "ended" : "reconnecting";
+    case "fail":
+      return "error";
+    case "abort":
+      return "ended";
+    default:
+      return current;
+  }
+}
+
+// `DesktopStreamCapability` is the desktop cell of `SessionCapabilities`; alias
+// it for the rotation reducer below without depending on the whole doc.
+export type DesktopStreamCapabilityLike = {
+  url: string | null;
+  token: string | null;
+  expiresAt: string | null;
+};
+
+/**
+ * Apply a `stream.url.rotated` event onto a desktop capability, fencing on
+ * leaseEpoch (split-brain). A rotation minted under an epoch the client has
+ * already advanced PAST is from a superseded owner and is dropped (returns
+ * null); otherwise the fresh url/token/expiresAt are folded in.
+ */
+export function applyUrlRotation<T extends DesktopStreamCapabilityLike>(
+  cap: T,
+  payload: StreamUrlRotatedPayload,
+  knownEpoch: number,
+): T | null {
+  if (payload.leaseEpoch < knownEpoch) {
+    return null;
+  }
+  return { ...cap, url: payload.url, token: payload.token, expiresAt: payload.expiresAt };
+}

package/src/index.ts

@@ -11,6 +11,27 @@ export {
 export type { ProxySessionEventStreamOptions, SseReStreamOptions } from "./proxy";
 export { parseSseStream } from "./sse";
 export type { SseMessage } from "./sse";
+// Desktop (noVNC) transport contract — pure, zero-dep (the RFB import lives in
+// @opengeni/react). URL assembler + connection state machine + rotation fence.
+export { desktopSocketUrl, nextDesktopState, applyUrlRotation } from "./desktop";
+export type {
+  DesktopRfbLike,
+  DesktopRfbFactory,
+  DesktopConnectionState,
+  DesktopStreamEvent,
+} from "./desktop";
+// Interactive terminal (ttyd PTY-over-websocket) transport contract — pure,
+// zero-dep (the WebSocket + xterm attach live in @opengeni/react). URL assembler
+// + the ttyd wire-protocol frame codec, symmetric with the desktop above.
+export {
+  terminalSocketUrl,
+  ttydAuthFrame,
+  ttydInputFrame,
+  ttydResizeFrame,
+  TTYD_SUBPROTOCOL,
+  TtydClientCommand,
+  TtydServerCommand,
+} from "./terminal";
 export { streamSessionEvents } from "./stream";
 export type {
   SessionEventStreamTransport,
@@ -49,6 +70,7 @@ export type {
   CapabilityPackSkillFile,
   CapabilityRuntime,
   CapabilitySource,
+  CapabilityUnavailableReason,
   ClientConfig,
   ClientModel,
   CompactSessionContextResult,
@@ -101,10 +123,19 @@ export type {
   Permission,
   ProductAccessMode,
   ReasoningEffort,
+  RecordingAvailablePayload,
+  RecordingCodec,
+  RecordingContentType,
+  RecordingFailedPayload,
+  RecordingFailedReason,
+  RecordingMode,
+  RecordingStartedPayload,
   RegisterCapabilityPackRequest,
   RepositoryResourceRef,
   ResourceRef,
   SandboxBackend,
+  SandboxCapabilityName,
+  SandboxOs,
   ScheduledTask,
   ScheduledTaskAgentConfig,
   ScheduledTaskAgentConfigInput,
@@ -117,6 +148,27 @@ export type {
   ScheduledTaskStatus,
   ScheduledTaskTriggerType,
   Session,
+  SessionCapabilities,
+  // Per-surface capability cell aliases (views of SessionCapabilities).
+  FileSystemCapability,
+  TerminalCapability,
+  GitCapability,
+  DesktopStreamCapability,
+  RecordingCapability,
+  ComputerUseCapability,
+  // Stream-surfacing client surface (Phase 5).
+  ClientAuthConfig,
+  StreamUrlRotatedPayload,
+  StreamOpenedPayload,
+  StreamClosedPayload,
+  StreamRevokedPayload,
+  AttachViewerRequest,
+  AttachViewerResponse,
+  ViewerHolder,
+  AcknowledgeStreamRequest,
+  AcknowledgeStreamResponse,
+  ViewerHeartbeatRequest,
+  ViewerHeartbeatResponse,
   SessionEvent,
   SessionEventType,
   SessionGoal,
@@ -124,12 +176,59 @@ export type {
   SessionGoalStatus,
   SessionStatus,
   SessionStatusChangedPayload,
+  SessionStructuredCapabilities,
   SessionTurn,
   SessionTurnSource,
   SessionTurnStatus,
+  // Channel-A structured services (P4.4) — A1 payloads + A2 request/response.
+  SandboxCommandOutputDeltaPayload,
+  FsChangeKind,
+  FsChangedPayload,
+  GitChangedPayload,
+  TerminalPtyStartedPayload,
+  TerminalPtyOutputDeltaPayload,
+  TerminalPtyExitedPayload,
+  FsNodeType,
+  FsTreeNode,
+  FsEncoding,
+  FsListRequest,
+  FsListResponse,
+  FsReadRequest,
+  FsReadResponse,
+  FsWriteRequest,
+  FsWriteResponse,
+  FsDeleteRequest,
+  FsDeleteResponse,
+  FsMoveRequest,
+  FsMoveResponse,
+  FsMkdirRequest,
+  FsMkdirResponse,
+  GitFileStatusCode,
+  GitFileStatus,
+  GitStatusRequest,
+  GitStatusResponse,
+  GitDiffLineType,
+  GitDiffLine,
+  GitDiffHunk,
+  GitFileDiff,
+  GitDiffRequest,
+  GitDiffResponse,
+  GitLogRequest,
+  GitCommit,
+  GitLogResponse,
+  GitShowRequest,
+  GitShowResponse,
+  TerminalExecRequest,
+  TerminalExecResponse,
+  PtyOpenRequest,
+  PtyOpenResponse,
+  PtyWriteRequest,
+  PtyResizeRequest,
+  PtyCloseRequest,
   ToolRef,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
+  UpdateSessionRequest,
   UpdateSessionTurnRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,

package/src/terminal.ts

@@ -0,0 +1,91 @@
+// Zero-dependency interactive-terminal (ttyd PTY-over-websocket) transport
+// contract. Symmetric with `desktop.ts`: the SDK ships only the pure transport
+// CONTRACT (a URL assembler + the ttyd wire-protocol frame codec), with no DOM
+// and no deps. The actual WebSocket open + xterm attach lives in `@opengeni/react`
+// (`use-terminal-stream.ts`).
+//
+// The interactive terminal is a REAL PTY streamed over the SAME Modal raw-TLS
+// tunnel as the desktop noVNC, with the SAME scoped stream-token mechanism. The
+// box bakes `ttyd` on `TERMINAL_STREAM_PORT` (7681); `session.resolveExposedPort`
+// mints the tunnel URL. The Terminal capability cell carries transport "pty-ws" +
+// that url + the scoped token when the box is warm and a viewer is attached.
+
+import type { TerminalCapability } from "./types";
+
+/**
+ * Translate the negotiated `pty-ws` Terminal capability into the WebSocket URL
+ * the ttyd client dials. The scoped provider token is ALREADY embedded in the
+ * minted `url` (the Modal tunnel host) by `session.resolveExposedPort(7681)` —
+ * we do NOT append `cap.token` (identical posture to the desktop: the gate is the
+ * unguessable short-TTL tunnel URL + the server-recorded scoped stream token; ttyd
+ * runs `--writable` with no `-c` credential in v1). We only normalize the scheme
+ * to `ws`/`wss`; a bare host is already the ttyd websocket endpoint.
+ */
+export function terminalSocketUrl(cap: Pick<TerminalCapability, "url">): string {
+  if (!cap.url) {
+    throw new Error("terminal capability has no url (transport is not pty-ws)");
+  }
+  const u = new URL(cap.url);
+  // https → wss, http → ws (ttyd is dialed as a WebSocket, not an HTTP page).
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  return u.toString();
+}
+
+// ── ttyd wire protocol ───────────────────────────────────────────────────────
+// ttyd frames are a single ASCII command char + payload. These mirror ttyd's
+// `protocol.h` Command enum. Client→server and server→client share the byte 0/1/2
+// values but mean different things per direction (see below).
+
+/** ttyd subprotocol — REQUIRED on the WebSocket handshake or ttyd refuses it. */
+export const TTYD_SUBPROTOCOL = "tty";
+
+/** Client→server command bytes (the first char of each outbound text frame). */
+export const TtydClientCommand = {
+  /** stdin: "0" + raw input bytes. */
+  INPUT: "0",
+  /** window resize: "1" + JSON.stringify({ columns, rows }). */
+  RESIZE: "1",
+  /** flow-control pause (back-pressure): "2". */
+  PAUSE: "2",
+  /** flow-control resume: "3". */
+  RESUME: "3",
+} as const;
+
+/** Server→client command bytes (the first char of each inbound frame). */
+export const TtydServerCommand = {
+  /** stdout/stderr: "0" + raw output bytes (write the rest into xterm). */
+  OUTPUT: "0",
+  /** set the window title: "1" + title string. */
+  SET_WINDOW_TITLE: "1",
+  /** ttyd client preferences JSON: "2" + json (ignored by us). */
+  SET_PREFERENCES: "2",
+} as const;
+
+/**
+ * The ttyd handshake's first frame: an auth message. ttyd expects
+ * `JSON.stringify({ AuthToken })` as the FIRST text frame on the socket. We send
+ * an empty token — our gate is the tunnel URL + scoped stream token, NOT a ttyd
+ * `-c` basic-auth credential (which the box does not set in v1). Optional ttyd
+ * `columns`/`rows` can ride this frame to seed the PTY size before the first
+ * resize. Pure (string-building only) so it stays unit-testable in the SDK.
+ */
+export function ttydAuthFrame(opts?: { columns?: number; rows?: number }): string {
+  const frame: { AuthToken: string; columns?: number; rows?: number } = { AuthToken: "" };
+  if (opts?.columns && opts.columns > 0) frame.columns = opts.columns;
+  if (opts?.rows && opts.rows > 0) frame.rows = opts.rows;
+  return JSON.stringify(frame);
+}
+
+/** Build a client→server INPUT (stdin) frame: "0" + data. */
+export function ttydInputFrame(data: string): string {
+  return TtydClientCommand.INPUT + data;
+}
+
+/** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
+export function ttydResizeFrame(columns: number, rows: number): string {
+  return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
+}