Skip to content

Commit 9dff1b9

Browse files
agu-zagu-z
authored
Stabilize Terminals (#81)
* Remove unstable cfg for terminal methods * Document terminals * Add docs ref * Terminal docs * Add docs to ts library * Add missing field docs
1 parent d258269 commit 9dff1b9

14 files changed

Lines changed: 1018 additions & 258 deletions

File tree

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
"protocol/content",
5757
"protocol/tool-calls",
5858
"protocol/file-system",
59+
"protocol/terminals",
5960
"protocol/agent-plan",
6061
"protocol/schema"
6162
]

‎docs/protocol/initialization.mdx‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ Before a Session can be created, Clients **MUST** initialize the connection by c
3939
"fs": {
4040
"readTextFile": true,
4141
"writeTextFile": true
42-
}
42+
},
43+
"terminal": true
4344
}
4445
}
4546
}
@@ -59,6 +60,10 @@ The Agent **MUST** respond with the chosen [protocol version](#protocol-version)
5960
"image": true,
6061
"audio": true,
6162
"embeddedContext": true
63+
},
64+
"mcp": {
65+
"http": true,
66+
"sse": true
6267
}
6368
},
6469
"authMethods": []
@@ -96,12 +101,10 @@ Capabilities may specify the availability of protocol methods, notifications, or
96101

97102
### Client Capabilities
98103

99-
The Client **SHOULD** specify whether it supports the following capability:
104+
The Client **SHOULD** specify whether it supports the following capabilities:
100105

101106
#### File System
102107

103-
The Client **MAY** expose its [File System](./file-system) abstraction to varying degrees:
104-
105108
<ParamField path="readTextFile" type="boolean">
106109
The `fs/read_text_file` method is available.
107110
</ParamField>
@@ -110,6 +113,21 @@ The Client **MAY** expose its [File System](./file-system) abstraction to varyin
110113
The `fs/write_text_file` method is available.
111114
</ParamField>
112115

116+
<Card icon="file" horizontal href="./file-system">
117+
Learn more about File System methods
118+
</Card>
119+
120+
#### Terminal
121+
122+
<ParamField path="terminal" type="boolean">
123+
All `terminal/*` methods are available, allowing the Agent to execute and
124+
manage shell commands.
125+
</ParamField>
126+
127+
<Card icon="terminal" horizontal href="./terminals">
128+
Learn more about Terminals
129+
</Card>
130+
113131
### Agent Capabilities
114132

115133
The Agent **SHOULD** specify whether it supports the following capabilities:

‎docs/protocol/schema.mdx‎

Lines changed: 264 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -358,13 +358,13 @@ Only available if the client supports the `fs.readTextFile` capability.
358358
**Properties:**
359359

360360
<ResponseField name="limit" type={"integer | null"} >
361-
Optional maximum number of lines to read.
361+
Maximum number of lines to read.
362362

363363
- Minimum: `0`
364364

365365
</ResponseField>
366366
<ResponseField name="line" type={"integer | null"} >
367-
Optional line number to start reading from (1-based).
367+
Line number to start reading from (1-based).
368368

369369
- Minimum: `0`
370370

@@ -523,6 +523,244 @@ See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protoc
523523
The actual update content.
524524
</ResponseField>
525525

