Module 18: Terminal Operations

Execute shell commands on the client through the terminal API.

What You’ll Learn

The four-step terminal lifecycle: create, wait, output, release, plus kill to end a command early
Implementing terminal handlers on the client, all five: advertising terminal needs every one
Using the terminal API from the agent side

The Code

Client: Implement terminal handlers

// As of 0.80.0, the client advertises the terminal capability once all five handlers below are
// registered (create, output, wait for exit, kill, release); with only some of them it logs a
// warning naming the missing ones and advertises no terminal, with no clientCapabilities(..) call
// needed either way.
AcpSyncClient client = AcpClient.sync(transport)
    .createTerminalHandler(req -> {
        List<String> cmd = new ArrayList<>();
        cmd.add(req.command());
        if (req.args() != null) cmd.addAll(req.args());

        Process process = new ProcessBuilder(cmd)
            .redirectErrorStream(true)
            .start();

        terminals.put(terminalId, process);
        return new CreateTerminalResponse(terminalId);
    })
    .waitForTerminalExitHandler(req -> {
        Process process = terminals.get(req.terminalId()).process();
        int exitCode = process.waitFor();
        return new WaitForTerminalExitResponse(exitCode, null);
    })
    .terminalOutputHandler(req -> {
        // Drained live by a reader thread as the process writes, not read only at the end,
        // so a terminal/output call mid-run sees everything printed so far
        String output = capturedOutput.get(req.terminalId());
        return new TerminalOutputResponse(output, false, null);
    })
    .killTerminalHandler(req -> {
        // Ends a still-running command early; the terminal stays valid, so its output can
        // still be read and the agent releases it afterwards, same as a terminal that exited
        terminals.get(req.terminalId()).process().destroyForcibly();
        return new KillTerminalCommandResponse();
    })
    .releaseTerminalHandler(req -> {
        Process process = terminals.remove(req.terminalId()).process();
        process.destroyForcibly();
        return new ReleaseTerminalResponse();
    })
    .build();

client.initialize();

initialize(InitializeRequest) is removed as of 0.80.0: capabilities come from the client builder, either derived from registered handlers (as here) or set explicitly with clientCapabilities(..). See the 0.80.0 migration guide.

Advertising terminal needs all five handlers registered; with only some of them, the client logs a warning naming the missing ones and advertises no terminal at all, rather than a partial one. createTerminalHandler starts a background thread that drains the process’s output as it arrives, so terminalOutputHandler can answer with everything printed so far even while the command is still running; waitForTerminalExitHandler joins that thread before answering, so a terminal/output call right after exit still sees the command’s last lines.

Agent: Use terminal API

.promptHandler((req, context) -> {
    // Check capability first
    if (!context.getClientCapabilities().supportsTerminal()) {
        context.sendMessage("Terminal not supported");
        return PromptResponse.endTurn();
    }

    String terminalId = null;
    try {
        // Step 1: Create terminal
        var createResp = context.client().createTerminal(
            new CreateTerminalRequest(
                context.getSessionId(),
                "sh", List.of("-c", command),
                null, null, null));
        terminalId = createResp.terminalId();

        // Step 2: Wait for exit
        var exitResp = context.client().waitForTerminalExit(
            new WaitForTerminalExitRequest(context.getSessionId(), terminalId));

        // Step 3: Get output
        var outputResp = context.client().getTerminalOutput(
            new TerminalOutputRequest(context.getSessionId(), terminalId));

        context.sendMessage("Exit: " + exitResp.exitCode() +
            "\nOutput:\n" + outputResp.output());
    } finally {
        // Step 4: Always release
        if (terminalId != null) {
            context.client().releaseTerminal(
                new ReleaseTerminalRequest(context.getSessionId(), terminalId));
        }
    }
    return PromptResponse.endTurn();
})

Terminal Lifecycle

Step	Agent calls	Client handles	Purpose
1	`client().createTerminal()`	`createTerminalHandler`	Spawn process
2	`client().waitForTerminalExit()`	`waitForTerminalExitHandler`	Block until done
3	`client().getTerminalOutput()`	`terminalOutputHandler`	Read stdout/stderr
4	`client().releaseTerminal()`	`releaseTerminalHandler`	Clean up resources

client().killTerminal() / killTerminalHandler ends a still-running command early, outside this four-step sequence: the terminal stays valid afterward, so its output can still be read and it’s released the same as any other terminal. All five handlers are required to advertise terminal at all, not only the four in the table above. The agent requests command execution, but the client controls what actually runs. This keeps command execution under the user’s control — the client decides whether to allow, sandbox, or deny terminal requests.

The SDK also provides context.execute() as a convenience method that combines all four steps.

Source Code

View on GitHub

Running the Example

./mvnw package -pl module-18-terminal-operations -q
./mvnw exec:java -pl module-18-terminal-operations

Next Module

Module 19: MCP Servers — pass MCP server configurations to agents.

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

18 terminal operations

Module 18: Terminal Operations

What You’ll Learn

The Code

Client: Implement terminal handlers

Agent: Use terminal API

Terminal Lifecycle

Source Code

Running the Example

Next Module

​Module 18: Terminal Operations

​What You’ll Learn

​The Code

​Client: Implement terminal handlers

​Agent: Use terminal API

​Terminal Lifecycle

​Source Code

​Running the Example

​Next Module

Module 18: Terminal Operations

What You’ll Learn

The Code

Client: Implement terminal handlers

Agent: Use terminal API

Terminal Lifecycle

Source Code

Running the Example

Next Module