@@ -340,10 +340,10 @@ pub struct ReadTextFileRequest {
340340pub session_id : SessionId ,
341341 /// Absolute path to the file to read.
342342pub path : PathBuf ,
343- /// Optional line number to start reading from (1-based).
343+ /// Line number to start reading from (1-based).
344344#[ serde( default , skip_serializing_if = "Option::is_none" ) ]
345345 pub line : Option < u32 > ,
346- /// Optional maximum number of lines to read.
346+ /// Maximum number of lines to read.
347347#[ serde( default , skip_serializing_if = "Option::is_none" ) ]
348348 pub limit : Option < u32 > ,
349349}
@@ -368,82 +368,119 @@ impl std::fmt::Display for TerminalId {
368368 }
369369}
370370
371+ /// Request to create a new terminal and execute a command.
371372#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
372373#[ serde( rename_all = "camelCase" ) ]
373374#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_CREATE_METHOD_NAME ) ) ]
374375pub struct CreateTerminalRequest {
376+ /// The session ID for this request.
375377pub session_id : SessionId ,
378+ /// The command to execute.
376379pub command : String ,
380+ /// Array of command arguments.
377381#[ serde( default , skip_serializing_if = "Vec::is_empty" ) ]
378382 pub args : Vec < String > ,
383+ /// Environment variables for the command.
379384#[ serde( default , skip_serializing_if = "Vec::is_empty" ) ]
380385 pub env : Vec < crate :: EnvVariable > ,
386+ /// Working directory for the command (absolute path).
381387#[ serde( default , skip_serializing_if = "Option::is_none" ) ]
382388 pub cwd : Option < PathBuf > ,
389+ /// Maximum number of output bytes to retain.
390+ ///
391+ /// When the limit is exceeded, the Client truncates from the beginning of the output
392+ /// to stay within the limit.
393+ ///
394+ /// The Client MUST ensure truncation happens at a character boundary to maintain valid
395+ /// string output, even if this means the retained output is slightly less than the
396+ /// specified limit.
383397#[ serde( default , skip_serializing_if = "Option::is_none" ) ]
384398 pub output_byte_limit : Option < u64 > ,
385399}
386400
401+ /// Response containing the ID of the created terminal.
387402#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
388403#[ serde( rename_all = "camelCase" ) ]
389404#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_CREATE_METHOD_NAME ) ) ]
390405pub struct CreateTerminalResponse {
406+ /// The unique identifier for the created terminal.
391407pub terminal_id : TerminalId ,
392408}
393409
410+ /// Request to get the current output and status of a terminal.
394411#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
395412#[ serde( rename_all = "camelCase" ) ]
396413#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_OUTPUT_METHOD_NAME ) ) ]
397414pub struct TerminalOutputRequest {
415+ /// The session ID for this request.
398416pub session_id : SessionId ,
417+ /// The ID of the terminal to get output from.
399418pub terminal_id : TerminalId ,
400419}
401420
421+ /// Response containing the terminal output and exit status.
402422#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
403423#[ serde( rename_all = "camelCase" ) ]
404424#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_OUTPUT_METHOD_NAME ) ) ]
405425pub struct TerminalOutputResponse {
426+ /// The terminal output captured so far.
406427pub output : String ,
428+ /// Whether the output was truncated due to byte limits.
407429pub truncated : bool ,
430+ /// Exit status if the command has completed.
408431pub exit_status : Option < TerminalExitStatus > ,
409432}
410433
434+ /// Request to release a terminal and free its resources.
411435#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
412436#[ serde( rename_all = "camelCase" ) ]
413437#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_RELEASE_METHOD_NAME ) ) ]
414438pub struct ReleaseTerminalRequest {
439+ /// The session ID for this request.
415440pub session_id : SessionId ,
441+ /// The ID of the terminal to release.
416442pub terminal_id : TerminalId ,
417443}
418444
445+ /// Request to kill a terminal command without releasing the terminal.
419446#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
420447#[ serde( rename_all = "camelCase" ) ]
421448#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_KILL_METHOD_NAME ) ) ]
422449pub struct KillTerminalCommandRequest {
450+ /// The session ID for this request.
423451pub session_id : SessionId ,
452+ /// The ID of the terminal to kill.
424453pub terminal_id : TerminalId ,
425454}
426455
456+ /// Request to wait for a terminal command to exit.
427457#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
428458#[ serde( rename_all = "camelCase" ) ]
429459#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_WAIT_FOR_EXIT_METHOD_NAME ) ) ]
430460pub struct WaitForTerminalExitRequest {
461+ /// The session ID for this request.
431462pub session_id : SessionId ,
463+ /// The ID of the terminal to wait for.
432464pub terminal_id : TerminalId ,
433465}
434466
467+ /// Response containing the exit status of a terminal command.
435468#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
436469#[ serde( rename_all = "camelCase" ) ]
437470#[ schemars( extend( "x-side" = "client" , "x-method" = TERMINAL_WAIT_FOR_EXIT_METHOD_NAME ) ) ]
438471pub struct WaitForTerminalExitResponse {
472+ /// The exit status of the terminal command.
439473#[ serde( flatten) ]
440474 pub exit_status : TerminalExitStatus ,
441475}
442476
477+ /// Exit status of a terminal command.
443478#[ derive( Debug , Clone , Serialize , Deserialize , JsonSchema ) ]
444479#[ serde( rename_all = "camelCase" ) ]
445480pub struct TerminalExitStatus {
481+ /// The process exit code (may be null if terminated by signal).
446482pub exit_code : Option < u32 > ,
483+ /// The signal that terminated the process (may be null if exited normally).
447484pub signal : Option < String > ,
448485}
449486
0 commit comments