@harbinger-ai/harbinger 0.1.0

package/templates/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+.env
+data/
+logs/
+.git

package/templates/.env.example

@@ -0,0 +1,63 @@
+# thepopebot Configuration
+# Copy this file to .env and fill in your values
+# NEVER commit the actual .env file with real secrets!
+
+# Auth.js secret for session encryption (auto-generated by setup wizard)
+# To generate manually: openssl rand -base64 32
+AUTH_SECRET=
+
+# Trust the host header when behind a reverse proxy (Traefik, ngrok, etc.)
+AUTH_TRUST_HOST=true
+
+# Public URL for webhooks, Telegram, and Traefik hostname
+APP_URL=
+
+# Hostname extracted from APP_URL (e.g., mybot.example.com) — used by docker-compose/Traefik
+# Auto-set by setup wizard
+APP_HOSTNAME=
+
+# GitHub Personal Access Token (needs repo, workflow scopes)
+GH_TOKEN=ghp_your_token_here
+
+# Repository info
+GH_OWNER=your_github_username
+GH_REPO=your_repo_name
+
+# Telegram bot token from @BotFather (optional)
+TELEGRAM_BOT_TOKEN=
+
+# Secret for validating Telegram webhooks (generate with: openssl rand -hex 32)
+TELEGRAM_WEBHOOK_SECRET=
+
+# Verification code for getting your chat ID (e.g., verify-abc12345)
+TELEGRAM_VERIFICATION=
+
+# Secret for GitHub Actions webhook auth (must match GH_WEBHOOK_SECRET secret)
+GH_WEBHOOK_SECRET=
+
+# Anthropic API key for Claude chat features
+ANTHROPIC_API_KEY=sk-ant-your_key_here
+
+# OpenAI API key for Whisper voice transcription (optional)
+OPENAI_API_KEY=
+
+# LLM provider: anthropic, openai, or google (default: anthropic)
+# LLM_PROVIDER=anthropic
+
+# LLM model name override (optional, provider-specific default if unset)
+# LLM_MODEL=
+
+# Default Telegram chat ID for scheduled notifications
+# Get this by messaging your bot and checking the webhook logs, or use @userinfobot
+TELEGRAM_CHAT_ID=
+
+# Let's Encrypt email for automatic SSL (docker-compose only, optional)
+# If not set, Traefik uses a self-signed certificate
+# LETSENCRYPT_EMAIL=
+
+# thepopebot version — auto-set by postinstall, used by docker-compose for image tags
+# THEPOPEBOT_VERSION=
+
+# Custom Docker images (optional, overrides the default stephengpope/thepopebot images)
+# EVENT_HANDLER_IMAGE_URL=
+# JOB_IMAGE_URL=

package/templates/.github/workflows/auto-merge.yml

