thepopebot 1.0.0

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

@@ -0,0 +1,34 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: vars.IMAGE_URL != '' && startsWith(vars.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
+          push: true
+          tags: ${{ vars.IMAGE_URL }}:latest

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

@@ -0,0 +1,40 @@
+name: Run thepopebot Job
+
+on:
+  create:
+
+jobs:
+  run-agent:
+    runs-on: ubuntu-latest
+    if: github.ref_type == 'branch' && startsWith(github.ref_name, 'job/')
+    permissions:
+      contents: write
+      packages: read
+
+    steps:
+      - name: Login to GHCR
+        if: startsWith(vars.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:
+          IMAGE_URL: ${{ vars.IMAGE_URL }}
+          MODEL: ${{ vars.MODEL }}
+        run: |
+          if [ -n "$IMAGE_URL" ]; then
+            IMAGE="${IMAGE_URL}:latest"
+          else
+            IMAGE="stephengpope/thepopebot:latest"
+          fi
+          echo "Using image: $IMAGE"
+          docker run --rm \
+            -e REPO_URL="${{ github.server_url }}/${{ github.repository }}.git" \
+            -e BRANCH="${{ github.ref_name }}" \
+            -e SECRETS='${{ secrets.SECRETS }}' \
+            -e LLM_SECRETS='${{ secrets.LLM_SECRETS }}' \
+            -e MODEL="${MODEL}" \
+            "$IMAGE"

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

@@ -0,0 +1,126 @@
+name: PR Webhook Notification
+
+on:
+  workflow_run:
+    workflows: ["Auto-Merge Job PR"]
+    types: [completed]
+
+jobs:
+  notify:
+    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')
+          PR_TITLE=$(gh pr view "$PR_NUMBER" --repo "${{ github.repository }}" --json title -q '.title')
+
+          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          echo "url=$PR_URL" >> "$GITHUB_OUTPUT"
+          echo "title=$PR_TITLE" >> "$GITHUB_OUTPUT"
+          echo "Found PR #$PR_NUMBER: $PR_TITLE"
+
+      - 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/}"
+          # Check actual PR merge state (workflow conclusion doesn't distinguish skipped merge from successful merge)
+          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.md (on disk after checkout)
+          JOB_CONTENT=""
+          if [ -f "logs/${JOB_ID}/job.md" ]; then
+            JOB_CONTENT=$(head -c 10000 "logs/${JOB_ID}/job.md")
+          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. Read log file (find .jsonl in logs/{jobId}/)
+          LOG_CONTENT=""
+          LOG_DIR="logs/${JOB_ID}"
+          if [ -d "$LOG_DIR" ]; then
+            LOG_FILE=$(find "$LOG_DIR" -name "*.jsonl" -type f | head -1)
+            if [ -n "$LOG_FILE" ]; then
+              LOG_CONTENT=$(tail -c 50000 "$LOG_FILE")
+            fi
+          fi
+
+          # 6. Build JSON payload with jq (handles escaping safely)
+          jq -n \
+            --arg action "${{ github.event.workflow_run.conclusion }}" \
+            --arg html_url "${{ steps.pr.outputs.url }}" \
+            --arg title "${{ steps.pr.outputs.title }}" \
+            --argjson number "$PR_NUMBER" \
+            --arg head_ref "$BRANCH" \
+            --arg job "$JOB_CONTENT" \
+            --arg commit_message "$COMMIT_MSG" \
+            --arg changed_files "$CHANGED_FILES" \
+            --arg pr_status "$PR_STATUS" \
+            --arg log "$LOG_CONTENT" \
+            --arg merge_result "$MERGE_RESULT" \
+            '{
+              action: $action,
+              pull_request: {
+                html_url: $html_url,
+                title: $title,
+                number: $number,
+                head: { ref: $head_ref }
+              },
+              job_results: {
+                job: $job,
+                commit_message: $commit_message,
+                changed_files: ($changed_files | split("\n") | map(select(length > 0))),
+                pr_status: $pr_status,
+                log: $log,
+                merge_result: $merge_result
+              }
+            }' > /tmp/payload.json
+
+          # 7. Send to event handler
+          curl -s -X POST "${{ vars.GH_WEBHOOK_URL }}/api/github/webhook" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Event: pull_request" \
+            -H "X-GitHub-Webhook-Secret-Token: ${{ secrets.GH_WEBHOOK_SECRET }}" \
+            -d @/tmp/payload.json

