AO: Agent Orchestrator

Documentation

CI recovery

How AO observes failing GitHub checks and sends focused context to the owning session.

When a claimed GitHub pull request has failing checks, AO's SCM observer records the new facts and routes a recovery message to the session that owns the PR.

The flow

  1. AO polls the claimed PR through its GitHub provider.
  2. The lifecycle reducer derives ci_failed from the stored PR facts.
  3. AO formats the failing check names and links into one focused message.
  4. The session manager delivers it through the active interface: a native Chat turn or the Terminal UI runtime.
  5. The desktop updates the PR summary and failing-check links from the same durable facts.

AO fingerprints the failing-check set. An unchanged failure is not resent on every poll; a changed set can produce a new nudge.

Make sure the PR is linked

PRs created by a session are discovered and associated through normal observation. To attach an existing PR explicitly:

ao session claim-pr <pr-number-or-url>
# From outside the worker, target it explicitly:
ao session claim-pr <session-id> <pr-number-or-url>

Inside a worker, the one-argument form uses AO_SESSION_ID automatically.

Or claim it while creating a session:

ao spawn --project my-project --name fix-pr-42 \
  --claim-pr 42 --mode chat

Use --no-takeover if the operation should fail when another active session already owns the PR.

What the agent receives

The message includes the failing checks and available run URLs, plus the PR identity. Raw CI logs are not copied into AO's desktop API; the agent can follow the supplied links and use the repository host's CLI to inspect logs.

Follow progress

Open the session inspector to see the PR, CI state, and failing-check links. The notification center is for human attention such as input requests and merge readiness; CI recovery itself is routed to the agent session.

Current limits

  • The shipped SCM observer is the GitHub path.
  • CI automation is built in and is not configured through a reactions: YAML block.
  • There is no ao review-check command or configurable CI retry/escalation budget.
  • Draft and required-check semantics come from the normalized PR facts rather than a user reaction rule.

If automatic delivery is unavailable, open the owning Chat or Terminal UI session and send a follow-up directly with the desktop composer or ao send.