teleportation-cli 1.0.0 → 1.0.2

package/lib/daemon/teleportation-daemon.js

@@ -4,26 +4,33 @@
  * Teleportation Daemon
  *
  * Persistent background service that:
- * - Polls relay API for approved tool requests
- * - Spawns child Claude Code processes via `claude --resume <session_id> -p "<prompt>"`
+ * - Polls relay API for approved tool requests and inbox messages
+ * - Routes all remote messages to Claude Code via the machine coder interface
  * - Executes approved tools asynchronously when user is away
  * - Maintains session registry and approval queue
  * - Provides HTTP server for hook communication
  *
  * SECURITY ARCHITECTURE:
  * ----------------------
- * This daemon executes shell commands via spawn('sh', ['-c', command]) which bypasses
- * Claude CLI's built-in security controls. This is an intentional architectural decision
- * to enable remote approval/execution, but requires defense-in-depth measures:
+ * Remote message execution is delegated to Claude Code's security model:
  *
- * 1. COMMAND WHITELIST: Only pre-approved command prefixes are allowed (see ALLOWED_COMMAND_PREFIXES)
- * 2. SHELL INJECTION BLOCKING: Commands containing metacharacters (;|&`$() etc.) are rejected
- * 3. APPROVAL FLOW: All commands must be explicitly approved via the relay API
- * 4. DEVELOPMENT BYPASS: ALLOW_ALL_COMMANDS requires TELEPORTATION_DANGER_ZONE confirmation
+ * 1. CLAUDE CODE PERMISSIONS: All tool calls go through Claude Code's permission system
+ *    - When hooks are active, tool approvals are routed via Teleportation Relay
+ *    - When using --dangerously-skip-permissions, Claude auto-approves tool calls
+ * 2. SESSION VALIDATION: Each execution validates the session is still active via Relay API
+ * 3. APPROVAL CONTEXT: All executions require an approvalContext (inbox_message, approval_queue)
+ *    for audit trail
+ * 4. MACHINE CODER INTERFACE: Unified interface supports Claude Code, Gemini CLI, and future backends
  *
- * For production deployments requiring Claude CLI integration, consider:
- * - Using the CLAUDE_CLI_PATH environment variable to specify a custom Claude CLI wrapper
- * - Implementing additional command validation in a proxy layer
+ * LEGACY SHELL EXECUTION:
+ * The daemon also supports direct shell command execution via executeCommand() for specific
+ * use cases like approval queue processing. This path uses:
+ * - COMMAND WHITELIST: Only pre-approved command prefixes (see ALLOWED_COMMAND_PREFIXES)
+ * - SHELL INJECTION BLOCKING: Commands with metacharacters (;|&`$() etc.) are rejected
+ *
+ * For production deployments, consider:
+ * - Using --dangerously-skip-permissions only in sandboxed environments
+ * - Implementing rate limiting on the relay API
  * - Enabling audit logging by setting DEBUG=1
  */
 
@@ -54,6 +61,11 @@ const CLAUDE_CLI = process.env.CLAUDE_CLI_PATH || 'claude'; // Configurable Clau
 const ALLOW_ALL_COMMANDS = process.env.TELEPORTATION_DAEMON_ALLOW_ALL_COMMANDS === 'true';
 const HEARTBEAT_INTERVAL_MS = parseInt(process.env.DAEMON_HEARTBEAT_INTERVAL_MS || '30000', 10); // 30 sec default
 
+// Message routing configuration
+// REQUIRE_COMMAND_WHITELIST: If true, use legacy shell execution with command whitelist
+// Default: false (all messages route to Claude Code)
+const REQUIRE_COMMAND_WHITELIST = process.env.TELEPORTATION_REQUIRE_COMMAND_WHITELIST === 'true';
+
 // Machine coder configuration
 // PREFERRED_CODER: 'claude-code' | 'gemini-cli' | 'auto' (default: auto)
 // 'auto' will use Claude Code if available, otherwise Gemini CLI
