Add per-task terminals over WebSocket with an xterm.js Terminal tab

api/openapi.yaml

@@ -485,6 +485,26 @@ paths:
         "404": { $ref: "#/components/responses/Error" }
         "409": { $ref: "#/components/responses/Error" }
 
+  /api/tasks/{taskId}/terminal:
+    parameters:
+      - { name: taskId, in: path, required: true, schema: { type: string } }
+    get:
+      operationId: getTaskTerminal
+      description: >
+        A WebSocket attached to the task's terminal, a login shell in its worktree, started at cols by rows if none is
+        running. The server first sends what the terminal has recently printed, then its output as it comes, all as
+        binary messages. The client sends input as binary messages and resizes as text messages holding a
+        TerminalSize. When the shell exits the server closes with code 4000 and the exit status as the reason.
+      parameters:
+        - { name: cols, in: query, required: true, schema: { type: integer, minimum: 1 } }
+        - { name: rows, in: query, required: true, schema: { type: integer, minimum: 1 } }
+      responses:
+        "101":
+          description: Switched to the WebSocket protocol.
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+
   /api/tasks/{taskId}/snapshots:
     parameters:
       - { name: taskId, in: path, required: true, schema: { type: string } }
@@ -1156,8 +1176,15 @@ components:
 
     TaskTab:
       type: string
-      enum: [transcript, changes, files, inbox, project]
-      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabInbox, TabProject]
+      enum: [transcript, changes, files, terminal, inbox, project]
+      x-enum-varnames: [TabTranscript, TabChanges, TabFiles, TabTerminal, TabInbox, TabProject]
+
+    TerminalSize:
+      type: object
+      required: [cols, rows]
+      properties:
+        cols: { type: integer, minimum: 1 }
+        rows: { type: integer, minimum: 1 }
 
     Status:
       type: object