feat(web): add terminal channel attach + replay client primitives

- Add TerminalChannelReplayEvent type with runtime_id, data, cols, rows
- Add buildTerminalChannelAttach and sendTerminalChannelAttach helpers
- Add subscribeTerminalChannelReplay for channel_replay event
- Add WsTerminalChannelAttachEnvelope to ws protocol for type safety

Author: pallyoung

apps/web/src/services/terminal-channel/client.ts

@@ -1,4 +1,4 @@
-import type { TerminalChannelOutputEvent } from "../../types/app.ts";
+import type { TerminalChannelOutputEvent, TerminalChannelReplayEvent } from "../../types/app.ts";
 
 const TERMINAL_CHANNEL_RESPONSE_PATTERNS = [
   /^\u001b\[I$/,
@@ -148,3 +148,37 @@ export const subscribeTerminalChannelOutput = (
   });
   return () => unsubscribe();
 };
+
+export const buildTerminalChannelAttach = (
+  workspaceId: string,
+  fencingToken: number,
+  runtimeId: string,
+) => ({
+  type: "terminal_channel_attach" as const,
+  workspace_id: workspaceId,
+  fencing_token: fencingToken,
+  runtime_id: runtimeId,
+});
+
+export const sendTerminalChannelAttach = (
+  workspaceId: string,
+  fencingToken: number,
+  runtimeId: string,
+) => {
+  void import("../../ws/client.ts").then(({ sendWsMessage }) => {
+    sendWsMessage(buildTerminalChannelAttach(workspaceId, fencingToken, runtimeId));
+  });
+};
+
+export const subscribeTerminalChannelReplay = (
+  handler: (payload: TerminalChannelReplayEvent) => void,
+) => {
+  let unsubscribe = () => {};
+  void import("../../ws/client.ts").then(({ subscribeWsEvent }) => {
+    unsubscribe = subscribeWsEvent<TerminalChannelReplayEvent>(
+      "terminal://channel_replay",
+      handler,
+    );
+  });
+  return () => unsubscribe();
+};

apps/web/src/types/app.ts

@@ -187,6 +187,13 @@ export type TerminalChannelOutputEvent = {
   data: string;
 };
 
+export interface TerminalChannelReplayEvent {
+  runtime_id: string;
+  data: string;
+  cols: number;
+  rows: number;
+}
+
 export type SessionRuntimeStartResult = {
   terminal_id: number;
   started: boolean;

apps/web/src/ws/protocol.ts

@@ -51,6 +51,13 @@ export type WsTerminalChannelInputEnvelope = {
   input: string;
 };
 
+export type WsTerminalChannelAttachEnvelope = {
+  type: "terminal_channel_attach";
+  workspace_id: string;
+  fencing_token: number;
+  runtime_id: string;
+};
+
 export type WsPingEnvelope = {
   type: "ping";
   ts: number;
@@ -69,7 +76,8 @@ export type WsClientEnvelope =
   | WsTerminalWriteEnvelope
   | WsTerminalResizeEnvelope
   | WsWorkspaceControllerHeartbeatEnvelope
-  | WsTerminalChannelInputEnvelope;
+  | WsTerminalChannelInputEnvelope
+  | WsTerminalChannelAttachEnvelope;
 
 export const parseWsEnvelope = (message: string): WsEnvelope | null => {
   try {