upfynai-code 2.9.4 → 2.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upfynai-code",
-  "version": "2.9.4",
+  "version": "2.9.6",
   "description": "Visual AI coding interface for Claude Code, Cursor & Codex. Canvas whiteboard, multi-agent chat, terminal, git, voice assistant. Self-host locally or connect to cli.upfyn.com for remote access.",
   "type": "module",
   "main": "server/index.js",
@@ -58,12 +58,10 @@
     "@iarna/toml": "^2.2.5",
     "@libsql/client": "^0.14.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@neondatabase/serverless": "^1.0.2",
     "@octokit/rest": "^22.0.0",
     "@openai/codex-sdk": "^0.101.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^4.0.3",
-    "composio-core": "^0.5.39",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "cross-spawn": "^7.0.3",
@@ -83,6 +81,8 @@
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
+    "composio-core": "^0.5.39",
+    "@neondatabase/serverless": "^1.0.2",
     "node-pty": "^1.1.0-beta34"
   },
   "devDependencies": {

package/server/relay-client.js

@@ -22,7 +22,7 @@ import {
   logRelayEvent,
   createSpinner,
 } from './cli-ui.js';
-import { executeAction, isStreamingAction } from '../../packages/shared/agents/index.js';
+import { executeAction, isStreamingAction } from '../shared/agents/index.js';
 
 // Load package.json for version
 import { fileURLToPath } from 'url';

package/shared/agents/claude.js

@@ -0,0 +1,229 @@
+/**
+ * Claude Agent
+ * Handles: claude-query, claude-task-query
+ *
+ * These are STREAMING actions — they use ctx.stream() to send chunks
+ * and return a Promise that resolves when the process completes.
+ *
+ * Three modes:
+ * - sdk (connect.js default) — full SDK streaming with rich messages (tool_use, text, result)
+ * - simple --print (relay-client.js) — basic stdout streaming
+ *
+ * The caller chooses the mode via ctx.streamMode ('structured' | 'simple').
+ * 'structured' now maps to SDK mode for rich message forwarding.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { spawn } from 'child_process';
+import os from 'os';
+
+export default {
+  name: 'claude',
+  actions: {
+    'claude-query': async (params, ctx) => {
+      const { command, options } = params;
+      const mode = ctx.streamMode || 'structured';
+
+      if (mode === 'simple') {
+        const resolveBinary = ctx.resolveBinary || ((name) => name);
+        return runSimpleClaudeQuery(command, options, ctx, resolveBinary);
+      }
+      return runSDKClaudeQuery(command, options, ctx);
+    },
+
+    'claude-task-query': async (params, ctx) => {
+      const { command, options } = params;
+      return runSDKClaudeTaskQuery(command, options, ctx);
+    },
+  },
+};
+
+/**
+ * Build SDK options from relay command options.
+ * Maps the relay format to SDK Options type.
+ */
+function buildSDKOptions(options = {}) {
+  const sdkOptions = {
+    cwd: options.projectPath || os.homedir(),
+    systemPrompt: { type: 'preset', preset: 'claude_code' },
+    settingSources: ['project', 'user', 'local'],
+  };
+
+  if (options.sessionId) {
+    sdkOptions.resume = options.sessionId;
+  }
+
+  if (options.model) {
+    sdkOptions.model = options.model;
+  }
+
+  if (options.maxBudgetUsd) {
+    sdkOptions.maxBudgetUsd = options.maxBudgetUsd;
+  }
+
+  if (options.permissionMode && options.permissionMode !== 'default') {
+    sdkOptions.permissionMode = options.permissionMode;
+  }
+
+  if (options.allowedTools && options.allowedTools.length > 0) {
+    sdkOptions.allowedTools = options.allowedTools;
+  }
+
+  if (options.disallowedTools && options.disallowedTools.length > 0) {
+    sdkOptions.disallowedTools = options.disallowedTools;
+  }
+
+  if (options.maxTurns) {
+    sdkOptions.maxTurns = options.maxTurns;
+  }
+
+  // Pass through tools preset to make all Claude Code tools available
+  sdkOptions.tools = { type: 'preset', preset: 'claude_code' };
+
+  return sdkOptions;
+}
+
+/**
+ * SDK-based structured streaming mode.
+ * Forwards rich SDK messages (tool_use, tool_result, text, system, result)
+ * through ctx.stream() for the relay to forward to the frontend.
+ */
+async function runSDKClaudeQuery(command, options, ctx) {
+  const sdkOptions = buildSDKOptions(options);
+
+  // Set stream-close timeout for interactive tools
+  const prevStreamTimeout = process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT;
+  process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT = '300000';
+
+  let queryInstance;
+  try {
+    queryInstance = query({
+      prompt: command || '',
+      options: sdkOptions,
+    });
+  } finally {
+    // Restore immediately — Query constructor already captured the value
+    if (prevStreamTimeout !== undefined) {
+      process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT = prevStreamTimeout;
+    } else {
+      delete process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT;
+    }
+  }
+
+  // Track the query instance for abort support (uses .interrupt() instead of .kill())
+  if (ctx.trackProcess) {
+    ctx.trackProcess(ctx.requestId, { instance: queryInstance, action: 'claude-query' });
+  }
+
+  let capturedSessionId = null;
+
+  try {
+    for await (const message of queryInstance) {
+      // Capture session ID from first message that has one
+      if (message.session_id && !capturedSessionId) {
+        capturedSessionId = message.session_id;
+      }
+
+      // Forward the full SDK message — the backend routeViaRelay() will
+      // detect 'claude-sdk-message' type and forward directly to frontend,
+      // matching the same format as queryClaudeSDK() in claude-sdk.js
+      ctx.stream({
+        type: 'claude-sdk-message',
+        data: message,
+        sessionId: capturedSessionId,
+      });
+    }
+
+    return { exitCode: 0, sessionId: capturedSessionId };
+  } catch (error) {
+    ctx.stream({ type: 'claude-error', content: error.message || 'SDK query failed' });
+    return { exitCode: 1, sessionId: capturedSessionId };
+  } finally {
+    if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+  }
+}
+
+/**
+ * SDK-based sub-agent for read-only research tasks.
+ * Restricts tools to read-only operations.
+ */
+async function runSDKClaudeTaskQuery(command, options, ctx) {
+  const sdkOptions = buildSDKOptions(options);
+
+  // Restrict to read-only tools
+  sdkOptions.allowedTools = ['View', 'Glob', 'Grep', 'LS', 'Read'];
+
+  let queryInstance;
+  try {
+    queryInstance = query({
+      prompt: command || '',
+      options: sdkOptions,
+    });
+  } catch (error) {
+    ctx.stream({ type: 'claude-error', content: error.message || 'SDK task query failed' });
+    return { exitCode: 1 };
+  }
+
+  if (ctx.trackProcess) {
+    ctx.trackProcess(ctx.requestId, { instance: queryInstance, action: 'claude-task-query' });
+  }
+
+  let capturedSessionId = null;
+
+  try {
+    for await (const message of queryInstance) {
+      if (message.session_id && !capturedSessionId) {
+        capturedSessionId = message.session_id;
+      }
+
+      ctx.stream({
+        type: 'claude-sdk-message',
+        data: message,
+        sessionId: capturedSessionId,
+      });
+    }
+
+    return { exitCode: 0, sessionId: capturedSessionId };
+  } catch (error) {
+    ctx.stream({ type: 'claude-error', content: error.message || 'SDK task query failed' });
+    return { exitCode: 1, sessionId: capturedSessionId };
+  } finally {
+    if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+  }
+}
+
+/**
+ * Simple streaming mode (--print).
+ * Just pipes stdout/stderr chunks. Kept for backward compat with relay-client.js.
+ */
+function runSimpleClaudeQuery(command, options, ctx, resolveBinary) {
+  return new Promise((resolve) => {
+    const args = ['--print'];
+    if (options?.sessionId) args.push('--continue', options.sessionId);
+
+    const proc = spawn(resolveBinary('claude'), [...args, command || ''], {
+      shell: true,
+      cwd: options?.projectPath || os.homedir(),
+      env: process.env,
+    });
+
+    if (ctx.trackProcess) ctx.trackProcess(ctx.requestId, { proc, action: 'claude-query' });
+
+    proc.stdout.on('data', (chunk) => {
+      ctx.stream({ type: 'claude-response', content: chunk.toString() });
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      ctx.stream({ type: 'claude-error', content: chunk.toString() });
+    });
+
+    proc.on('close', (code) => {
+      if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+      resolve({ exitCode: code });
+    });
+
+    proc.on('error', () => {
+      if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+      resolve({ exitCode: 1 });
+    });
+  });
+}

package/shared/agents/codex.js

@@ -0,0 +1,48 @@
+/**
+ * Codex Agent
+ * Handles: codex-query
+ * Spawns the OpenAI Codex CLI and streams output.
+ */
+import { spawn } from 'child_process';
+import os from 'os';
+
+export default {
+  name: 'codex',
+  actions: {
+    'codex-query': async (params, ctx) => {
+      const { command, options } = params;
+      const resolveBinary = ctx.resolveBinary || ((name) => name);
+
+      return new Promise((resolve) => {
+        const args = ['--quiet'];
+        if (options?.model) args.push('--model', options.model);
+
+        const proc = spawn(resolveBinary('codex'), [...args, command || ''], {
+          shell: true,
+          cwd: options?.projectPath || options?.cwd || os.homedir(),
+          env: process.env,
+        });
+
+        if (ctx.trackProcess) ctx.trackProcess(ctx.requestId, { proc, action: 'codex-query' });
+
+        proc.stdout.on('data', (chunk) => {
+          ctx.stream({ type: 'codex-response', content: chunk.toString() });
+        });
+
+        proc.stderr.on('data', (chunk) => {
+          ctx.stream({ type: 'codex-error', content: chunk.toString() });
+        });
+
+        proc.on('close', (code) => {
+          if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+          resolve({ exitCode: code });
+        });
+
+        proc.on('error', () => {
+          if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+          resolve({ exitCode: 1 });
+        });
+      });
+    },
+  },
+};

package/shared/agents/cursor.js

@@ -0,0 +1,48 @@
+/**
+ * Cursor Agent
+ * Handles: cursor-query
+ * Spawns the Cursor Agent CLI and streams output.
+ */
+import { spawn } from 'child_process';
+import os from 'os';
+
+export default {
+  name: 'cursor',
+  actions: {
+    'cursor-query': async (params, ctx) => {
+      const { command, options } = params;
+      const resolveBinary = ctx.resolveBinary || ((name) => name);
+
+      return new Promise((resolve) => {
+        const args = [];
+        if (options?.model) args.push('--model', options.model);
+
+        const proc = spawn(resolveBinary('cursor-agent'), [...args, command || ''], {
+          shell: true,
+          cwd: options?.projectPath || options?.cwd || os.homedir(),
+          env: process.env,
+        });
+
+        if (ctx.trackProcess) ctx.trackProcess(ctx.requestId, { proc, action: 'cursor-query' });
+
+        proc.stdout.on('data', (chunk) => {
+          ctx.stream({ type: 'cursor-response', content: chunk.toString() });
+        });
+
+        proc.stderr.on('data', (chunk) => {
+          ctx.stream({ type: 'cursor-error', content: chunk.toString() });
+        });
+
+        proc.on('close', (code) => {
+          if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+          resolve({ exitCode: code });
+        });
+
+        proc.on('error', () => {
+          if (ctx.untrackProcess) ctx.untrackProcess(ctx.requestId);
+          resolve({ exitCode: 1 });
+        });
+      });
+    },
+  },
+};

package/shared/agents/detect.js

@@ -0,0 +1,51 @@
+/**
+ * Detect Agent
+ * Handles: detect-agents
+ * Checks which AI CLI agents are installed on the local machine.
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const AGENT_DEFINITIONS = [
+  { name: 'claude', binary: 'claude', label: 'Claude Code' },
+  { name: 'codex', binary: 'codex', label: 'OpenAI Codex' },
+  { name: 'cursor', binary: 'cursor-agent', label: 'Cursor Agent' },
+];
+
+export default {
+  name: 'detect',
+  actions: {
+    'detect-agents': async (params, ctx) => {
+      const isWindows = process.platform === 'win32';
+      const whichCmd = isWindows ? 'where' : 'which';
+      const localBinDir = ctx.localBinDir || null;
+
+      const agents = {};
+      for (const agent of AGENT_DEFINITIONS) {
+        try {
+          const result = execSync(`${whichCmd} ${agent.binary}`, {
+            stdio: 'pipe',
+            timeout: 5000,
+          }).toString().trim();
+          agents[agent.name] = {
+            installed: true,
+            path: result.split('\n')[0].trim(),
+            label: agent.label,
+          };
+        } catch {
+          // Check local node_modules/.bin as fallback
+          if (localBinDir) {
+            const localPath = path.join(localBinDir, agent.binary + (isWindows ? '.cmd' : ''));
+            if (fs.existsSync(localPath)) {
+              agents[agent.name] = { installed: true, path: localPath, label: agent.label };
+              continue;
+            }
+          }
+          agents[agent.name] = { installed: false, label: agent.label };
+        }
+      }
+      return { agents };
+    },
+  },
+};

package/shared/agents/exec.js

@@ -0,0 +1,31 @@
+/**
+ * Exec Agent
+ * Handles: exec (arbitrary command execution)
+ */
+import { execSync } from 'child_process';
+
+export default {
+  name: 'exec',
+  actions: {
+    'exec': async (params) => {
+      const { command, timeout: cmdTimeout = 60000, cwd } = params;
+      if (!command) throw new Error('No command provided');
+
+      try {
+        const output = execSync(command, {
+          encoding: 'utf8',
+          timeout: cmdTimeout,
+          cwd: cwd || process.cwd(),
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { output, exitCode: 0 };
+      } catch (execErr) {
+        return {
+          output: execErr.stdout || '',
+          stderr: execErr.stderr || '',
+          exitCode: execErr.status || 1,
+        };
+      }
+    },
+  },
+};

package/shared/agents/files.js

@@ -0,0 +1,105 @@
+/**
+ * File System Agent
+ * Handles: file-read, file-write, file-tree, browse-dirs, validate-path, create-folder
+ */
+import { promises as fsPromises } from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  buildFileTree,
+  resolveTildePath,
+  isBlockedPath,
+  BLOCKED_READ_PATTERNS,
+  BLOCKED_WRITE_PATTERNS,
+} from './utils.js';
+
+export default {
+  name: 'files',
+  actions: {
+    'file-read': async (params) => {
+      let { filePath, encoding } = params;
+      if (!filePath || typeof filePath !== 'string') throw new Error('Invalid file path');
+
+      filePath = resolveTildePath(filePath);
+      const normalizedPath = path.resolve(filePath);
+      if (isBlockedPath(normalizedPath, BLOCKED_READ_PATTERNS)) throw new Error('Access denied');
+
+      const content = await fsPromises.readFile(normalizedPath, encoding === 'base64' ? null : 'utf8');
+      const result = encoding === 'base64' ? content.toString('base64') : content;
+      return { content: result };
+    },
+
+    'file-write': async (params) => {
+      let { filePath, content } = params;
+      if (!filePath || typeof filePath !== 'string') throw new Error('Invalid file path');
+
+      filePath = resolveTildePath(filePath);
+      const normalizedPath = path.resolve(filePath);
+      if (isBlockedPath(normalizedPath, BLOCKED_WRITE_PATTERNS)) throw new Error('Access denied');
+
+      const parentDir = path.dirname(normalizedPath);
+      await fsPromises.mkdir(parentDir, { recursive: true }).catch(() => {});
+      await fsPromises.writeFile(normalizedPath, content, 'utf8');
+      return { success: true };
+    },
+
+    'file-tree': async (params) => {
+      const { dirPath, depth, maxDepth } = params;
+      const treeDepth = depth || maxDepth || 3;
+      const resolvedDir = dirPath ? path.resolve(dirPath) : process.cwd();
+      const tree = await buildFileTree(resolvedDir, treeDepth, 0, {
+        maxEntries: 200,
+        includeStats: true,
+        skipDotfilesAtRoot: true,
+      });
+      return { files: tree };
+    },
+
+    'browse-dirs': async (params) => {
+      const { dirPath: browsePath } = params;
+      let targetDir = resolveTildePath(browsePath);
+      targetDir = path.resolve(targetDir);
+
+      let drives = [];
+      // On Windows, detect available 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 { /* wmic not available */ }
+      }
+
+      const entries = await fsPromises.readdir(targetDir, { withFileTypes: true });
+      const 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));
+
+      return { path: targetDir, suggestions: dirs, drives, homedir: os.homedir() };
+    },
+
+    'validate-path': async (params) => {
+      const { targetPath } = params;
+      const checkPath = resolveTildePath(targetPath);
+      const resolved = path.resolve(checkPath);
+
+      try {
+        const stats = await fsPromises.stat(resolved);
+        return { exists: true, isDirectory: stats.isDirectory(), resolvedPath: resolved };
+      } catch {
+        return { exists: false, resolvedPath: resolved };
+      }
+    },
+
+    'create-folder': async (params) => {
+      const { folderPath } = params;
+      const mkPath = path.resolve(resolveTildePath(folderPath));
+      await fsPromises.mkdir(mkPath, { recursive: true });
+      return { success: true, path: mkPath };
+    },
+  },
+};

