engineering.yml

name: Engineering Pipeline

# Unified pipeline for all engineering work in this repo.
#
# build      — triggered by type:suggestion label, cron sweep, or dispatch.
#              Plans, builds, and tests new/modified examples in a Docker
#              sandbox with a neurosymbolic agent loop. PRs are opened for
#              human review before anything merges.
#
# engineering — triggered when a Deepgram org member @mentions @deepgram-robot
#              in any issue or PR comment. Full unrestricted access to the entire
#              repo. Acts on the request, commits if needed, replies in thread.
#
# Both jobs gate on Deepgram org membership before spending any AI budget.

on:
  issues:
    types: [labeled]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  schedule:
    - cron: '0 */4 * * *'  # Every 4 hours — sweep for unprocessed suggestions
  workflow_dispatch:
    inputs:
      issue_number:
        description: 'Issue number to process (leave blank for auto-discovery)'
        required: false

jobs:

  # ── Build: create or modify examples from issue suggestions ─────────────────
  build:
    if: |
      (github.event_name == 'issues' && github.event.label.name == 'type:suggestion') ||
      github.event_name == 'schedule' ||
      github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    timeout-minutes: 120

    concurrency:
      group: build-${{ github.event.issue.number || 'sweep' }}
      cancel-in-progress: false

    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - name: Checkout repo
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          token: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          fetch-depth: 0  # Full clone so feature branches are available for checkout

      - name: Snapshot workflow scripts
        run: |
          rm -rf /tmp/engineering-scripts
          mkdir -p /tmp/engineering-scripts
          cp -R .github/scripts/. /tmp/engineering-scripts/

      # ------------------------------------------------------------------
      # 1. Resolve which issue to work on
      #    - label event    → use the triggering issue
      #    - dispatch+input → use the provided issue number
      #    - schedule/bare dispatch → auto-discover oldest unprocessed suggestion
      # ------------------------------------------------------------------
      - name: Resolve issue
        id: issue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          EVENT="${{ github.event_name }}"
          INPUT_NUM="${{ inputs.issue_number }}"

          if [ "$EVENT" = "issues" ]; then
            number="${{ github.event.issue.number }}"
          elif [ -n "$INPUT_NUM" ]; then
            number="$INPUT_NUM"
          else
            # Auto-discover: oldest open type:suggestion with no build started yet.
            # <!-- pr-opened --> is injected into the issue comment when a PR is
            # opened, so its presence means a build is already in progress or done.
            result=$(gh issue list \
              --label "type:suggestion" \
              --state open \
              --json number \
              --limit 50 | python3 /tmp/engineering-scripts/find_unprocessed_issue.py \
              --repo "${{ github.repository }}")
            if [ "$result" = "SKIP" ] || [ -z "$result" ]; then
              echo "No unprocessed suggestions found."
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            number=$(echo "$result" | python3 -c "import json,sys; print(json.load(sys.stdin)['number'])")
          fi

          # Fetch author, body, and labels in one call
          issue_json=$(gh issue view "$number" --repo "${{ github.repository }}" --json author,body,labels)
          author=$(echo "$issue_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['author']['login'])")
          body=$(echo "$issue_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['body'])")
          has_suggestion=$(echo "$issue_json" | python3 -c "import json,sys; d=json.load(sys.stdin); print('true' if any(l['name']=='type:suggestion' for l in d['labels']) else 'false')")

          # ------------------------------------------------------------------
          # Authz: build if any of the following are true:
          #   1. Author is a bot (automated suggestions)
          #   2. Author is a Deepgram org member
          #   3. Issue carries the type:suggestion label — only users with write
          #      access can apply labels, so its presence means an org member
          #      has explicitly approved this external issue for building.
          #      This is the manual approval path for non-org-member issues.
          # ------------------------------------------------------------------
          if [[ "$author" != *"[bot]"* ]] && [[ "$has_suggestion" != "true" ]]; then
            http_line=$(gh api "orgs/deepgram/members/${author}" -i 2>/dev/null | head -1)
            if ! echo "$http_line" | grep -q "204"; then
              echo "Issue #${number} author '${author}' is not a Deepgram org member and has no label approval. Skipping."
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
            fi
          fi

          echo "number=$number" >> "$GITHUB_OUTPUT"
          # Multiline body — use unique heredoc delimiter
          echo "body<<ISSUE_BODY_EOF" >> "$GITHUB_OUTPUT"
          echo "$body" >> "$GITHUB_OUTPUT"
          echo "ISSUE_BODY_EOF" >> "$GITHUB_OUTPUT"

          prior_state=$(gh issue view "$number" \
            --repo "${{ github.repository }}" \
            --json body,comments \
            --jq '([.body] + [.comments[].body]) | map(select(contains("<!-- agent-state:"))) | last' \
            2>/dev/null | python3 /tmp/engineering-scripts/extract_agent_state.py || true)
          echo "prior_state<<PRIOR_STATE_EOF" >> "$GITHUB_OUTPUT"
          echo "$prior_state" >> "$GITHUB_OUTPUT"
          echo "PRIOR_STATE_EOF" >> "$GITHUB_OUTPUT"

      - name: Skip if nothing to build
        if: steps.issue.outputs.skip == 'true'
        run: echo "Skipping — no eligible issue to build."

      # ------------------------------------------------------------------
      # 2. Mark issue as build in progress
      # ------------------------------------------------------------------
      - name: Label build in progress
        if: steps.issue.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue edit ${{ steps.issue.outputs.number }} \
            --repo "${{ github.repository }}" \
            --add-label "build:in-progress"

      # ------------------------------------------------------------------
      # 3. Extract secret names (not values) from the secrets context
      # ------------------------------------------------------------------
      - name: Extract secret names
        id: secret_names
        if: steps.issue.outputs.skip != 'true'
        env:
          ALL_SECRETS: ${{ toJSON(secrets) }}
        run: |
          echo "$ALL_SECRETS" | python3 -c "
          import json, sys
          names = list(json.load(sys.stdin).keys())
          # Strip the auto-injected GitHub token — agent doesn't need it
          names = [n for n in names if n.upper() not in ('GITHUB_TOKEN',)]
          print(','.join(names))
          " > /tmp/secret_names.txt
          echo "names=$(cat /tmp/secret_names.txt)" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 3. Determine next example number (used only if action=new)
      # ------------------------------------------------------------------
      - name: Determine example number
        id: example_number
        if: steps.issue.outputs.skip != 'true'
        run: |
          number=$(python3 /tmp/engineering-scripts/next_example_number.py \
            --examples-dir examples)
          echo "number=$number" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 4. Planning phase — detect runtime, slug, action, required secrets
      # ------------------------------------------------------------------
      - name: Plan example
        id: plan
        if: steps.issue.outputs.skip != 'true'
        env:
          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL || 'https://api.openai.com/v1' }}
          LLM_MODEL: ${{ secrets.LLM_MODEL || 'gpt-5.4' }}
          ISSUE_BODY: ${{ steps.issue.outputs.body }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          EXAMPLE_NUMBER: ${{ steps.example_number.outputs.number }}
          SECRET_NAMES: ${{ steps.secret_names.outputs.names }}
          EXAMPLES_DIR: ${{ github.workspace }}/examples
        run: |
          plan=$(python3 /tmp/engineering-scripts/plan_agent.py)
          echo "plan=$plan" >> "$GITHUB_OUTPUT"

          # Extract fields for subsequent steps
          echo "action=$(echo "$plan" | python3 -c "import json,sys; print(json.load(sys.stdin).get('action','new'))")" >> "$GITHUB_OUTPUT"
          echo "runtime=$(echo "$plan" | python3 -c "import json,sys; print(json.load(sys.stdin)['runtime'])")" >> "$GITHUB_OUTPUT"
          echo "slug=$(echo "$plan" | python3 -c "import json,sys; print(json.load(sys.stdin)['slug'])")" >> "$GITHUB_OUTPUT"
          echo "docker_image=$(echo "$plan" | python3 -c "import json,sys; print(json.load(sys.stdin)['docker_image'])")" >> "$GITHUB_OUTPUT"
          echo "required_secrets=$(echo "$plan" | python3 -c "import json,sys; print(','.join(json.load(sys.stdin)['required_secrets']))")" >> "$GITHUB_OUTPUT"
          # workspace_subdir is NNN-slug for new, existing dir name for modify
          echo "workspace_subdir=$(echo "$plan" | python3 -c "import json,sys; print(json.load(sys.stdin)['workspace_subdir'])")" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 6. Prepare working branch early
      #    Reuse the existing branch/PR when present so continuation runs add
      #    history instead of failing on push. This also gives the agent a
      #    stable branch for deterministic checkpoint commits during the run.
      # ------------------------------------------------------------------
      - name: Prepare working branch
        id: branch_ctx
        if: steps.issue.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          GH_BOT_LOGIN: ${{ secrets.GH_BOT_LOGIN || 'github-actions[bot]' }}
          WORKSPACE_SUBDIR: ${{ steps.plan.outputs.workspace_subdir }}
          WORKSPACE_ACTION: ${{ steps.plan.outputs.action }}
        run: |
          if [ "$WORKSPACE_ACTION" = "modify" ]; then
            branch="example/update-${WORKSPACE_SUBDIR}"
          else
            branch="example/${WORKSPACE_SUBDIR}"
          fi
          echo "branch=$branch" >> "$GITHUB_OUTPUT"

          git config user.name "$GH_BOT_LOGIN"
          git config user.email "$GH_BOT_LOGIN@users.noreply.github.com"

          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
            git fetch origin "$branch"
            git checkout -B "$branch" "origin/$branch"
          else
            git checkout -b "$branch"
          fi

          pr_url=$(gh pr list \
            --repo "${{ github.repository }}" \
            --head "$branch" \
            --state open \
            --json url \
            -q '.[0].url' 2>/dev/null || true)
          pr_number=$(gh pr list \
            --repo "${{ github.repository }}" \
            --head "$branch" \
            --state open \
            --json number \
            -q '.[0].number' 2>/dev/null || true)

          echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 7. Create or reuse the draft PR before the agent starts looping
      # ------------------------------------------------------------------
      - name: Ensure draft pull request exists
        id: kickoff_pr
        if: steps.issue.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          REPO_SLUG: ${{ github.repository }}
          BRANCH_NAME: ${{ steps.branch_ctx.outputs.branch }}
          WORKSPACE_SUBDIR: ${{ steps.plan.outputs.workspace_subdir }}
          WORKSPACE_ACTION: ${{ steps.plan.outputs.action }}
          RUNTIME: ${{ steps.plan.outputs.runtime }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          ISSUE_BODY: ${{ steps.issue.outputs.body }}
          WORKSPACE_DIR: ${{ github.workspace }}/examples/${{ steps.plan.outputs.workspace_subdir }}
        run: |
          if [ "$WORKSPACE_ACTION" = "modify" ]; then
            title_base="update ${WORKSPACE_SUBDIR}"
          else
            title_base="add ${WORKSPACE_SUBDIR}"
          fi

          if [ -n "${{ steps.branch_ctx.outputs.pr_number }}" ]; then
            echo "url=${{ steps.branch_ctx.outputs.pr_url }}" >> "$GITHUB_OUTPUT"
            echo "number=${{ steps.branch_ctx.outputs.pr_number }}" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          python3 -c "from pathlib import Path; import json; Path('/tmp/agent-state.json').write_text(json.dumps({'turns_used': 0, 'max_turns': 150, 'phases': [], 'tests_passing': False, 'tests_failing': False, 'last_test_command': '', 'last_test_exit_code': None, 'last_test_output': '', 'files_written': []}, indent=2))"

          python3 /tmp/engineering-scripts/build_pr_body.py \
            --workspace "$WORKSPACE_DIR" \
            --issue "$ISSUE_NUMBER" \
            --issue-body "$ISSUE_BODY" \
            --action "$WORKSPACE_ACTION" \
            --runtime "$RUNTIME" \
            --example "$WORKSPACE_SUBDIR" \
            --build-log /tmp/build-log.md \
            --agent-state /tmp/agent-state.json \
            --bootstrap >/dev/null

          ahead=$(git rev-list --count origin/main..HEAD 2>/dev/null || printf '0')
          if [ "$ahead" -eq 0 ]; then
            git commit --allow-empty -m "chore(examples): start ${WORKSPACE_SUBDIR}

            Relates to #${ISSUE_NUMBER}"
          fi

          git push -u origin "HEAD:${BRANCH_NAME}"

          url=$(gh pr create \
            --repo "$REPO_SLUG" \
            --head "$BRANCH_NAME" \
            --base main \
            --title "feat(examples): ${title_base}" \
            --body-file /tmp/pr-body.md \
            --draft)
          number=$(gh pr view "$url" --repo "$REPO_SLUG" --json number -q .number)
          gh pr edit "$number" --repo "$REPO_SLUG" --add-label "type:example" --add-label "automated" >/dev/null 2>&1 || true
          echo "url=$url" >> "$GITHUB_OUTPUT"
          echo "number=$number" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 8. Build filtered env file (only required secrets, values injected)
      # ------------------------------------------------------------------
      - name: Build sandbox env file
        if: steps.issue.outputs.skip != 'true'
        env:
          ALL_SECRETS: ${{ toJSON(secrets) }}
          REQUIRED_SECRETS: ${{ steps.plan.outputs.required_secrets }}
        run: |
          python3 /tmp/engineering-scripts/filter_secrets.py \
            --required "$REQUIRED_SECRETS" \
            --secrets-json "$ALL_SECRETS" \
            > /tmp/sandbox.env

          echo "Env file written with $(wc -l < /tmp/sandbox.env) secrets"

      # ------------------------------------------------------------------
      # 9. Pull Docker image
      # ------------------------------------------------------------------
      - name: Pull sandbox image
        if: steps.issue.outputs.skip != 'true'
        run: docker pull ${{ steps.plan.outputs.docker_image }}

      # ------------------------------------------------------------------
      # 10. Run the agent build loop
      #    exit 0 = complete, exit 2 = turn limit (draft PR), exit 1 = error
      # ------------------------------------------------------------------
      - name: Run agent
        id: agent
        if: steps.issue.outputs.skip != 'true'
        continue-on-error: true
        env:
          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL || 'https://api.openai.com/v1' }}
          LLM_MODEL: ${{ secrets.LLM_MODEL || 'gpt-5.4' }}
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ISSUE_BODY: ${{ steps.issue.outputs.body }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          EXAMPLE_NUMBER: ${{ steps.example_number.outputs.number }}
          EXAMPLE_SLUG: ${{ steps.plan.outputs.slug }}
          WORKSPACE_ACTION: ${{ steps.plan.outputs.action }}
          WORKSPACE_SUBDIR: ${{ steps.plan.outputs.workspace_subdir }}
          DOCKER_IMAGE: ${{ steps.plan.outputs.docker_image }}
          RUNTIME: ${{ steps.plan.outputs.runtime }}
          WORKSPACE_DIR: ${{ github.workspace }}/examples/${{ steps.plan.outputs.workspace_subdir }}
          EXAMPLES_DIR: ${{ github.workspace }}
          REPO_ROOT: ${{ github.workspace }}
          REPO_SLUG: ${{ github.repository }}
          BRANCH_NAME: ${{ steps.branch_ctx.outputs.branch }}
          BUILD_LOG: /tmp/build-log.md
          MAX_TURNS: "150"
          PRIOR_STATE: ${{ steps.issue.outputs.prior_state }}
          PYTHONDONTWRITEBYTECODE: "1"
        run: |
          set +e
          # Strip bytecode from previous runs — stale __pycache__ causes permission errors
          # Files may be root-owned from Docker runs, use sudo
          sudo find "$WORKSPACE_DIR" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
          sudo find "$WORKSPACE_DIR" -name "*.pyc" -delete 2>/dev/null || true
          python3 /tmp/engineering-scripts/run_agent.py
          agent_exit=$?
          echo "agent_exit=$agent_exit" >> "$GITHUB_OUTPUT"
          exit "$agent_exit"
        # Capture exit code explicitly — continue-on-error swallows it
      - name: Capture agent exit code
        id: agent_exit
        if: steps.issue.outputs.skip != 'true'
        run: |
          code="${{ steps.agent.outputs.agent_exit }}"
          if [ -z "$code" ]; then
            code=1
          fi
          echo "code=$code" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 11. Commit any residual changes not already checkpointed
      # ------------------------------------------------------------------
      - name: Commit and push residual changes
        if: steps.issue.outputs.skip != 'true'
        env:
          WORKSPACE_SUBDIR: ${{ steps.plan.outputs.workspace_subdir }}
          WORKSPACE_ACTION: ${{ steps.plan.outputs.action }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          AGENT_EXIT: ${{ steps.agent_exit.outputs.code }}
          BRANCH_NAME: ${{ steps.branch_ctx.outputs.branch }}
        run: |
          sudo chown -R "$(id -u):$(id -g)" "examples/${WORKSPACE_SUBDIR}/" 2>/dev/null || true
          python3 -c "from pathlib import Path; import shutil; root=Path('examples/${WORKSPACE_SUBDIR}'); [shutil.rmtree(p, ignore_errors=True) for p in root.rglob('__pycache__') if p.is_dir()]; [p.unlink(missing_ok=True) for p in root.rglob('*.pyc')]; [shutil.rmtree(p, ignore_errors=True) for p in [root/'.pytest_cache'] if p.exists()]"

          if ! git status --porcelain -- "examples/${WORKSPACE_SUBDIR}/" | grep -q .; then
            echo "No residual changes to commit"
            exit 0
          fi

          git add "examples/${WORKSPACE_SUBDIR}/"
          if git diff --cached --quiet -- "examples/${WORKSPACE_SUBDIR}/"; then
            echo "No staged residual changes"
            exit 0
          fi

          if [ "$AGENT_EXIT" = "0" ]; then
            commit_subject="complete ${WORKSPACE_SUBDIR}"
            commit_type="feat"
          else
            commit_subject="checkpoint ${WORKSPACE_SUBDIR}"
            commit_type="chore"
          fi

          git commit -m "${commit_type}(examples): ${commit_subject}

          Relates to #${ISSUE_NUMBER}"

          git push origin "HEAD:${BRANCH_NAME}" || {
            git pull --rebase origin "$BRANCH_NAME"
            git push origin "HEAD:${BRANCH_NAME}"
          }

      # ------------------------------------------------------------------
      # 12. Update the draft PR with final state and test output
      # ------------------------------------------------------------------
      - name: Upsert pull request
        id: pr
        if: steps.issue.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          REPO_SLUG: ${{ github.repository }}
          BRANCH_NAME: ${{ steps.branch_ctx.outputs.branch }}
          WORKSPACE_SUBDIR: ${{ steps.plan.outputs.workspace_subdir }}
          RUNTIME: ${{ steps.plan.outputs.runtime }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          ISSUE_BODY: ${{ steps.issue.outputs.body }}
          WORKSPACE_ACTION: ${{ steps.plan.outputs.action }}
          WORKSPACE_DIR: ${{ github.workspace }}/examples/${{ steps.plan.outputs.workspace_subdir }}
          AGENT_EXIT: ${{ steps.agent_exit.outputs.code }}
          EXISTING_PR_NUMBER: ${{ steps.kickoff_pr.outputs.number || steps.branch_ctx.outputs.pr_number }}
          EXISTING_PR_URL: ${{ steps.kickoff_pr.outputs.url || steps.branch_ctx.outputs.pr_url }}
        run: |
          if [ "$WORKSPACE_ACTION" = "modify" ]; then
            title_base="update ${WORKSPACE_SUBDIR}"
          else
            title_base="add ${WORKSPACE_SUBDIR}"
          fi

          if [ "$AGENT_EXIT" = "0" ]; then
            pr_title="feat(examples): ${title_base}"
            needs_creds=$(python3 /tmp/engineering-scripts/build_pr_body.py \
              --workspace "$WORKSPACE_DIR" \
              --issue "$ISSUE_NUMBER" \
              --issue-body "$ISSUE_BODY" \
              --action "$WORKSPACE_ACTION" \
              --runtime "$RUNTIME" \
              --example "$WORKSPACE_SUBDIR" \
              --build-log /tmp/build-log.md \
              --agent-state /tmp/agent-state.json)
          else
            pr_title="feat(examples): ${title_base}"
            needs_creds=$(python3 /tmp/engineering-scripts/build_pr_body.py \
              --workspace "$WORKSPACE_DIR" \
              --issue "$ISSUE_NUMBER" \
              --issue-body "$ISSUE_BODY" \
              --action "$WORKSPACE_ACTION" \
              --runtime "$RUNTIME" \
              --example "$WORKSPACE_SUBDIR" \
              --build-log /tmp/build-log.md \
              --agent-state /tmp/agent-state.json \
              --incomplete)
          fi

          existing_number="$EXISTING_PR_NUMBER"
          existing_url="$EXISTING_PR_URL"
          if [ -z "$existing_number" ]; then
            existing_number=$(gh pr list \
              --repo "$REPO_SLUG" \
              --head "$BRANCH_NAME" \
              --state open \
              --json number \
              -q '.[0].number' 2>/dev/null || true)
          fi
          if [ -z "$existing_url" ]; then
            existing_url=$(gh pr list \
              --repo "$REPO_SLUG" \
              --head "$BRANCH_NAME" \
              --state open \
              --json url \
              -q '.[0].url' 2>/dev/null || true)
          fi

          if [ -n "$existing_number" ]; then
            gh pr edit "$existing_number" \
              --repo "$REPO_SLUG" \
              --title "$pr_title" \
              --body-file /tmp/pr-body.md
            gh pr edit "$existing_number" --repo "$REPO_SLUG" --add-label "type:example" --add-label "automated" >/dev/null 2>&1 || true
            if [ "$needs_creds" = "needs-credentials" ]; then
              gh pr edit "$existing_number" --repo "$REPO_SLUG" --add-label "needs-credentials" >/dev/null 2>&1 || true
            fi
            echo "url=$existing_url" >> "$GITHUB_OUTPUT"
            echo "number=$existing_number" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          url=$(gh pr create \
            --repo "$REPO_SLUG" \
            --head "$BRANCH_NAME" \
            --base main \
            --title "$pr_title" \
            --body-file /tmp/pr-body.md \
            --draft)

          pr_number=$(gh pr view "$url" --repo "$REPO_SLUG" --json number -q .number 2>/dev/null || true)
          gh pr edit "$pr_number" --repo "$REPO_SLUG" --add-label "type:example" --add-label "automated" >/dev/null 2>&1 || true
          if [ "$needs_creds" = "needs-credentials" ]; then
            gh pr edit "$pr_number" --repo "$REPO_SLUG" --add-label "needs-credentials" >/dev/null 2>&1 || true
          fi
          echo "url=$url" >> "$GITHUB_OUTPUT"
          echo "number=$pr_number" >> "$GITHUB_OUTPUT"

      # ------------------------------------------------------------------
      # 13. Comment on issue with completion / continuation status
      # ------------------------------------------------------------------
      - name: Comment on issue (complete)
        if: steps.issue.outputs.skip != 'true' && steps.agent_exit.outputs.code == '0' && steps.pr.outputs.url != ''
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          PR_URL: ${{ steps.pr.outputs.url }}
        run: |
          gh issue comment "$ISSUE_NUMBER" \
            --repo "${{ github.repository }}" \
            --body "✅ Draft PR updated and ready for human review: ${PR_URL}

          The engineering loop finished with passing tests and the PR remains draft for human review.

          <!-- pr-opened -->"

      - name: Comment on issue (incomplete)
        if: steps.issue.outputs.skip != 'true' && steps.agent_exit.outputs.code != '0' && steps.pr.outputs.url != ''
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
          PR_URL: ${{ steps.pr.outputs.url }}
          AGENT_EXIT: ${{ steps.agent_exit.outputs.code }}
        run: |
          state=$(cat /tmp/agent-state.json 2>/dev/null || echo '{}')
          phases=$(echo "$state" | python3 -c "import json,sys; d=json.load(sys.stdin); print(', '.join(d.get('phases',[])))")
          tests=$(echo "$state" | python3 -c "import json,sys; d=json.load(sys.stdin); print('passing' if d.get('tests_passing') else ('failing' if d.get('tests_failing') else 'not yet run'))")
          turns=$(echo "$state" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('turns_used','?'))")
          if [ "$AGENT_EXIT" = "2" ]; then
            intro="⚠️ Build hit the turn limit after ${turns} turns. Draft PR opened: ${PR_URL}"
          else
            intro="⚠️ Build stopped before completion, but progress was checkpointed: ${PR_URL}"
          fi

          gh issue comment "$ISSUE_NUMBER" \
            --repo "${{ github.repository }}" \
            --body "${intro}

          **Progress so far:**
          - Phases complete: ${phases:-none}
          - Tests: ${tests}

          To continue: comment \`@deepgram-robot continue\` on this issue or on the draft PR.

          <!-- pr-opened -->
          <!-- agent-state: ${state} -->"

      - name: Comment on issue (hard failure without PR)
        if: steps.issue.outputs.skip != 'true' && steps.agent_exit.outputs.code == '1' && steps.pr.outputs.url == ''
        env:
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ISSUE_NUMBER: ${{ steps.issue.outputs.number }}
        run: |
          gh issue comment "$ISSUE_NUMBER" \
            --repo "${{ github.repository }}" \
            --body "❌ Build failed before any checkpointed branch/PR could be created. Check the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details."

      # ------------------------------------------------------------------
      # Cleanup — always remove build:in-progress label
      # ------------------------------------------------------------------
      - name: Remove build-in-progress label
        if: always() && steps.issue.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue edit ${{ steps.issue.outputs.number }} \
            --repo "${{ github.repository }}" \
            --remove-label "build:in-progress" 2>/dev/null || true


  # ── Engineering: act on @deepgram-robot mentions anywhere in the repo ────────
  engineering:
    if: |
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@deepgram-robot')) ||
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@deepgram-robot'))
    runs-on: ubuntu-latest
    timeout-minutes: 60

    concurrency:
      group: engineering-${{ github.event.issue.number || github.event.pull_request.number }}
      cancel-in-progress: false

    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write

    steps:
      # ------------------------------------------------------------------
      # Auth: commenter must be a Deepgram org member.
      # Bots are explicitly excluded — we don't want bot-to-bot loops.
      # ------------------------------------------------------------------
      - name: Check commenter org membership
        id: auth
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          COMMENTER="${{ github.event.comment.user.login }}"

          # Never respond to bots — prevents feedback loops
          if [[ "$COMMENTER" == *"[bot]"* ]]; then
            echo "allowed=false" >> "$GITHUB_OUTPUT"
            echo "Commenter is a bot — skipping"
            exit 0
          fi

          http_line=$(gh api "orgs/deepgram/members/${COMMENTER}" -i 2>/dev/null | head -1)
          if echo "$http_line" | grep -q "204"; then
            echo "allowed=true" >> "$GITHUB_OUTPUT"
            echo "$COMMENTER is a Deepgram org member — proceeding"
          else
            echo "allowed=false" >> "$GITHUB_OUTPUT"
            echo "$COMMENTER is not a Deepgram org member — ignoring"
          fi

      - name: Checkout workflow source
        if: steps.auth.outputs.allowed == 'true'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          token: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ref: ${{ github.sha }}
          fetch-depth: 1

      - name: Snapshot workflow scripts
        if: steps.auth.outputs.allowed == 'true'
        run: |
          rm -rf /tmp/engineering-scripts
          mkdir -p /tmp/engineering-scripts
          cp -R .github/scripts/. /tmp/engineering-scripts/

      # ------------------------------------------------------------------
      # Resolve context: which issue/PR, which branch to check out
      # ------------------------------------------------------------------
      - name: Resolve context
        id: ctx
        if: steps.auth.outputs.allowed == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          EVENT="${{ github.event_name }}"
          pr_number=""

          if [ "$EVENT" = "pull_request_review_comment" ]; then
            number="${{ github.event.pull_request.number }}"
            pr_number="$number"
            branch="${{ github.event.pull_request.head.ref }}"
            context_type="PR"
          else
            # issue_comment — could be on an issue or a PR
            number="${{ github.event.issue.number }}"
            branch=$(gh pr view "$number" --json headRefName -q .headRefName 2>/dev/null || true)
            pr_number="$number"
            if [ -n "$branch" ]; then
              context_type="PR"
            else
              linked_pr=$(gh api search/issues \
                -f q="repo:${{ github.repository }} is:pr is:open \"Relates to #${number}\" in:body" \
                2>/dev/null || echo '{"items": []}')
              pr_number=$(echo "$linked_pr" | python3 -c "import json,sys; items=json.load(sys.stdin).get('items', []); print(items[0]['number'] if items else '')")
              if [ -n "$pr_number" ]; then
                branch=$(gh pr view "$pr_number" --json headRefName -q .headRefName 2>/dev/null || true)
                context_type="PR"
              else
                pr_number=""
                branch="main"
                context_type="issue"
              fi
            fi
          fi

          echo "number=$number"             >> "$GITHUB_OUTPUT"
          echo "pr_number=$pr_number"       >> "$GITHUB_OUTPUT"
          echo "branch=$branch"             >> "$GITHUB_OUTPUT"
          echo "context_type=$context_type" >> "$GITHUB_OUTPUT"

          # Fetch full PR body for context — contains original issue, extra context, agent state
          if [ "$context_type" = "PR" ] && [ -n "$pr_number" ]; then
            pr_body=$(gh pr view "$pr_number" \
              --repo "${{ github.repository }}" \
              --json body \
              -q '.body' 2>/dev/null || echo '')
          else
            pr_body=""
          fi
          echo "pr_body<<PR_BODY_EOF" >> "$GITHUB_OUTPUT"
          echo "$pr_body" >> "$GITHUB_OUTPUT"
          echo "PR_BODY_EOF" >> "$GITHUB_OUTPUT"

          # Extract prior agent-state from any hidden comment on this issue/PR
          prior_state=$(gh issue view "$number" \
            --repo "${{ github.repository }}" \
            --json body,comments \
            --jq '([.body] + [.comments[].body]) | map(select(contains("<!-- agent-state:"))) | last' \
            2>/dev/null | \
            python3 /tmp/engineering-scripts/extract_agent_state.py || true)
          echo "prior_state=$prior_state" >> "$GITHUB_OUTPUT"

      - name: Checkout
        if: steps.auth.outputs.allowed == 'true'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          token: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          ref: ${{ steps.ctx.outputs.branch }}
          fetch-depth: 0  # Full clone so the target branch is available

      - name: Configure git
        if: steps.auth.outputs.allowed == 'true'
        env:
          GH_BOT_LOGIN: ${{ secrets.GH_BOT_LOGIN || 'github-actions[bot]' }}
        run: |
          git config user.name "$GH_BOT_LOGIN"
          git config user.email "$GH_BOT_LOGIN@users.noreply.github.com"

      # ------------------------------------------------------------------
      # Run the engineering agent — full unrestricted access to the repo.
      # Acts on whatever was asked, commits if needed, replies in thread.
      # ------------------------------------------------------------------
      - name: Run engineering agent
        if: steps.auth.outputs.allowed == 'true'
        env:
          REPO_SLUG: ${{ github.repository }}
          ISSUE_NUMBER: ${{ steps.ctx.outputs.number }}
          COMMENT_BODY: ${{ github.event.comment.body }}
          COMMENTER: ${{ github.event.comment.user.login }}
          BRANCH: ${{ steps.ctx.outputs.branch }}
          PR_BODY: ${{ steps.ctx.outputs.pr_body }}
          PRIOR_STATE: ${{ steps.ctx.outputs.prior_state }}
          COMMENT_URL: ${{ github.event.comment.html_url }}
          GH_TOKEN: ${{ secrets.GH_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL || 'https://api.openai.com/v1' }}
          LLM_MODEL: ${{ secrets.LLM_MODEL || 'gpt-5.4' }}
          DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
          GH_BOT_LOGIN: ${{ secrets.GH_BOT_LOGIN || 'github-actions[bot]' }}
        run: |
          set +e
          python3 /tmp/engineering-scripts/run_engineering_agent.py
          result=$?
          exit $result