@anusornneal/chat-relay 0.7.1 → 0.8.0

package/agent/windows-desktop-worker.ps1

@@ -0,0 +1,508 @@
+param()
+
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+Add-Type @"
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class ChatRelayNative {
+  public const uint INPUT_MOUSE = 0;
+  public const uint INPUT_KEYBOARD = 1;
+  public const uint KEYEVENTF_KEYUP = 0x0002;
+  public const uint KEYEVENTF_UNICODE = 0x0004;
+
+  [StructLayout(LayoutKind.Sequential)]
+  public struct MOUSEINPUT {
+    public int dx;
+    public int dy;
+    public uint mouseData;
+    public uint dwFlags;
+    public uint time;
+    public UIntPtr dwExtraInfo;
+  }
+
+  [StructLayout(LayoutKind.Sequential)]
+  public struct KEYBDINPUT {
+    public ushort wVk;
+    public ushort wScan;
+    public uint dwFlags;
+    public uint time;
+    public UIntPtr dwExtraInfo;
+  }
+
+  [StructLayout(LayoutKind.Explicit)]
+  public struct INPUTUNION {
+    [FieldOffset(0)] public MOUSEINPUT mi;
+    [FieldOffset(0)] public KEYBDINPUT ki;
+  }
+
+  [StructLayout(LayoutKind.Sequential)]
+  public struct INPUT {
+    public uint type;
+    public INPUTUNION U;
+  }
+
+  [StructLayout(LayoutKind.Sequential)]
+  public struct RECT {
+    public int Left;
+    public int Top;
+    public int Right;
+    public int Bottom;
+  }
+
+  public sealed class WindowInfo {
+    public string WindowId;
+    public uint ProcessId;
+    public string Title;
+    public int X;
+    public int Y;
+    public int Width;
+    public int Height;
+    public bool IsForeground;
+  }
+
+  public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+
+  [DllImport("user32.dll")] public static extern uint SendInput(uint nInputs, INPUT[] pInputs, int cbSize);
+  [DllImport("user32.dll")] public static extern bool SetCursorPos(int X, int Y);
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc callback, IntPtr lParam);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool IsWindow(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetWindowTextLength(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] public static extern int GetWindowText(IntPtr hWnd, StringBuilder text, int maxCount);
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint processId);
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool ShowWindowAsync(IntPtr hWnd, int command);
+
+  public static WindowInfo[] ListWindows(int limit) {
+    var items = new List<WindowInfo>();
+    var foreground = GetForegroundWindow();
+    EnumWindows(delegate(IntPtr hWnd, IntPtr lParam) {
+      if (items.Count >= limit) return false;
+      if (!IsWindowVisible(hWnd)) return true;
+      int titleLength = GetWindowTextLength(hWnd);
+      if (titleLength <= 0) return true;
+      var title = new StringBuilder(titleLength + 1);
+      if (GetWindowText(hWnd, title, title.Capacity) <= 0) return true;
+      uint pid;
+      GetWindowThreadProcessId(hWnd, out pid);
+      RECT rect;
+      if (!GetWindowRect(hWnd, out rect)) return true;
+      items.Add(new WindowInfo {
+        WindowId = unchecked((ulong)hWnd.ToInt64()).ToString(),
+        ProcessId = pid,
+        Title = title.ToString(),
+        X = rect.Left,
+        Y = rect.Top,
+        Width = Math.Max(0, rect.Right - rect.Left),
+        Height = Math.Max(0, rect.Bottom - rect.Top),
+        IsForeground = hWnd == foreground,
+      });
+      return true;
+    }, IntPtr.Zero);
+    return items.ToArray();
+  }
+
+  public static bool FocusWindow(string windowId) {
+    ulong raw;
+    if (!UInt64.TryParse(windowId, out raw) || raw == 0) return false;
+    var hWnd = new IntPtr(unchecked((long)raw));
+    if (!IsWindow(hWnd)) return false;
+    ShowWindowAsync(hWnd, 9);
+    return SetForegroundWindow(hWnd);
+  }
+
+  public static bool MouseButton(uint downFlag, uint upFlag) {
+    var inputs = new INPUT[2];
+    inputs[0].type = INPUT_MOUSE;
+    inputs[0].U.mi.dwFlags = downFlag;
+    inputs[1].type = INPUT_MOUSE;
+    inputs[1].U.mi.dwFlags = upFlag;
+    return SendInput(2, inputs, Marshal.SizeOf(typeof(INPUT))) == 2;
+  }
+
+  public static bool Key(ushort virtualKey, bool down) {
+    var input = new INPUT[1];
+    input[0].type = INPUT_KEYBOARD;
+    input[0].U.ki.wVk = virtualKey;
+    input[0].U.ki.dwFlags = down ? 0u : KEYEVENTF_KEYUP;
+    return SendInput(1, input, Marshal.SizeOf(typeof(INPUT))) == 1;
+  }
+
+  public static bool UnicodeText(string text) {
+    foreach (char c in text) {
+      var inputs = new INPUT[2];
+      inputs[0].type = INPUT_KEYBOARD;
+      inputs[0].U.ki.wScan = c;
+      inputs[0].U.ki.dwFlags = KEYEVENTF_UNICODE;
+      inputs[1].type = INPUT_KEYBOARD;
+      inputs[1].U.ki.wScan = c;
+      inputs[1].U.ki.dwFlags = KEYEVENTF_UNICODE | KEYEVENTF_KEYUP;
+      if (SendInput(2, inputs, Marshal.SizeOf(typeof(INPUT))) != 2) return false;
+    }
+    return true;
+  }
+}
+"@
+
+[ChatRelayNative]::SetProcessDPIAware() | Out-Null
+
+function Result-Error([string]$Code) {
+  return [pscustomobject]@{ ok = $false; error = $Code }
+}
+
+function Test-InteractiveSession {
+  return [System.Windows.Forms.SystemInformation]::UserInteractive -and
+    ([ChatRelayNative]::GetForegroundWindow() -ne [IntPtr]::Zero)
+}
+
+function Resolve-Screen($Monitor) {
+  $screens = @([System.Windows.Forms.Screen]::AllScreens)
+  if ($screens.Count -eq 0) { return $null }
+
+  if ($null -eq $Monitor -or [string]$Monitor -eq "primary") {
+    for ($i = 0; $i -lt $screens.Count; $i++) {
+      if ($screens[$i].Primary) {
+        return [pscustomobject]@{ screen = $screens[$i]; index = $i }
+      }
+    }
+    return $null
+  }
+
+  if ([string]$Monitor -eq "secondary") {
+    for ($i = 0; $i -lt $screens.Count; $i++) {
+      if (-not $screens[$i].Primary) {
+        return [pscustomobject]@{ screen = $screens[$i]; index = $i }
+      }
+    }
+    return $null
+  }
+
+  $parsedIndex = 0
+  if (-not [int]::TryParse([string]$Monitor, [ref]$parsedIndex)) { return $null }
+  if ($parsedIndex -lt 0 -or $parsedIndex -ge $screens.Count) { return $null }
+  return [pscustomobject]@{ screen = $screens[$parsedIndex]; index = $parsedIndex }
+}
+
+function Invoke-Screenshot($Payload) {
+  if (-not [System.Windows.Forms.SystemInformation]::UserInteractive) {
+    return Result-Error "session_unavailable"
+  }
+
+  $resolved = Resolve-Screen $Payload.monitor
+  if ($null -eq $resolved) { return Result-Error "monitor_not_found" }
+
+  $screen = $resolved.screen
+  $bounds = $screen.Bounds
+  if ($bounds.Width -le 0 -or $bounds.Height -le 0) {
+    return Result-Error "session_unavailable"
+  }
+
+  $source = $null
+  try {
+    $source = New-Object System.Drawing.Bitmap $bounds.Width, $bounds.Height
+    $graphics = [System.Drawing.Graphics]::FromImage($source)
+    try {
+      $graphics.CopyFromScreen($bounds.Left, $bounds.Top, 0, 0, $bounds.Size)
+    } finally {
+      $graphics.Dispose()
+    }
+
+    $codec = [System.Drawing.Imaging.ImageCodecInfo]::GetImageEncoders() |
+      Where-Object { $_.MimeType -eq "image/jpeg" } |
+      Select-Object -First 1
+    if ($null -eq $codec) { return Result-Error "capture_failed" }
+
+    $maxBytes = 32768
+    $requestedMaxWidth = if ($null -eq $Payload.maxWidth) { 960 } else { [int]$Payload.maxWidth }
+    if ($requestedMaxWidth -lt 320 -or $requestedMaxWidth -gt 1920) { return Result-Error "invalid_max_width" }
+    $requestedQuality = if ($null -eq $Payload.quality) { 58 } else { [int]$Payload.quality }
+    if ($requestedQuality -lt 20 -or $requestedQuality -gt 85) { return Result-Error "invalid_quality" }
+    $targetWidth = [Math]::Min($bounds.Width, $requestedMaxWidth)
+    $targetHeight = [Math]::Max(1, [int][Math]::Round($bounds.Height * ($targetWidth / [double]$bounds.Width)))
+    $qualities = @([long]$requestedQuality, [long][Math]::Min($requestedQuality, 42), [long][Math]::Min($requestedQuality, 30), 20L) | Select-Object -Unique
+    $bytes = $null
+    $finalWidth = $targetWidth
+    $finalHeight = $targetHeight
+    $finalQuality = $requestedQuality
+
+    for ($sizeAttempt = 0; $sizeAttempt -lt 3 -and $null -eq $bytes; $sizeAttempt++) {
+      $resized = New-Object System.Drawing.Bitmap $targetWidth, $targetHeight
+      $draw = [System.Drawing.Graphics]::FromImage($resized)
+      try {
+        $draw.CompositingQuality = [System.Drawing.Drawing2D.CompositingQuality]::HighSpeed
+        $draw.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::Bilinear
+        $draw.PixelOffsetMode = [System.Drawing.Drawing2D.PixelOffsetMode]::HighSpeed
+        $draw.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::HighSpeed
+        $draw.DrawImage($source, 0, 0, $targetWidth, $targetHeight)
+      } finally {
+        $draw.Dispose()
+      }
+
+      try {
+        foreach ($quality in $qualities) {
+          $stream = New-Object System.IO.MemoryStream
+          $parameters = New-Object System.Drawing.Imaging.EncoderParameters 1
+          $parameters.Param[0] = New-Object System.Drawing.Imaging.EncoderParameter(
+            [System.Drawing.Imaging.Encoder]::Quality,
+            $quality
+          )
+          try {
+            $resized.Save($stream, $codec, $parameters)
+            if ($stream.Length -le $maxBytes) {
+              $bytes = $stream.ToArray()
+              $finalWidth = $targetWidth
+              $finalHeight = $targetHeight
+              $finalQuality = [int]$quality
+              break
+            }
+          } finally {
+            $parameters.Dispose()
+            $stream.Dispose()
+          }
+        }
+      } finally {
+        $resized.Dispose()
+      }
+
+      if ($null -eq $bytes) {
+        $targetWidth = [Math]::Max(320, [int][Math]::Floor($targetWidth * 0.78))
+        $targetHeight = [Math]::Max(180, [int][Math]::Round($bounds.Height * ($targetWidth / [double]$bounds.Width)))
+      }
+    }
+
+    if ($null -eq $bytes) { return Result-Error "screenshot_too_large" }
+    $virtualBounds = [System.Windows.Forms.SystemInformation]::VirtualScreen
+    $monitorCount = @([System.Windows.Forms.Screen]::AllScreens).Count
+
+    return [pscustomobject]@{
+      ok = $true
+      mimeType = "image/jpeg"
+      data = [Convert]::ToBase64String($bytes)
+      width = $finalWidth
+      height = $finalHeight
+      virtualDesktopOriginX = $virtualBounds.Left
+      virtualDesktopOriginY = $virtualBounds.Top
+      virtualDesktopWidth = $virtualBounds.Width
+      virtualDesktopHeight = $virtualBounds.Height
+      monitorCount = $monitorCount
+      jpegQuality = $finalQuality
+      desktopOriginX = $bounds.Left
+      desktopOriginY = $bounds.Top
+      desktopWidth = $bounds.Width
+      desktopHeight = $bounds.Height
+      scaleX = $bounds.Width / [double]$finalWidth
+      scaleY = $bounds.Height / [double]$finalHeight
+      monitorIndex = $resolved.index
+      isPrimary = [bool]$screen.Primary
+      deviceName = [string]$screen.DeviceName
+      byteLength = $bytes.Length
+    }
+  } catch {
+    return Result-Error "capture_failed"
+  } finally {
+    if ($null -ne $source) { $source.Dispose() }
+  }
+}
+
+function Invoke-MouseClick($Payload) {
+  if (-not (Test-InteractiveSession)) { return Result-Error "session_unavailable" }
+
+  $x = [int]$Payload.x
+  $y = [int]$Payload.y
+  $containsPoint = $false
+  foreach ($screen in @([System.Windows.Forms.Screen]::AllScreens)) {
+    if ($screen.Bounds.Contains($x, $y)) {
+      $containsPoint = $true
+      break
+    }
+  }
+  if (-not $containsPoint) { return Result-Error "invalid_coordinates" }
+
+  switch ([string]$Payload.button) {
+    "left" { $down = 0x0002; $up = 0x0004 }
+    "right" { $down = 0x0008; $up = 0x0010 }
+    "middle" { $down = 0x0020; $up = 0x0040 }
+    default { return Result-Error "invalid_button" }
+  }
+
+  if (-not [ChatRelayNative]::SetCursorPos($x, $y)) { return Result-Error "input_failed" }
+
+  $clicks = [int]$Payload.clicks
+  for ($i = 0; $i -lt $clicks; $i++) {
+    if (-not [ChatRelayNative]::MouseButton($down, $up)) { return Result-Error "input_failed" }
+    if ($i + 1 -lt $clicks) { Start-Sleep -Milliseconds 100 }
+  }
+
+  return [pscustomobject]@{ ok = $true; action = "mouse_click" }
+}
+
+function Invoke-KeyboardInput($Payload) {
+  if (-not (Test-InteractiveSession)) { return Result-Error "session_unavailable" }
+
+  if ($null -ne $Payload.text) {
+    if (-not [ChatRelayNative]::UnicodeText([string]$Payload.text)) {
+      return Result-Error "input_failed"
+    }
+  } else {
+    $mods = New-Object System.Collections.Generic.List[uint16]
+    if ($Payload.ctrl) { $mods.Add(0x11) }
+    if ($Payload.alt) { $mods.Add(0x12) }
+    if ($Payload.shift) { $mods.Add(0x10) }
+    if ($Payload.win) { $mods.Add(0x5B) }
+
+    foreach ($vk in $mods) {
+      if (-not [ChatRelayNative]::Key($vk, $true)) { return Result-Error "input_failed" }
+    }
+
+    try {
+      $keyCode = [uint16]$Payload.keyCode
+      if (-not [ChatRelayNative]::Key($keyCode, $true)) { return Result-Error "input_failed" }
+      if (-not [ChatRelayNative]::Key($keyCode, $false)) { return Result-Error "input_failed" }
+    } finally {
+      for ($i = $mods.Count - 1; $i -ge 0; $i--) {
+        [ChatRelayNative]::Key($mods[$i], $false) | Out-Null
+      }
+    }
+  }
+
+  return [pscustomobject]@{ ok = $true; action = "keyboard_input" }
+}
+
+function Invoke-ClipboardRead($Payload) {
+  if (-not [System.Windows.Forms.SystemInformation]::UserInteractive) { return Result-Error "session_unavailable" }
+  try {
+    $text = if ([System.Windows.Forms.Clipboard]::ContainsText()) { [System.Windows.Forms.Clipboard]::GetText() } else { "" }
+    $truncated = $text.Length -gt 8192
+    if ($truncated) { $text = $text.Substring(0, 8192) }
+    return [pscustomobject]@{ ok = $true; text = $text; truncated = $truncated }
+  } catch { return Result-Error "clipboard_failed" }
+}
+
+function Invoke-ClipboardWrite($Payload) {
+  if (-not (Test-InteractiveSession)) { return Result-Error "session_unavailable" }
+  try {
+    $text = [string]$Payload.text
+    if ($text.Length -gt 8192) { return Result-Error "text_too_large" }
+    if ($text.Length -eq 0) { [System.Windows.Forms.Clipboard]::Clear() } else { [System.Windows.Forms.Clipboard]::SetText($text) }
+    return [pscustomobject]@{ ok = $true; action = "clipboard_write"; length = $text.Length }
+  } catch { return Result-Error "clipboard_failed" }
+}
+
+function Invoke-WindowList($Payload) {
+  if (-not [System.Windows.Forms.SystemInformation]::UserInteractive) { return Result-Error "session_unavailable" }
+  $limit = if ($null -eq $Payload.limit) { 50 } else { [int]$Payload.limit }
+  if ($limit -lt 1 -or $limit -gt 100) { return Result-Error "invalid_window_limit" }
+  try {
+    $windows = @([ChatRelayNative]::ListWindows($limit))
+    return [pscustomobject]@{ ok = $true; windows = $windows; count = $windows.Count }
+  } catch { return Result-Error "window_list_failed" }
+}
+
+function Invoke-WindowFocus($Payload) {
+  if (-not (Test-InteractiveSession)) { return Result-Error "session_unavailable" }
+  $windowId = [string]$Payload.windowId
+  if ($windowId -notmatch '^[1-9][0-9]{0,19}$') { return Result-Error "invalid_window_id" }
+  try {
+    if (-not [ChatRelayNative]::FocusWindow($windowId)) { return Result-Error "focus_failed" }
+    return [pscustomobject]@{ ok = $true; action = "window_focus"; windowId = $windowId }
+  } catch { return Result-Error "focus_failed" }
+}
+
+function Invoke-Step($Payload) {
+  $completed = 0
+  foreach ($action in @($Payload.actions)) {
+    $result = $null
+    switch ([string]$action.type) {
+      "click" { $result = Invoke-MouseClick $action }
+      "text" { $result = Invoke-KeyboardInput $action }
+      "key" { $result = Invoke-KeyboardInput $action }
+      "wait" {
+        Start-Sleep -Milliseconds ([int]$action.ms)
+        $result = [pscustomobject]@{ ok = $true; action = "wait" }
+      }
+      default { $result = Result-Error "invalid_step_action" }
+    }
+
+    if (-not $result.ok) {
+      return [pscustomobject]@{
+        ok = $false
+        error = $result.error
+        actionsCompleted = $completed
+      }
+    }
+    $completed++
+  }
+
+  if ([int]$Payload.settleMs -gt 0) {
+    Start-Sleep -Milliseconds ([int]$Payload.settleMs)
+  }
+
+  if ($Payload.captureAfter -eq $false) {
+    return [pscustomobject]@{
+      ok = $true
+      action = "step"
+      actionsCompleted = $completed
+    }
+  }
+
+  $shotPayload = [pscustomobject]@{ monitor = $Payload.monitor; maxWidth = $Payload.maxWidth; quality = $Payload.quality }
+  $shot = Invoke-Screenshot $shotPayload
+  if (-not $shot.ok) {
+    return [pscustomobject]@{
+      ok = $false
+      error = $shot.error
+      actionsCompleted = $completed
+    }
+  }
+
+  $shot | Add-Member -NotePropertyName action -NotePropertyValue "step" -Force
+  $shot | Add-Member -NotePropertyName actionsCompleted -NotePropertyValue $completed -Force
+  return $shot
+}
+
+function Invoke-Operation([string]$Operation, $Payload) {
+  switch ($Operation) {
+    "screenshot" { return Invoke-Screenshot $Payload }
+    "clipboard_read" { return Invoke-ClipboardRead $Payload }
+    "clipboard_write" { return Invoke-ClipboardWrite $Payload }
+    "window_list" { return Invoke-WindowList $Payload }
+    "window_focus" { return Invoke-WindowFocus $Payload }
+    "mouse_click" { return Invoke-MouseClick $Payload }
+    "keyboard_input" { return Invoke-KeyboardInput $Payload }
+    "step" { return Invoke-Step $Payload }
+    default { return Result-Error "unknown_desktop_operation" }
+  }
+}
+
+while (($line = [Console]::In.ReadLine()) -ne $null) {
+  if ([string]::IsNullOrWhiteSpace($line)) { continue }
+
+  $id = $null
+  $result = $null
+  try {
+    $request = $line | ConvertFrom-Json
+    $id = [string]$request.id
+    $result = Invoke-Operation ([string]$request.operation) $request.args
+  } catch {
+    $result = Result-Error "desktop_worker_error"
+  }
+
+  $response = [pscustomobject]@{
+    id = $id
+    result = $result
+  }
+
+  [Console]::Out.WriteLine(($response | ConvertTo-Json -Compress -Depth 10))
+  [Console]::Out.Flush()
+}