@@ -68,6 +80,10 @@ const ROUTER_ENABLED = process.env.TELEPORTATION_ROUTER_ENABLED !== 'false' && !
 const ROUTER_VERBOSE = process.env.TELEPORTATION_ROUTER_VERBOSE === 'true';
 const ROUTER_MAX_ESCALATIONS = parseInt(process.env.TELEPORTATION_ROUTER_MAX_ESCALATIONS || '2', 10);
 
+// Test helper: allows mocking executeWithMachineCoder in tests
+// In production, this just holds null and the real function is called
+const _executeWithMachineCoderRef = { fn: null };
+
 // Lazy-initialized router instance
 let _router = null;
 function getRouter() {
@@ -184,8 +200,17 @@ const MAX_EXECUTIONS = 1000; // Maximum executions to keep in memory (LRU cache)
 // Maximum output size to prevent memory issues
 const MAX_OUTPUT_SIZE = 100_000; // 100KB
 
-// Command whitelist for inbox execution (security: prevents arbitrary command execution)
-// Only commands starting with these prefixes are allowed
+// LEGACY SHELL EXECUTION:
+// These constants and functions are kept for:
+// 1. Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+// 2. Direct shell execution via approval queue processing
+// 3. Backward compatibility with existing tests
+//
+// For inbox messages, all prompts are now routed to Claude Code by default.
+// See handleInboxMessage() for the current flow.
+
+// Command whitelist for legacy shell execution (security: prevents arbitrary command execution)
+// Only commands starting with these prefixes are allowed when TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true
 const ALLOWED_COMMAND_PREFIXES = [
   'git ',        // Git operations
   'npm ',        // NPM package management
@@ -253,7 +278,15 @@ function sanitizeCommand(command) {
 }
 
 /**
- * Check if a command is allowed based on the whitelist
+ * LEGACY: Check if a command is allowed based on the whitelist
+ *
+ * This function is kept for:
+ * - Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+ * - executeCommand() which is used by approval queue processing
+ * - Backward compatibility with existing tests
+ *
+ * For inbox messages, all prompts are now routed to Claude Code by default.
+ *
  * @param {string} command - The command to validate
  * @returns {{ allowed: boolean, reason?: string }}
  */
@@ -685,9 +718,17 @@ async function checkIdleTimeout() {
 }
 
 /**
- * Execute a shell command in the session's working directory
+ * LEGACY: Execute a shell command in the session's working directory
  * Returns { success, stdout, stderr, exit_code, error }
  *
+ * This function is kept for:
+ * - Approval queue processing (executing approved tool calls)
+ * - Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+ * - Backward compatibility with existing tests
+ *
+ * For inbox messages, all prompts are now routed to Claude Code by default.
+ * See handleInboxMessage() and executeWithMachineCoder() for the current flow.
+ *
  * Security: Commands must be in the ALLOWED_COMMAND_PREFIXES whitelist
  */
 async function executeCommand(session_id, command) {
@@ -755,7 +796,18 @@ async function handleInboxMessage(session_id, message) {
     // For command messages, execute the command and post result back to the main agent inbox
     if (meta.type === 'command') {
       const replyAgentId = meta.reply_agent_id || 'main';
-      const commandText = message.text || '';
+      const commandText = (message.text || '').trim();
+
+      // Validate non-empty message before processing
+      if (!commandText) {
+        console.warn(`[daemon] Received empty message ${message.id}, skipping execution`);
+        // Still acknowledge the message to prevent re-delivery
+        await fetch(`${RELAY_API_URL}/api/messages/${encodeURIComponent(message.id)}/ack`, {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${RELAY_API_KEY}` }
+        });
+        return;
+      }
 
       // Invalidate pending approvals BEFORE executing new command
       // This prevents race conditions where stale approvals could be acted upon
@@ -783,39 +835,57 @@ async function handleInboxMessage(session_id, message) {
         // Continue with execution - this is not critical
       }
 
-      // Hybrid Execution Logic:
-      // 1. Check if it's a valid whitelisted shell command
-      const validation = isCommandAllowed(commandText);
+      // Route message to Claude Code (default) or use legacy shell execution (with feature flag)
       let executionResult;
-      let executionType = 'shell';
-
-      if (validation.allowed) {
-        // Fast path: Execute shell command directly
-        console.log(`[daemon] Executing direct shell command: ${commandText}`);
-        executionResult = await executeCommand(session_id, commandText);
+      let executionType;
+
+      // Feature flag: TELEPORTATION_REQUIRE_COMMAND_WHITELIST enables legacy whitelist-based execution
+      if (REQUIRE_COMMAND_WHITELIST) {
+        // Legacy mode: check if command is in whitelist, execute via shell if allowed
+        const validation = isCommandAllowed(commandText);
+        if (validation.allowed) {
+          executionType = 'shell';
+          console.log(`[daemon] Legacy shell execution: ${commandText.substring(0, 100)}`);
+          executionResult = await executeCommand(session_id, commandText);
+        } else {
+          // Command not in whitelist - reject in legacy mode
+          console.log(`[daemon] Command rejected by whitelist: ${commandText.substring(0, 100)}`);
+          executionResult = {
+            success: false,
+            exit_code: -1,
+            stdout: '',
+            stderr: '',
+            error: validation.reason
+          };
+          executionType = 'rejected';
+        }
       } else {
-        // Fallback: Natural language prompt via machine coder (Claude/Gemini/etc.)
-        console.log(`[daemon] Command not in whitelist, handing off to machine coder: ${commandText}`);
+        // Default mode: route all messages to Claude Code
         executionType = 'agent';
-        
-        // Stream output callback for inbox message execution
+        console.log(`[daemon] Routing message to Claude Code: ${commandText.substring(0, 100)}`);
+
+        // Stream output callback for message execution
         const onOutput = createStreamingCallback(session_id, message.id, {
           message_id: message.id
         });
-        
+
         // Use the unified machine coder interface
         // This supports Claude Code, Gemini CLI, and future backends
+        // Note: _executeWithMachineCoderRef.fn is used for test mocking
         try {
-          executionResult = await executeWithMachineCoder(session_id, commandText, {
+          const executeFn = _executeWithMachineCoderRef.fn || executeWithMachineCoder;
+          executionResult = await executeFn(session_id, commandText, {
             onOutput,
             approvalContext: { type: 'inbox_message', id: message.id },
           });
-          
+
           // Track which coder was used
           if (executionResult.coder_used) {
             console.log(`[daemon] Executed via ${executionResult.coder_used}`);
           }
         } catch (error) {
+          const preview = commandText.substring(0, 50);
+          console.error(`[daemon] Machine coder execution failed for "${preview}...":`, error.message);
           executionResult = {
             success: false,
             exit_code: -1,
@@ -838,13 +908,17 @@ async function handleInboxMessage(session_id, message) {
       );
 
       // Build result message with execution details
+      // Note: executeWithMachineCoder returns 'output', legacy executeCommand returns 'stdout'
+      // Using ?? to handle empty string correctly (|| would skip empty string)
       let resultText = '';
       if (executionResult.success) {
-        const header = executionType === 'agent' ? 'Claude executed your request:\n\n' : 'Command executed successfully:\n\n';
-        resultText = `${header}${executionResult.stdout}`;
+        const resultOutput = executionResult.output ?? executionResult.stdout ?? '';
+        resultText = `Claude completed your request:\n\n${resultOutput}`;
       } else {
-        const header = executionType === 'agent' ? 'Claude failed to execute request:\n\n' : `Command failed with exit code ${executionResult.exit_code}:\n\n`;
-        resultText = `${header}Error: ${executionResult.error}\n\nStderr:\n${executionResult.stderr}`;
+        resultText = `Claude failed to complete request:\n\nError: ${executionResult.error}`;
+        if (executionResult.stderr) {
+          resultText += `\n\nDetails:\n${executionResult.stderr}`;
+        }
       }
 
       try {
@@ -1525,11 +1599,19 @@ async function executeWithMachineCoder(session_id, prompt, options = {}) {
   
   // Execute via the coder
   const startedAt = Date.now();
-  
+
   try {
-    // For Claude Code with resume support, use resume if we have a claude_session_id
+    // Always use execute() for remote inbox messages since our claude_session_id
+    // is actually the teleportation UUID, not a real Claude Code session ID.
+    // Passing UUID to claude --resume causes it to fail.
+    // Use UUID v4 regex pattern for robust detection instead of fragile hyphen check.
+    const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     let result;
-    if (coder.name === 'claude-code' && session.claude_session_id) {
+    const isValidClaudeSession = session.claude_session_id &&
+      session.claude_session_id !== session.session_id &&
+      !UUID_V4_PATTERN.test(session.claude_session_id);
+
+    if (coder.name === 'claude-code' && isValidClaudeSession) {
       result = await coder.resume(session.claude_session_id, prompt, execOptions);
     } else {
       result = await coder.execute(execOptions);
@@ -1975,7 +2057,14 @@ const __test = {
   _setLastSessionActivityAt: (value) => {
     lastSessionActivityAt = value;
   },
-  _getSessionsMap: () => sessions
+  _getSessionsMap: () => sessions,
+  // Test helper: inject mock for executeWithMachineCoder
+  _setExecuteWithMachineCoder: (mockFn) => {
+    _executeWithMachineCoderRef.fn = mockFn;
+  },
+  _resetExecuteWithMachineCoder: () => {
+    _executeWithMachineCoderRef.fn = null;
+  }
 };
 
 export {
@@ -2000,6 +2089,7 @@ export {
   sendStreamingMessage,
   MAX_EXECUTIONS,
   PREFERRED_CODER, // New: machine coder preference
+  REQUIRE_COMMAND_WHITELIST, // Feature flag for legacy whitelist mode
   // Router integration for cost-aware LLM calls
   routedCompletion,
   classifyTaskTier,

package/lib/install/installer.js

@@ -40,7 +40,7 @@ function getProjectSettings() {
 
 // Claude Code reads settings from ~/.claude/settings.json (user-level)
 function getUserSettings() {
-  return join(HOME_DIR, '.claude', 'settings.json');
+  return process.env.TEST_USER_SETTINGS || join(HOME_DIR, '.claude', 'settings.json');
 }
 
 /**
@@ -133,7 +133,11 @@ export async function verifyHooks(sourceHooksDir) {
     try {
       await stat(hookPath);
       // Set executable permissions (755)
-      await chmod(hookPath, 0o755);
+      try {
+        await chmod(hookPath, 0o755);
+      } catch (_) {
+        // Ignore chmod errors
+      }
       found.push(hook);
     } catch (e) {
       if (e.code === 'ENOENT') {
@@ -154,6 +158,14 @@ export async function installHooks(sourceHooksDir) {
   const destHooksDir = getProjectHooksDir();
   const copyFailed = [];
 
+  try {
+    await mkdir(destHooksDir, { recursive: true });
+  } catch (e) {
+    if (e.code !== 'EEXIST') {
+      throw e;
+    }
+  }
+
   // Copy hooks from source to destination if they're different
   if (sourceHooksDir !== destHooksDir) {
     for (const hook of result.found) {
@@ -298,7 +310,8 @@ export async function installLibFiles() {
   const libFiles = [
     { subdir: 'auth', files: ['credentials.js', 'api-key.js'] },
     { subdir: 'session', files: ['metadata.js'] },
-    { subdir: 'config', files: ['manager.js'] }
+    { subdir: 'config', files: ['manager.js'] },
+    { subdir: 'daemon', files: ['lifecycle.js', 'pid-manager.js'] }  // Required for heartbeat daemon auto-start
   ];
 
   const installed = [];
@@ -425,11 +438,13 @@ export async function createSettings() {
   
   // IMPORTANT: Also write to user-level settings (~/.claude/settings.json)
   // Claude Code reads from this location, not from the project directory
-  const userSettings = getUserSettings();
-  await mkdir(dirname(userSettings), { recursive: true });
-  await writeFile(userSettings, JSON.stringify(settings, null, 2));
+  if (!process.env.TEST_SETTINGS) {
+    const userSettings = getUserSettings();
+    await mkdir(dirname(userSettings), { recursive: true });
+    await writeFile(userSettings, JSON.stringify(settings, null, 2));
+  }
   
-  return { projectSettings, userSettings };
+  return projectSettings;
 }
 
 /**