ZǻiKdZddlmZddlmZmZddlmZmZm Z m Z m Z m Z m Z ddlZddlmZmZmZmZddlmZddlmZmZdd lmZerdd lmZeGd d Zy) z?Sandbox class for interacting with a specific sandbox instance.) annotations) dataclassfield) TYPE_CHECKINGAnyCallableLiteralOptionalUnionoverloadN)DataplaneNotConfiguredErrorResourceNotFoundErrorSandboxConnectionErrorSandboxNotReadyError)handle_sandbox_http_error) CommandHandleExecutionResult)Tunnel) SandboxClientc eZdZUdZded<ded<dZded<dZded<d Zded <dZded <dZ ded <dZ ded <e ddZ ded<e ddZ ded<e d/ d0dZd1dZ d2dZd3dZedddddddddddd d4dZeddddddddddd d5dZddddddd dd!ddd d6d"Zd dd!dd# d7d$Z d8d%Zd&d&d' d9d(Zdd) d:d*Zdd)d;d+Zd&d,d- dt{{mLEE !!-DII;'>> !!!r1.) timeoutenvcwdshell on_stdout on_stderr idle_timeoutkill_on_disconnect ttl_secondsptywaitc yNr3 r5commandr@rArBrCrDrErFrGrHrIrJs r/runz Sandbox.runs r1 r@rArBrCrDrErFrGrHrIc yrLr3rMs r/rOz Sandbox.runs r1<z /bin/bashi,iXc >| s|s|r td|j| xs|xs|} | r|j|||||| |||| | |  S |j|||||ddd|| | |  S#ttt t f$r|j|||||cYSwxYw)aS Execute a command in the sandbox. Args: command: Shell command to execute. timeout: Command timeout in seconds. env: Environment variables to set for the command. cwd: Working directory for command execution. If None, uses sandbox default. shell: Shell to use for command execution. Defaults to "/bin/bash". on_stdout: Callback invoked with each stdout chunk as it arrives. Blocks until the command completes and returns ExecutionResult. Cannot be combined with wait=False. on_stderr: Callback invoked with each stderr chunk as it arrives. Blocks until the command completes and returns ExecutionResult. Cannot be combined with wait=False. idle_timeout: Idle timeout in seconds. If the command has no connected clients for this duration, it is killed. Defaults to 300 (5 minutes). Set to -1 for no idle timeout. Only applies to WebSocket execution. kill_on_disconnect: If True, kill the command immediately when the last client disconnects. Defaults to False (command continues running and can be reconnected to). ttl_seconds: How long (in seconds) a finished command's session is kept for reconnection. Defaults to 600 (10 minutes). Set to -1 to keep indefinitely. pty: If True, allocate a pseudo-terminal for the command. Useful for commands that require a TTY (e.g., interactive programs, commands that use terminal control codes). Defaults to False. wait: If True (default), block until the command completes and return ExecutionResult. If False, return a CommandHandle immediately for streaming output, kill, stdin input, and reconnection. Cannot be combined with on_stdout/on_stderr callbacks. Returns: ExecutionResult when wait=True (default). CommandHandle when wait=False. Raises: ValueError: If wait=False is combined with callbacks. DataplaneNotConfiguredError: If dataplane_url is not configured. SandboxOperationError: If command execution fails. CommandTimeoutError: If command exceeds its timeout. SandboxConnectionError: If connection to sandbox fails after retries. SandboxNotReadyError: If sandbox is not ready. SandboxClientError: For other errors. z}Cannot combine wait=False with on_stdout/on_stderr callbacks. Use wait=False and iterate the CommandHandle, or use callbacks.) r@rArBrCrJrDrErFrGrHrITN)r@rArBrC) ValueErrorr?_run_wsr ImportErrorOSError TypeError _run_http)r5rNr@rArBrCrDrErFrGrHrIrJuse_wss r/rOz Sandbox.runs~iR  ##%3Y3) <<##)#5'  $ <<)#5'  ' WiH >> "  s A**/BB)rFrGrHrIc ddlm} |j}|jj}| |||||||||| | | |  \}}t |||}|s|S|j S)z"Execute via WebSocket /execute/ws.r) run_ws_streamrP)langsmith.sandbox._ws_executer\r?r%_api_keyrresult)r5rNr@rArBrCrJrDrErFrGrHrIr\rapi_key msg_streamcontrolhandles r/rUzSandbox._run_ws s}" @335 ,,''+   %1#  G z7D9M}}r1c|j}|d}|||d}|||d<|||d< |jjj|||dz} | j | j } t | jdd | jd d | jd d  S#tj$r} t| d} ~ wwxYw)z9Execute via HTTP POST /execute (existing implementation).z/execute)rNr@rCNrArB )jsonr@stdoutr)stderr exit_code)rgrhri) r?r%_httppostraise_for_statusrfrr*httpxHTTPStatusErrorr) r5rNr@rArBrCrurlpayloadresponser,es r/rYzSandbox._run_httpMs335 x(#  ? GEN ? GEN ||))..s'TV,.WH  % % '==?D"xx"-xx"-((;3  $$  %a (  sBB44C CCr stdout_offset stderr_offsetcddlm}|j}|jj}||||||\}}t ||||||S)aReconnect to a running or recently-finished command. Resumes output from the given byte offsets. Any output produced while the client was disconnected is replayed from the server's ring buffer. Args: command_id: The command ID from handle.command_id. stdout_offset: Byte offset to resume stdout from (default: 0). stderr_offset: Byte offset to resume stderr from (default: 0). Returns: A CommandHandle for the command. Raises: SandboxOperationError: If command_id is not found or session expired. SandboxConnectionError: If connection to sandbox fails after retries. r)reconnect_ws_streamrt) command_idrurv)r]rxr?r%r^r) r5ryrurvrxrr`rarbs r/ reconnectzSandbox.reconnectpsd0 F335 ,,''1   ''   G   !''   r1)r@cJ|j}|d}t|tr|jd}dd|fi} |jj j |d|i||}|jy#tj$r}t|Yd}~yd}~wwxYw)a*Write content to a file in the sandbox. Args: path: Target file path in the sandbox. content: File content (str or bytes). timeout: Request timeout in seconds. Raises: DataplaneNotConfiguredError: If dataplane_url is not configured. SandboxOperationError: If file write fails. SandboxConnectionError: If connection to sandbox fails after retries. SandboxNotReadyError: If sandbox is not ready. SandboxClientError: For other errors. z/uploadzutf-8filepath)paramsfilesr@N) r? isinstancerencoder%rkrlrmrnror) r5r}contentr@rrprrrrss r/writez Sandbox.writes*335 w' gs #nnW-G&'*+ )||))..VTN%/H  % % '$$ ) %a ( ( )s;A::B" BB"cx|j}|d} |jjj|d|i|}|j |j S#t j$rI}|jjdk(rtd|d|jdd |t|d }~wwxYw) aRead a file from the sandbox. Args: path: File path to read. Supports both absolute paths (e.g., /tmp/file.txt) and relative paths (resolved from /home/user/). timeout: Request timeout in seconds. Returns: File contents as bytes. Raises: DataplaneNotConfiguredError: If dataplane_url is not configured. ResourceNotFoundError: If the file doesn't exist. SandboxOperationError: If file read fails. SandboxConnectionError: If connection to sandbox fails after retries. SandboxNotReadyError: If sandbox is not ready. SandboxClientError: For other errors. z /downloadr})r~r@izFile 'z' not found in sandbox ''r|) resource_typeN) r?r%rkr*rmrrnrorr status_coderrr)r5r}r@rrprrrss r/readz Sandbox.reads&335 y) ||))--VTNG.H  % % '## #$$ zz%%,+TF":499+QG"( &a (  sAAB90AB44B9 local_portmax_reconnectscd|cxkrdksntd|d|rd|cxkrdksntd|d|j}|jj}t |||||}|j |S)aOpen a TCP tunnel to a port inside the sandbox. Creates a local TCP listener that forwards connections through a yamux-multiplexed WebSocket to the specified port inside the sandbox. Works with any TCP protocol (databases, Redis, HTTP, etc.). Use as a context manager for automatic cleanup:: with sandbox.tunnel(remote_port=5432) as t: conn = psycopg2.connect(host="127.0.0.1", port=t.local_port) Or manage the lifecycle explicitly:: t = sandbox.tunnel(remote_port=5432) # ... use tunnel ... t.close() Args: remote_port: TCP port inside the sandbox to tunnel to (1-65535). local_port: Local port to listen on. Defaults to mirroring remote_port. Use 0 to let the OS pick an available port. max_reconnects: Maximum number of automatic reconnect attempts when the WebSocket session drops. Set to 0 to disable. Returns: A Tunnel instance (context manager). Raises: ValueError: If port values are out of range. DataplaneNotConfiguredError: If dataplane_url is not configured. SandboxNotReadyError: If sandbox is not ready. iz-remote_port must be between 1 and 65535 (got )z,local_port must be between 1 and 65535 (got r)rTr?r%r^r_start)r5 remote_portrrrr`ts r/tunnelzSandbox.tunnelsNK(5(? }AN  a:66>zl!L 335 ,,''    !)    r1)T)r,zdict[str, Any]r-rr.r&returnr)rr)r:zOptional[type]r;zOptional[BaseException]r<z Optional[Any]rNone)rr)rNrr@intrAOptional[dict[str, str]]rBrrCrrDOptional[Callable[[str], Any]]rErrFrrGr&rHrrIr&rJz Literal[True]rr)rNrr@rrArrBrrCrrDrrErrFrrGr&rHrrIr&rJzLiteral[False]rr)rNrr@rrArrBrrCrrDrrErrFrrGr&rHrrIr&rJr&r%Union[ExecutionResult, CommandHandle])rNrr@rrArrBrrCrrJr&rDrrErrFrrGr&rHrrIr&rr) rNrr@rrArrBrrCrrr)ryrrurrvrrr)r}rrzUnion[str, bytes]r@rrr)r}rr@rrbytes)rrrrrrrr)__name__ __module__ __qualname____doc____annotations__rrrr r!r"rr%r' classmethodr0r6r=r?r rOrUrYrzrrrr3r1r/rrs0 I#'M='B FC$(NM( $J $ $J $#trsVE"(SSS  A-7 GG Gr1