package/templates/.pi/skills/modify-self/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: modify-self
+description: Use when a job requires modifying the agent's own code, configuration, personality, cron jobs, skills, or operating system files.
+---
+
+# Modify Self
+
+Before making any changes, read the project documentation for a full understanding of the system architecture:
+
+```bash
+cat /job/CLAUDE.md
+```

package/templates/CLAUDE.md

@@ -0,0 +1,52 @@
+# My Agent
+
+## What is this?
+
+This is an autonomous AI agent powered by [thepopebot](https://github.com/stephengpope/thepopebot). It features a two-layer architecture: a Next.js Event Handler for orchestration (webhooks, Telegram chat, cron scheduling) and a Docker Agent for autonomous task execution.
+
+## Directory Structure
+
+```
+/
+├── .github/workflows/          # CI/CD workflows (managed by thepopebot)
+├── .pi/skills/                 # Custom Pi agent skills
+├── operating_system/           # Agent configuration
+│   ├── SOUL.md                 # Agent personality and identity
+│   ├── CHATBOT.md              # Telegram chat system prompt
+│   ├── JOB_SUMMARY.md          # Job completion summary prompt
+│   ├── HEARTBEAT.md            # Periodic check instructions
+│   ├── TELEGRAM.md             # Telegram formatting guidelines
+│   ├── AGENT.md                # Agent runtime environment
+│   ├── CRONS.json              # Scheduled job definitions
+│   └── TRIGGERS.json           # Webhook trigger definitions
+├── app/                        # Next.js app directory
+│   ├── layout.js               # Root layout
+│   ├── page.js                 # Home page
+│   └── api/[...thepopebot]/    # Framework API routes
+├── cron/                       # Working dir for command-type cron actions
+├── triggers/                   # Working dir for command-type trigger actions
+├── logs/                       # Per-job directories (job.md + session logs)
+├── next.config.mjs             # Next.js config with thepopebot wrapper
+├── .env                        # API keys and tokens (gitignored)
+└── package.json                # Dependencies
+```
+
+## Customization
+
+- **operating_system/** — Agent personality, prompts, crons, triggers
+- **.pi/skills/** — Custom Pi agent skills
+- **cron/** and **triggers/** — Shell scripts for command-type actions
+- **app/** — Add Next.js pages, API routes, components
+
+## API Endpoints
+
+All API routes are under `/api/`:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/webhook` | POST | Create a new job (requires API_KEY) |
+| `/api/telegram/webhook` | POST | Telegram bot webhook |
+| `/api/telegram/register` | POST | Register Telegram webhook URL |
+| `/api/github/webhook` | POST | Receives notifications from GitHub Actions |
+| `/api/jobs/status` | GET | Check status of a running job |
+| `/api/ping` | GET | Health check |

package/templates/app/api/[...thepopebot]/route.js

@@ -0,0 +1 @@
+export { GET, POST } from 'thepopebot/api';

package/templates/app/layout.js

@@ -0,0 +1,12 @@
+export const metadata = {
+  title: 'thepopebot',
+  description: 'AI Agent',
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/app/page.js

@@ -0,0 +1,8 @@
+export default function Home() {
+  return (
+    <main style={{ padding: '2rem', fontFamily: 'system-ui, sans-serif' }}>
+      <h1>thepopebot</h1>
+      <p>Your AI agent is running. Use the API endpoints or Telegram to interact.</p>
+    </main>
+  );
+}

package/templates/instrumentation.js

@@ -0,0 +1 @@
+export { register } from 'thepopebot/instrumentation';

package/templates/next.config.mjs

@@ -0,0 +1,3 @@
+import { withThepopebot } from 'thepopebot/config';
+
+export default withThepopebot({});

package/templates/operating_system/AGENT.md

@@ -0,0 +1,32 @@
+# Agent Environment
+
+**This document describes what you are and your operating environment**
+
+---
+
+## 1. What You Are
+
+You are an autonomous AI agent running inside a Docker container.
+- You have full access to the machine and anything it can do to get the job done.
+
+---
+
+## 2. Local Docker Environment Reference
+
+This section tells you where things about your operating container environment.
+
+### WORKDIR
+
+Your working dir WORKDIR=`/job` -- this is the root folder for the agent.
+
+So you can assume that:
+- /folder/file.ext is /job/folder/file.txt
+- folder/file.ext is /job/folder/file.txt (missing /)
+
+### Where Temporary Files Go `/job/tmp/`
+
+**Important:** Temporary files are defined as files that you create (that are NOT part of the final job.md deliverables)
+
+**Always** use `/job/tmp/` for any temporary files you create.
+
+Scripts in `/job/tmp/` can use `__dirname`-relative paths (e.g., `../docs/data.json`) to reference repo files, because they're inside the repo tree. The `.gitignore` excludes `tmp/` so nothing in this directory gets committed.

package/templates/operating_system/CHATBOT.md

@@ -0,0 +1,74 @@
+# Event Handler Agent
+
+You are the agent's conversational interface, responding to messages on Telegram.
+
+## How you help
+- **General discussions**: Web search, quick answers, or planning new tasks/jobs
+- **Managing jobs**: Planning, creating, and managing autonomous multi-step jobs
+
+## Decision Flow
+
+1. User signals a task/job ("I have a task for you", "create a job", "run a job", "do this") -> Develop a clear job description with the user, get approval, then create the job.
+2. User asks for code/file changes -> Create a job (background)
+3. User asks for complex tasks -> Create a job (background)
+4. Everything else -> Respond directly via chat (you have web_search available when you need real-time data or the user asks you to look something up)
+
+## When to Use Web Search
+
+Web search is fast and runs inline -- no job needed.
+
+Use the `web_search` tool for search:
+- When we're researching for a new job plan
+- Current information (weather, news, prices, events)
+- Looking up documentation or APIs
+- Fact-checking or research questions
+- Anything that needs up-to-date information for our conversation
+
+## When to Create Jobs
+
+Jobs are autonomous multi-step tasks that run in the background.
+
+**CRITICAL: NEVER call create_job without explicit user approval first.**
+
+### Job Creation Step-by-Step Sequence
+
+You MUST follow these steps in order, every time:
+
+1. **Develop the job description with the user.** Ask clarifying questions if anything is ambiguous.
+2. **Present the COMPLETE job description to the user.** Show them the full text of what you intend to pass to `create_job`, formatted clearly so they can review it.
+3. **Wait for explicit approval.** The user must respond with clear confirmation before you proceed. Examples of approval:
+   - "approved"
+   - "yes"
+   - "go ahead"
+   - "looks good"
+   - "send it"
+   - "do it"
+   - "lgtm"
+4. **ONLY THEN call `create_job`** with the EXACT approved description. Do not modify it after approval without re-presenting and getting approval again.
+
+**NO EXCEPTIONS.** This applies to every job -- including simple, obvious, or one-line tasks.
+
+## Creating Jobs
+
+Use the `create_job` tool when the task needs autonomous work -- jobs run a full AI agent with browser automation and tools, so they can handle virtually any multi-step task that's connected to the web.
+
+## Checking Job Status
+
+**Important:** When someone asks about a job always use this tool do not use chat memory.
+
+Use the `get_job_status` tool when the user asks about job progress, running jobs, or wants an update.
+
+## Response Guidelines
+
+- Keep responses concise (Telegram has a 4096 character limit)
+- Be helpful, direct, and efficient
+- When you use web search, summarize the key findings concisely
+
+{{operating_system/TELEGRAM.md}}
+
+# Technical Reference
+
+Below are technical details on how the agent is built.
+- Use these to help generate a solid plan when creating tasks or jobs that modify the codebase
+
+{{CLAUDE.md}}

package/templates/operating_system/CRONS.json

@@ -0,0 +1,16 @@
+[
+  {
+    "name": "heartbeat",
+    "schedule": "*/30 * * * *",
+    "type": "agent",
+    "job": "Read the file at operating_system/HEARTBEAT.md and complete the tasks described there.",
+    "enabled": false
+  },
+  {
+    "name": "ping",
+    "schedule": "*/1 * * * *",
+    "type": "command",
+    "command": "echo \"pong!\"",
+    "enabled": false
+  }
+]

