Skip to content

Commit 5d8d5d4

Browse files
agu-zagu-z
committed
Terminal docs
1 parent a4ebb2d commit 5d8d5d4

4 files changed

Lines changed: 311 additions & 4 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: 21 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,20 @@ 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 manage shell commands.
124+
</ParamField>
125+
126+
<Card icon="terminal" horizontal href="./terminals">
127+
Learn more about Terminals
128+
</Card>
129+
113130
### Agent Capabilities
114131

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

‎docs/protocol/terminals.mdx‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
title: "Terminals"
3+
description: "Executing and managing terminal commands"
4+
---
5+
6+
The terminal methods allow Agents to execute shell commands within the Client's environment. These methods enable Agents to run build processes, execute scripts, and interact with command-line tools while providing real-time output streaming and process control.
7+
8+
## Checking Support
9+
10+
Before attempting to use terminal methods, Agents **MUST** verify that the Client supports this capability by checking the [Client Capabilities](./initialization#client-capabilities) field in the `initialize` response:
11+
12+
```json highlight={7}
13+
{
14+
"jsonrpc": "2.0",
15+
"id": 0,
16+
"result": {
17+
"protocolVersion": 1,
18+
"clientCapabilities": {
19+
"terminal": true
20+
}
21+
}
22+
}
23+
```
24+
25+
If `terminal` is `false` or not present, the Agent **MUST NOT** attempt to call any terminal methods.
26+
27+
## Executing Commands
28+
29+
The `terminal/create` method starts a command in a new terminal:
30+
31+
```json
32+
{
33+
"jsonrpc": "2.0",
34+
"id": 5,
35+
"method": "terminal/create",
36+
"params": {
37+
"sessionId": "sess_abc123def456",
38+
"command": "npm",
39+
"args": ["test", "--coverage"],
40+
"env": [
41+
{
42+
"name": "NODE_ENV",
43+
"value": "test"
44+
}
45+
],
46+
"cwd": "/home/user/project",
47+
"outputByteLimit": 1048576
48+
}
49+
}
50+
```
51+
52+
<ParamField path="sessionId" type="SessionId" required>
53+
The [Session ID](./session-setup#session-id) for this request
54+
</ParamField>
55+
56+
<ParamField path="command" type="string" required>
57+
The command to execute
58+
</ParamField>
59+
60+
<ParamField path="args" type="string[]">
61+
Optional array of command arguments
62+
</ParamField>
63+
64+
<ParamField path="env" type="EnvVariable[]">
65+
Optional environment variables for the command.
66+
67+
Each variable has:
68+
- `name`: The environment variable name
69+
- `value`: The environment variable value
70+
</ParamField>
71+
72+
<ParamField path="cwd" type="string">
73+
Optional working directory for the command (absolute path)
74+
</ParamField>
75+
76+
<ParamField path="outputByteLimit" type="number">
77+
Optional maximum number of output bytes to retain. Once exceeded, earlier output is truncated to stay within this limit.
78+
</ParamField>
79+
80+
The Client returns a Terminal ID immediately without waiting for completion:
81+
82+
```json
83+
{
84+
"jsonrpc": "2.0",
85+
"id": 5,
86+
"result": {
87+
"terminalId": "term_xyz789"
88+
}
89+
}
90+
```
91+
92+
This allows the command to run in the background while the Agent performs other operations.
93+
94+
After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete.
95+
96+
<Note>
97+
The Agent **MUST** release the terminal using `terminal/release` when it's no longer needed.
98+
</Note>
99+
100+
101+
102+
## Embedding in Tool Calls
103+
104+
Terminals can be embedded directly in [tool calls](./tool-calls) to provide real-time output to users:
105+
106+
```json
107+
{
108+
"jsonrpc": "2.0",
109+
"method": "session/update",
110+
"params": {
111+
"sessionId": "sess_abc123def456",
112+
"update": {
113+
"sessionUpdate": "tool_call",
114+
"toolCallId": "call_002",
115+
"title": "Running tests",
116+
"kind": "execute",
117+
"status": "in_progress",
118+
"content": [
119+
{
120+
"type": "terminal",
121+
"terminalId": "term_xyz789"
122+
}
123+
]
124+
}
125+
}
126+
}
127+
```
128+
129+
When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released.
130+
131+
## Getting Output
132+
133+
The `terminal/output` method retrieves the current terminal output without waiting for the command to complete:
134+
135+
```json
136+
{
137+
"jsonrpc": "2.0",
138+
"id": 6,
139+
"method": "terminal/output",
140+
"params": {
141+
"sessionId": "sess_abc123def456",
142+
"terminalId": "term_xyz789"
143+
}
144+
}
145+
```
146+
147+
The Client responds with the current output and exit status (if the command has finished):
148+
149+
```json
150+
{
151+
"jsonrpc": "2.0",
152+
"id": 6,
153+
"result": {
154+
"output": "Running tests...\n✓ All tests passed (42 total)\n",
155+
"truncated": false,
156+
"exitStatus": {
157+
"exitCode": 0,
158+
"signal": null
159+
}
160+
}
161+
}
162+
```
163+
164+
<ResponseField name="output" type="string" required>
165+
The terminal output captured so far
166+
</ResponseField>
167+
168+
<ResponseField name="truncated" type="boolean" required>
169+
Whether the output was truncated due to byte limits
170+
</ResponseField>
171+
172+
<ResponseField name="exitStatus" type="TerminalExitStatus">
173+
Present only if the command has exited. Contains:
174+
- `exitCode`: The process exit code (may be null)
175+
- `signal`: The signal that terminated the process (may be null)
176+
</ResponseField>
177+
178+
## Waiting for Exit
179+
180+
The `terminal/wait_for_exit` method returns once the command completes:
181+
182+
```json
183+
{
184+
"jsonrpc": "2.0",
185+
"id": 7,
186+
"method": "terminal/wait_for_exit",
187+
"params": {
188+
"sessionId": "sess_abc123def456",
189+
"terminalId": "term_xyz789"
190+
}
191+
}
192+
```
193+
194+
The Client responds once the command exits:
195+
196+
```json
197+
{
198+
"jsonrpc": "2.0",
199+
"id": 7,
200+
"result": {
201+
"exitCode": 0,
202+
"signal": null
203+
}
204+
}
205+
```
206+
207+
<ResponseField name="exitCode" type="number">
208+
The process exit code (may be null if terminated by signal)
209+
</ResponseField>
210+
211+
<ResponseField name="signal" type="string">
212+
The signal that terminated the process (may be null if exited normally)
213+
</ResponseField>
214+
215+
## Killing Commands
216+
217+
The `terminal/kill` method terminates a command without releasing the terminal:
218+
219+
```json
220+
{
221+
"jsonrpc": "2.0",
222+
"id": 8,
223+
"method": "terminal/kill",
224+
"params": {
225+
"sessionId": "sess_abc123def456",
226+
"terminalId": "term_xyz789"
227+
}
228+
}
229+
```
230+
231+
After killing a command, the terminal remains valid and can be used with:
232+
- `terminal/output` to get the final output
233+
- `terminal/wait_for_exit` to get the exit status
234+
235+
The Agent **MUST** still call `terminal/release` when it's done using it.
236+
237+
### Building a Timeout
238+
239+
Agents can implement command timeouts by combining terminal methods:
240+
241+
1. Create a terminal with `terminal/create`
242+
2. Start a timer for the desired timeout duration
243+
3. Concurrently wait for either the timer to expire or `terminal/wait_for_exit` to return
244+
4. If the timer expires first:
245+
- Call `terminal/kill` to terminate the command
246+
- Call `terminal/output` to retrieve any final output
247+
- Include the output in the response to the model
248+
5. Call `terminal/release` when done
249+
250+
## Releasing Terminals
251+
252+
The `terminal/release` kills the command if still running and releases all resources:
253+
254+
```json
255+
{
256+
"jsonrpc": "2.0",
257+
"id": 9,
258+
"method": "terminal/release",
259+
"params": {
260+
"sessionId": "sess_abc123def456",
261+
"terminalId": "term_xyz789"
262+
}
263+
}
264+
```
265+
266+
After release the terminal ID becomes invalid for all other `terminal/*` methods.
267+
268+
If the terminal was added to a tool call, the client **SHOULD** continue to display its output after release.

‎docs/protocol/tool-calls.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,27 @@ File modifications shown as diffs:
269269
The new content after modification
270270
</ParamField>
271271

272+
### Terminals
273+
274+
Live terminal output from command execution:
275+
276+
```json
277+
{
278+
"type": "terminal",
279+
"terminalId": "term_xyz789"
280+
}
281+
```
282+
283+
<ParamField path="terminalId" type="string" required>
284+
The ID of a terminal created with `terminal/create`
285+
</ParamField>
286+
287+
When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released.
288+
289+
<Card icon="terminal" horizontal href="./terminals">
290+
Learn more about Terminals
291+
</Card>
292+
272293
## Following the Agent
273294

274295
Tool calls can report file locations they're working with, enabling Clients to implement "follow-along" features that track which files the Agent is accessing or modifying in real-time.

0 commit comments

Comments
 (0)