package/cli/index.mjs

@@ -1,6 +1,6 @@
 import { clearConfig, configPath, loadConfig, saveConfig } from "./config.mjs";
 import { login, requestJson } from "./device-login.mjs";
-import { remote, validateConfig } from "./remote.mjs";
+import { protocolCompatibility, remote, validateConfig } from "./remote.mjs";
 
 function parseOptions(args) {
   const options = {};
@@ -31,6 +31,9 @@ Usage:
   chat-relay remote [options]   Connect this computer to ChatGPT
   chat-relay login [options]    Sign in and register this computer
   chat-relay status             Show account and connection status
+  chat-relay drain              Stop accepting new long-running work
+  chat-relay resume             Resume normal work admission
+  chat-relay restart            Restart after drain completes
   chat-relay logout             Revoke this computer login
   chat-relay help               Show this help
 
@@ -124,6 +127,15 @@ async function status() {
       "Scopes:   " +
       (Array.isArray(agentStatus.data.scopes) ? agentStatus.data.scopes.join(",") : "-"),
     );
+    const connection = agentStatus.data.connection || {};
+    const compatibility = protocolCompatibility(connection.protocolVersion, agentStatus.data.expectedProtocolVersion);
+    console.log("Version:  " + (connection.agentVersion || "-"));
+    console.log(`Protocol: ${connection.protocolVersion ?? "?"}/${agentStatus.data.expectedProtocolVersion ?? "?"} (${compatibility})`);
+    if (agentStatus.data.lifecycle) {
+      const lifecycle = agentStatus.data.lifecycle;
+      console.log("Lifecycle: " + lifecycle.state + (lifecycle.readyToRestart ? " (ready to restart)" : ""));
+      if (lifecycle.work?.total) console.log("ActiveWork: " + lifecycle.work.total);
+    }
   }
   console.log("Files:   " + config.allowedRoots);
   console.log("Desktop: " + (config.desktopEnabled === true ? "enabled" : "disabled"));