package/shared/agents/git.js

@@ -0,0 +1,18 @@
+/**
+ * Git Agent
+ * Handles: git-operation
+ */
+import path from 'path';
+import { execCommand } from './utils.js';
+
+export default {
+  name: 'git',
+  actions: {
+    'git-operation': async (params) => {
+      const { gitCommand, cwd } = params;
+      const resolvedCwd = cwd ? path.resolve(cwd) : process.cwd();
+      const result = await execCommand('git', [gitCommand], { cwd: resolvedCwd });
+      return { stdout: result };
+    },
+  },
+};

package/shared/agents/gitagent.js

@@ -0,0 +1,67 @@
+/**
+ * Gitagent Agent
+ * Handles: gitagent-detect, gitagent-parse
+ *
+ * Relay-compatible actions for detecting and parsing gitagent directory structures
+ * on the user's local machine.
+ */
+import fs from 'fs';
+import { promises as fsp } from 'fs';
+import path from 'path';
+import { detectGitagent, parseGitagentRepo } from '../gitagent/parser.js';
+
+/** fs-backed helpers injected into the parser */
+async function fsFileExists(filePath) {
+  try {
+    await fsp.access(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function fsReadFile(filePath) {
+  try {
+    return await fsp.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function fsListDir(dirPath) {
+  try {
+    return await fsp.readdir(dirPath);
+  } catch {
+    return [];
+  }
+}
+
+export default {
+  name: 'gitagent',
+  actions: {
+    /**
+     * Lightweight check for agent.yaml existence.
+     * @param {{ projectPath: string }} params
+     * @returns {{ detected: boolean }}
+     */
+    'gitagent-detect': async (params) => {
+      const projectPath = params.projectPath;
+      if (!projectPath) return { detected: false };
+      const detected = await detectGitagent(projectPath, fsFileExists);
+      return { detected };
+    },
+
+    /**
+     * Full parse — returns the complete GitagentDefinition as JSON.
+     * @param {{ projectPath: string }} params
+     * @returns {{ definition: object|null }}
+     */
+    'gitagent-parse': async (params) => {
+      const projectPath = params.projectPath;
+      if (!projectPath) return { definition: null };
+
+      const definition = await parseGitagentRepo(projectPath, fsReadFile, fsListDir);
+      return { definition };
+    },
+  },
+};

package/shared/agents/index.js

@@ -0,0 +1,88 @@
+/**
+ * Agent Registry
+ * Central dispatch for all command actions.
+ *
+ * Usage:
+ *   import { executeAction, isStreamingAction } from 'upfynai-shared/agents';
+ *
+ *   // Sync action (file-read, git-operation, etc.)
+ *   const result = await executeAction('file-read', { filePath: '/foo' }, ctx);
+ *   // result = { content: '...' }
+ *
+ *   // Streaming action (claude-query, codex-query, etc.)
+ *   const result = await executeAction('claude-query', params, {
+ *     ...ctx,
+ *     stream: (data) => ws.send(JSON.stringify({ type: 'relay-stream', requestId, data })),
+ *   });
+ *   // result = { exitCode: 0, sessionId: '...' }
+ */
+import claudeAgent from './claude.js';
+import codexAgent from './codex.js';
+import cursorAgent from './cursor.js';
+import shellAgent from './shell.js';
+import filesAgent from './files.js';
+import gitAgent from './git.js';
+import execAgent from './exec.js';
+import detectAgent from './detect.js';
+import gitagentAgent from './gitagent.js';
+
+const agents = [claudeAgent, codexAgent, cursorAgent, shellAgent, filesAgent, gitAgent, execAgent, detectAgent, gitagentAgent];
+
+/** Map of action name → handler function */
+const actionMap = new Map();
+
+/** Set of actions that use streaming (ctx.stream) instead of returning data */
+const streamingActions = new Set(['claude-query', 'claude-task-query', 'codex-query', 'cursor-query']);
+
+for (const agent of agents) {
+  for (const [action, handler] of Object.entries(agent.actions)) {
+    actionMap.set(action, handler);
+  }
+}
+
+/**
+ * Execute an agent action.
+ * @param {string} action - Action name (e.g., 'file-read', 'claude-query')
+ * @param {object} params - Action parameters from the command payload
+ * @param {object} ctx - Execution context:
+ *   - stream(data): Send streaming chunk (required for streaming actions)
+ *   - requestId: Current request ID
+ *   - trackProcess(id, entry): Register process for abort support
+ *   - untrackProcess(id): Remove process from tracking
+ *   - getPersistentShell(cwd): Get persistent shell instance (CLI only)
+ *   - resolveBinary(name): Resolve binary path (CLI only)
+ *   - localBinDir: Path to local node_modules/.bin (CLI only)
+ *   - streamMode: 'structured' | 'simple' (claude agent only)
+ *   - log(msg): Logging function
+ * @returns {Promise<object>} Action result
+ */
+export async function executeAction(action, params, ctx = {}) {
+  const handler = actionMap.get(action);
+  if (!handler) throw new Error(`Unknown action: ${action}`);
+  return handler(params, ctx);
+}
+
+/**
+ * Check if an action uses streaming.
+ * Streaming actions require ctx.stream() and return { exitCode, ... } via Promise.
+ * Non-streaming actions return { data } directly.
+ */
+export function isStreamingAction(action) {
+  return streamingActions.has(action);
+}
+
+/**
+ * Check if an action is registered.
+ */
+export function hasAction(action) {
+  return actionMap.has(action);
+}
+
+/**
+ * Get all registered action names.
+ */
+export function getActionNames() {
+  return Array.from(actionMap.keys());
+}
+
+export { agents };

package/shared/agents/shell.js

@@ -0,0 +1,38 @@
+/**
+ * Shell Agent
+ * Handles: shell-command
+ *
+ * Two execution modes:
+ * - Persistent shell (connect.js) — commands share one shell process
+ * - Simple exec (relay-client.js) — each command spawns a new process
+ *
+ * The caller provides the execution strategy via ctx.execShell or falls back to execCommand.
+ */
+import { execCommand, DANGEROUS_SHELL_PATTERNS } from './utils.js';
+
+export default {
+  name: 'shell',
+  actions: {
+    'shell-command': async (params, ctx) => {
+      const { command, cwd } = params;
+      if (!command || typeof command !== 'string') throw new Error('Invalid command');
+
+      // Block dangerous shell patterns
+      const cmdLower = command.toLowerCase();
+      if (DANGEROUS_SHELL_PATTERNS.some(d => cmdLower.includes(d.toLowerCase()))) {
+        throw new Error('Command blocked for safety');
+      }
+
+      // Use persistent shell if provided (connect.js), otherwise simple exec
+      if (ctx.getPersistentShell) {
+        const shell = ctx.getPersistentShell(cwd || process.cwd());
+        const result = await shell.exec(command, { timeoutMs: 60000 });
+        return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, cwd: result.cwd };
+      }
+
+      // Simple exec fallback
+      const result = await execCommand(command, [], { cwd: cwd || process.cwd(), timeout: 60000 });
+      return { stdout: result };
+    },
+  },
+};

package/shared/agents/utils.js

@@ -0,0 +1,136 @@
+/**
+ * Shared utilities for agent command handlers.
+ * Used by both CLI relay clients and backend server.
+ */
+import { spawn } from 'child_process';
+import { promises as fsPromises } from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * Execute a shell command and return stdout.
+ * @param {string} cmd - Command to run
+ * @param {string[]} args - Command arguments
+ * @param {object} options - { cwd, env, timeout }
+ * @returns {Promise<string>} stdout
+ */
+export function execCommand(cmd, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, {
+      shell: true,
+      cwd: options.cwd || os.homedir(),
+      env: { ...process.env, ...options.env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d; });
+    proc.stderr.on('data', (d) => { stderr += d; });
+
+    const timeout = setTimeout(() => {
+      proc.kill();
+      reject(new Error('Command timed out'));
+    }, options.timeout || 30000);
+
+    proc.on('close', (code) => {
+      clearTimeout(timeout);
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr || `Exit code ${code}`));
+    });
+
+    proc.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Build a file tree for a directory (recursive).
+ * @param {string} dirPath - Directory to scan
+ * @param {number} maxDepth - Maximum recursion depth
+ * @param {number} currentDepth - Current depth (internal)
+ * @param {object} options - { maxEntries, includeStats, skipDotfilesAtRoot }
+ * @returns {Promise<Array>} File tree items
+ */
+export async function buildFileTree(dirPath, maxDepth, currentDepth = 0, options = {}) {
+  const { maxEntries = 200, includeStats = false, skipDotfilesAtRoot = false } = options;
+  if (currentDepth >= maxDepth) return [];
+
+  const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.svn', '.hg']);
+
+  try {
+    const entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
+    const items = [];
+    for (const entry of entries.slice(0, maxEntries)) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith('.') && skipDotfilesAtRoot && currentDepth === 0) continue;
+
+      const itemPath = path.join(dirPath, entry.name);
+      const item = {
+        name: entry.name,
+        path: itemPath,
+        type: entry.isDirectory() ? 'directory' : 'file',
+      };
+
+      if (includeStats) {
+        try {
+          const stats = await fsPromises.stat(itemPath);
+          item.size = stats.size;
+          item.modified = stats.mtime.toISOString();
+        } catch { /* ignore stat errors */ }
+      }
+
+      if (entry.isDirectory() && currentDepth < maxDepth - 1) {
+        item.children = await buildFileTree(itemPath, maxDepth, currentDepth + 1, options);
+      }
+      items.push(item);
+    }
+    return items;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve a path that may start with ~ to an absolute path.
+ * @param {string} inputPath - Path to resolve
+ * @returns {string} Resolved absolute path
+ */
+export function resolveTildePath(inputPath) {
+  if (!inputPath) return os.homedir();
+  if (inputPath === '~') return os.homedir();
+  if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+  return path.resolve(inputPath);
+}
+
+/** Blocked paths for file reads (security) */
+export const BLOCKED_READ_PATTERNS = ['/etc/shadow', '/etc/passwd', '.ssh/id_rsa', '.ssh/id_ed25519', '/.env'];
+
+/** Blocked paths for file writes (security) */
+export const BLOCKED_WRITE_PATTERNS = [
+  '/etc/', '/usr/bin/', '/usr/sbin/',
+  '/windows/system32', '/windows/syswow64', '/program files',
+  '.ssh/', '/.env',
+];
+
+/** Dangerous shell patterns to block */
+export const DANGEROUS_SHELL_PATTERNS = [
+  'rm -rf /', 'mkfs', 'dd if=', ':(){', 'fork bomb', '> /dev/sd',
+  'format c:', 'format d:', 'format e:', 'del /s /q c:\\',
+  'rd /s /q c:\\', 'reg delete', 'bcdedit',
+];
+
+/**
+ * Check if a normalized path matches any blocked patterns.
+ * @param {string} normalizedPath - Absolute path (resolved)
+ * @param {string[]} patterns - Blocked patterns to check
+ * @returns {boolean}
+ */
+export function isBlockedPath(normalizedPath, patterns) {
+  const lower = normalizedPath.toLowerCase().replace(/\\/g, '/');
+  return patterns.some(b => lower.includes(b));
+}