Add convenience API for PromptContext with reduced boilerplate

Author: Mark Pollack

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/Command.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.agent;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Builder for terminal command execution via the convenience API.
+ *
+ * <p>
+ * This record allows configuring command execution with options like
+ * working directory, environment variables, and output limits.
+ *
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * // Simple command
+ * CommandResult result = context.execute("echo", "hello");
+ *
+ * // Command with options
+ * CommandResult result = context.execute(
+ *     Command.of("make", "build")
+ *         .cwd("/workspace")
+ *         .env(Map.of("DEBUG", "true"))
+ *         .outputLimit(10000));
+ * }</pre>
+ *
+ * @param executable The command to execute
+ * @param args The arguments to pass to the command
+ * @param cwd The working directory (null for default)
+ * @param env Environment variables to set (null for default)
+ * @param outputByteLimit Maximum bytes of output to capture (null for default)
+ * @author Mark Pollack
+ * @since 0.9.2
+ * @see SyncPromptContext#execute(Command)
+ * @see PromptContext#execute(Command)
+ */
+public record Command(
+		String executable,
+		List<String> args,
+		String cwd,
+		Map<String, String> env,
+		Long outputByteLimit
+) {
+
+	/**
+	 * Creates a Command from command-line arguments.
+	 * The first argument is the executable, remaining arguments are passed as args.
+	 * @param commandAndArgs The command and its arguments
+	 * @return A new Command instance
+	 */
+	public static Command of(String... commandAndArgs) {
+		if (commandAndArgs == null || commandAndArgs.length == 0) {
+			throw new IllegalArgumentException("At least one argument (the command) is required");
+		}
+		return new Command(
+				commandAndArgs[0],
+				commandAndArgs.length > 1
+						? Arrays.asList(commandAndArgs).subList(1, commandAndArgs.length)
+						: List.of(),
+				null, null, null);
+	}
+
+	/**
+	 * Returns a new Command with the specified working directory.
+	 * @param cwd The working directory
+	 * @return A new Command with the working directory set
+	 */
+	public Command cwd(String cwd) {
+		return new Command(executable, args, cwd, env, outputByteLimit);
+	}
+
+	/**
+	 * Returns a new Command with the specified environment variables.
+	 * @param env The environment variables
+	 * @return A new Command with the environment variables set
+	 */
+	public Command env(Map<String, String> env) {
+		return new Command(executable, args, cwd, env, outputByteLimit);
+	}
+
+	/**
+	 * Returns a new Command with the specified output byte limit.
+	 * @param limit The maximum bytes of output to capture
+	 * @return A new Command with the output byte limit set
+	 */
+	public Command outputByteLimit(long limit) {
+		return new Command(executable, args, cwd, env, limit);
+	}
+
+}

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/CommandResult.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package com.agentclientprotocol.sdk.agent;
+
+/**
+ * Result of executing a terminal command via the convenience API.
+ *
+ * <p>
+ * This record wraps the output and exit code from a terminal command execution,
+ * providing a clean interface for the common case of running a command and
+ * checking its result.
+ *
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * CommandResult result = context.execute("make", "build");
+ * if (result.exitCode() == 0) {
+ *     context.sendMessage("Build succeeded!");
+ * } else {
+ *     context.sendMessage("Build failed: " + result.output());
+ * }
+ * }</pre>
+ *
+ * @param output The combined stdout/stderr output from the command
+ * @param exitCode The exit code (0 typically means success)
+ * @param timedOut Whether the command was terminated due to timeout
+ * @author Mark Pollack
+ * @since 0.9.2
+ * @see SyncPromptContext#execute(String...)
+ * @see PromptContext#execute(String...)
+ */
+public record CommandResult(
+		String output,
+		int exitCode,
+		boolean timedOut
+) {
+
+	/**
+	 * Creates a CommandResult with the given output and exit code.
+	 * Sets timedOut to false.
+	 * @param output The command output
+	 * @param exitCode The exit code
+	 */
+	public CommandResult(String output, int exitCode) {
+		this(output, exitCode, false);
+	}
+
+	/**
+	 * Returns true if the command completed successfully (exit code 0).
+	 * @return true if exit code is 0 and command did not time out
+	 */
+	public boolean success() {
+		return exitCode == 0 && !timedOut;
+	}
+
+}

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultAcpAsyncAgent.java

@@ -137,7 +137,7 @@ public Mono<Void> start() {
 							new TypeRef<AcpSchema.PromptRequest>() {
 							});
 					// Create PromptContext that wraps this agent, giving handler access to all capabilities
-					PromptContext context = new DefaultPromptContext(this);
+					PromptContext context = new DefaultPromptContext(this, request.sessionId());
 					return promptHandler.handle(request, context)
 						.cast(Object.class);
 				});

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultPromptContext.java

@@ -4,8 +4,29 @@
 
 package com.agentclientprotocol.sdk.agent;
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
 import com.agentclientprotocol.sdk.capabilities.NegotiatedCapabilities;
 import com.agentclientprotocol.sdk.spec.AcpSchema;
