upfynai-code 2.6.7 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upfynai-code",
-  "version": "2.6.7",
+  "version": "2.7.0",
   "description": "Unified AI coding interface — access AI chat, terminal, file explorer, git, and visual canvas from any browser. Connect your local machine and code from anywhere.",
   "type": "module",
   "bin": {

package/src/connect.js

@@ -6,6 +6,139 @@ import path from 'path';
 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';
+
+// 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.
+ * Spawns a PTY-like process and streams I/O via WebSocket.
+ */
+function handleShellSessionStart(data, ws) {
+  const shellSessionId = data.requestId;
+  const projectPath = data.projectPath || process.cwd();
+  const isWin = process.platform === 'win32';
+
+  console.log(chalk.cyan(`  [relay] Starting shell session in ${projectPath}`));
+
+  // Build the shell command
+  let shellCmd, shellArgs;
+  const provider = data.provider || 'claude';
+  const isPlainShell = data.isPlainShell || (!!data.initialCommand && !data.hasSession) || provider === 'plain-shell';
+
+  if (isPlainShell && data.initialCommand) {
+    // Run a specific command
+    if (isWin) {
+      shellCmd = 'powershell.exe';
+      shellArgs = ['-Command', `Set-Location -Path "${projectPath}"; ${data.initialCommand}`];
+    } else {
+      shellCmd = 'bash';
+      shellArgs = ['-c', `cd "${projectPath}" && ${data.initialCommand}`];
+    }
+  } else if (isPlainShell) {
+    // Interactive shell
+    if (isWin) {
+      shellCmd = 'powershell.exe';
+      shellArgs = ['-NoExit', '-Command', `Set-Location -Path "${projectPath}"`];
+    } else {
+      shellCmd = process.env.SHELL || 'bash';
+      shellArgs = ['--login'];
+    }
+  } else if (provider === 'cursor') {
+    if (isWin) {
+      shellCmd = 'powershell.exe';
+      const cursorCmd = data.hasSession && data.sessionId
+        ? `cursor-agent --resume="${data.sessionId}"`
+        : 'cursor-agent';
+      shellArgs = ['-Command', `Set-Location -Path "${projectPath}"; ${cursorCmd}`];
+    } else {
+      shellCmd = 'bash';
+      const cursorCmd = data.hasSession && data.sessionId
+        ? `cursor-agent --resume="${data.sessionId}"`
+        : 'cursor-agent';
+      shellArgs = ['-c', `cd "${projectPath}" && ${cursorCmd}`];
+    }
+  } else {
+    // Claude (default)
+    const command = data.initialCommand || 'claude';
+    if (isWin) {
+      shellCmd = 'powershell.exe';
+      const claudeCmd = data.hasSession && data.sessionId
+        ? `claude --resume ${data.sessionId}`
+        : command;
+      shellArgs = ['-Command', `Set-Location -Path "${projectPath}"; ${claudeCmd}`];
+    } else {
+      shellCmd = 'bash';
+      const claudeCmd = data.hasSession && data.sessionId
+        ? `claude --resume ${data.sessionId} || claude`
+        : command;
+      shellArgs = ['-c', `cd "${projectPath}" && ${claudeCmd}`];
+    }
+  }
+
+  const proc = spawn(shellCmd, shellArgs, {
+    cwd: isPlainShell && !data.initialCommand ? projectPath : undefined,
+    env: {
+      ...process.env,
+      TERM: 'xterm-256color',
+      COLORTERM: 'truecolor',
+      FORCE_COLOR: '3',
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  activeShellSessions.set(shellSessionId, { proc, projectPath });
+
+  // Stream stdout → browser via relay
+  proc.stdout.on('data', (chunk) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({
+        type: 'relay-shell-output',
+        shellSessionId,
+        data: chunk.toString(),
+      }));
+    }
+  });
+
+  // Stream stderr → browser via relay
+  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`,
+      }));
+    }
+  });
+}
 
 /**
  * Execute a shell command and return stdout
@@ -71,12 +204,25 @@ 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;
+      }
+    }
+
     switch (action) {
       case 'claude-query': {
         const { command, options } = data;
         console.log(chalk.cyan('  [relay] Processing Claude query...'));
 
-        const args = ['--print'];
+        // Stream-JSON mode for real-time token streaming (opencode pattern)
+        const args = ['-p', '--output-format', 'stream-json', '--include-partial-messages'];
         if (options?.projectPath) args.push('--cwd', options.projectPath);
         if (options?.sessionId) args.push('--continue', options.sessionId);
 
@@ -86,29 +232,75 @@ async function handleRelayCommand(data, ws) {
           env: process.env,
         });
 
+        // Track for abort support (opencode pattern: activeRequests)
+        activeProcesses.set(requestId, { proc, action: 'claude-query' });
+
+        let stdoutBuffer = '';
+        let capturedSessionId = null;
+
+        // Parse NDJSON line-by-line (same pattern as cursor-cli.js)
         proc.stdout.on('data', (chunk) => {
-          ws.send(JSON.stringify({
-            type: 'relay-stream',
-            requestId,
-            data: { type: 'claude-response', content: chunk.toString() },
-          }));
+          stdoutBuffer += chunk.toString();
+          const lines = stdoutBuffer.split('\n');
+          stdoutBuffer = lines.pop(); // keep incomplete last line in buffer
+
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const evt = JSON.parse(line);
+
+              if (evt.type === 'system' && evt.subtype === 'init') {
+                // Capture session ID for resume support
+                if (evt.session_id) capturedSessionId = evt.session_id;
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-system', sessionId: evt.session_id, model: evt.model, cwd: evt.cwd },
+                }));
+              } else if (evt.type === 'assistant' && evt.message?.content?.length) {
+                // Real-time text delta
+                const text = evt.message.content[0].text || '';
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-response', content: text },
+                }));
+              } else if (evt.type === 'result') {
+                // Session complete — include captured session ID
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-result', sessionId: capturedSessionId, subtype: evt.subtype },
+                }));
+              }
+            } catch {
+              // Non-JSON line — send as raw text
+              if (line.trim()) {
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-response', content: line },
+                }));
+              }
+            }
+          }
         });
 
         proc.stderr.on('data', (chunk) => {
           ws.send(JSON.stringify({
-            type: 'relay-stream',
-            requestId,
+            type: 'relay-stream', requestId,
             data: { type: 'claude-error', content: chunk.toString() },
           }));
         });
 
         proc.on('close', (code) => {
+          activeProcesses.delete(requestId);
           ws.send(JSON.stringify({
-            type: 'relay-complete',
-            requestId,
+            type: 'relay-complete', requestId,
             exitCode: code,
+            sessionId: capturedSessionId,
           }));
         });
+
+        proc.on('error', () => {
+          activeProcesses.delete(requestId);
+        });
         break;
       }
 
@@ -123,8 +315,13 @@ async function handleRelayCommand(data, ws) {
         ];
         if (dangerous.some(d => cmdLower.includes(d.toLowerCase()))) throw new Error('Command blocked for safety');
         console.log(chalk.dim('  [relay] Executing shell command...'));
-        const result = await execCommand(cmd, [], { cwd: cwd || process.cwd(), timeout: 60000 });
-        ws.send(JSON.stringify({ type: 'relay-response', requestId, data: { stdout: result } }));
+        // Persistent shell singleton (opencode pattern: commands share one shell process)
+        const shell = getPersistentShell(cwd || process.cwd());
+        const result = await shell.exec(cmd, { timeoutMs: 60000 });
+        ws.send(JSON.stringify({
+          type: 'relay-response', requestId,
+          data: { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, cwd: result.cwd },
+        }));
         break;
       }
 
@@ -175,12 +372,26 @@ async function handleRelayCommand(data, ws) {
         else if (targetDir.startsWith('~/') || targetDir.startsWith('~\\')) targetDir = path.join(os.default.homedir(), targetDir.slice(2));
         targetDir = path.resolve(targetDir);
 
+        let dirs = [];
+        // On Windows, detect available drives to show alongside directory listing
+        let drives = [];
+        if (process.platform === 'win32') {
+          try {
+            const { execSync } = await import('child_process');
+            const wmicOut = execSync('wmic logicaldisk get name', { encoding: 'utf8', timeout: 5000 });
+            drives = wmicOut.split('\n')
+              .map(l => l.trim())
+              .filter(l => /^[A-Z]:$/.test(l))
+              .map(d => ({ name: d + '\\', path: d + '\\', type: 'drive' }));
+          } catch { /* ignore — wmic not available */ }
+        }
+
         const entries = await fsPromises.readdir(targetDir, { withFileTypes: true });
-        const dirs = entries
+        dirs = entries
           .filter(e => e.isDirectory() && !e.name.startsWith('.'))
           .map(e => ({ name: e.name, path: path.join(targetDir, e.name), type: 'directory' }))
           .sort((a, b) => a.name.localeCompare(b.name));
-        ws.send(JSON.stringify({ type: 'relay-response', requestId, data: { path: targetDir, suggestions: dirs, homedir: os.default.homedir() } }));
+        ws.send(JSON.stringify({ type: 'relay-response', requestId, data: { path: targetDir, suggestions: dirs, drives, homedir: os.default.homedir() } }));
         break;
       }
 
@@ -202,6 +413,20 @@ async function handleRelayCommand(data, ws) {
         break;
       }
 
+      case 'create-folder': {
+        // Create a directory on user's machine
+        const { folderPath } = data;
+        const os3 = await import('os');
+        let mkPath = folderPath || '';
+        if (mkPath === '~') mkPath = os3.default.homedir();
+        else if (mkPath.startsWith('~/') || mkPath.startsWith('~\\')) mkPath = path.join(os3.default.homedir(), mkPath.slice(2));
+        mkPath = path.resolve(mkPath);
+
+        await fsPromises.mkdir(mkPath, { recursive: true });
+        ws.send(JSON.stringify({ type: 'relay-response', requestId, data: { success: true, path: mkPath } }));
+        break;
+      }
+
       case 'git-operation': {
         const { gitCommand, cwd: gitCwd } = data;
         console.log(chalk.dim('  [relay] Running git operation...'));
@@ -211,6 +436,68 @@ async function handleRelayCommand(data, ws) {
         break;
       }
 
+      // Sub-agent: read-only research agent (opencode pattern: AgentTask)
+      // Spawns a separate claude process with --allowedTools limited to read-only
+      case 'claude-task-query': {
+        const { command: taskCmd, options: taskOpts } = data;
+        console.log(chalk.cyan('  [relay] Spawning sub-agent for research...'));
+
+        const taskArgs = ['-p', '--output-format', 'stream-json', '--include-partial-messages'];
+        // Sub-agents are read-only: use --allowedTools to restrict
+        taskArgs.push('--allowedTools', 'View,Glob,Grep,LS,Read');
+        if (taskOpts?.projectPath) taskArgs.push('--cwd', taskOpts.projectPath);
+        // Sub-agents always start fresh (no --continue)
+
+        const taskProc = spawn('claude', [...taskArgs, taskCmd || ''], {
+          shell: true,
+          cwd: taskOpts?.projectPath || os.homedir(),
+          env: process.env,
+        });
+
+        activeProcesses.set(requestId, { proc: taskProc, action: 'claude-task-query' });
+        let taskBuffer = '';
+
+        taskProc.stdout.on('data', (chunk) => {
+          taskBuffer += chunk.toString();
+          const lines = taskBuffer.split('\n');
+          taskBuffer = lines.pop();
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const evt = JSON.parse(line);
+              if (evt.type === 'assistant' && evt.message?.content?.length) {
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-response', content: evt.message.content[0].text || '' },
+                }));
+              }
+            } catch {
+              if (line.trim()) {
+                ws.send(JSON.stringify({
+                  type: 'relay-stream', requestId,
+                  data: { type: 'claude-response', content: line },
+                }));
+              }
+            }
+          }
+        });
+
+        taskProc.stderr.on('data', (chunk) => {
+          ws.send(JSON.stringify({
+            type: 'relay-stream', requestId,
+            data: { type: 'claude-error', content: chunk.toString() },
+          }));
+        });
+
+        taskProc.on('close', (code) => {
+          activeProcesses.delete(requestId);
+          ws.send(JSON.stringify({ type: 'relay-complete', requestId, exitCode: code }));
+        });
+
+        taskProc.on('error', () => { activeProcesses.delete(requestId); });
+        break;
+      }
+
       default:
         ws.send(JSON.stringify({
           type: 'relay-response',
@@ -286,6 +573,19 @@ export async function connect(options = {}) {
       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'));
 
+      // Send initial working directory so it becomes the default project
+      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' }));
@@ -307,6 +607,51 @@ export async function connect(options = {}) {
           handleRelayCommand(data, ws);
           return;
         }
+        // Abort handler (opencode pattern: cancel via context propagation)
+        if (data.type === 'relay-abort') {
+          const entry = activeProcesses.get(data.requestId);
+          if (entry?.proc) {
+            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;
+        }
+        // Permission response from browser (opencode pattern: grant/deny flow)
+        if (data.type === 'relay-permission-response') {
+          handlePermissionResponse(data);
+          return;
+        }
+        // ── Relay Shell: interactive terminal on local machine ──────────
+        if (data.type === 'relay-command' && data.action === 'shell-session-start') {
+          handleShellSessionStart(data, ws);
+          return;
+        }
+        if (data.type === 'relay-shell-input') {
+          const session = activeShellSessions.get(data.shellSessionId);
+          if (session?.proc?.stdin?.writable) {
+            session.proc.stdin.write(data.data);
+          }
+          return;
+        }
+        if (data.type === 'relay-shell-resize') {
+          // PTY resize not available with basic spawn — ignored for non-pty
+          return;
+        }
+        if (data.type === 'relay-shell-kill') {
+          const session = activeShellSessions.get(data.shellSessionId);
+          if (session?.proc) {
+            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 === 'error') {
           console.error(chalk.red(`  Server error: ${data.error}`));

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;
+}

package/src/persistent-shell.js

@@ -0,0 +1,261 @@
+/**
+ * Persistent Shell Singleton
+ * Ported from opencode-ai/opencode internal/llm/tools/shell/shell.go
+ *
+ * Maintains a single long-running shell process across commands.
+ * - Commands are queued and executed sequentially
+ * - Environment and cwd persist between commands
+ * - Child processes can be killed on abort
+ * - Shell respawns automatically if it dies
+ */
+import { spawn, execSync } from 'child_process';
+import os from 'os';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+let shellInstance = null;
+
+/**
+ * Get or create the persistent shell singleton.
+ * @param {string} workingDir - Initial working directory
+ * @returns {PersistentShell}
+ */
+export function getPersistentShell(workingDir) {
+  if (!shellInstance || !shellInstance.isAlive) {
+    shellInstance = new PersistentShell(workingDir || os.homedir());
+  }
+  return shellInstance;
+}
+
+class PersistentShell {
+  constructor(cwd) {
+    this.cwd = cwd;
+    this.isAlive = false;
+    this.commandQueue = [];
+    this.processing = false;
+    this.proc = null;
+    this.stdin = null;
+    this._start();
+  }
+
+  _start() {
+    const isWin = process.platform === 'win32';
+    const shellPath = isWin
+      ? process.env.COMSPEC || 'cmd.exe'
+      : process.env.SHELL || '/bin/bash';
+    const shellArgs = isWin ? ['/Q'] : ['-l'];
+
+    this.proc = spawn(shellPath, shellArgs, {
+      cwd: this.cwd,
+      env: { ...process.env, GIT_EDITOR: 'true' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: false,
+    });
+
+    this.stdin = this.proc.stdin;
+    this.isAlive = true;
+
+    this.proc.on('close', () => {
+      this.isAlive = false;
+      // Reject any queued commands
+      for (const queued of this.commandQueue) {
+        queued.reject(new Error('Shell process died'));
+      }
+      this.commandQueue = [];
+    });
+
+    this.proc.on('error', () => {
+      this.isAlive = false;
+    });
+  }
+
+  /**
+   * Execute a command in the persistent shell.
+   * Queued and executed sequentially (opencode pattern: commandQueue channel).
+   *
+   * @param {string} command - Shell command to execute
+   * @param {object} opts - { timeoutMs, abortSignal }
+   * @returns {Promise<{ stdout, stderr, exitCode, interrupted, cwd }>}
+   */
+  exec(command, opts = {}) {
+    return new Promise((resolve, reject) => {
+      this.commandQueue.push({ command, opts, resolve, reject });
+      this._processNext();
+    });
+  }
+
+  async _processNext() {
+    if (this.processing || this.commandQueue.length === 0) return;
+    this.processing = true;
+
+    const { command, opts, resolve, reject } = this.commandQueue.shift();
+
+    try {
+      const result = await this._execCommand(command, opts);
+      resolve(result);
+    } catch (err) {
+      reject(err);
+    } finally {
+      this.processing = false;
+      // Process next in queue
+      if (this.commandQueue.length > 0) {
+        this._processNext();
+      }
+    }
+  }
+
+  async _execCommand(command, { timeoutMs = 60000, abortSignal } = {}) {
+    if (!this.isAlive) {
+      throw new Error('Shell is not alive');
+    }
+
+    const isWin = process.platform === 'win32';
+    const tmpDir = os.tmpdir();
+    const ts = Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+    const stdoutFile = path.join(tmpDir, `uc-stdout-${ts}`);
+    const stderrFile = path.join(tmpDir, `uc-stderr-${ts}`);
+    const statusFile = path.join(tmpDir, `uc-status-${ts}`);
+    const cwdFile = path.join(tmpDir, `uc-cwd-${ts}`);
+
+    try {
+      // Build the shell command that redirects output to temp files
+      // Exact same pattern as opencode's shell.go execCommand
+      let fullCommand;
+      if (isWin) {
+        // Windows cmd.exe variant
+        fullCommand = [
+          `${command} > "${stdoutFile}" 2> "${stderrFile}"`,
+          `echo %ERRORLEVEL% > "${statusFile}"`,
+          `cd > "${cwdFile}"`,
+        ].join(' & ');
+      } else {
+        // Unix bash variant (identical to opencode)
+        const escaped = command.replace(/'/g, "'\\''");
+        fullCommand = [
+          `eval '${escaped}' < /dev/null > '${stdoutFile}' 2> '${stderrFile}'`,
+          `EXEC_EXIT_CODE=$?`,
+          `pwd > '${cwdFile}'`,
+          `echo $EXEC_EXIT_CODE > '${statusFile}'`,
+        ].join('\n');
+      }
+
+      this.stdin.write(fullCommand + '\n');
+
+      // Poll for status file (same polling pattern as opencode)
+      let interrupted = false;
+      const startTime = Date.now();
+
+      await new Promise((done, fail) => {
+        const poll = setInterval(async () => {
+          // Check abort
+          if (abortSignal?.aborted) {
+            this.killChildren();
+            interrupted = true;
+            clearInterval(poll);
+            done();
+            return;
+          }
+
+          // Check timeout
+          if (timeoutMs > 0 && Date.now() - startTime > timeoutMs) {
+            this.killChildren();
+            interrupted = true;
+            clearInterval(poll);
+            done();
+            return;
+          }
+
+          // Check if status file exists and has content
+          try {
+            const stat = await fs.stat(statusFile);
+            if (stat.size > 0) {
+              clearInterval(poll);
+              done();
+            }
+          } catch {
+            // File doesn't exist yet
+          }
+        }, 50);
+      });
+
+      // Read results from temp files
+      const stdout = await this._readFileOrEmpty(stdoutFile);
+      const stderr = await this._readFileOrEmpty(stderrFile);
+      const exitCodeStr = await this._readFileOrEmpty(statusFile);
+      const newCwd = await this._readFileOrEmpty(cwdFile);
+
+      let exitCode = 0;
+      if (exitCodeStr.trim()) {
+        exitCode = parseInt(exitCodeStr.trim(), 10) || 0;
+      } else if (interrupted) {
+        exitCode = 143;
+      }
+
+      if (newCwd.trim()) {
+        this.cwd = newCwd.trim();
+      }
+
+      return {
+        stdout: stdout,
+        stderr: interrupted ? stderr + '\nCommand execution timed out or was interrupted' : stderr,
+        exitCode,
+        interrupted,
+        cwd: this.cwd,
+      };
+    } finally {
+      // Cleanup temp files
+      await Promise.all([
+        fs.unlink(stdoutFile).catch(() => {}),
+        fs.unlink(stderrFile).catch(() => {}),
+        fs.unlink(statusFile).catch(() => {}),
+        fs.unlink(cwdFile).catch(() => {}),
+      ]);
+    }
+  }
+
+  /**
+   * Kill child processes of the shell (opencode pattern: killChildren).
+   * On Unix: pgrep -P <pid> → SIGTERM each child.
+   * On Windows: taskkill /PID /T.
+   */
+  killChildren() {
+    if (!this.proc?.pid) return;
+    try {
+      if (process.platform === 'win32') {
+        execSync(`taskkill /PID ${this.proc.pid} /T /F`, { stdio: 'ignore', timeout: 5000 });
+        // Respawn since taskkill kills the parent too on Windows
+        this._start();
+      } else {
+        const output = execSync(`pgrep -P ${this.proc.pid}`, { encoding: 'utf8', timeout: 5000 });
+        for (const line of output.split('\n')) {
+          const pid = parseInt(line.trim(), 10);
+          if (pid > 0) {
+            try { process.kill(pid, 'SIGTERM'); } catch { /* already dead */ }
+          }
+        }
+      }
+    } catch {
+      // pgrep/taskkill failed — no children to kill
+    }
+  }
+
+  /**
+   * Close the persistent shell.
+   */
+  close() {
+    if (!this.isAlive) return;
+    try {
+      this.stdin.write('exit\n');
+      this.proc.kill('SIGTERM');
+    } catch { /* ignore */ }
+    this.isAlive = false;
+  }
+
+  async _readFileOrEmpty(filePath) {
+    try {
+      return await fs.readFile(filePath, 'utf8');
+    } catch {
+      return '';
+    }
+  }
+}