Proposal: IDE Run Configuration execution support

[bartvanhoutte]

Motivation

Most modern IDEs (JetBrains, VS Code, Eclipse, Visual Studio, etc.) have a concept of Run Configurations — named, pre-configured launch profiles that describe how to build, run, test, or debug a project. These configurations capture not just a command to execute, but also the working directory, environment variables, argument presets, and other IDE-managed context (e.g. classpath setup, pre-launch tasks, debugger attachment).

Today, ACP agents can execute arbitrary shell commands via the terminal/create API. However, this requires the agent to know or reconstruct the exact command, environment, and setup independently — bypassing the project's established run configurations entirely. This means agents can't easily trigger a "Run Tests" or "Run App" action the way a developer would naturally do it in their IDE.

Proposal

Add a new optional client capability that allows agents to discover and execute named run configurations defined in the client IDE.

Suggested capability flag

"clientCapabilities": {
  "runConfigurations": true
}

New methods

runConfig/list — returns the list of available run configurations for the current workspace:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "runConfig/list",
  "params": { "sessionId": "sess_abc123" }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "configurations": [
      {
        "id": "config_1",
        "name": "Run App",
        "type": "application",
        "description": "Starts the main application server"
      },
      {
        "id": "config_2",
        "name": "PHPUnit Tests",
        "type": "test",
        "description": "Runs all unit tests"
      }
    ]
  }
}

runConfig/execute — executes a named run configuration and returns a terminal ID for output streaming (reusing the existing terminal/* API):

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "runConfig/execute",
  "params": {
    "sessionId": "sess_abc123",
    "configId": "config_2"
  }
}

// Response (terminal ID for output streaming)
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "terminalId": "term_xyz789"
  }
}

Once a terminalId is returned, agents can use the existing terminal/output, terminal/wait_for_exit, and terminal/release methods to stream and manage output — no new streaming primitives needed.

Configuration types (non-exhaustive)

To keep this IDE-agnostic, the type field uses a set of well-known semantic values:

Type	Description
application	Launches the main application entry point
test	Runs a test suite
build	Triggers a build/compile task
debug	Launches with a debugger attached
custom	Any other IDE-specific configuration

Unknown types MUST be handled gracefully by agents.

IDE Agnosticism

This proposal is intentionally abstract — it maps to:

• JetBrains IDEs: Run/Debug Configurations dialog
• VS Code: launch.json configurations and tasks.json tasks
• Visual Studio: Launch profiles
• Eclipse: Launch configurations
• Xcode: Schemes

Clients are free to surface any subset of their configured launch profiles as runConfigurations, and agents MUST NOT assume any specific IDE behavior.

Alternatives Considered

• Just use terminal/create: Works for simple cases, but requires the agent to reverse-engineer the run command, missing pre-launch hooks, classpath setup, and IDE-managed environment.
• Expose via MCP tools: Possible, but this is a common enough IDE concept to warrant a first-class ACP protocol method.