@easbot/agent 0.2.21 → 0.2.22

package/dist/assets/txt/tool/pty_session.txt

@@ -1,34 +1,17 @@
 Create and manage persistent interactive PTY sessions for long-running processes. Enables background execution, session persistence, and reconnection capabilities for continuous operations.
 
-**!! CRITICAL WARNING: PERSISTENT BACKGROUND SESSIONS !!**
+**!! CRITICAL: PERSISTENT BACKGROUND SESSIONS !!**
 
 Key capabilities:
-- Persistent session creation
+- Persistent session creation (default: persistent=true)
 - Background process management
-- Session reconnection
+- Session reconnection (persistent mode)
 - Multi-session support
-- State preservation
+- Output buffer with configurable truncation
 
-Usage scenarios:
-- Long-running services (web servers, databases)
-- Interactive SSH sessions
-- REPL environments (Node.js, Python, etc.)
-- Continuous monitoring (log tailing, system monitoring)
-- Interactive development environments
+**!! IMPORTANT: MUST CREATE SESSION FIRST !!**
 
-Parameters:
-- command (required): Initial command to run in session
-- sessionName (optional): Unique identifier for session
-- cols/rows (optional): Terminal dimensions
-- persistent (optional): Keep session running after command completes (default: true)
-- truncateMode (optional): head or tail for output truncation (default: tail)
-
-**!! INPUT INTERACTION !!**
-
-Send input to session using pty_manage tool:
-```
-pty_manage { "action": "write", "sessionId": "<sessionId>", "data": "your input\n" }
-```
+You MUST create a session before interacting with it. There is NO direct command execution.
 
 Interactive workflow:
 1. Create session: pty_session { "command": "ssh user@host" }
@@ -37,24 +20,84 @@ Interactive workflow:
 4. Check output: pty_manage { "action": "get", "sessionId": "..." }
 5. Close session: pty_manage { "action": "close", "sessionId": "..." }
 
-**!! ABSOLUTELY CRITICAL RESOURCE MANAGEMENT !!**
+**!! WHEN TO USE PTY vs BASH !!**
+
+Use pty_session for:
+- SSH connections: ssh user@host
+- Interactive sessions: top, htop, vim, nano
+- Long-running processes: tail -f logfile
+- Any command requiring a terminal (TTY)
+
+Use bash tool for:
+- Simple commands: ls, git status, npm build
+- One-shot commands: echo, cat, grep
+- Scripts: ./script.sh
+
+**!! PARAMETERS !!**
+
+Parameters:
+- command (required): Command to run in session
+  - Windows: "cmd.exe", "powershell.exe", "ssh.exe"
+  - Unix: "/bin/bash", "/usr/bin/ssh"
+- args (optional): Command arguments as array
+- cwd (optional): Working directory (defaults to project directory)
+- env (optional): Environment variables
+- sessionName (optional): Custom name for identification
+- cols (optional): Terminal columns (default: 120, range: 10-500)
+- rows (optional): Terminal rows (default: 30, range: 5-200)
+- truncateMode (optional): head or tail for output truncation (default: tail)
+- persistent (optional): Keep session after process exits (default: true, RECOMMENDED)
+
+**!! COMMAND PATH REQUIREMENTS !!**
 
-**WARNING**: Sessions run PERSISTENTLY in background until EXPLICITLY terminated!
+PTY directly executes the command you provide. The command MUST be:
+- An executable file path, OR
+- A command in system PATH
 
-**MANDATORY CLEANUP PROCEDURES**:
-1. **MUST use pty_manage** tool for ALL session cleanup operations
-2. **UNUSED sessions CONTINUE consuming system resources indefinitely**
-3. **Sessions do not automatically terminate** - they run indefinitely until explicitly closed
-4. **REGULAR monitoring required**: pty_manage { "action": "list" }
-5. **IMMEDIATE termination**: pty_manage { "action": "close", "sessionId": "id" }
-6. **FAILURE to clean up WILL lead to SYSTEM RESOURCE EXHAUSTION**
-7. **SECURITY RISK**: Uncleaned sessions provide persistent system access
+Examples:
+- Windows: "cmd.exe", "powershell.exe", "ssh.exe", "C:\\Windows\\System32\\cmd.exe"
+- Unix: "/bin/bash", "/usr/bin/ssh", "ssh"
 
-**RESOURCE CONSUMPTION IMPACT**:
+If command not found, you'll see error:
+  "Failed to create PTY session: File not found"
+
+💡 Fix: Use full path or ensure command is in PATH
+
+**!! SESSION PERSISTENCE BEHAVIOR !!**
+
+When persistent=true (DEFAULT):
+- Session is NOT deleted when process exits
+- Session remains available for inspection
+- Can still query output buffer and session info
+- MUST explicitly close with pty_manage { "action": "close" }
+
+When persistent=false:
+- Session is automatically deleted when process exits
+- Use for short-lived commands
+
+**!! SESSION STATUS !!**
+
+Sessions can have status:
+- running: Process is active
+- exited: Process has completed (session still exists if persistent=true)
+
+**!! RESOURCE MANAGEMENT !!**
+
+**WARNING**: Sessions consume system resources until EXPLICITLY closed!
+
+MANDATORY CLEANUP:
+1. ALWAYS close sessions when done: pty_manage { "action": "close", "sessionId": "id" }
+2. Monitor active sessions: pty_manage { "action": "list" }
+3. Unclosed sessions cause RESOURCE LEAK
+
+Resource consumption:
 - CPU cycles for active processes
-- Memory allocation for session buffers
+- Memory for session buffers
 - File descriptors for terminal I/O
 - Network connections (if applicable)
-- System limits may be reached causing crashes
 
-Security: Requires authorization for session creation and management.
+**!! SECURITY !!**
+
+- Requires authorization for session creation and management
+- Sessions provide direct system access
+- Always close sessions to prevent unauthorized access