claude-remote-cli 2.15.16 → 3.0.3

package/dist/server/sessions.js

@@ -1,229 +1,93 @@
-import pty from 'node-pty';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { readMeta, writeMeta } from './config.js';
+import { AGENT_COMMANDS, AGENT_CONTINUE_ARGS, AGENT_YOLO_ARGS } from './types.js';
+import { createPtySession } from './pty-handler.js';
+import { createSdkSession, killSdkSession, sendMessage as sdkSendMessage, handlePermission as sdkHandlePermission, serializeSdkSession, restoreSdkSession } from './sdk-handler.js';
 const execFileAsync = promisify(execFile);
-const AGENT_COMMANDS = {
-    claude: 'claude',
-    codex: 'codex',
-};
-const AGENT_CONTINUE_ARGS = {
-    claude: ['--continue'],
-    codex: ['resume', '--last'],
-};
-const AGENT_YOLO_ARGS = {
-    claude: ['--dangerously-skip-permissions'],
-    codex: ['--full-auto'],
-};
 const STALE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
-function generateTmuxSessionName(displayName, id) {
-    const sanitized = displayName.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-+/g, '-').slice(0, 30);
-    return `crc-${sanitized}-${id.slice(0, 8)}`;
-}
-function resolveTmuxSpawn(command, args, tmuxSessionName) {
-    return {
-        command: 'tmux',
-        args: [
-            '-u', 'new-session', '-s', tmuxSessionName, '--', command, ...args,
-            // ';' tokens are tmux command separators — parsed at the top level before
-            // dispatching to new-session, not passed as argv to `command`.
-            ';', 'set', 'set-clipboard', 'on',
-            ';', 'set', 'allow-passthrough', 'on',
-            ';', 'set', 'mode-keys', 'vi',
-        ],
-    };
-}
+const SDK_IDLE_CHECK_INTERVAL_MS = 60 * 1000; // 60 seconds
+const SDK_MAX_IDLE_MS = 30 * 60 * 1000; // 30 minutes
+const SDK_MAX_IDLE_SESSIONS = 5;
 // In-memory registry: id -> Session
 const sessions = new Map();
-const IDLE_TIMEOUT_MS = 5000;
 let terminalCounter = 0;
 const idleChangeCallbacks = [];
 function onIdleChange(cb) {
     idleChangeCallbacks.push(cb);
 }