526+
<a id="terminal-create"></a>
527+
### <span class="font-mono">terminal/create</span>
528+
529+
Executes a command in a new terminal
530+
531+
Only available if the `terminal` Client capability is set to `true`.
532+
533+
Returns a `TerminalId` that can be used with other terminal methods
534+
to get the current output, wait for exit, and kill the command.
535+
536+
The `TerminalId` can also be used to embed the terminal in a tool call
537+
by using the `ToolCallContent::Terminal` variant.
538+
539+
The Agent is responsible for releasing the terminal by using the `terminal/release`
540+
method.
541+
542+
See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
543+
544+
#### <span class="font-mono">CreateTerminalRequest</span>
545+
546+
Request to create a new terminal and execute a command.
547+
548+
**Type:** Object
549+
550+
**Properties:**
551+
552+
<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
553+
Array of command arguments.
554+
</ResponseField>
555+
<ResponseField name="command" type={"string"} required>
556+
The command to execute.
557+
</ResponseField>
558+
<ResponseField name="cwd" type={"string | null"} >
559+
Working directory for the command (absolute path).
560+
</ResponseField>
561+
<ResponseField name="env" type={<><span><a href="#envvariable">EnvVariable</a></span><span>[]</span></>} >
562+
Environment variables for the command.
563+
</ResponseField>
564+
<ResponseField name="outputByteLimit" type={"integer | null"} >
565+
Maximum number of output bytes to retain.
566+
567+
When the limit is exceeded, the Client truncates from the beginning of the output
568+
to stay within the limit.
569+
570+
The Client MUST ensure truncation happens at a character boundary to maintain valid
571+
string output, even if this means the retained output is slightly less than the
572+
specified limit.
573+
574+
- Minimum: `0`
575+
576+
</ResponseField>
577+
<ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
578+
The session ID for this request.
579+
</ResponseField>
580+
581+
#### <span class="font-mono">CreateTerminalResponse</span>
582+
583+
Response containing the ID of the created terminal.
584+
585+
**Type:** Object
586+
587+
**Properties:**
588+
589+
<ResponseField name="terminalId" type={"string"} required>
590+
The unique identifier for the created terminal.
591+
</ResponseField>
592+
593+
<a id="terminal-kill"></a>
594+
### <span class="font-mono">terminal/kill</span>
595+
596+
Kills the terminal command without releasing the terminal
597+
598+
While `terminal/release` will also kill the command, this method will keep
599+
the `TerminalId` valid so it can be used with other methods.
600+
601+
This method can be helpful when implementing command timeouts which terminate
602+
the command as soon as elapsed, and then get the final output so it can be sent
603+
to the model.
604+
605+
Note: `terminal/release` when `TerminalId` is no longer needed.
606+
607+
See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
608+
609+
#### <span class="font-mono">KillTerminalCommandRequest</span>
610+
611+
Request to kill a terminal command without releasing the terminal.
612+
613+
**Type:** Object
614+
615+
**Properties:**
616+
617+
<ResponseField
618+
name="sessionId"
619+
type={<a href="#sessionid">SessionId</a>}
620+
required
621+
>
622+
The session ID for this request.
623+
</ResponseField>
624+
<ResponseField name="terminalId" type={"string"} required>
625+
The ID of the terminal to kill.
626+
</ResponseField>
627+
628+
<a id="terminal-output"></a>
629+
### <span class="font-mono">terminal/output</span>
630+
631+
Gets the terminal ouput and exit status
632+
633+
Returns the current content in the terminal without waiting for the command to exit.
634+
If the command has already exited, the exit status is included.
635+
636+
See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
637+
638+
#### <span class="font-mono">TerminalOutputRequest</span>
639+
640+
Request to get the current output and status of a terminal.
641+
642+
**Type:** Object
643+
644+
**Properties:**
645+
646+
<ResponseField
647+
name="sessionId"
648+
type={<a href="#sessionid">SessionId</a>}
649+
required
650+
>
651+
The session ID for this request.
652+
</ResponseField>
653+
<ResponseField name="terminalId" type={"string"} required>
654+
The ID of the terminal to get output from.
655+
</ResponseField>
656+
657+
#### <span class="font-mono">TerminalOutputResponse</span>
658+
659+
Response containing the terminal output and exit status.
660+
661+
**Type:** Object
662+
663+
**Properties:**
664+
665+
<ResponseField
666+
name="exitStatus"
667+
type={
668+
<>
669+
<span>
670+
<a href="#terminalexitstatus">TerminalExitStatus</a>
671+
</span>
672+
<span> | null</span>
673+
</>
674+
}
675+
>
676+
Exit status if the command has completed.
677+
</ResponseField>
678+
<ResponseField name="output" type={"string"} required>
679+
The terminal output captured so far.
680+
</ResponseField>
681+
<ResponseField name="truncated" type={"boolean"} required>
682+
Whether the output was truncated due to byte limits.
683+
</ResponseField>
684+
685+
<a id="terminal-release"></a>
686+
### <span class="font-mono">terminal/release</span>
687+
688+
Releases a terminal
689+
690+
The command is killed if it hasn't exited yet. Use `terminal/wait_for_exit`
691+
to wait for the command to exit before releasing the terminal.
692+
693+
After release, the `TerminalId` can no longer be used with other `terminal/*` methods,
694+
but tool calls that already contain it, continue to display its output.
695+
696+
The `terminal/kill` method can be used to terminate the command without releasing
697+
the terminal, allowing the Agent to call `terminal/output` and other methods.
698+
699+
See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
700+
701+
#### <span class="font-mono">ReleaseTerminalRequest</span>
702+
703+
Request to release a terminal and free its resources.
704+
705+
**Type:** Object
706+
707+
**Properties:**
708+
709+
<ResponseField
710+
name="sessionId"
711+
type={<a href="#sessionid">SessionId</a>}
712+
required
713+
>
714+
The session ID for this request.
715+
</ResponseField>
716+
<ResponseField name="terminalId" type={"string"} required>
717+
The ID of the terminal to release.
718+
</ResponseField>
719+
720+
<a id="terminal-wait_for_exit"></a>
721+
### <span class="font-mono">terminal/wait_for_exit</span>
722+
723+
Waits for the terminal command to exit and return its exit status
724+
725+
See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
726+
727+
#### <span class="font-mono">WaitForTerminalExitRequest</span>
728+
729+
Request to wait for a terminal command to exit.
730+
731+
**Type:** Object
732+
733+
**Properties:**
734+
735+
<ResponseField
736+
name="sessionId"
737+
type={<a href="#sessionid">SessionId</a>}
738+
required
739+
>
740+
The session ID for this request.
741+
</ResponseField>
742+
<ResponseField name="terminalId" type={"string"} required>
743+
The ID of the terminal to wait for.
744+
</ResponseField>
745+
746+
#### <span class="font-mono">WaitForTerminalExitResponse</span>
747+
748+
Response containing the exit status of a terminal command.
749+
750+
**Type:** Object
751+
752+
**Properties:**
753+
754+
<ResponseField name="exitCode" type={"integer | null"} >
755+
The process exit code (may be null if terminated by signal).
756+
757+
- Minimum: `0`
758+
759+
</ResponseField>
760+
<ResponseField name="signal" type={"string | null"} >
761+
The signal that terminated the process (may be null if exited normally).
762+
</ResponseField>
763+
526764
## <span class="font-mono">AgentCapabilities</span>
527765