@@ -139,6 +151,31 @@ async function status() {
   }
   return 0;
 }
+async function lifecycleAction(action) {
+  const config = loadConfig();
+  if (!config) {
+    console.error("Chat Relay: not signed in");
+    return 1;
+  }
+  const result = await requestJson(config.relayUrl + "/relay?agentId=" + encodeURIComponent(config.agentId), {
+    method: "POST",
+    headers: { authorization: "Bearer " + config.userToken, "content-type": "application/json" },
+    body: JSON.stringify({ payload: { action: "agent.lifecycle." + action } }),
+  }).catch((error) => ({ response: { ok: false, status: 0 }, data: { error: error.message } }));
+  if (!result.response.ok) {
+    console.error("Lifecycle action failed: " + (result.data?.error || ("HTTP " + result.response.status)));
+    return 1;
+  }
+  const payload = result.data?.payload || result.data;
+  if (payload?.ok === false) {
+    console.error("Lifecycle action rejected: " + (payload.error || "unknown_error"));
+    if (payload.lifecycle?.work?.total) console.error("Active work remaining: " + payload.lifecycle.work.total);
+    return 1;
+  }
+  console.log("Agent lifecycle: " + (payload?.lifecycle?.state || "unknown"));
+  return 0;
+}
+
 async function logout() {
   const config = loadConfig();
   if (!config) {
@@ -190,6 +227,9 @@ export async function runCli(argv = process.argv.slice(2)) {
 
   if (command === "logout") return logout();
   if (command === "status") return status();
+  if (command === "drain") return lifecycleAction("drain");
+  if (command === "resume") return lifecycleAction("resume");
+  if (command === "restart") return lifecycleAction("restart");
   if (command === "remote") {
     await remote(options);
     return 0;

package/cli/remote.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadConfig, saveConfig } from "./config.mjs";
@@ -7,6 +7,32 @@ import { login, requestJson } from "./device-login.mjs";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 let stopping = false;
 
+export function shouldRestartAgent(result, stoppingNow = false) {
+  return !stoppingNow && result?.code !== 2 && result?.code !== 3;
+}
+
+export function protocolCompatibility(agentProtocolVersion, expectedProtocolVersion) {
+  if (agentProtocolVersion === null || agentProtocolVersion === undefined || expectedProtocolVersion === null || expectedProtocolVersion === undefined) return "unknown";
+  if (!Number.isInteger(Number(agentProtocolVersion)) || !Number.isInteger(Number(expectedProtocolVersion))) return "unknown";
+  return Number(agentProtocolVersion) === Number(expectedProtocolVersion) ? "compatible" : "incompatible";
+}
+
+function terminateChildTree(child) {
+  if (child.killed) return;
+  if (process.platform === "win32" && child.pid) {
+    const pid = child.pid;
+    execFile("taskkill.exe", ["/PID", String(pid), "/T"], { windowsHide: true }, () => {
+      setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) {
+          execFile("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }, () => {});
+        }
+      }, 1000);
+    });
+    return;
+  }
+  child.kill("SIGTERM");
+}
+
 async function validateConfig(config) {
   if (!config?.relayUrl || !config?.userToken || !config?.agentToken || !config?.agentId) return false;
   const { response } = await requestJson(`${config.relayUrl}/auth/me`, {
@@ -49,6 +75,7 @@ function spawnAgent(config) {
 }
 
 export async function remote(options = {}) {
+  stopping = false;
   let config = loadConfig();
   if (!(await validateConfig(config))) {
     console.log("No valid Chat Relay login found. Starting sign in...");
@@ -71,7 +98,7 @@ export async function remote(options = {}) {
 
     const stop = () => {
       stopping = true;
-      if (!child.killed) child.kill();
+      terminateChildTree(child);
     };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
@@ -84,10 +111,28 @@ export async function remote(options = {}) {
     process.removeListener("SIGTERM", stop);
     if (stopping) break;
 
-    console.error(
-      `Agent stopped (code=${result.code ?? "null"}, signal=${result.signal ?? "none"}). Restarting in 2s...`,
-    );
-    await new Promise((resolve) => setTimeout(resolve, 2000));
+    if (result.code === 2) {
+      stopping = true;
+      console.error("Agent authorization is no longer valid. Run chat-relay login --force, then chat-relay remote.");
+      break;
+    }
+    if (result.code === 3) {
+      stopping = true;
+      console.error("Agent protocol is incompatible with the relay. Update Chat Relay, then run chat-relay remote again.");
+      break;
+    }
+
+    if (result.code === 4) {
+      console.log("Agent restart requested. Restarting local agent...");
+      continue;
+    }
+
+    if (shouldRestartAgent(result, stopping)) {
+      console.error(
+        `Agent stopped (code=${result.code ?? "null"}, signal=${result.signal ?? "none"}). Restarting in 2s...`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
   }
 }