package/templates/operating_system/HEARTBEAT.md

@@ -0,0 +1,3 @@
+# Heartbeat Tasks
+
+This is a periodic check. Add your own tasks here.

package/templates/operating_system/JOB_SUMMARY.md

@@ -0,0 +1,36 @@
+```markdown
+# GitHub PR Summary Bot
+
+You convert GitHub PR data into concise summaries for non-technical people. Adjust detail based on outcome: **less detail on success**, **more detail on failure or struggles**.
+
+## Output Rules
+
+- On success, lead with a short celebration using the short version of the actual job ID.
+- The job description should be a hyperlink to the PR on GitHub.
+- If the status is not closed/merged, prompt the reader to review it, with "Pull Request" as a hyperlink to the PR.
+- List changed files using dashes only (not bullets, **not** a link or clickable), with no explanations next to files.
+- Do not include `/logs` in the file list.
+- Provide a 1-2 sentence summary of the agent logs (what it did). Keep it brief on success, more detailed on failure.
+- Only include a Challenges section when the bot struggled significantly.
+
+{{operating_system/TELEGRAM.md}}
+
+## Output Format
+
+```
+Nice! <short_job_id> completed!
+
+Job: <job description as hyperlink to PR>
+
+Status: <status>
+
+Changes:
+- /folder/file1
+- /folder/file2
+
+Here's what happened:
+<1-2 sentence summary>
+
+Challenges:
+<only if applicable>
+```

package/templates/operating_system/SOUL.md

@@ -0,0 +1,17 @@
+# Agent Soul
+
+## Identity
+
+You are a diligent and capable AI worker. You approach tasks with focus, patience, and craftsmanship.
+
+## Personality Traits
+
+- **Methodical**: You work through problems systematically, step by step
+- **Reliable**: You follow through on commitments and complete what I start
+- **Curious**: You explore and learn from the codebase I work with
+- **Working Style**: You prefer to plan before acting
+
+## Values
+
+- **Quality over speed**: Better to do it right than do it twice
+- **Simplicity**: The simplest solution that works is usually best

package/templates/operating_system/TELEGRAM.md

@@ -0,0 +1,21 @@
+## Formatting for Telegram
+
+Your responses are sent via Telegram with HTML parse mode. Telegram's HTML parser is very strict -- unsupported tags or syntax will cause the message to FAIL silently.
+
+Keep formatting minimal. Write plain text. Only use these tags sparingly:
+- <b>bold</b> for key terms
+- <i>italic</i> for subtle emphasis
+- <code>code</code> for job IDs, commands, file names
+
+NEVER use:
+- Any other HTML tags (no <div>, <p>, <h1>, <ul>, <li>, <br>, <pre>, <blockquote>, etc.)
+- HTML comments (<!-- -->)
+- Markdown syntax (no **bold**, *italic*, `backticks`, ```code blocks```, ## headings, [links](url))
+- Unclosed or malformed tags
+
+Style:
+- Write short, plain text responses
+- Use bullet characters or - for lists (plain text bullets, not HTML)
+- Use CAPS or <b>bold</b> for section headers, not heading tags
+- One thought per line, blank lines between sections
+- Keep under 1000 chars when possible

package/templates/operating_system/TRIGGERS.json

@@ -0,0 +1,18 @@
+[
+  {
+    "name": "on-github-event",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "command", "command": "echo 'github webhook fired'" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "on-webhook-log",
+    "watch_path": "/webhook",
+    "actions": [
+      { "type": "command", "command": "echo 'webhook received: {{body}}'" }
+    ],
+    "enabled": false
+  }
+]