528766
Capabilities supported by the agent.
@@ -694,9 +932,7 @@ Determines which file operations the agent can request.
694932

695933
</ResponseField>
696934
<ResponseField name="terminal" type={"boolean"} >
697-
**UNSTABLE**
698-
699-
This capability is not part of the spec yet, and may be removed or changed at any point.
935+
Whether the Client support all `terminal/*` methods.
700936

701937
- Default: `false`
702938

@@ -1781,6 +2017,24 @@ response to confirm successful cancellation.
17812017

17822018
</ResponseField>
17832019

2020+
## <span class="font-mono">TerminalExitStatus</span>
2021+
2022+
Exit status of a terminal command.
2023+
2024+
**Type:** Object
2025+
2026+
**Properties:**
2027+
2028+
<ResponseField name="exitCode" type={"integer | null"} >
2029+
The process exit code (may be null if terminated by signal).
2030+
2031+
- Minimum: `0`
2032+
2033+
</ResponseField>
2034+
<ResponseField name="signal" type={"string | null"} >
2035+
The signal that terminated the process (may be null if exited normally).
2036+
</ResponseField>
2037+
17842038
## <span class="font-mono">TextContent</span>
17852039

17862040
Text provided to or from an LLM.
@@ -1929,7 +2183,11 @@ File modification shown as a diff.
19292183
</ResponseField>
19302184

19312185
<ResponseField name="terminal">
1932-
{""}
2186+
Embed a terminal created with `terminal/create` by its id.
2187+
2188+
The terminal must be added before calling `terminal/release`.
2189+
2190+
See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminal)
19332191

19342192
<Expandable title="Properties">
19352193

0 commit comments

Comments
 (0)