upfynai-code 3.0.3 → 3.1.0

package/src/connect.js

@@ -0,0 +1,416 @@
+import WebSocket from 'ws';
+import os from 'os';
+import { spawn } from 'child_process';
+import { promises as fsPromises, existsSync } from 'fs';
+import path, { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { readConfig, writeConfig, displayUrl } from './config.js';
+import { getToken, validateToken } from './auth.js';
+import { getPersistentShell } from './persistent-shell.js';
+import { needsPermission, requestPermission, handlePermissionResponse } from './permissions.js';
+import { playConnectAnimation } from './animation.js';
+
+// Optional node-pty for proper terminal emulation (graceful fallback to spawn)
+let pty;
+try { pty = (await import('node-pty')).default; } catch { pty = null; }
+
+// Resolve agents: dist/agents/ (npm package) or ../../shared/agents/ (monorepo)
+const __connectDir = dirname(fileURLToPath(import.meta.url));
+const _agentsPath = existsSync(join(__connectDir, '../dist/agents/index.js'))
+  ? '../dist/agents/index.js'
+  : '../../shared/agents/index.js';
+const { executeAction, isStreamingAction } = await import(_agentsPath);
+
+// Active process tracking (opencode pattern: activeRequests sync.Map)
+const activeProcesses = new Map(); // requestId → { proc, action }
+
+// Active shell sessions for relay terminal (shellSessionId → { proc })
+const activeShellSessions = new Map();
+
+/**
+ * Start an interactive shell session on the local machine, relayed to the browser.
+ * Uses node-pty for proper terminal emulation when available, falls back to spawn.
+ */
+function handleShellSessionStart(data, ws) {
+  const shellSessionId = data.requestId;
+  const projectPath = data.projectPath || process.cwd();
+  const isWin = process.platform === 'win32';
+  const shellType = data.shellType;
+  const cols = data.cols || 80;
+  const rows = data.rows || 24;
+
+  console.log(chalk.cyan(`  [relay] Starting shell session in ${projectPath}${pty ? ' (pty)' : ' (spawn)'}`));
+
+  let shellCmd, shellArgs;
+  const provider = data.provider || 'claude';
+  const isPlainShell = data.isPlainShell || (!!data.initialCommand && !data.hasSession) || provider === 'plain-shell';
+
+  function getInteractiveShell(projectDir) {
+    if (isWin) {
+      if (shellType === 'cmd') return { cmd: 'cmd.exe', args: [] };
+      return { cmd: 'powershell.exe', args: ['-NoExit'] };
+    }
+    const sh = shellType || process.env.SHELL || 'bash';
+    return { cmd: sh, args: ['--login'] };
+  }
+
+  function wrapCommand(command, projectDir) {
+    if (isWin) {
+      if (shellType === 'cmd') return { cmd: 'cmd.exe', args: ['/C', `cd /d "${projectDir}" && ${command}`] };
+      return { cmd: 'powershell.exe', args: ['-Command', `Set-Location -LiteralPath '${projectDir.replace(/'/g, "''")}'; ${command}`] };
+    }
+    const sh = shellType || 'bash';
+    return { cmd: sh, args: ['-c', `cd "${projectDir}" && ${command}`] };
+  }
+
+  if (isPlainShell && data.initialCommand) {
+    const s = wrapCommand(data.initialCommand, projectPath);
+    shellCmd = s.cmd; shellArgs = s.args;
+  } else if (isPlainShell) {
+    const s = getInteractiveShell(projectPath);
+    shellCmd = s.cmd; shellArgs = s.args;
+  } else if (provider === 'cursor') {
+    const cursorCmd = data.hasSession && data.sessionId
+      ? `cursor-agent --resume="${data.sessionId}"`
+      : 'cursor-agent';
+    const s = wrapCommand(cursorCmd, projectPath);
+    shellCmd = s.cmd; shellArgs = s.args;
+  } else {
+    const command = data.initialCommand || 'claude';
+    let claudeCmd;
+    if (isWin) {
+      claudeCmd = data.hasSession && data.sessionId
+        ? `claude --resume ${data.sessionId}`
+        : command;
+    } else {
+      claudeCmd = data.hasSession && data.sessionId
+        ? `claude --resume ${data.sessionId} || claude`
+        : command;
+    }
+    const s = wrapCommand(claudeCmd, projectPath);
+    shellCmd = s.cmd; shellArgs = s.args;
+  }
+
+  ws.send(JSON.stringify({ type: 'relay-shell-output', shellSessionId, data: '' }));
+
+  // Use node-pty for proper terminal emulation (resize, isatty, line discipline)
+  if (pty) {
+    const proc = pty.spawn(shellCmd, shellArgs, {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: projectPath,
+      env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor', FORCE_COLOR: '3' },
+    });
+
+    activeShellSessions.set(shellSessionId, { proc, projectPath, isPty: true });
+
+    proc.onData((chunk) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-output', shellSessionId, data: chunk }));
+      }
+    });
+
+    proc.onExit(({ exitCode }) => {
+      activeShellSessions.delete(shellSessionId);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-exited', shellSessionId, exitCode }));
+      }
+      console.log(chalk.dim(`  [relay] Shell session ended (code ${exitCode})`));
+    });
+  } else {
+    // Fallback: spawn without PTY (text wrapping may be incorrect)
+    const proc = spawn(shellCmd, shellArgs, {
+      cwd: projectPath,
+      env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor', FORCE_COLOR: '3', COLUMNS: String(cols), LINES: String(rows) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    activeShellSessions.set(shellSessionId, { proc, projectPath, isPty: false });
+
+    proc.stdout.on('data', (chunk) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-output', shellSessionId, data: chunk.toString() }));
+      }
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-output', shellSessionId, data: chunk.toString() }));
+      }
+    });
+
+    proc.on('close', (code) => {
+      activeShellSessions.delete(shellSessionId);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-exited', shellSessionId, exitCode: code }));
+      }
+      console.log(chalk.dim(`  [relay] Shell session ended (code ${code})`));
+    });
+
+    proc.on('error', (err) => {
+      activeShellSessions.delete(shellSessionId);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-shell-output', shellSessionId, data: `\r\n\x1b[31mError: ${err.message}\x1b[0m\r\n` }));
+      }
+    });
+  }
+}
+
+/**
+ * Build execution context for shared agents.
+ * Provides CLI-specific capabilities (persistent shell, process tracking, streaming).
+ */
+function buildAgentContext(requestId, ws) {
+  return {
+    requestId,
+    streamMode: 'structured',
+    getPersistentShell,
+    trackProcess: (id, entry) => activeProcesses.set(id, entry),
+    untrackProcess: (id) => activeProcesses.delete(id),
+    stream: (data) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'relay-stream', requestId, data }));
+      }
+    },
+  };
+}
+
+/**
+ * Handle incoming relay commands from the server.
+ * Delegates to shared agent modules for action execution.
+ */
+async function handleRelayCommand(data, ws) {
+  const { requestId, action } = data;
+
+  try {
+    // Permission gate (opencode pattern: dangerous actions require browser approval)
+    if (needsPermission(action, data)) {
+      const approved = await requestPermission(ws, requestId, action, data);
+      if (!approved) {
+        ws.send(JSON.stringify({ type: 'relay-response', requestId, error: 'Permission denied by user' }));
+        return;
+      }
+    }
+
+    const ctx = buildAgentContext(requestId, ws);
+
+    // For the exec action, params come from data.options in the old format
+    const params = action === 'exec'
+      ? { command: data.options?.command || data.command, timeout: data.options?.timeout || data.timeout, cwd: data.options?.cwd || data.cwd }
+      : data;
+
+    if (isStreamingAction(action)) {
+      // Streaming actions: agent calls ctx.stream() for chunks, returns on completion
+      const result = await executeAction(action, params, ctx);
+      ws.send(JSON.stringify({ type: 'relay-complete', requestId, exitCode: result.exitCode, sessionId: result.sessionId }));
+    } else {
+      // Sync actions: agent returns data directly
+      const result = await executeAction(action, params, ctx);
+      ws.send(JSON.stringify({ type: 'relay-response', requestId, data: result }));
+    }
+  } catch (err) {
+    ws.send(JSON.stringify({ type: 'relay-response', requestId, error: err.message }));
+  }
+}
+
+/**
+ * Connect to the remote server via WebSocket relay.
+ * Bridges local Claude Code, shell, filesystem, and git to the web UI.
+ */
+export async function connect(options = {}) {
+  const config = readConfig();
+  const serverUrl = options.server || config.serverUrl;
+  let relayKey = options.key;
+
+  if (!relayKey) {
+    const token = getToken();
+    if (!token) {
+      console.log(chalk.yellow('\n  No account found. Run `uc login` first.\n'));
+      process.exit(1);
+    }
+
+    console.log(chalk.dim('\n  Validating session...'));
+    const user = await validateToken();
+    if (!user) {
+      console.log(chalk.yellow('  Session expired. Run `uc login` to re-authenticate.\n'));
+      process.exit(1);
+    }
+
+    try {
+      const res = await fetch(`${serverUrl}/api/auth/connect-token`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!res.ok) throw new Error('Failed to get connect token');
+      const data = await res.json();
+      relayKey = data.token;
+    } catch (err) {
+      console.log(chalk.red('\n  Could not get connection token. Check your network and try again.\n'));
+      process.exit(1);
+    }
+  }
+
+  writeConfig({ relayKey });
+
+  const wsUrl = serverUrl.replace(/^http/, 'ws') + '/relay?token=' + encodeURIComponent(relayKey);
+
+  // Play spaceship launch animation
+  try { await playConnectAnimation(); } catch { /* cosmetic — don't block connect */ }
+
+  console.log(chalk.bold('\n  Upfyn-Code Relay Client\n'));
+  console.log(`  Server:  ${chalk.cyan(displayUrl(serverUrl))}`);
+  console.log(`  Machine: ${chalk.dim(os.hostname())}`);
+  console.log(`  User:    ${chalk.dim(os.userInfo().username)}\n`);
+
+  let reconnectAttempts = 0;
+  const MAX_RECONNECT = 10;
+
+  function doConnect() {
+    const ws = new WebSocket(wsUrl, {
+      headers: {
+        'x-upfyn-machine': os.hostname(),
+        'x-upfyn-platform': process.platform,
+        'x-upfyn-cwd': process.cwd(),
+      },
+    });
+
+    // Respond to native WebSocket pings from server (Railway proxy keepalive)
+    ws.on('ping', () => { try { ws.pong(); } catch { /* ignore */ } });
+
+    ws.on('open', () => {
+      reconnectAttempts = 0;
+      console.log(chalk.green('  Connected! Your local machine is now bridged to the server.'));
+      console.log(chalk.dim('  Claude Code is the AI brain. Press Ctrl+C to disconnect.\n'));
+
+      const cwd = process.cwd();
+      const dirName = path.basename(cwd);
+      ws.send(JSON.stringify({
+        type: 'relay-init', cwd, dirName,
+        homedir: os.homedir(), platform: process.platform, hostname: os.hostname(),
+      }));
+      console.log(chalk.dim(`  Default project: ${cwd}\n`));
+
+      const heartbeat = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'ping' }));
+          try { ws.ping(); } catch { /* ignore */ }
+        }
+      }, 20000);
+      ws.on('close', () => clearInterval(heartbeat));
+    });
+
+    ws.on('message', (rawMessage) => {
+      try {
+        const data = JSON.parse(rawMessage);
+
+        if (data.type === 'relay-connected') {
+          console.log(chalk.green(`  ${data.message}`));
+          return;
+        }
+        if (data.type === 'relay-command') {
+          if (data.action === 'shell-session-start') {
+            handleShellSessionStart(data, ws);
+          } else {
+            handleRelayCommand(data, ws);
+          }
+          return;
+        }
+        if (data.type === 'relay-abort') {
+          const entry = activeProcesses.get(data.requestId);
+          if (entry?.instance?.interrupt) {
+            // SDK query instance — use interrupt()
+            entry.instance.interrupt().catch(() => {});
+            activeProcesses.delete(data.requestId);
+            ws.send(JSON.stringify({ type: 'relay-complete', requestId: data.requestId, exitCode: -1, aborted: true }));
+            console.log(chalk.yellow('  [relay] SDK session interrupted by user'));
+          } else if (entry?.proc) {
+            // Legacy subprocess — use kill()
+            entry.proc.kill('SIGTERM');
+            activeProcesses.delete(data.requestId);
+            ws.send(JSON.stringify({ type: 'relay-complete', requestId: data.requestId, exitCode: -1, aborted: true }));
+            console.log(chalk.yellow('  [relay] Process aborted by user'));
+          }
+          return;
+        }
+        if (data.type === 'relay-permission-response') {
+          handlePermissionResponse(data);
+          return;
+        }
+        if (data.type === 'relay-shell-input') {
+          const session = activeShellSessions.get(data.shellSessionId);
+          if (session) {
+            if (session.isPty) {
+              session.proc.write(data.data);
+            } else if (session.proc?.stdin?.writable) {
+              session.proc.stdin.write(data.data);
+            }
+          }
+          return;
+        }
+        if (data.type === 'relay-shell-resize') {
+          const session = activeShellSessions.get(data.shellSessionId);
+          if (session?.isPty && session.proc?.resize) {
+            try { session.proc.resize(data.cols || 80, data.rows || 24); } catch { /* ignore resize errors */ }
+          }
+          return;
+        }
+        if (data.type === 'relay-shell-kill') {
+          const session = activeShellSessions.get(data.shellSessionId);
+          if (session?.proc) {
+            if (session.isPty) {
+              session.proc.kill();
+            } else {
+              session.proc.kill('SIGTERM');
+            }
+            activeShellSessions.delete(data.shellSessionId);
+            console.log(chalk.dim('  [relay] Shell session killed'));
+          }
+          return;
+        }
+        if (data.type === 'pong') return;
+        if (data.type === 'server-ping') {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'server-pong' }));
+          }
+          return;
+        }
+        if (data.type === 'error') {
+          console.error(chalk.red(`  Server error: ${data.error}`));
+          return;
+        }
+      } catch (e) {
+        // message parse error
+      }
+    });
+
+    ws.on('close', (code) => {
+      if (code === 1000) {
+        console.log(chalk.dim('  Disconnected.'));
+        process.exit(0);
+      }
+      reconnectAttempts++;
+      if (reconnectAttempts <= MAX_RECONNECT) {
+        const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+        console.log(chalk.dim(`  Connection lost. Reconnecting in ${delay / 1000}s... (${reconnectAttempts}/${MAX_RECONNECT})`));
+        setTimeout(doConnect, delay);
+      } else {
+        console.error(chalk.red('  Max reconnection attempts reached. Exiting.'));
+        process.exit(1);
+      }
+    });
+
+    ws.on('error', (err) => {
+      if (err.code === 'ECONNREFUSED') {
+        console.error(chalk.red(`  Cannot reach ${displayUrl(serverUrl)}. Is the server running?`));
+      }
+    });
+  }
+
+  doConnect();
+
+  process.on('SIGINT', () => {
+    console.log(chalk.dim('\n  Disconnecting...'));
+    process.exit(0);
+  });
+}

