jocdZddlmZddlmZddlmZmZddlm Z m Z m Z m Z m Z mZmZddlZddlmZmZmZmZddlmZdd lmZmZmZmZdd lmZe rdd lm Z e ee!e!fZ"eGd d Z#dS)z?Sandbox class for interacting with a specific sandbox instance.) annotations)Mapping) dataclassfield) TYPE_CHECKINGAnyCallableLiteralOptionalUnionoverloadN)DataplaneNotConfiguredErrorResourceNotFoundErrorSandboxConnectionErrorSandboxNotReadyError)handle_sandbox_http_error) CommandHandleExecutionResult ServiceURLSnapshot)Tunnel) SandboxClientceZdZUdZded<dZded<dZded<dZded <dZded <dZ ded <dZ ded <dZ d ed<dZ d ed<dZ ded<dZded<dZd ed<dZd ed<dZd ed<eddZded<eddZded<e dndod!Zdpd"Zdqd*Zdrd+Zed,d,d,d,d,d,d,d,d,d,d,d,d- dsd@Zed,d,d,d,d,d,d,d,d,d,d,dA dtdDZdEdddFdddGddHdddd- dudJZdGddHdddKdvdLZdwdMZdNdNddOdxdSZdEddTdydXZdEddTdzdZZ dNd[dd\d{daZ!dHddbd|dfZ"dgddTd}dhZ#ddid~djZ$ddid~dkZ%dEddTddmZ&dS)SandboxaRepresents an active sandbox for running commands and file operations. This class is typically obtained from SandboxClient.sandbox() and supports the context manager protocol for automatic cleanup. Attributes: name: Display name (can be updated). dataplane_url: URL for data plane operations (file I/O, command execution). Only functional when status is "ready". id: Unique identifier (UUID). Remains constant even if name changes. May be None for resources created before ID support was added. status: Sandbox lifecycle status. One of "provisioning", "ready", "failed", "stopped". status_message: Human-readable details when status is "failed", None otherwise. created_at: Timestamp when the sandbox was created. updated_at: Timestamp when the sandbox was last updated. ttl_seconds: Maximum lifetime TTL in seconds (0 means disabled). idle_ttl_seconds: Idle timeout TTL in seconds (``0`` means disabled). Newly-created sandboxes receive a server-side default of ``600`` seconds (10 minutes) when the caller did not set ``idle_ttl_seconds`` explicitly. expires_at: Computed expiration timestamp, or None if no TTL is set. snapshot_id: Snapshot ID used to create this sandbox. vcpus: Number of vCPUs allocated. mem_bytes: Memory allocation in bytes. fs_capacity_bytes: Root filesystem capacity in bytes. Example: with client.sandbox(snapshot_id="") as sandbox: result = sandbox.run("python --version") print(result.stdout) strnameN Optional[str] dataplane_urlidreadystatusstatus_message created_at updated_atz Optional[int] ttl_secondsidle_ttl_seconds expires_at snapshot_idvcpus mem_bytesfs_capacity_bytesF)reprdefaultr_clientTbool _auto_deletedatadict[str, Any]client auto_deletereturnc |did|ddd|dd|dd|ddd|dd|dd |d d |d d |d d |d d |d d|dd|dd|dd|d|S)a4Create a Sandbox from API response dict. Args: data: API response dictionary containing sandbox data. client: Parent SandboxClient for operations. auto_delete: Whether to delete the sandbox on context exit. Returns: Sandbox instance. rrrr!r r"r#r$r%r&r'r(r)r*r+r.r0)get)clsr1r3r4s d/lsinfo/ai/hellotax_ai/base_platform/venv/lib/python3.11/site-packages/langsmith/sandbox/_sandbox.py from_dictzSandbox.from_dictXs"s   &"%%% ((?333 xx~~~ 88Hg...   88$4555  xx ---  xx --- /// "XX&8999 xx --- /// ((7### hh{+++ #hh':;;; F %!  c|S)zEnter context manager.r8selfs r; __enter__zSandbox.__enter__|s r=exc_typeOptional[type]exc_valOptional[BaseException]exc_tb Optional[Any]Nonecz|jr3 |j|jdS#t$rYdSwxYwdS)z6Exit context manager, optionally deleting the sandbox.N)r0r.delete_sandboxr Exception)r@rBrDrFs r;__exit__zSandbox.__exit__s^     ++DI66666      s * 88c|jdkr td|jd|jd|jst d|jd|jS)aValidate and return the dataplane URL. Returns: The dataplane URL. Raises: SandboxNotReadyError: If sandbox status is not "ready". DataplaneNotConfiguredError: If dataplane_url is not configured. r z Sandbox 'z' is not ready (status: z5). Wait for status 'ready' before running operations.zW' does not have a dataplane_url configured. Runtime operations require a dataplane URL.)r!rrrrr?s r;_require_dataplane_urlzSandbox._require_dataplane_urls ;' ! !&EDIEEt{EEE ! ->DI>>> !!r=.) timeoutenvcwdshell on_stdout on_stderr idle_timeoutkill_on_disconnectr%ptyheaderswaitcommandrOintrPOptional[dict[str, str]]rQrRrSOptional[Callable[[str], Any]]rTrUrVrWrXRequestHeadersrY Literal[True]rc dSNr8r@rZrOrPrQrRrSrTrUrVr%rWrXrYs r;runz Sandbox.runs "#r=) rOrPrQrRrSrTrUrVr%rWrXLiteral[False]rc dSrar8rbs r;rcz Sandbox.runs "r=<z /bin/bashi,iX%Union[ExecutionResult, CommandHandle]c l| s|s|rtd|| p|p|}|r"||||||| |||| | | |  S ||||||ddd|| | | |  S#ttt t f$r||||||| 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.) rOrPrQrRrYrSrTrUrVr%rWrXTN)rOrPrQrRrX) ValueErrorrN_run_wsr ImportErrorOSError TypeError _run_http)r@rZrOrPrQrRrSrTrUrVr%rWrXrYuse_wss r;rcz Sandbox.runsH@  i R  ##%%%3Y3)  <<##)#5'  & <<)#5'  ' WiH   >> "    s!A888B32B3)rUrVr%rWrXc ddlm}|}|jj}||||||| | | | d }| | |d<||||fi|\}}t |||}|s|S|jS)z"Execute via WebSocket /execute/ws.r) run_ws_stream) rOrPrQrRrSrTrUrVr%rWNrX)langsmith.sandbox._ws_executerqrNr._api_keyrresult)r@rZrOrPrQrRrYrSrTrUrVr%rWrXrqrapi_key ws_kwargs msg_streamcontrolhandles r;rjzSandbox._run_wsBs$ @?????3355 ,'""("4& % %   #*Ii +m         Gz7D99 M}r=c|}|d}|||d} ||| d<||| d< |jj|| |dz|j|} | | } t| dd | d d | d d  S#tj $r} t| d} ~ wwxYw)z9Execute via HTTP POST /execute (existing implementation).z/execute)rZrOrRNrPrQ )jsonrOrXstdoutr7stderr exit_code)r}r~r) rNr._httppost_request_headersraise_for_statusr|rr9httpxHTTPStatusErrorr) r@rZrOrPrQrRrXrurlpayloadresponser1es r;rnzSandbox._run_httpvs:3355 (((# #  ? GEN ? GEN |).."  55g>> /H  % % ' ' '==??D"xx"--xx"--((;33  $    %a ( ( (  sB3C##D2DDr) stdout_offset stderr_offsetrX command_idrrcddlm}|}|jj}||d}|||d<||||fi|\} } 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_stream)rrNrX)rrr)rrrrNr.rsr) r@rrrrXrrrureconnect_kwargsrwrxs r; reconnectzSandbox.reconnects2 FEEEEE3355 ,'+*, ,   *1 Y '11         G   !''     r=rOrXpathcontentUnion[str, bytes]c |}|d}t|tr|d}dd|fi} |jj|d|i|||j|}|dS#tj $r} t| Yd} ~ dSd} ~ 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-8filer)paramsfilesrOrXN) rN isinstancerencoder.rrrrrrr) r@rrrOrXrrrrrs r;writez Sandbox.writes,3355 ''' gs # # .nnW--G&'*+ )|)..~ 55g>> /H  % % ' ' ' ' '$ ) ) ) %a ( ( ( ( ( ( ( ( ( )s ABC.CCbytesc|}|d} |jj|d|i||j|}||jS#tj$rC}|j j dkrtd|d|j dd |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)rrOrXizFile 'z' not found in sandbox ''r) resource_typeN)rNr.rr9rrrrrr status_coderrr)r@rrOrXrrrrs r;readz Sandbox.reads*3355 ))) |)--~ 55g>> .H  % % ' ' '# #$   z%,,+GTGG49GGG"( &a ( ( (  sAA33C>CC local_portmax_reconnectsrX remote_portrrrc$d|cxkrdksntd|d|r"d|cxkrdksntd|d|}|jj}t ||||||}||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)rirNr.rsr_start)r@rrrrXrruts r;tunnelzSandbox.tunnel*sPK((((5((((N NNN   a:66666666LzLLL 3355 ,'    !)      r=expires_in_secondsrXportrrcH|j|j|||S)aGet an authenticated URL for a service running in this sandbox. Returns a :class:`ServiceURL` whose properties auto-refresh the token transparently before it expires. Args: port: Port the service is listening on inside the sandbox. expires_in_seconds: Token TTL in seconds (1--86400, default 600). headers: Optional per-request header overrides. Returns: ServiceURL with auto-refreshing token and HTTP helpers. Raises: ResourceNotFoundError: If sandbox not found. ValueError: If port or expires_in_seconds is out of range. SandboxClientError: For other errors. r)r.servicer)r@rrrXs r;rzSandbox.servicegs12|## I 1 $   r=xcz|j|j||}|j|_|j|_dS)a1Start a stopped sandbox and wait until ready. After starting, the sandbox's status and dataplane_url are updated in place. Args: timeout: Timeout in seconds when waiting for ready. headers: Optional per-request header overrides. Raises: ResourceNotFoundError: If sandbox not found. ResourceCreationError: If sandbox fails during startup. ResourceTimeoutError: If sandbox doesn't become ready within timeout. SandboxClientError: For other errors. rN)r. start_sandboxrr!r)r@rOrX refresheds r;startz Sandbox.startsF*L.. Iw/   & &4r=rXcd|j|j|d|_d|_dS)aStop a running sandbox (preserves sandbox files for later restart). Args: headers: Optional per-request header overrides. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. rstoppedN)r. stop_sandboxrr!rr@rXs r;stopz Sandbox.stops6 !!$)W!=== !r=cH|j|j|dS)zDelete this sandbox. Args: headers: Optional per-request header overrides. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. rN)r.rJrrs r;deletezSandbox.deletes' ##DIw#?????r=rcH|j|j|||S)a!Capture a snapshot from this sandbox. Args: name: Snapshot name. timeout: Timeout in seconds when waiting for ready. headers: Optional per-request header overrides. Returns: Snapshot in "ready" status. Raises: ResourceNotFoundError: If sandbox not found. ResourceTimeoutError: If snapshot doesn't become ready within timeout. ResourceCreationError: If snapshot capture fails. SandboxClientError: For other errors. r)r.capture_snapshotr)r@rrOrXs r;rzSandbox.capture_snapshots1.|,, I  -   r=)T)r1r2r3rr4r/r5r)r5r)rBrCrDrErFrGr5rH)r5r)rZrrOr[rPr\rQrrRrrSr]rTr]rUr[rVr/r%r[rWr/rXr^rYr_r5r)rZrrOr[rPr\rQrrRrrSr]rTr]rUr[rVr/r%r[rWr/rXr^rYrdr5r)rZrrOr[rPr\rQrrRrrSr]rTr]rUr[rVr/r%r[rWr/rXr^rYr/r5rg)rZrrOr[rPr\rQrrRrrYr/rSr]rTr]rUr[rVr/r%r[rWr/rXr^r5rg)rZrrOr[rPr\rQrrRrrXr^r5r) rrrr[rr[rXr^r5r) rrrrrOr[rXr^r5rH)rrrOr[rXr^r5r) rr[rr[rr[rXr^r5r)rr[rr[rXr^r5r)rOr[rXr^r5rH)rXr^r5rH)rrrOr[rXr^r5r)'__name__ __module__ __qualname____doc____annotations__rrr!r"r#r$r%r&r'r(r)r*r+rr.r0 classmethodr<rArLrNr rcrjrnrrrrrrrrrr8r=r;rr!s?DIII#'M''''BF$(N(((( $J$$$$ $J$$$$!%K%%%%&***** $J$$$$!%K%%%%E#I####'+++++#Ut<<rsEE""""""######((((((((SSSSSSSSSSSSSSSSSS  A@@@@@ -,,,,,8777777'#s(+, v  v  v  v  v  v  v   v  v  v  r=