CLI Agent Orchestrator (CAO)

Highlights

This is a substantial release. CAO 2.3 introduces cao workflow — a script-tier orchestration engine that lets a supervisor author multi-agent runs as plain JavaScript (agent() / parallel() / pipeline()), with a durable run journal, resumable execution, and a linter + run-step env guard for safety (#312, Bolts 1–4). Alongside it: CAO memory federation and portability — cross-project FEDERATED scope, Open Knowledge Format (OKF) export/import, and self-healing wiki repair (cao memory heal); a major event-driven architecture rebase (#273) that removes polling from inbox delivery across the terminal/session stack; a new cross-node fleet coordinator + web control panel for managing many CAO nodes from one place; and a broad kiro-cli 2.11 compatibility pass that fixes a supervisor deadlock plus several TUI status-detection regressions. New providers this release: Cursor CLI, Antigravity CLI (agy), Kimi CLI, and Hermes/herdr backends; Amazon Q CLI and Gemini CLI providers were removed. (cao profile and the graph rendering layer are in progress on main and will ship in a following minor release, not 2.3.0.)

Added

• cao workflow — script-tier orchestration engine (#312, Bolts 1–4) — A new way to author multi-agent runs as a plain JS script instead of prose instructions to a supervisor. Ships incrementally across this release:

  • Spec grammar + run_agent_step substrate (Bolt 1) by @fanhongy in #320
  • Authoring, persistence & structured returns (Bolt 2) by @fanhongy in #326
  • Orchestration run engine (Bolt 3 / N5) by @fanhongy in #329
  • Durable run journal + resume — a crashed or killed workflow can resume from its last completed step (N6) by @fanhongy in #372
  • Script-tier journal extension (C3/U3) by @fanhongy in #391
  • Script linter + run-step env guard (B2: U1+U2) — catches unsafe scripts before they run by @fanhongy in #394
  • Script-tier execution engine, U4 runner by @fanhongy in #396

• CAO memory: cross-project federation — FEDERATED scope (Phase 4 U3) — A new scope that lets memories be shared and recalled across projects rather than pinned to one, closing a gap flagged during Phase 2.5 hardening by @fanhongy in #314

• CAO memory: Open Knowledge Format (OKF) export/import (Phase 4 U2) — cao memory export/cao memory import CLI commands plus a read-scoped GET /memory/export API endpoint stream a memory scope as a portable tar.gz bundle, enabling memory migration and backup by @fanhongy in #384

• CAO memory: wiki self-healing — cao memory heal (Phase 4 U1) — Detects and repairs structural drift in the memory wiki (orphaned entries, broken cross-references, stale index) without a full rebuild by @fanhongy in #306

• CAO memory Phase 3 — LLM wiki compile, cross-references, lint, audit log, scoring — Compiles raw memory entries into a browsable wiki via LLM summarization, adds cross-reference linking, a lint pass for wiki health, a daily audit log, and a memory-quality scoring pass by @fanhongy in #285

• CAO memory: Web UI support — Browse, search, and manage stored memories from the Web UI dashboard by @fanhongy in #290

• CAO memory: bundle built-in memory plugins for Claude Code, Kiro, and Codex — Ships ready-to-use memory-injection plugins for the three most common providers so memory.enabled works out of the box without custom wiring by @fanhongy in #269

• CAO memory: docs — per-scope store samples, on-disk comparison, SQLite architecture diagram by @fanhongy in #355

• Enable/disable an agent-profile directory (closes #280, #281) — A profile directory's profiles can now be toggled out of the active set without removing the directory from config by @call-me-ram in #368

• Scope the per-agent skill catalog via a profile allowlist — Optional skills field on AgentProfile restricts which skills a given agent can see, via an fnmatch allowlist; runtime-prompt providers only by @vprudnikoff in #351

• Discover skills from extra_skill_dirs — Mirrors the existing extra_agent_dirs pattern so custom skill directories are picked up the same way custom agent directories are by @vprudnikoff in #277

• Event-driven architecture (rebase onto main + green suite) — Replaces polling-based inbox delivery with an event-driven model across the terminal/session stack by @call-me-ram in #273

• cao-mcp-server operations tools + orchestration worker profiles — Adds worker status/output MCP tools and bundled worker profiles tuned for the ops MCP server by @call-me-ram in #324

• Gate network egress behind a web_fetch tool category (closes #310) — Network-fetch capability is now an explicit, allowlist-gated tool category rather than implicit access, tightening the default security posture by @call-me-ram in #311

• pyte rendered-screen status detection (closes #287) — Uses a virtual terminal screen buffer (pyte) instead of raw-buffer regex matching for provider status detection, reducing false IDLE/PROCESSING reads by @call-me-ram in #293

• Herdr terminal backend with event-driven inbox delivery — A new terminal backend option with native event-driven message delivery by @anilkmr-a2z in #271

• Hermes provider support — Adds Hermes Agent as a supported provider by @NorethSea in #272

• Cursor CLI provider — Adds Cursor CLI as a first-class provider by @ThePlenkov in #296

• Antigravity CLI (agy) provider — Adds Google's terminal-native coding agent, the successor to the Gemini CLI after its free "Login with Google" path was retired by @MarkusWohlmuth in #323

• codexConfig field on AgentProfile — Optional per-agent config overrides for the codex provider by @vprudnikoff in #278

• Web UI: optional Session Name field on the Spawn Agent dialog — Lets operators name a session at spawn time instead of only after the fact by @vprudnikoff in #279

• Configurable server timeouts + file-based Claude Code prompt delivery by @jitendrasinghsankhwar in #318

• cao flow renamed to cao schedule — Avoids confusion with the new cao workflow feature. cao flow remains as a hidden, deprecated alias that warns on stderr; flow files, ~/.cao/flows, stored schedules, and the /flows REST API are unchanged by @fanhongy in #380

• cao-mcp-apps: canonical-source fidelity + host-delegated dogfooding by @plauzy in #347

• Sandboxed host-rendered fleet UI (SEP-1865) by @plauzy in #332

• examples/fleet — cross-node fleet coordinator — Manages many CAO nodes from one place: one-command node bootstrap, a fleet control helper (list/show/exec against any node), and an AI conductor wired to one cao-ops-mcp-server per node. Purely additive under examples/; each node stays a stateless client of the existing cao-server API by @SparkyWen in #365, plus a web control panel + live console (#366) and a coordinator guide (docs/fleet_instructions.md, #367)

• examples/aws — cloud-ops agent examples with config by @sujoydc in #377

Changed

• Unify CAO configuration into a single source of truth — Consolidates config resolution that was previously spread across multiple layers/files by @fanhongy in #381

Removed

• Amazon Q CLI and Gemini CLI providers removed — Q CLI is superseded by kiro_cli; Gemini CLI's free "Login with Google" path was retired (see the new Antigravity CLI provider above) by @gutosantos82 in #353

Deprecated

• cao flow — use cao schedule instead; the alias will be removed in a future release (#380)

Fixed

• kiro-cli 2.11 compatibility — unblock multi-agent orchestration — A multi-part fix for a supervisor deadlock and detection regressions introduced by kiro-cli 2.11: bracketed paste now sends 2 Enters with a submit delay (2.11's TUI swallowed the single-Enter used by older versions); TUI_PROCESSING_PATTERN matches both the pre-2.11 and 2.11+ processing strings; the no-Credits completion check now requires a full bordered response box instead of any idle-prompt match; and kiro-cli chat always launches with --trust-all-tools so the new "subagent requires approval" dialog doesn't deadlock headless orchestration (CAO still enforces tool scoping at its own layers) by @haofeif in #390

• claude_code: backgrounded task no longer reads as COMPLETED (fixes #392) — The "✻ Waiting for N workflows" wait line has no spinner ellipsis and can look like a finished turn; both the raw-buffer and pyte screen paths now correctly report PROCESSING until a real completion signal appears by @call-me-ram in #393

• memory: validate user-derived path components, closing CodeQL path-injection alerts — Every user-derived path component (key, scope, scope_id) is now validated as a single safe path segment and confined under the memory base directory via realpath + containment guard, closing 11 CodeQL py/path-injection alerts by @gutosantos82 in #401

• mcp: launch bundled cao-mcp-server without a per-launch network fetch by @tedswinyar in #403

• fifo: non-blocking reader loop + event-loop-safe session teardown (fixes #382) — Reader threads could be stranded in a blocking FIFO open() by a stop/reopen race; DELETE /sessions now runs teardown in a worker thread so repeated create/delete cycles can't wedge cao-server by @call-me-ram in #383

• cli: auto-detect server backend + herdr reconcile fixes by @anilkmr-a2z in #309

• cli: add --version/-V option (#354) by @fanhongy in #379

• providers: read herdr native status in all providers (#359) by @fanhongy in #361

• providers: harden Claude and OpenCode status detection by @aygnep in #327

• kiro: detect TUI idle state without falling back to --legacy-ui by @haofeif in #330

• claude_code: echoed system prompt false-matches idle, blocking the workspace-trust dialog by @cdrury526 in #319

• Allow permissionMode to override yolo in the claude_code provider by @zz327455573 in #322

• antigravity: dismiss startup feedback survey so init doesn't block by @SeaCold in #371

• antigravity: accept workspace-trust dialog so init doesn't hang by @SeaCold in #364

• kimi: dismiss startup upgrade-reminder dialog so init doesn't hang by @SeaCold in #363

• tool-restrictions: also deny Claude Code's renamed subagent tool (Agent) by @vprudnikoff in #350

• cao-mcp-apps: adopt vite 8 / vitest 4 and restore the 90% coverage floor by @plauzy in #346

• Structural callback routing for worker agents (#284) by @fanhongy in #289

• codex: handle v0.136+ TUI footer and skip MCP tool-call markers — codex 0.136 dropped a status-bar segment CAO relied on for footer detection; the last-message extractor also now skips over MCP tool-call markers instead of leaking their contents into the extracted response by @haofeif in #274

• inbox: mark messages DELIVERED before send_input to stop double delivery by @call-me-ram in #265

• inbox: add reconciliation sweep for orphaned PENDING messages by @call-me-ram in #266

• ci: stop TestPyPI squats breaking the release smoke test by @fanhongy in #270

• Quickly remove some comments by @fanhongy in #370

Security

• CodeQL #66 — command-injection and URL-sanitization fixes by @haofeif in #288

• Potential fix for code scanning alert no. 66: Uncontrolled command line by @haofeif in #275

• Dependency bumps: starlette 0.49.1→1.0.1→1.3.1 (#276, #304), python-multipart 0.0.27→0.0.31 (#302), pyjwt 2.12.0→2.13.0 (#301), cryptography 46.0.7→48.0.1 (#303), form-data 4.0.5→4.0.6 in /web (#305), esbuild/@vitejs/plugin-react/vite in /web (#295), happy-dom 15.11.7→20.10.6 in /cao_mcp_apps (#341), ws 8.20.0→8.21.0 in /web (#398) — all via @dependabot

Testing

• Fix kiro/q integration tests (mock_db signature + event-loop starvation) by @plauzy in #333

New Contributors

@NorethSea, @vprudnikoff, @jitendrasinghsankhwar, @cdrury526, @zz327455573, @MarkusWohlmuth, @aygnep, @plauzy, @SeaCold, @SparkyWen, @sujoydc, @tedswinyar all made their first contribution this release.

Upgrade

uv tool install git+https://github.com/awslabs/[email protected] --upgrade

Or via PyPI:

pip install --upgrade cli-agent-orchestrator==2.3.0

Breaking: Amazon Q CLI and Gemini CLI providers have been removed — profiles pinned to provider: q_cli or provider: gemini_cli will need to migrate to kiro_cli or antigravity_cli respectively. cao flow continues to work as a deprecated alias for cao schedule.

Full Changelog: https://github.com/awslabs/cli-agent-orchestrator/compare/v2.2.0...main