awslabs / awslabs/cli-agent-orchestrator

[Feat] Add CLI equivalents for in-session MCP orchestration

Open
#616 1 comment 0 reactions 1 assignee Claimed by @anilkmr-a2z View on GitHub
Dominant language
Python
Stars
1.3k
Forks
267
Avg merge
1d 23h
Merged PRs (30d)
70

Description

## Problem

We observed an OpenCode supervisor lose its `cao-mcp-server` child process while the agent, `cao-server`, and the `cao` CLI remained healthy.

OpenCode did not reconnect the MCP client, so `assign`, `handoff`, and `send_message` disappeared. The supervisor could no longer create a reviewer or continue coordinating workers and had to ask an external driver to relay the task.

The existing CLI can inspect sessions and message existing terminals, but it cannot perform the same-session orchestration currently provided by `cao-mcp-server`.

## Proposal

Expose the in-session orchestration operations as short-lived CLI commands backed by the same server-side implementation:

```bash
cao agent assign reviewer --message-file task.md --json
cao agent handoff reviewer --message-file task.md --detach --json
cao agent send-message --receiver TERMINAL_ID --message-file result.md --json
cao agent status JOB_ID --json
cao agent result JOB_ID --json
cao agent cancel JOB_ID --json
```

These commands should:

- Infer the caller from `CAO_TERMINAL_ID`
- Preserve session membership, caller routing, provider/model, working directory, and allowed-tool inheritance
- Support messages through files/stdin and stable JSON output
- Allow profiles to use CLI orchestration without launching `cao-mcp-server`

Long-running operations should be durable and idempotent. Starting a handoff should immediately return a stable job ID. If the CLI process exits or its response is lost, retrying with the same request ID must return the existing job rather than create a duplicate worker. Status and results must remain retrievable through later CLI calls.

MCP can remain supported for clients that prefer it. The goal is to make it optional for shell-capable agents and avoid a persistent MCP connection becoming a single point of failure.

## Acceptance criteria

- An OpenCode supervisor can complete a supervisor → developer → reviewer workflow with `cao-mcp-server` disabled.
- Killing the CLI process after submission does not lose the job or its result.
- Retrying the same request does not create duplicate workers.
- Existing MCP behavior remains compatible.

Related: #447 and #505.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.