+import com.agentclientprotocol.sdk.spec.AcpSchema.AgentMessageChunk;
+import com.agentclientprotocol.sdk.spec.AcpSchema.AgentThoughtChunk;
+import com.agentclientprotocol.sdk.spec.AcpSchema.CreateTerminalRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.EnvVariable;
+import com.agentclientprotocol.sdk.spec.AcpSchema.PermissionOption;
+import com.agentclientprotocol.sdk.spec.AcpSchema.PermissionOptionKind;
+import com.agentclientprotocol.sdk.spec.AcpSchema.PermissionSelected;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ReadTextFileRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ReleaseTerminalRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.RequestPermissionRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.TerminalOutputRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.TextContent;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ToolCallStatus;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ToolCallUpdate;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ToolKind;
+import com.agentclientprotocol.sdk.spec.AcpSchema.WaitForTerminalExitRequest;
+import com.agentclientprotocol.sdk.spec.AcpSchema.WriteTextFileRequest;
 import reactor.core.publisher.Mono;
 
 /**
@@ -23,14 +44,22 @@ class DefaultPromptContext implements PromptContext {
 
 	private final AcpAsyncAgent agent;
 
+	private final String sessionId;
+
 	/**
 	 * Creates a new prompt context wrapping the given agent.
 	 * @param agent The agent to delegate to
+	 * @param sessionId The session ID for this prompt invocation
 	 */
-	DefaultPromptContext(AcpAsyncAgent agent) {
+	DefaultPromptContext(AcpAsyncAgent agent, String sessionId) {
 		this.agent = agent;
+		this.sessionId = sessionId;
 	}
 
+	// ========================================================================
+	// Low-Level API
+	// ========================================================================
+
 	@Override
 	public Mono<Void> sendUpdate(String sessionId, AcpSchema.SessionUpdate update) {
 		return agent.sendSessionUpdate(sessionId, update);
@@ -82,4 +111,109 @@ public NegotiatedCapabilities getClientCapabilities() {
 		return agent.getClientCapabilities();
 	}
 
+	// ========================================================================
+	// Convenience API
+	// ========================================================================
+
+	@Override
+	public String getSessionId() {
+		return sessionId;
+	}
+
+	@Override
+	public Mono<Void> sendMessage(String text) {
+		return sendUpdate(sessionId, new AgentMessageChunk("agent_message_chunk", new TextContent(text)));
+	}
+
+	@Override
+	public Mono<Void> sendThought(String text) {
+		return sendUpdate(sessionId, new AgentThoughtChunk("agent_thought_chunk", new TextContent(text)));
+	}
+
+	@Override
+	public Mono<String> readFile(String path) {
+		return readFile(path, null, null);
+	}
+
+	@Override
+	public Mono<String> readFile(String path, Integer startLine, Integer lineCount) {
+		return readTextFile(new ReadTextFileRequest(sessionId, path, startLine, lineCount))
+				.map(AcpSchema.ReadTextFileResponse::content);
+	}
+
+	@Override
+	public Mono<Void> writeFile(String path, String content) {
+		return writeTextFile(new WriteTextFileRequest(sessionId, path, content)).then();
+	}
+
+	@Override
+	public Mono<Boolean> askPermission(String action) {
+		ToolCallUpdate toolCall = new ToolCallUpdate(
+				UUID.randomUUID().toString(), action, ToolKind.EDIT, ToolCallStatus.PENDING,
+				null, null, null, null);
+
+		List<PermissionOption> options = List.of(
+				new PermissionOption("allow", "Allow", PermissionOptionKind.ALLOW_ONCE),
+				new PermissionOption("deny", "Deny", PermissionOptionKind.REJECT_ONCE));
+
+		return requestPermission(new RequestPermissionRequest(sessionId, toolCall, options))
+				.map(response -> response.outcome() instanceof PermissionSelected s
+						&& "allow".equals(s.optionId()));
+	}
+
+	@Override
+	public Mono<String> askChoice(String question, String... options) {
+		if (options == null || options.length < 2) {
+			return Mono.error(new IllegalArgumentException("At least 2 options are required"));
+		}
+
+		List<PermissionOption> permOptions = new ArrayList<>();
+		for (int i = 0; i < options.length; i++) {
+			permOptions.add(new PermissionOption(
+					String.valueOf(i), options[i], PermissionOptionKind.ALLOW_ONCE));
+		}
+
+		ToolCallUpdate toolCall = new ToolCallUpdate(
+				UUID.randomUUID().toString(), question, ToolKind.OTHER,
+				ToolCallStatus.PENDING, null, null, null, null);
+
+		return requestPermission(new RequestPermissionRequest(sessionId, toolCall, permOptions))
+				.map(response -> {
+					if (response.outcome() instanceof PermissionSelected s) {
+						int idx = Integer.parseInt(s.optionId());
+						return options[idx];
+					}
+					return null;
+				});
+	}
+
+	@Override
+	public Mono<CommandResult> execute(String... commandAndArgs) {
+		return execute(Command.of(commandAndArgs));
+	}
+
+	@Override
+	public Mono<CommandResult> execute(Command command) {
+		// Convert env map to list of EnvVariable
+		List<EnvVariable> envList = null;
+		if (command.env() != null) {
+			envList = command.env().entrySet().stream()
+					.map(e -> new EnvVariable(e.getKey(), e.getValue()))
+					.toList();
+		}
+
+		return createTerminal(new CreateTerminalRequest(
+				sessionId, command.executable(), command.args(),
+				command.cwd(), envList, command.outputByteLimit()))
+			.flatMap(createResp -> {
+				String terminalId = createResp.terminalId();
+
+				return waitForTerminalExit(new WaitForTerminalExitRequest(sessionId, terminalId))
+						.flatMap(exitResp -> getTerminalOutput(new TerminalOutputRequest(sessionId, terminalId))
+								.map(outputResp -> new CommandResult(outputResp.output(), exitResp.exitCode(), false)))
+						.doFinally(signal -> releaseTerminal(new ReleaseTerminalRequest(sessionId, terminalId))
+								.subscribe());
+			});
+	}
+
 }