openhands-queue.yml

name: openhands-queue

# 24/7 external-agent queue: every 3h (fits the OpenHands Cloud free tier's
# 10 conversations/day), if no @openhands claim is open, invoke @openhands on
# the lowest-numbered issue labeled `agent-queue` (explicit per-issue opt-in),
# then set the agent:openhands claim label directly — comments authored with
# GITHUB_TOKEN never fire issue_comment workflows (anti-recursion), so
# openhands-claim.yml only scaffolds human-typed mentions.
on:
  schedule:
    - cron: "0 */3 * * *"
  workflow_dispatch: {}

concurrency:
  group: openhands-queue
  cancel-in-progress: false

permissions:
  issues: write

jobs:
  drain:
    runs-on: ubuntu-latest
    steps:
      - name: One-at-a-time guard
        id: guard
        run: |
          if gh issue list --state open --label "agent:openhands" --json number --jq 'length' | grep -qv '^0$'; then
            echo "busy=true" >> "$GITHUB_OUTPUT"
            echo "an @openhands claim is already open — skipping this tick"
          else
            echo "busy=false" >> "$GITHUB_OUTPUT"
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}

      - name: Invoke @openhands on the oldest queued issue
        if: steps.guard.outputs.busy == 'false'
        run: |
          ISSUE=$(gh issue list --state open --label "agent-queue" --json number --jq 'sort_by(.number) | .[0].number // empty' 2>/dev/null || true)
          # note: a missing label makes gh exit 1 ("not found") — treated as an
          # empty queue, not a workflow failure; the label is repo-side config.
          if [ -z "$ISSUE" ]; then
            echo "queue empty"
            exit 0
          fi
          gh issue comment "$ISSUE" --body "@openhands please implement this issue end-to-end and open a pull request. Read AGENTS.md at the repo root first for the repo laws (determinism, suite gate, conventional commits, no live-store configs: any scratch config needs an explicit state_dir)."
          gh issue edit "$ISSUE" --remove-label "agent-queue"
          # claim marker set here, not in openhands-claim.yml: a GITHUB_TOKEN
          # comment cannot trigger the claim workflow (anti-recursion rule),
          # and this job has no checkout to build the placeholder branch.
          # The label alone broadcasts ownership and feeds the one-at-a-time
          # guard; unclaim removes it when the real PR arrives.
          gh label create "agent:openhands" --color D4C5F9 --description "claimed by @openhands (external agent)" || true
          gh issue edit "$ISSUE" --add-label "agent:openhands"
          echo "invoked @openhands on #$ISSUE"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}