shellbase 0.13.4 → 0.13.5

package/dist/agent.js

@@ -66,11 +66,28 @@ const MAX_FRAMES_IN_FLIGHT = 6;
 // 그래도 서버가 거부하면(RATE_LIMITED 등) 잠시 간격을 넉넉히 벌려서 재시도한다
 const SEND_PENALTY_MS = 500;
 const PENALTY_INTERVAL_MS = 250;
-// 이 컴퓨터의 모든 세션이 실시간 통로(WebSocket) 하나를 함께 쓴다. 카테고리 한도는 **채널 전체로**
-// 초당 100건인데, 위의 30ms 는 세션마다 따로 지키는 간격이라 세션이 넷이면 채널로는 초당 130건이
-// 나간다 — 한도를 넘는 순간부터 서버가 거부하기 시작하고, 거부된 출력이 밀리면서 화면이 멈춘다.
-// 그래서 채널 전체에도 간격을 둔다 (12ms = 초당 약 83건, 한도에 여유를 남긴 값).
-const CHANNEL_MIN_GAP_MS = 12;
+// ── 채널 페이싱 ─────────────────────────────────────────────────────────────
+// 이 컴퓨터의 모든 세션이 실시간 통로(WebSocket) 하나를 함께 쓴다. 예전에는 여기를 12ms(초당 83건)
+// 고정으로 두고 "실측해보니 서버가 40회 연속도 받아줬다"고 적어뒀는데, **그 실측은 세션이 하나일
+// 때** 한 것이었다. 세션이 셋이 되는 순간 채널이 포화돼 ack 이 안 돌아왔고(`Request timeout`),
+// 실패할 때마다 화면을 통째로 다시 보내는 바람에 프레임이 더 늘어나는 악순환이 생겼다
+// ("타자가 사라졌다 3초 뒤에 몰아서 나타난다" 의 정체 — 세션 3개째를 연 지 50초 만에 시작됐다).
+//
+// 그래서 고정값을 버리고 **실제 왕복 시간을 재서 스스로 조절**한다. 잘 나가면 조금씩 좁히고,
+// 실패하면 크게 벌린다(AIMD). 세션이 하나면 예전만큼 빠르고, 여러 개여도 스스로 안전한 값을 찾는다.
+const CHANNEL_GAP_MIN_MS = 12;
+const CHANNEL_GAP_MAX_MS = 200;
+const CHANNEL_GAP_START_MS = 12;
+// 실패했을 때 간격을 몇 배로 벌릴지 / 잘 나갈 때 얼마씩 좁힐지
+const CHANNEL_GAP_GROW = 2;
+const CHANNEL_GAP_SHRINK_MS = 1;
+// 슬롯 예약이 이만큼 넘게 밀렸으면 = 통로가 막혔다는 뜻. 이때는 프레임을 **더 부치지 않고**
+// 출력을 계속 모은다(coalescing). 터미널은 "최종 화면"만 맞으면 되므로 중간 프레임을 합쳐도
+// 잃는 게 없다 — 오히려 막힌 통로에 프레임을 밀어 넣지 않아서 훨씬 빨리 따라잡는다.
+const MAX_SLOT_LAG_MS = 250;
+// 폰이 이 세션을 보고 있다고 볼 수 있는 시간. 폰은 보고 있는 동안 10초마다 ping 을 보내므로
+// 세 번 놓칠 때까지 기다린다 (화면 잠금·터널 전환 등으로 잠깐 끊기는 것과 구분).
+const VIEWER_ACTIVE_MS = 30_000;
 // 화면 복원 전에 "지금까지 나온 출력이 보이지 않는 터미널에 다 반영됐는지" 기다리는 횟수.
 // 기다리는 동안 새 출력이 또 들어오면 한 번 더 기다린다 — 쉬지 않고 쏟아지는 세션에서 영영
 // 못 기다리는 일이 없도록 상한을 둔다.
@@ -223,13 +240,31 @@ export async function runAgent(options) {
             .map((session) => ({ dir: session.cwd, name: session.name })));
     }
     // 이 컴퓨터의 모든 세션이 실시간 통로(WebSocket) 하나를 함께 쓴다 — 채널 전체의 전송 간격은