package/src/launch.js

@@ -0,0 +1,81 @@
+import open from 'open';
+import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { readConfig } from './config.js';
+import { getToken, validateToken } from './auth.js';
+import { startServer } from './server.js';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function openHosted() {
+  const token = getToken();
+
+  if (!token) {
+    console.log(chalk.yellow('\n  No account found. Run `uc login` first.\n'));
+    process.exit(1);
+  }
+
+  console.log(chalk.dim('\n  Validating session...'));
+  const user = await validateToken();
+
+  if (!user) {
+    console.log(chalk.yellow('  Session expired. Run `uc login` to re-authenticate.\n'));
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  const url = `${config.serverUrl}?token=${encodeURIComponent(token)}`;
+
+  const name = user.first_name || user.username;
+  console.log(chalk.green(`  Welcome back, ${chalk.bold(name)}!`));
+  console.log(chalk.dim('  Opening Upfyn-Code in your browser...\n'));
+
+  await open(url);
+}
+
+export async function startLocal() {
+  const config = readConfig();
+  const port = config.localPort || 3001;
+
+  console.log(chalk.dim('\n  Starting local server...'));
+
+  // Try bundled local-server first (npm installs), then monorepo path
+  const bundledPath = join(__dirname, '../dist/local-server.js');
+  const monoRepoPath = join(__dirname, '../../local-server/index.js');
+  const localServerPath = existsSync(bundledPath) ? bundledPath : monoRepoPath;
+
+  try {
+    // Dynamically import the local server
+    process.env.PORT = String(port);
+    await import(localServerPath);
+
+    // Auto-open browser after server starts
+    setTimeout(async () => {
+      const url = `http://localhost:${port}/app/`;
+      console.log(chalk.dim(`  Opening ${url} in browser...\n`));
+      await open(url);
+    }, 2000);
+  } catch (err) {
+    // Fallback: if local-server fails (missing deps), use the old proxy approach
+    console.log(chalk.dim(`  Local server not available (${err.message}), falling back to proxy mode...`));
+
+    const token = getToken();
+    if (!token) {
+      console.log(chalk.yellow('\n  No account found. Run `uc login` first.\n'));
+      process.exit(1);
+    }
+
+    const user = await validateToken();
+    if (!user) {
+      console.log(chalk.yellow('  Session expired. Run `uc login` to re-authenticate.\n'));
+      process.exit(1);
+    }
+
+    const name = user.first_name || user.username;
+    console.log(chalk.green(`  Welcome back, ${chalk.bold(name)}!`));
+    await startServer(port, config.serverUrl, token);
+  }
+}

package/src/mcp.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { readConfig } from './config.js';
+import { getToken, validateToken } from './auth.js';
+
+/**
+ * Print MCP configuration for Claude / Cursor / other AI tools.
+ * Optionally accepts --server and --key overrides.
+ */
+export async function mcp(options = {}) {
+  const config = readConfig();
+  const serverUrl = options.server || config.serverUrl;
+  let relayKey = options.key;
+
+  // If no key provided, fetch one using auth token
+  if (!relayKey) {
+    const token = getToken();
+    if (!token) {
+      console.log(chalk.yellow('\n  No account found. Run `uc login` first.\n'));
+      process.exit(1);
+    }
+
+    const user = await validateToken();
+    if (!user) {
+      console.log(chalk.yellow('\n  Session expired. Run `uc login` to re-authenticate.\n'));
+      process.exit(1);
+    }
+
+    try {
+      const res = await fetch(`${serverUrl}/api/auth/connect-token`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!res.ok) throw new Error('Failed to get connect token');
+      const data = await res.json();
+      relayKey = data.token;
+    } catch (err) {
+      console.log(chalk.red('\n  Could not get connection token. Check your network and try again.\n'));
+      process.exit(1);
+    }
+  }
+
+  const mcpConfig = {
+    mcpServers: {
+      'upfynai-code': {
+        url: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${relayKey}`,
+        },
+      },
+    },
+  };
+
+  console.log(chalk.bold('\n  Upfyn-Code — MCP Integration\n'));
+  console.log(chalk.dim('  Add this to your Claude / Cursor MCP settings:\n'));
+  console.log(chalk.white(JSON.stringify(mcpConfig, null, 2)));
+  console.log('');
+  console.log(chalk.dim('  The JSON above contains your MCP URL and authorization header.\n'));
+}

package/src/permissions.js

@@ -0,0 +1,140 @@
+/**
+ * Permission-Gated Tool Execution
+ * Ported from opencode-ai/opencode internal/permission/permission.go
+ *
+ * Splits relay actions into safe (auto-approve) and dangerous (require browser approval).
+ * Permission requests are sent to the server → browser, and we wait for the response.
+ */
+
+// Safe actions — auto-approved, read-only (opencode pattern: tools without permission flag)
+const SAFE_ACTIONS = new Set([
+  'file-read',
+  'file-tree',
+  'browse-dirs',
+  'validate-path',
+  'detect-agents',
+]);
+
+// Dangerous actions — require user approval (opencode pattern: tools with permission flag)
+const DANGEROUS_ACTIONS = new Set([
+  'shell-command',
+  'file-write',
+  'create-folder',
+  'git-operation',
+]);
+
+// Safe shell command prefixes — auto-approved even within shell-command
+// (opencode pattern: safe bash commands bypass permission)
+const SAFE_SHELL_PREFIXES = [
+  'ls', 'dir', 'pwd', 'echo', 'cat', 'head', 'tail', 'wc',
+  'git status', 'git log', 'git diff', 'git branch', 'git remote',
+  'node --version', 'npm --version', 'python --version',
+  'which', 'where', 'type', 'whoami', 'hostname',
+  'date', 'uptime', 'df', 'free',
+];
+
+// Pending permission requests: requestId → { resolve }
+const pendingPermissions = new Map();
+
+/**
+ * Check if an action needs user permission.
+ * @param {string} action - Relay action type
+ * @param {object} payload - Action payload
+ * @returns {boolean}
+ */
+export function needsPermission(action, payload) {
+  if (SAFE_ACTIONS.has(action)) return false;
+  if (!DANGEROUS_ACTIONS.has(action)) return false; // unknown actions handled elsewhere
+
+  // Shell commands: check if it's a safe read-only command
+  if (action === 'shell-command' && payload?.command) {
+    const cmd = payload.command.trim().toLowerCase();
+    if (SAFE_SHELL_PREFIXES.some(prefix => cmd.startsWith(prefix))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Request permission from the browser via the relay WebSocket.
+ * Blocks until the user approves or denies.
+ *
+ * @param {WebSocket} ws - Relay WebSocket connection
+ * @param {string} requestId - Relay request ID
+ * @param {string} action - Action being requested
+ * @param {object} payload - Action payload
+ * @param {number} timeoutMs - Timeout for waiting (default 60s)
+ * @returns {Promise<boolean>} - true if approved, false if denied
+ */
+export function requestPermission(ws, requestId, action, payload, timeoutMs = 60000) {
+  return new Promise((resolve) => {
+    const permId = `perm-${requestId}`;
+
+    const timeout = setTimeout(() => {
+      pendingPermissions.delete(permId);
+      resolve(false); // Timeout = deny
+    }, timeoutMs);
+
+    pendingPermissions.set(permId, {
+      resolve: (approved) => {
+        clearTimeout(timeout);
+        pendingPermissions.delete(permId);
+        resolve(approved);
+      },
+    });
+
+    // Send permission request to server → browser
+    ws.send(JSON.stringify({
+      type: 'relay-permission-request',
+      requestId,
+      permissionId: permId,
+      action,
+      description: describeAction(action, payload),
+      payload: sanitizePayload(action, payload),
+    }));
+  });
+}
+
+/**
+ * Handle a permission response from the server.
+ * @param {object} data - { permissionId, approved }
+ */
+export function handlePermissionResponse(data) {
+  const pending = pendingPermissions.get(data.permissionId);
+  if (pending) {
+    pending.resolve(Boolean(data.approved));
+  }
+}
+
+/**
+ * Generate a human-readable description of the action.
+ */
+function describeAction(action, payload) {
+  switch (action) {
+    case 'shell-command':
+      return `Execute command: ${payload?.command || '(unknown)'}`;
+    case 'file-write':
+      return `Write to file: ${payload?.filePath || '(unknown)'}`;
+    case 'create-folder':
+      return `Create folder: ${payload?.folderPath || '(unknown)'}`;
+    case 'git-operation':
+      return `Run git: ${payload?.gitCommand || '(unknown)'}`;
+    default:
+      return `${action}: ${JSON.stringify(payload || {}).slice(0, 200)}`;
+  }
+}
+
+/**
+ * Sanitize payload for display — remove large content fields.
+ */
+function sanitizePayload(action, payload) {
+  if (!payload) return {};
+  const safe = { ...payload };
+  // Don't send file content to browser for permission display
+  if (safe.content && safe.content.length > 500) {
+    safe.content = safe.content.slice(0, 500) + `... (${safe.content.length} chars total)`;
+  }
+  return safe;
+}