-function create({ id: providedId, type, agent = 'claude', repoName, repoPath, cwd, root, worktreeName, branchName, displayName, command, args = [], cols = 80, rows = 24, configPath, useTmux: paramUseTmux, initialScrollback }) {
+function create({ id: providedId, type, agent = 'claude', repoName, repoPath, cwd, root, worktreeName, branchName, displayName, command, args = [], cols = 80, rows = 24, configPath, useTmux: paramUseTmux, tmuxSessionName: paramTmuxSessionName, initialScrollback, restored: paramRestored }) {
     const id = providedId || crypto.randomBytes(8).toString('hex');
-    const createdAt = new Date().toISOString();
-    const resolvedCommand = command || AGENT_COMMANDS[agent];
-    // Strip CLAUDECODE env var to allow spawning claude inside a claude-managed server
-    const env = Object.assign({}, process.env);
-    delete env.CLAUDECODE;
-    const useTmux = !command && !!paramUseTmux;
-    let spawnCommand = resolvedCommand;
-    let spawnArgs = args;
-    const tmuxSessionName = useTmux ? generateTmuxSessionName(displayName || repoName || 'session', id) : '';
-    if (useTmux) {
-        const tmux = resolveTmuxSpawn(resolvedCommand, args, tmuxSessionName);
-        spawnCommand = tmux.command;
-        spawnArgs = tmux.args;
+    // Dispatch: if agent is claude, no custom command, try SDK first
+    if (agent === 'claude' && !command) {
+        const sdkResult = createSdkSession({
+            id,
+            type,
+            agent,
+            repoName,
+            repoPath,
+            cwd,
+            root,
+            worktreeName,
+            branchName,
+            displayName,
+        }, sessions, idleChangeCallbacks);
+        if (!('fallback' in sdkResult)) {
+            return { ...sdkResult.result, pid: undefined };
+        }
+        // SDK init failed — fall through to PTY
     }
-    const ptyProcess = pty.spawn(spawnCommand, spawnArgs, {
-        name: 'xterm-256color',
-        cols,
-        rows,
-        cwd: cwd || repoPath,
-        env,
-    });
-    // Scrollback buffer: stores all PTY output so we can replay on WebSocket (re)connect
-    const scrollback = initialScrollback ? [...initialScrollback] : [];
-    let scrollbackBytes = initialScrollback ? initialScrollback.reduce((sum, s) => sum + s.length, 0) : 0;
-    const MAX_SCROLLBACK = 256 * 1024; // 256KB max
-    const resolvedCwd = cwd || repoPath;
-    const session = {
+    // PTY path: codex, terminal, custom command, or SDK fallback
+    const ptyParams = {
         id,
-        type: type || 'worktree',
+        type,
         agent,
-        root: root || '',
-        repoName: repoName || '',
+        repoName,
         repoPath,
-        worktreeName: worktreeName || '',
-        branchName: branchName || worktreeName || '',
-        displayName: displayName || worktreeName || repoName || '',
-        pty: ptyProcess,
-        createdAt,
-        lastActivity: createdAt,
-        scrollback,
-        idle: false,
-        cwd: resolvedCwd,
-        customCommand: command || null,
-        useTmux,
-        tmuxSessionName,
-        onPtyReplacedCallbacks: [],
+        cwd,
+        root,
+        worktreeName,
+        branchName,
+        displayName,
+        command,
+        args,
+        cols,
+        rows,
+        configPath,
+        useTmux: paramUseTmux,
+        tmuxSessionName: paramTmuxSessionName,
+        initialScrollback,
+        restored: paramRestored,
     };
-    sessions.set(id, session);
-    // Load existing metadata to preserve a previously-set displayName
-    if (configPath && worktreeName) {
-        const existing = readMeta(configPath, repoPath);
-        if (existing && existing.displayName) {
-            session.displayName = existing.displayName;
-        }
-        writeMeta(configPath, { worktreePath: repoPath, displayName: session.displayName, lastActivity: createdAt });
-    }
-    let metaFlushTimer = null;
-    let idleTimer = null;
-    function resetIdleTimer() {
-        if (session.idle) {
-            session.idle = false;
-            for (const cb of idleChangeCallbacks)
-                cb(session.id, false);
-        }
-        if (idleTimer)
-            clearTimeout(idleTimer);
-        idleTimer = setTimeout(() => {
-            if (!session.idle) {
-                session.idle = true;
-                for (const cb of idleChangeCallbacks)
-                    cb(session.id, true);
-            }
-        }, IDLE_TIMEOUT_MS);
-    }
-    const continueArgs = AGENT_CONTINUE_ARGS[agent];
-    function attachHandlers(proc, canRetry) {
-        const spawnTime = Date.now();
-        proc.onData((data) => {
-            session.lastActivity = new Date().toISOString();
-            resetIdleTimer();
-            scrollback.push(data);
-            scrollbackBytes += data.length;
-            // Trim oldest entries if over limit
-            while (scrollbackBytes > MAX_SCROLLBACK && scrollback.length > 1) {
-                scrollbackBytes -= scrollback.shift().length;
-            }
-            if (configPath && worktreeName && !metaFlushTimer) {
-                metaFlushTimer = setTimeout(() => {
-                    metaFlushTimer = null;
-                    writeMeta(configPath, { worktreePath: repoPath, displayName: session.displayName, lastActivity: session.lastActivity });
-                }, 5000);
-            }
-        });
-        proc.onExit(() => {
-            // If continue args failed quickly, retry without them.
-            // Exit code is intentionally not checked: tmux wrapping exits 0 even
-            // when the inner command (e.g. claude --continue) fails, because the
-            // tmux client doesn't propagate inner exit codes. The 3-second window
-            // is the primary heuristic — no user quits a session that fast.
-            if (canRetry && (Date.now() - spawnTime) < 3000) {
-                const retryArgs = args.filter(a => !continueArgs.includes(a));
-                const retryNotice = '\r\n[claude-remote-cli] --continue not available; starting new session...\r\n';
-                scrollback.length = 0;
-                scrollbackBytes = 0;
-                scrollback.push(retryNotice);
-                scrollbackBytes = retryNotice.length;
-                let retryCommand = resolvedCommand;
-                let retrySpawnArgs = retryArgs;
-                if (useTmux && tmuxSessionName) {
-                    const retryTmuxName = tmuxSessionName + '-retry';
-                    session.tmuxSessionName = retryTmuxName;
-                    const tmux = resolveTmuxSpawn(resolvedCommand, retryArgs, retryTmuxName);
-                    retryCommand = tmux.command;
-                    retrySpawnArgs = tmux.args;
-                }
-                let retryPty;
-                try {
-                    retryPty = pty.spawn(retryCommand, retrySpawnArgs, {
-                        name: 'xterm-256color',
-                        cols,
-                        rows,
-                        cwd: cwd || repoPath,
-                        env,
-                    });
-                }
-                catch {
-                    // Retry spawn failed — fall through to normal exit cleanup
-                    if (idleTimer)
-                        clearTimeout(idleTimer);
-                    if (metaFlushTimer)
-                        clearTimeout(metaFlushTimer);
-                    sessions.delete(id);
-                    return;
-                }
-                session.pty = retryPty;
-                for (const cb of session.onPtyReplacedCallbacks)
-                    cb(retryPty);
-                attachHandlers(retryPty, false);
-                return;
-            }
-            if (idleTimer)
-                clearTimeout(idleTimer);
-            if (metaFlushTimer)
-                clearTimeout(metaFlushTimer);
-            if (configPath && worktreeName) {
-                writeMeta(configPath, { worktreePath: repoPath, displayName: session.displayName, lastActivity: session.lastActivity });
-            }
-            sessions.delete(id);
-            const tmpDir = path.join(os.tmpdir(), 'claude-remote-cli', id);
-            fs.rm(tmpDir, { recursive: true, force: true }, () => { });
-        });
-    }
-    attachHandlers(ptyProcess, continueArgs.some(a => args.includes(a)));
-    return { id, type: session.type, agent: session.agent, root: session.root, repoName: session.repoName, repoPath, worktreeName: session.worktreeName, branchName: session.branchName, displayName: session.displayName, pid: ptyProcess.pid, createdAt, lastActivity: createdAt, idle: false, cwd: resolvedCwd, customCommand: command || null, useTmux, tmuxSessionName };
+    const { result } = createPtySession(ptyParams, sessions, idleChangeCallbacks);
+    return result;
 }
 function get(id) {
     return sessions.get(id);
 }
 function list() {
     return Array.from(sessions.values())
-        .map(({ id, type, agent, root, repoName, repoPath, worktreeName, branchName, displayName, createdAt, lastActivity, idle, cwd, customCommand, useTmux, tmuxSessionName }) => ({
-        id,
-        type,
-        agent,
-        root,
-        repoName,
-        repoPath,
-        worktreeName,
-        branchName,
-        displayName,
-        createdAt,
-        lastActivity,
-        idle,
-        cwd,
-        customCommand,
-        useTmux,
-        tmuxSessionName,
+        .map((s) => ({
+        id: s.id,
+        type: s.type,
+        agent: s.agent,
+        mode: s.mode,
+        root: s.root,
+        repoName: s.repoName,
+        repoPath: s.repoPath,
+        worktreeName: s.worktreeName,
+        branchName: s.branchName,
+        displayName: s.displayName,
+        createdAt: s.createdAt,
+        lastActivity: s.lastActivity,
+        idle: s.idle,
+        cwd: s.cwd,
+        customCommand: s.customCommand,
+        useTmux: s.mode === 'pty' ? s.useTmux : false,
+        tmuxSessionName: s.mode === 'pty' ? s.tmuxSessionName : '',
+        status: s.status,
     }))
         .sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
 }
@@ -239,15 +103,25 @@ function kill(id) {
     if (!session) {
         throw new Error(`Session not found: ${id}`);
     }
-    session.pty.kill('SIGTERM');
-    if (session.tmuxSessionName) {
-        execFile('tmux', ['kill-session', '-t', session.tmuxSessionName], () => { });
+    if (session.mode === 'pty') {
+        try {
+            session.pty.kill('SIGTERM');
+        }
+        catch {
+            // PTY may already be dead (e.g. disconnected sessions) — still delete from registry
+        }
+        if (session.tmuxSessionName) {
+            execFile('tmux', ['kill-session', '-t', session.tmuxSessionName], () => { });
+        }
+    }
+    else if (session.mode === 'sdk') {
+        killSdkSession(id);
     }
     sessions.delete(id);
 }
 function killAllTmuxSessions() {
     for (const session of sessions.values()) {
-        if (session.tmuxSessionName) {
+        if (session.mode === 'pty' && session.tmuxSessionName) {
             execFile('tmux', ['kill-session', '-t', session.tmuxSessionName], () => { });
         }
     }
@@ -257,14 +131,25 @@ function resize(id, cols, rows) {
     if (!session) {
         throw new Error(`Session not found: ${id}`);
     }
-    session.pty.resize(cols, rows);
+    if (session.mode === 'pty') {
+        session.pty.resize(cols, rows);
+    }
+    // SDK sessions don't support resize (no PTY)
 }
 function write(id, data) {
     const session = sessions.get(id);
     if (!session) {
         throw new Error(`Session not found: ${id}`);
     }
-    session.pty.write(data);
+    if (session.mode === 'pty') {
+        session.pty.write(data);
+    }
+    else if (session.mode === 'sdk') {
+        sdkSendMessage(id, data);
+    }
+}
+function handlePermission(id, requestId, approved) {
+    sdkHandlePermission(id, requestId, approved);
 }
 function findRepoSession(repoPath) {
     return list().find((s) => s.type === 'repo' && s.repoPath === repoPath);
@@ -275,33 +160,40 @@ function nextTerminalName() {
 function serializeAll(configDir) {
     const scrollbackDirPath = path.join(configDir, 'scrollback');
     fs.mkdirSync(scrollbackDirPath, { recursive: true });
-    const serialized = [];
+    const serializedPty = [];
+    const serializedSdk = [];
     for (const session of sessions.values()) {
-        // Write scrollback to disk
-        const scrollbackPath = path.join(scrollbackDirPath, session.id + '.buf');
-        fs.writeFileSync(scrollbackPath, session.scrollback.join(''), 'utf-8');
-        serialized.push({
-            id: session.id,
-            type: session.type,
-            agent: session.agent,
-            root: session.root,
-            repoName: session.repoName,
-            repoPath: session.repoPath,
-            worktreeName: session.worktreeName,
-            branchName: session.branchName,
-            displayName: session.displayName,
-            createdAt: session.createdAt,
-            lastActivity: session.lastActivity,
-            useTmux: session.useTmux,
-            tmuxSessionName: session.tmuxSessionName,
-            customCommand: session.customCommand,
-            cwd: session.cwd,
-        });
+        if (session.mode === 'pty') {
+            // Write scrollback to disk
+            const scrollbackPath = path.join(scrollbackDirPath, session.id + '.buf');
+            fs.writeFileSync(scrollbackPath, session.scrollback.join(''), 'utf-8');
+            serializedPty.push({
+                id: session.id,
+                type: session.type,
+                agent: session.agent,
+                root: session.root,
+                repoName: session.repoName,
+                repoPath: session.repoPath,
+                worktreeName: session.worktreeName,
+                branchName: session.branchName,
+                displayName: session.displayName,
+                createdAt: session.createdAt,
+                lastActivity: session.lastActivity,
+                useTmux: session.useTmux,
+                tmuxSessionName: session.tmuxSessionName,
+                customCommand: session.customCommand,
+                cwd: session.cwd,
+            });
+        }
+        else if (session.mode === 'sdk') {
+            serializedSdk.push(serializeSdkSession(session));
+        }
     }
     const pending = {
         version: 1,
         timestamp: new Date().toISOString(),
-        sessions: serialized,
+        sessions: serializedPty,
+        sdkSessions: serializedSdk.length > 0 ? serializedSdk : undefined,
     };
     fs.writeFileSync(path.join(configDir, 'pending-sessions.json'), JSON.stringify(pending, null, 2), 'utf-8');
 }
@@ -324,6 +216,7 @@ async function restoreFromDisk(configDir) {
     }
     const scrollbackDirPath = path.join(configDir, 'scrollback');
     let restored = 0;
+    // Restore PTY sessions
     for (const s of pending.sessions) {
         // Load scrollback from disk
         let initialScrollback;
@@ -381,6 +274,8 @@ async function restoreFromDisk(configDir) {
                 displayName: s.displayName,
                 args,
                 useTmux: false, // Don't re-wrap in tmux — either attaching to existing or using plain agent
+                tmuxSessionName: s.tmuxSessionName,
+                restored: true,
             };
             if (command)
                 createParams.command = command;
@@ -398,6 +293,18 @@ async function restoreFromDisk(configDir) {
         }
         catch { /* ignore */ }
     }
+    // Restore SDK sessions (as disconnected — they can't resume a live process)
+    if (pending.sdkSessions) {
+        for (const sdkData of pending.sdkSessions) {
+            try {
+                restoreSdkSession(sdkData, sessions);
+                restored++;
+            }
+            catch {
+                console.error(`Failed to restore SDK session ${sdkData.id} (${sdkData.displayName})`);
+            }
+        }
+    }
     // Clean up
     try {
         fs.unlinkSync(pendingPath);
@@ -413,9 +320,55 @@ async function restoreFromDisk(configDir) {
 function activeTmuxSessionNames() {
     const names = new Set();
     for (const session of sessions.values()) {
-        if (session.tmuxSessionName)
+        if (session.mode === 'pty' && session.tmuxSessionName)
             names.add(session.tmuxSessionName);
     }
     return names;
 }
-export { create, get, list, kill, killAllTmuxSessions, resize, updateDisplayName, write, onIdleChange, findRepoSession, nextTerminalName, serializeAll, restoreFromDisk, activeTmuxSessionNames, AGENT_COMMANDS, AGENT_CONTINUE_ARGS, AGENT_YOLO_ARGS, resolveTmuxSpawn, generateTmuxSessionName };
+// SDK idle sweep: check every 60s, terminate SDK sessions idle > 30min, max 5 idle
+let sdkIdleSweepTimer = null;
+function startSdkIdleSweep() {
+    if (sdkIdleSweepTimer)
+        return;
+    sdkIdleSweepTimer = setInterval(() => {
+        const now = Date.now();
+        const sdkSessions = [];
+        for (const session of sessions.values()) {
+            if (session.mode === 'sdk') {
+                sdkSessions.push(session);
+            }
+        }
+        // Terminate sessions idle > 30 minutes
+        for (const session of sdkSessions) {
+            const lastActivity = new Date(session.lastActivity).getTime();
+            if (session.idle && (now - lastActivity) > SDK_MAX_IDLE_MS) {
+                console.log(`SDK idle sweep: terminating session ${session.id} (${session.displayName}) — idle for ${Math.round((now - lastActivity) / 60000)}min`);
+                try {
+                    kill(session.id);
+                }
+                catch { /* already dead */ }
+            }
+        }
+        // LRU eviction: if more than 5 idle SDK sessions remain, evict oldest
+        const idleSdkSessions = Array.from(sessions.values())
+            .filter((s) => s.mode === 'sdk' && s.idle)
+            .sort((a, b) => a.lastActivity.localeCompare(b.lastActivity));
+        while (idleSdkSessions.length > SDK_MAX_IDLE_SESSIONS) {
+            const oldest = idleSdkSessions.shift();
+            console.log(`SDK idle sweep: evicting session ${oldest.id} (${oldest.displayName}) — LRU`);
+            try {
+                kill(oldest.id);
+            }
+            catch { /* already dead */ }
+        }
+    }, SDK_IDLE_CHECK_INTERVAL_MS);
+}
+function stopSdkIdleSweep() {
+    if (sdkIdleSweepTimer) {
+        clearInterval(sdkIdleSweepTimer);
+        sdkIdleSweepTimer = null;
+    }
+}
+// Re-export pty-handler utilities for backward compatibility
+export { generateTmuxSessionName, resolveTmuxSpawn } from './pty-handler.js';
+export { create, get, list, kill, killAllTmuxSessions, resize, updateDisplayName, write, handlePermission, onIdleChange, findRepoSession, nextTerminalName, serializeAll, restoreFromDisk, activeTmuxSessionNames, startSdkIdleSweep, stopSdkIdleSweep, AGENT_COMMANDS, AGENT_CONTINUE_ARGS, AGENT_YOLO_ARGS };

package/dist/server/types.js

@@ -1 +1,13 @@
-export {};
+// Agent command records (shared by PTY and SDK handlers)
+export const AGENT_COMMANDS = {
+    claude: 'claude',
+    codex: 'codex',
+};
+export const AGENT_CONTINUE_ARGS = {
+    claude: ['--continue'],
+    codex: ['resume', '--last'],
+};
+export const AGENT_YOLO_ARGS = {
+    claude: ['--dangerously-skip-permissions'],
+    codex: ['--full-auto'],
+};

package/dist/server/ws.js

@@ -1,5 +1,8 @@
 import { WebSocketServer } from 'ws';
 import * as sessions from './sessions.js';
+import { onSdkEvent, sendMessage as sdkSendMessage, handlePermission as sdkHandlePermission } from './sdk-handler.js';
+const BACKPRESSURE_HIGH = 1024 * 1024; // 1MB
+const BACKPRESSURE_LOW = 512 * 1024; // 512KB
 function parseCookies(cookieHeader) {
     const cookies = {};
     if (!cookieHeader)
@@ -47,7 +50,7 @@ function setupWebSocket(server, authenticatedTokens, watcher) {
             });
             return;
         }
-        // PTY channel: /ws/:sessionId
+        // PTY/SDK channel: /ws/:sessionId
         const match = request.url && request.url.match(/^\/ws\/([a-f0-9]+)$/);
         if (!match) {
             socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
@@ -71,6 +74,16 @@ function setupWebSocket(server, authenticatedTokens, watcher) {
         const session = sessionMap.get(ws);
         if (!session)
             return;
+        if (session.mode === 'sdk') {
+            handleSdkConnection(ws, session);
+            return;
+        }
+        // PTY mode — existing behavior
+        if (session.mode !== 'pty') {
+            ws.close(1008, 'Session mode does not support PTY streaming');
+            return;
+        }
+        const ptySession = session;
         let dataDisposable = null;
         let exitDisposable = null;
         function attachToPty(ptyProcess) {
@@ -78,7 +91,7 @@ function setupWebSocket(server, authenticatedTokens, watcher) {
             dataDisposable?.dispose();
             exitDisposable?.dispose();
             // Replay scrollback
-            for (const chunk of session.scrollback) {
+            for (const chunk of ptySession.scrollback) {
                 if (ws.readyState === ws.OPEN)
                     ws.send(chunk);
             }
@@ -91,30 +104,100 @@ function setupWebSocket(server, authenticatedTokens, watcher) {
                     ws.close(1000);
             });
         }
-        attachToPty(session.pty);
+        attachToPty(ptySession.pty);
         const ptyReplacedHandler = (newPty) => attachToPty(newPty);
-        session.onPtyReplacedCallbacks.push(ptyReplacedHandler);
+        ptySession.onPtyReplacedCallbacks.push(ptyReplacedHandler);
         ws.on('message', (msg) => {
             const str = msg.toString();
             try {
                 const parsed = JSON.parse(str);
                 if (parsed.type === 'resize' && parsed.cols && parsed.rows) {
-                    sessions.resize(session.id, parsed.cols, parsed.rows);
+                    sessions.resize(ptySession.id, parsed.cols, parsed.rows);
                     return;
                 }
             }
             catch (_) { }
-            // Use session.pty dynamically so writes go to current PTY
-            session.pty.write(str);
+            // Use ptySession.pty dynamically so writes go to current PTY
+            ptySession.pty.write(str);
         });
         ws.on('close', () => {
             dataDisposable?.dispose();
             exitDisposable?.dispose();
-            const idx = session.onPtyReplacedCallbacks.indexOf(ptyReplacedHandler);
+            const idx = ptySession.onPtyReplacedCallbacks.indexOf(ptyReplacedHandler);
             if (idx !== -1)
-                session.onPtyReplacedCallbacks.splice(idx, 1);
+                ptySession.onPtyReplacedCallbacks.splice(idx, 1);
         });
     });
+    function handleSdkConnection(ws, session) {
+        // Send session info
+        const sessionInfo = JSON.stringify({
+            type: 'session_info',
+            mode: 'sdk',
+            sessionId: session.id,
+        });
+        if (ws.readyState === ws.OPEN)
+            ws.send(sessionInfo);
+        // Replay stored events (send as-is — client expects raw SdkEvent shape)
+        for (const event of session.events) {
+            if (ws.readyState !== ws.OPEN)
+                break;
+            ws.send(JSON.stringify(event));
+        }
+        // Subscribe to live events with backpressure
+        let paused = false;
+        const unsubscribe = onSdkEvent(session.id, (event) => {
+            if (ws.readyState !== ws.OPEN)
+                return;
+            // Backpressure check
+            if (ws.bufferedAmount > BACKPRESSURE_HIGH) {
+                paused = true;
+                return;
+            }
+            ws.send(JSON.stringify(event));
+        });
+        // Periodically check if we can resume
+        const backpressureInterval = setInterval(() => {
+            if (paused && ws.bufferedAmount < BACKPRESSURE_LOW) {
+                paused = false;
+            }
+        }, 100);
+        // Handle incoming messages
+        ws.on('message', (msg) => {
+            const str = msg.toString();
+            try {
+                const parsed = JSON.parse(str);
+                if (parsed.type === 'message' && typeof parsed.text === 'string') {
+                    if (parsed.text.length > 100_000)
+                        return;
+                    sdkSendMessage(session.id, parsed.text);
+                    return;
+                }
+                if (parsed.type === 'permission' && typeof parsed.requestId === 'string' && typeof parsed.approved === 'boolean') {
+                    sdkHandlePermission(session.id, parsed.requestId, parsed.approved);
+                    return;
+                }
+                if (parsed.type === 'resize' && typeof parsed.cols === 'number' && typeof parsed.rows === 'number') {
+                    // TODO: wire up companion shell — currently open_companion message is unhandled server-side
+                    return;
+                }
+                if (parsed.type === 'open_companion') {
+                    // TODO: spawn companion PTY in session CWD and relay via terminal_data/terminal_exit frames
+                    return;
+                }
+            }
+            catch (_) {
+                // Not JSON — ignore for SDK sessions
+            }
+        });
+        ws.on('close', () => {
+            unsubscribe();
+            clearInterval(backpressureInterval);
+        });
+        ws.on('error', () => {
+            unsubscribe();
+            clearInterval(backpressureInterval);
+        });
+    }
     sessions.onIdleChange((sessionId, idle) => {
         broadcastEvent('session-idle-changed', { sessionId, idle });
     });