-    // 여기서 지킨다. 세션마다 따로 간격을 지켜도 세션이 여럿이면 채널로는 한도(초당 100건)를 넘고,
-    // 넘는 순간부터 서버가 거부하기 시작해 그 출력이 밀리고 화면이 멈춘다.
+    // 여기서 지킨다. 세션마다 따로 간격을 지켜도 세션이 여럿이면 채널로는 한도를 넘고, 넘는 순간부터
+    // ack 이 안 돌아와 그 출력이 밀리고 화면이 멈춘다.
+    //
+    // 간격은 **고정하지 않는다**. 잘 나가면 조금씩 좁히고(–1ms), 실패하면 두 배로 벌린다.
+    // 고정값은 "세션 하나에서 잰 값"이라 세션이 늘어나는 순간 그대로 무너졌다 (§상수 주석 참고).
+    let channelGapMs = CHANNEL_GAP_START_MS;
+    const easeChannelGap = () => {
+        if (channelGapMs > CHANNEL_GAP_MIN_MS) {
+            channelGapMs = Math.max(CHANNEL_GAP_MIN_MS, channelGapMs - CHANNEL_GAP_SHRINK_MS);
+        }
+    };
+    const widenChannelGap = (why) => {
+        if (channelGapMs >= CHANNEL_GAP_MAX_MS)
+            return;
+        channelGapMs = Math.min(CHANNEL_GAP_MAX_MS, Math.max(1, channelGapMs) * CHANNEL_GAP_GROW);
+        console.error(`통로가 막혀서 전송 간격을 ${channelGapMs}ms 로 벌렸어요 (${why})`);
+    };
     let nextSlotAt = 0;
+    // 지금 슬롯 예약이 얼마나 미래로 밀려 있는지. 이게 크면 = 통로가 막혔다는 뜻이고,
+    // 그때 프레임을 더 부치면 상황이 나빠지기만 한다 (예전에 3초씩 밀리던 직접 원인).
+    const slotLagMs = () => Math.max(0, nextSlotAt - Date.now());
     const takeSendSlot = async () => {
         const now = Date.now();
         const at = Math.max(now, nextSlotAt);
-        nextSlotAt = at + CHANNEL_MIN_GAP_MS;
+        nextSlotAt = at + channelGapMs;
         if (at > now)
             await new Promise((resolve) => setTimeout(resolve, at - now));
     };