@@ -0,0 +1,117 @@
+name: Auto-Merge Job PR
+
+on:
+  pull_request:
+    types: [opened]
+    branches: [main]
+
+jobs:
+  auto-merge:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: startsWith(github.event.pull_request.head.ref, 'job/')
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Wait for merge check
+        id: merge-check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          for i in $(seq 1 30); do
+            sleep 10
+            MERGEABLE=$(gh pr view "$PR_NUMBER" --repo "${{ github.repository }}" --json mergeable -q '.mergeable')
+            if [ "$MERGEABLE" != "" ] && [ "$MERGEABLE" != "UNKNOWN" ]; then
+              echo "mergeable=$MERGEABLE" >> "$GITHUB_OUTPUT"
+              echo "Mergeable: $MERGEABLE"
+              exit 0
+            fi
+            echo "Still computing... (attempt $i/30)"
+          done
+          echo "mergeable=UNKNOWN" >> "$GITHUB_OUTPUT"
+          echo "Timed out waiting for merge check"
+
+      - name: Check AUTO_MERGE setting
+        if: steps.merge-check.outputs.mergeable == 'MERGEABLE'
+        id: check-setting
+        run: |
+          AUTO_MERGE="${{ vars.AUTO_MERGE }}"
+          if [ "$AUTO_MERGE" = "false" ]; then
+            echo "Auto-merge disabled via AUTO_MERGE=false"
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Auto-merge enabled"
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check ALLOWED_PATHS
+        if: steps.merge-check.outputs.mergeable == 'MERGEABLE' && steps.check-setting.outputs.enabled == 'true'
+        id: check-paths
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ALLOWED_PATHS="${{ vars.ALLOWED_PATHS }}"
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+
+          # Default: only logs allowed
+          if [ -z "$ALLOWED_PATHS" ]; then
+            ALLOWED_PATHS="/logs"
+          fi
+
+          # Normalize: ensure each prefix starts with /
+          IFS=',' read -ra RAW_PREFIXES <<< "$ALLOWED_PATHS"
+          PREFIXES=()
+          for p in "${RAW_PREFIXES[@]}"; do
+            trimmed=$(echo "$p" | xargs)
+            [ -z "$trimmed" ] && continue
+            # Ensure leading /
+            [[ "$trimmed" != /* ]] && trimmed="/$trimmed"
+            PREFIXES+=("$trimmed")
+          done
+
+          # "/" means everything allowed
+          for p in "${PREFIXES[@]}"; do
+            if [ "$p" = "/" ]; then
+              echo "All paths allowed (ALLOWED_PATHS contains /)"
+              echo "allowed=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          done
+
+          # Get changed files
+          CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --name-only --repo "${{ github.repository }}")
+          if [ -z "$CHANGED_FILES" ]; then
+            echo "No changed files"
+            echo "allowed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Check each file against prefixes
+          # Strip leading / from prefixes for comparison (git paths are relative)
+          ALL_OK=true
+          while IFS= read -r file; do
+            [ -z "$file" ] && continue
+            FILE_OK=false
+            for prefix in "${PREFIXES[@]}"; do
+              compare="${prefix#/}"
+              if [[ "$file" == "$compare"* ]]; then
+                FILE_OK=true
+                break
+              fi
+            done
+            if [ "$FILE_OK" = "false" ]; then
+              echo "BLOCKED: $file"
+              ALL_OK=false
+            fi
+          done <<< "$CHANGED_FILES"
+
+          echo "allowed=$ALL_OK" >> "$GITHUB_OUTPUT"
+
+      - name: Merge PR
+        if: steps.merge-check.outputs.mergeable == 'MERGEABLE' && steps.check-setting.outputs.enabled == 'true' && steps.check-paths.outputs.allowed == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr merge ${{ github.event.pull_request.number }} --squash --delete-branch --repo "${{ github.repository }}"

package/templates/.github/workflows/build-image.yml

@@ -0,0 +1,36 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [main]
+    paths: ['docker/job-pi-coding-agent/**']
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: vars.JOB_IMAGE_URL != '' && startsWith(vars.JOB_IMAGE_URL, 'ghcr.io/')
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: ./docker/job-pi-coding-agent
+          push: true
+          tags: ${{ vars.JOB_IMAGE_URL }}:latest

package/templates/.github/workflows/notify-job-failed.yml

@@ -0,0 +1,64 @@
+name: Notify Job Failed
+
+on:
+  workflow_run:
+    workflows: ["Agent Job"]
+    types: [completed]
+
+jobs:
+  notify-failure:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: >
+      github.event.workflow_run.conclusion != 'success' &&
+      startsWith(github.event.workflow_run.head_branch, 'job/')
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout job branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_branch }}
+
+      - name: Send failure notification
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="${{ github.event.workflow_run.head_branch }}"
+          JOB_ID="${BRANCH#job/}"
+          RUN_ID="${{ github.event.workflow_run.id }}"
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${RUN_ID}"
+
+          # Read job description from job.config.json (exists on branch from job creation)
+          JOB_CONTENT=""
+          if [ -f "logs/${JOB_ID}/job.config.json" ]; then
+            JOB_CONTENT=$(jq -r '.job // empty' "logs/${JOB_ID}/job.config.json")
+          fi
+
+          COMMIT_SHA=$(git rev-parse HEAD)
+          STATUS="${{ github.event.workflow_run.conclusion }}"
+
+          jq -n \
+            --arg job_id "$JOB_ID" \
+            --arg branch "$BRANCH" \
+            --arg status "$STATUS" \
+            --arg job "$JOB_CONTENT" \
+            --arg run_url "$RUN_URL" \
+            --arg commit_sha "$COMMIT_SHA" \
+            '{
+              job_id: $job_id,
+              branch: $branch,
+              status: $status,
+              job: $job,
+              run_url: $run_url,
+              pr_url: "",
+              changed_files: [],
+              commit_message: "",
+              commit_sha: $commit_sha,
+              merge_result: ""
+            }' > /tmp/payload.json
+
+          curl -s -X POST "${{ vars.APP_URL }}/api/github/webhook" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Webhook-Secret-Token: ${{ secrets.GH_WEBHOOK_SECRET }}" \
+            -d @/tmp/payload.json

package/templates/.github/workflows/notify-pr-complete.yml

@@ -0,0 +1,119 @@
+name: Notify Event Handler
+
+on:
+  workflow_run:
+    workflows: ["Auto-Merge Job PR"]
+    types: [completed]
+
+jobs:
+  notify:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: startsWith(github.event.workflow_run.head_branch, 'job/')
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Get PR number
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="${{ github.event.workflow_run.head_branch }}"
+
+          # Try workflow_run.pull_requests first
+          PR_NUMBER=$(echo '${{ toJson(github.event.workflow_run.pull_requests) }}' | jq -r '.[0].number // empty')
+
+          # Fallback: look up PR by head branch
+          if [ -z "$PR_NUMBER" ]; then
+            PR_NUMBER=$(gh pr list --head "$BRANCH" --state all --repo "${{ github.repository }}" --json number -q '.[0].number')
+          fi
+
+          if [ -z "$PR_NUMBER" ]; then
+            echo "No PR found for branch $BRANCH"
+            exit 1
+          fi
+
+          PR_URL=$(gh pr view "$PR_NUMBER" --repo "${{ github.repository }}" --json url -q '.url')
+
+          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          echo "url=$PR_URL" >> "$GITHUB_OUTPUT"
+          echo "Found PR #$PR_NUMBER"
+
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Gather job results and notify
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_NUMBER="${{ steps.pr.outputs.number }}"
+          BRANCH="${{ github.event.workflow_run.head_branch }}"
+          JOB_ID="${BRANCH#job/}"
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}"
+
+          # Check actual PR merge state
+          PR_MERGED=$(gh pr view "$PR_NUMBER" --repo "${{ github.repository }}" --json mergedAt -q '.mergedAt')
+          if [ -n "$PR_MERGED" ] && [ "$PR_MERGED" != "null" ]; then
+            MERGE_RESULT="merged"
+          else
+            MERGE_RESULT="not_merged"
+          fi
+
+          # 1. Read job description from job.config.json (on disk after checkout)
+          JOB_CONTENT=""
+          if [ -f "logs/${JOB_ID}/job.config.json" ]; then
+            JOB_CONTENT=$(jq -r '.job // empty' "logs/${JOB_ID}/job.config.json")
+          fi
+
+          # 2. Get last commit message via gh CLI
+          COMMIT_MSG=$(gh pr view "$PR_NUMBER" --json commits --jq '.commits[-1].messageHeadline' --repo "${{ github.repository }}" 2>/dev/null || echo "")
+
+          # 3. Get changed files (names only)
+          CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --name-only --repo "${{ github.repository }}" 2>/dev/null || echo "")
+
+          # 4. Get PR status
+          PR_STATUS=$(gh pr view "$PR_NUMBER" --json state --jq '.state' --repo "${{ github.repository }}" 2>/dev/null || echo "open")
+
+          # 5. Commit SHA for server-side log fetching
+          COMMIT_SHA="${{ github.event.workflow_run.head_sha }}"
+
+          # Determine status based on merge result and PR state
+          if [ "$MERGE_RESULT" = "merged" ]; then
+            STATUS="completed"
+          else
+            STATUS="$PR_STATUS"
+          fi
+
+          # 6. Build flat JSON payload
+          jq -n \
+            --arg job_id "$JOB_ID" \
+            --arg branch "$BRANCH" \
+            --arg status "$STATUS" \
+            --arg job "$JOB_CONTENT" \
+            --arg run_url "$RUN_URL" \
+            --arg pr_url "${{ steps.pr.outputs.url }}" \
+            --arg commit_message "$COMMIT_MSG" \
+            --arg changed_files "$CHANGED_FILES" \
+            --arg commit_sha "$COMMIT_SHA" \
+            --arg merge_result "$MERGE_RESULT" \
+            '{
+              job_id: $job_id,
+              branch: $branch,
+              status: $status,
+              job: $job,
+              run_url: $run_url,
+              pr_url: $pr_url,
+              changed_files: ($changed_files | split("\n") | map(select(length > 0))),
+              commit_message: $commit_message,
+              commit_sha: $commit_sha,
+              merge_result: $merge_result
+            }' > /tmp/payload.json
+
+          # 7. Send to event handler
+          curl -s -X POST "${{ vars.APP_URL }}/api/github/webhook" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Webhook-Secret-Token: ${{ secrets.GH_WEBHOOK_SECRET }}" \
+            -d @/tmp/payload.json

package/templates/.github/workflows/rebuild-event-handler.yml

@@ -0,0 +1,121 @@
+name: Rebuild Event Handler
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: event-handler-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: self-hosted
+    timeout-minutes: 20
+    steps:
+      - name: Pull latest and detect version change
+        id: pull
+        run: |
+          docker exec thepopebot-event-handler bash -c '
+            export GH_TOKEN=$(grep "^GH_TOKEN=" /app/.env | cut -d= -f2-)
+            echo "${GH_TOKEN}" | gh auth login --with-token
+            gh auth setup-git
+
+            git fetch origin main
+            CHANGED=$(git diff --name-only HEAD origin/main)
+            if ! echo "$CHANGED" | grep -qv "^logs/"; then
+              echo "SKIP" > /app/.rebuild-status
+              git reset --hard origin/main
+              exit 0
+            fi
+
+            # Detect thepopebot version change from package-lock.json in git
+            git show HEAD:package-lock.json > /tmp/old-lock.json 2>/dev/null || echo "{}" > /tmp/old-lock.json
+            git show origin/main:package-lock.json > /tmp/new-lock.json
+            OLD_TPB=$(node -p "try{require(\"/tmp/old-lock.json\").packages[\"node_modules/thepopebot\"]?.version||\"\"}catch(e){\"\"}")
+            NEW_TPB=$(node -p "try{require(\"/tmp/new-lock.json\").packages[\"node_modules/thepopebot\"]?.version||\"\"}catch(e){\"\"}")
+            rm -f /tmp/old-lock.json /tmp/new-lock.json
+
+            git reset --hard origin/main
+
+            if [ -n "$OLD_TPB" ] && [ "$OLD_TPB" != "$NEW_TPB" ]; then
+              # Version changed — run thepopebot init to scaffold new templates
+              if echo "$NEW_TPB" | grep -q "-"; then
+                npx --yes "thepopebot@${NEW_TPB}" init
+              else
+                npx --yes thepopebot@latest init
+              fi
+
+              # Commit any template changes from init
+              git add -A
+              if ! git diff --cached --quiet; then
+                git commit -m "chore: apply thepopebot init after upgrade"
+                git push origin main
+              fi
+
+              # Update THEPOPEBOT_VERSION in .env so docker compose pulls the right image
+              if grep -q "^THEPOPEBOT_VERSION=" /app/.env; then
+                sed -i "s/^THEPOPEBOT_VERSION=.*/THEPOPEBOT_VERSION=$NEW_TPB/" /app/.env
+              else
+                echo "THEPOPEBOT_VERSION=$NEW_TPB" >> /app/.env
+              fi
+              echo "VERSION_CHANGED" > /app/.rebuild-status
+            else
+              npm install --omit=dev
+              echo "REBUILD" > /app/.rebuild-status
+            fi
+          '
+
+          STATUS=$(docker exec thepopebot-event-handler cat /app/.rebuild-status)
+          docker exec thepopebot-event-handler rm -f /app/.rebuild-status
+          echo "status=$STATUS" >> $GITHUB_OUTPUT
+
+      - name: Rebuild (no version change)
+        if: steps.pull.outputs.status == 'REBUILD'
+        run: |
+          docker exec thepopebot-event-handler bash -c '
+            rm -rf .next-new .next-old
+            NEXT_BUILD_DIR=.next-new npm run build
+
+            mv .next .next-old 2>/dev/null || true
+            mv .next-new .next
+
+            echo "Rebuild complete, reloading Next.js..."
+            npx pm2 reload all
+
+            rm -rf .next-old
+          '
+
+      - name: Pull new image and restart container
+        if: steps.pull.outputs.status == 'VERSION_CHANGED'
+        run: |
+          HOST_DIR=$(docker inspect thepopebot-event-handler --format '{{index .Config.Labels "com.docker.compose.project.working_dir"}}')
+          docker compose -f /project/docker-compose.yml --project-directory "$HOST_DIR" --env-file /project/.env pull event-handler
+          docker stop thepopebot-event-handler || true
+          docker rm thepopebot-event-handler || true
+          docker compose -f /project/docker-compose.yml --project-directory "$HOST_DIR" --env-file /project/.env up -d event-handler
+
+      - name: Rebuild in new container
+        if: steps.pull.outputs.status == 'VERSION_CHANGED'
+        run: |
+          echo "Waiting for new container..."
+          for i in $(seq 1 30); do
+            if docker exec thepopebot-event-handler echo "ready" 2>/dev/null; then
+              break
+            fi
+            sleep 2
+          done
+
+          docker exec thepopebot-event-handler bash -c '
+            npm install --omit=dev
+
+            rm -rf .next-new .next-old
+            NEXT_BUILD_DIR=.next-new npm run build
+
+            mv .next .next-old 2>/dev/null || true
+            mv .next-new .next
+
+            npx pm2 restart all
+
+            rm -rf .next-old
+          '

package/templates/.github/workflows/run-job.yml

@@ -0,0 +1,89 @@
+name: Agent Job
+
+on:
+  create:
+
+jobs:
+  run-agent:
+    runs-on: ${{ vars.RUNS_ON || 'ubuntu-latest' }}
+    if: github.ref_type == 'branch' && startsWith(github.ref_name, 'job/')
+    permissions:
+      contents: write
+      packages: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+          sparse-checkout: |
+            package-lock.json
+            logs/*/job.config.json
+          sparse-checkout-cone-mode: false
+
+      - name: Get thepopebot version
+        id: version
+        run: |
+          VERSION=$(jq -r '.packages["node_modules/thepopebot"].version // "latest"' package-lock.json)
+          echo "tag=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Read job config overrides
+        id: job-config
+        run: |
+          JOB_ID="${{ github.ref_name }}"
+          JOB_ID="${JOB_ID#job/}"
+          CONFIG_FILE="logs/${JOB_ID}/job.config.json"
+          if [ -f "$CONFIG_FILE" ]; then
+            echo "llm_provider=$(jq -r '.llm_provider // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+            echo "llm_model=$(jq -r '.llm_model // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+            echo "agent_backend=$(jq -r '.agent_backend // empty' "$CONFIG_FILE")" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Login to GHCR
+        if: startsWith(vars.JOB_IMAGE_URL, 'ghcr.io/')
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run thepopebot Agent
+        env:
+          ALL_SECRETS: ${{ toJson(secrets) }}
+          JOB_IMAGE_URL: ${{ vars.JOB_IMAGE_URL }}
+          THEPOPEBOT_VERSION: ${{ steps.version.outputs.tag }}
+          LLM_MODEL: ${{ steps.job-config.outputs.llm_model || vars.LLM_MODEL }}
+          LLM_PROVIDER: ${{ steps.job-config.outputs.llm_provider || vars.LLM_PROVIDER }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          AGENT_BACKEND: ${{ steps.job-config.outputs.agent_backend || vars.AGENT_BACKEND || '' }}
+        run: |
+          AGENT_BACKEND="${AGENT_BACKEND:-pi}"
+          if [ -n "$JOB_IMAGE_URL" ]; then
+            IMAGE="${JOB_IMAGE_URL}:latest"
+          elif [ "$AGENT_BACKEND" = "claude-code" ]; then
+            IMAGE="stephengpope/thepopebot:job-claude-code-${THEPOPEBOT_VERSION}"
+          else
+            IMAGE="stephengpope/thepopebot:job-${THEPOPEBOT_VERSION}"
+          fi
+          echo "Using image: $IMAGE"
+
+          # Build SECRETS JSON from AGENT_* (excluding AGENT_LLM_*) secrets
+          export SECRETS=$(echo "$ALL_SECRETS" | jq -c '
+            [to_entries[] | select(.key | startswith("AGENT_")) | select(.key | startswith("AGENT_LLM_") | not)]
+            | map({key: (.key | sub("^AGENT_"; "")), value: .value}) | from_entries')
+
+          # Build LLM_SECRETS JSON from AGENT_LLM_* secrets
+          export LLM_SECRETS=$(echo "$ALL_SECRETS" | jq -c '
+            [to_entries[] | select(.key | startswith("AGENT_LLM_"))]
+            | map({key: (.key | sub("^AGENT_LLM_"; "")), value: .value}) | from_entries')
+
+          docker run --rm \
+            -e REPO_URL="${{ github.server_url }}/${{ github.repository }}.git" \
+            -e BRANCH="${{ github.ref_name }}" \
+            -e SECRETS \
+            -e LLM_SECRETS \
+            -e LLM_MODEL="${LLM_MODEL}" \
+            -e LLM_PROVIDER="${LLM_PROVIDER}" \
+            -e OPENAI_BASE_URL="${OPENAI_BASE_URL}" \
+            -e AGENT_BACKEND="${AGENT_BACKEND}" \
+            "$IMAGE"

package/templates/.github/workflows/upgrade-event-handler.yml

@@ -0,0 +1,62 @@
+name: Upgrade Event Handler
+
+on:
+  workflow_dispatch:
+    inputs:
+      target_version:
+        description: 'Target version to install (empty for latest stable)'
+        required: false
+        default: ''
+
+concurrency:
+  group: event-handler-deploy
+  cancel-in-progress: false
+
+jobs:
+  upgrade:
+    runs-on: self-hosted
+    timeout-minutes: 20
+    steps:
+      - name: Upgrade thepopebot
+        run: |
+          docker exec thepopebot-event-handler bash -c '
+            export GH_TOKEN=$(grep "^GH_TOKEN=" /app/.env | cut -d= -f2-)
+            echo "${GH_TOKEN}" | gh auth login --with-token
+            gh auth setup-git
+
+            REPO_URL=$(git -C /app remote get-url origin)
+            WORK_DIR=$(mktemp -d)
+            git clone --depth 1 "$REPO_URL" "$WORK_DIR"
+            cd "$WORK_DIR"
+
+            git config user.name "thepopebot"
+            git config user.email "thepopebot@users.noreply.github.com"
+
+            npm install --omit=dev
+            OLD_VERSION=$(node -p "require(\"./node_modules/thepopebot/package.json\").version")
+
+            TARGET="${{ github.event.inputs.target_version }}"
+            if [ -n "$TARGET" ] && echo "$TARGET" | grep -q "-"; then
+              # Beta: npm update cannot upgrade an exact-pinned dependency, must use install
+              npm install "thepopebot@${TARGET}" --prefer-online
+            else
+              # Stable: npm update resolves to latest within semver range
+              npm update thepopebot --prefer-online
+            fi
+
+            NEW_VERSION=$(node -p "require(\"./node_modules/thepopebot/package.json\").version")
+
+            if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
+              BRANCH="upgrade/thepopebot-${NEW_VERSION}-$(date +%s)"
+              git add -A
+              git checkout -b "$BRANCH"
+              git commit -m "chore: upgrade thepopebot to $NEW_VERSION"
+              git push origin "$BRANCH"
+              gh pr create --title "chore: upgrade thepopebot" --body "Automated upgrade via upgrade-event-handler workflow." --base main --head "$BRANCH"
+              gh pr merge "$BRANCH" --squash --auto --delete-branch
+            else
+              echo "No changes — thepopebot is already up to date."
+            fi
+
+            rm -rf "$WORK_DIR"
+          '