@@ -237,7 +272,16 @@ export async function runAgent(options) {
     // (그래서 아래에서 여러 조각을 한꺼번에 부쳐도 순서가 지켜진다).
     const sendFrame = async (frame) => {
         await takeSendSlot();
-        await channel.send(frame, { includeSelf: false });
+        try {
+            await channel.send(frame, { includeSelf: false });
+        }
+        catch (err) {
+            // 실패 = 통로가 감당 못 하고 있다는 가장 확실한 신호. 여기서 간격을 벌려두면
+            // 뒤따르는 프레임들이 자동으로 느슨해져서 스스로 회복한다.
+            widenChannelGap(err.message);
+            throw err;
+        }
+        easeChannelGap();
     };
     const send = async (frame) => {
         try {
@@ -363,13 +407,13 @@ export async function runAgent(options) {
                     if (/too large|TOO_LARGE|size|크기/i.test(message))
                         shrinkFrameBudget(message);
                     session.sendPenaltyUntil = Date.now() + SEND_PENALTY_MS;
-                    // 못 간 것을 다시 보내는 대신 **화면을 통째로 다시 보낸다**.
+                    // 못 간 것을 다시 보내는 대신 **화면을 통째로 다시 맞춘다**.
                     // 답을 기다리지 않고 잇달아 부치기 때문에, 실패를 알게 된 시점에는 그 뒤의 출력이
                     // 이미 나가 있을 수 있다 — 거기에 옛 조각을 뒤늦게 끼워 넣으면 화면이 뒤섞인다.
                     // 지금 화면이 어떻게 생겼는지는 session.screen 이 정확히 들고 있어서,
                     // 통째로 다시 보내면 빠지지도 겹치지도 않는다.
-                    if (!session.closing)
-                        void sendRestore(session);
+                    // 다만 **그 자리에서 바로 보내지는 않는다** — scheduleResync 주석 참고.
+                    scheduleResync(session, message);
                 })
                     .finally(() => {
                     session.inFlight -= parts.length;
@@ -394,6 +438,16 @@ export async function runAgent(options) {
     };
     // 폰이 "화면을 통째로 다시 달라"고 할 때 (처음 접속·재연결·크기 변경 뒤).
     const sendRestore = async (session) => {
+        // 아무도 안 보는 세션에 화면을 보내봐야 받는 사람이 없다 — 통로만 먹는다.
+        // (다시 보기 시작하면 그때 ping/connect_request 가 오고, 거기서 복원한다)
+        if (!hasViewer(session)) {
+            if (session.resyncTimer !== null) {
+                clearTimeout(session.resyncTimer);
+                session.resyncTimer = null;
+            }
+            session.outBuffer = '';
+            return;
+        }
         if (session.restoring) {
             // 보내는 중에 또 요청이 왔다 — 지금 것이 끝난 뒤 한 번만 더 보낸다.
             // 두 벌을 동시에 보내면 조각이 서로 끼어들어 폰 화면에 같은 내용이 두 번 그려진다.
@@ -490,6 +544,26 @@ export async function runAgent(options) {
                 void sendRestore(session);
         }, wait);
     };
+    // 폰이 지금 이 세션을 보고 있는가. 폰은 보고 있는 세션에만 10초마다 ping 을 보내므로,
+    // 마지막 신호가 최근이면 "보고 있다" 로 본다. 이 판단 하나가 채널 부하를 세션 수만큼 줄인다.
+    const hasViewer = (session) => Date.now() - session.viewerSeenAt < VIEWER_ACTIVE_MS;
+    // 화면을 통째로 다시 맞춰야 할 때 쓴다 — 단, **곧바로 보내지 않는다**.
+    // 예전에는 프레임 하나가 실패할 때마다 그 자리에서 화면 전체를 다시 보냈다. 통로가 막혀서
+    // 실패한 것인데 가장 큰 프레임을 더 밀어 넣는 셈이라, 실패가 실패를 부르며 눈덩이처럼 커졌다
+    // (실패 106회 · 복원까지 연쇄 실패). 이제는 잠깐 모았다가 **한 번만** 보낸다 — 그 사이 실패가
+    // 열 번 더 나도 복원은 여전히 한 번이고, 통로에는 숨 쉴 틈이 생긴다.
+    const scheduleResync = (session, why) => {
+        if (session.closing || session.resyncTimer !== null)
+            return;
+        // 통로가 밀려 있으면 그만큼 더 기다렸다 보낸다 (막힌 곳에 큰 프레임을 얹지 않는다)
+        const wait = Math.max(SEND_PENALTY_MS, slotLagMs());
+        console.error(`화면을 ${wait}ms 뒤에 한 번 다시 맞출게요 ("${session.name}" — ${why})`);
+        session.resyncTimer = setTimeout(() => {
+            session.resyncTimer = null;
+            if (!session.closing)
+                void sendRestore(session);
+        }, wait);
+    };
     const scheduleFlush = (session) => {
         if (session.pendingFlush !== null || session.flushing || session.restoring)
             return;
@@ -498,7 +572,11 @@ export async function runAgent(options) {
         if (session.inFlight >= MAX_FRAMES_IN_FLIGHT)
             return;
         const interval = Date.now() < session.sendPenaltyUntil ? PENALTY_INTERVAL_MS : MIN_SEND_INTERVAL_MS;
-        const wait = Math.max(0, interval - (Date.now() - session.lastSentAt));
+        // 통로가 막혀 슬롯 예약이 한참 밀려 있으면, 지금 부쳐봐야 그 프레임은 몇 초 뒤에나 나간다.
+        // 그럴 바엔 **부치지 말고 계속 모은다** — 밀린 만큼 기다렸다 한 덩이로 보내면 조각 수가
+        // 늘지 않아 통로가 스스로 풀리고, 폰에는 오히려 더 빨리 최신 화면이 도착한다.
+        const lag = slotLagMs();
+        const wait = lag > MAX_SLOT_LAG_MS ? lag : Math.max(0, interval - (Date.now() - session.lastSentAt));
         session.pendingFlush = setTimeout(() => void flush(session), wait);
     };
     // ── 작업 완료 알림 ──────────────────────────────────────────────────────────
@@ -623,6 +701,7 @@ export async function runAgent(options) {
             restoreAgain: false,
             restoreRetry: null,
             restoreFails: 0,
+            resyncTimer: null,
             lastSentAt: 0,
             sendPenaltyUntil: 0,
             pendingFlush: null,
@@ -638,11 +717,21 @@ export async function runAgent(options) {
         };
         session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
-            session.outBuffer += data;
-            // 화면 상태를 그대로 따라 그려둔다 (재접속 복원용)
+            // 화면 상태는 보든 안 보든 항상 따라 그려둔다 — 여기가 "지금 화면이 어떻게 생겼는지" 의
+            // 유일한 진실이고, 폰이 (다시) 들어오면 여기서 통째로 복원해 보낸다.
             session.screen.write(data);
-            scheduleFlush(session);
             trackBusy(session, data.length);
+            // 🔴 **아무도 안 보고 있으면 실시간 프레임을 아예 만들지 않는다.**
+            // 폰은 한 번에 세션 하나만 화면에 띄우는데, 예전에는 열려 있는 모든 세션이 각자 출력을
+            // 채널로 밀어 넣고 있었다. 세션이 넷이면 채널 부하가 그대로 4배가 되고, 정작 폰은 그중
+            // 셋을 받아서 버렸다 — 보이지도 않는 화면 때문에 보이는 화면이 3초씩 밀렸던 것이다.
+            // 안 보는 동안 쌓인 것은 위 screen 에 이미 다 들어 있으므로 하나도 잃지 않는다.
+            if (!hasViewer(session)) {
+                session.outBuffer = '';
+                return;
+            }
+            session.outBuffer += data;
+            scheduleFlush(session);
         });
         session.pty.onExit(() => {
             console.log(`"${session.name}" 세션의 셸이 종료돼서 세션도 닫아요.`);
@@ -679,6 +768,8 @@ export async function runAgent(options) {
             clearTimeout(session.pendingFlush);
         if (session.restoreRetry !== null)
             clearTimeout(session.restoreRetry);
+        if (session.resyncTimer !== null)
+            clearTimeout(session.resyncTimer);
         if (session.idleTimer !== null)
             clearTimeout(session.idleTimer);
         await flush(session);
@@ -757,8 +848,12 @@ export async function runAgent(options) {
     // 접두사를 붙여 UUID 로 보이지 않게 만든다. 프레임 배분은 userId 가 아니라 frame.to 로 한다.
     // timeout 은 "보낸 것에 서버가 답하기를 기다리는 시간" 이기도 하다. 기본값 30초는 터미널에는
     // 너무 길다 — 한 번 막히면 그 세션의 화면이 30초 동안 통째로 멈춘 것처럼 보이고, 그 사이 밀린
-    // 출력이 더 쌓여서 회복도 늦어진다. 10초면 넉넉하면서 회복은 세 배 빠르다.
-    await cb.realtime.connect({ userId: `agent-${crypto.randomUUID()}`, timeout: 10_000 });
+    // 출력이 더 쌓여서 회복도 늦어진다.
+    //
+    // 10초도 여전히 길었다. 답을 못 받은 조각은 MAX_FRAMES_IN_FLIGHT(6) 자리를 물고 있는데, 그게
+    // 전부 타임아웃을 기다리면 그 세션은 **10초 동안 아무 화면도 못 보낸다**. 이 컴퓨터↔서버 왕복은
+    // 정상일 때 0.3초 안쪽이라, 4초면 느린 회선까지 충분히 품으면서 막혔을 때 회복이 두 배 빠르다.
+    await cb.realtime.connect({ userId: `agent-${crypto.randomUUID()}`, timeout: 4_000 });
     const channel = await cb.realtime.subscribe(TERMINAL_CATEGORY);
     // 이 채널은 앱의 모든 멤버가 공유하므로, 프레임 내용(data)은 세션별 키로 암호화해서 주고받는다.
     // Claude Code 훅이 남긴 "대답 마쳤어요" 쪽지를 받는다 (notify.ts).
@@ -782,8 +877,14 @@ export async function runAgent(options) {
         const session = sessions.get(frame.to);
         if (!session || session.closing)
             return;
-        // 폰에서 온 프레임 = 누군가 이 세션을 보고 있다는 뜻 (임시 터미널 정리 판단에 쓴다)
+        // 폰에서 온 프레임 = 누군가 이 세션을 보고 있다는 뜻 (임시 터미널 정리·출력 게이트에 쓴다)
+        const wasUnwatched = !hasViewer(session);
         session.viewerSeenAt = Date.now();
+        // 안 보는 동안에는 실시간 프레임을 만들지 않으므로(pty.onData 참고), 다시 보기 시작하면
+        // 그 사이 화면이 어떻게 바뀌었는지 알 길이 없다 — 지금 화면을 통째로 보내 맞춰준다.
+        // connect_request 는 아래에서 어차피 복원하므로 여기서 두 번 하지 않는다.
+        if (wasUnwatched && frame.kind !== 'connect_request')
+            void sendRestore(session);
         if (frame.kind === 'connect_request') {
             // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 지금 화면부터 그대로 복원해준다
             void sendRestore(session);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellbase",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {