thepopebot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen G. Pope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# thepopebot
+
+**Autonomous AI agents. All the power. None of the leaked API keys.**
+
+---
+
+## Why thepopebot?
+
+**Secure by default** — Other frameworks hand credentials to the LLM and hope for the best. thepopebot is different: the AI literally cannot access your secrets, even if it tries. Secrets are filtered at the process level before the agent's shell even starts.
+
+**The repository IS the agent** — Every action your agent takes is a git commit. You can see exactly what it did, when, and why. If it screws up, revert it. Want to clone your agent? Fork the repo — code, personality, scheduled jobs, full history, all of it goes with your fork.
+
+**Free compute, built in** — Every GitHub account comes with free cloud computing time. thepopebot uses that to run your agent. One task or a hundred in parallel — the compute is already included.
+
+**Self-evolving** — The agent modifies its own code through pull requests. Every change is auditable, every change is reversible. You stay in control.
+
+---
+
+## How It Works
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│                                                                       │
+│  ┌─────────────────┐         ┌─────────────────┐                     │
+│  │  Event Handler  │ ──1──►  │     GitHub      │                     │
+│  │  (creates job)  │         │ (job/* branch)  │                     │
+│  └────────▲────────┘         └────────┬────────┘                     │
+│           │                           │                              │
+│           │                           2 (triggers run-job.yml)    │
+│           │                           │                              │
+│           │                           ▼                              │
+│           │                  ┌─────────────────┐                     │
+│           │                  │  Docker Agent   │                     │
+│           │                  │  (runs Pi, PRs) │                     │
+│           │                  └────────┬────────┘                     │
+│           │                           │                              │
+│           │                           3 (creates PR)                 │
+│           │                           │                              │
+│           │                           ▼                              │
+│           │                  ┌─────────────────┐                     │
+│           │                  │     GitHub      │                     │
+│           │                  │   (PR opened)   │                     │
+│           │                  └────────┬────────┘                     │
+│           │                           │                              │
+│           │                           4a (auto-merge.yml)            │
+│           │                           4b (update-event-handler.yml)  │
+│           │                           │                              │
+│           5 (Telegram notification)   │                              │
+│           └───────────────────────────┘                              │
+│                                                                       │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+You talk to your bot on Telegram (or hit a webhook). The Event Handler creates a job branch. GitHub Actions spins up a Docker container with the Pi coding agent. The agent does the work, commits the results, and opens a PR. Auto-merge handles the rest. You get a Telegram notification when it's done.
+
+---
+
+## Get FREE server time on Github!
+
+| | thepopebot | Other platforms |
+|---|---|---|
+| **Public repos** | Free. $0. GitHub Actions doesn't charge. | $20-100+/month |
+| **Private repos** | 2,000 free minutes/month (every GitHub plan, including free) | $20-100+/month |
+| **Infrastructure** | GitHub Actions (already included) | Dedicated servers |
+
+You just bring your own [Anthropic API key](https://console.anthropic.com/).
+
+---
+
+## Get Started
+
+### Prerequisites
+
+| Requirement | Install |
+|-------------|---------|
+| **Node.js 18+** | [nodejs.org](https://nodejs.org) |
+| **npm** | Included with Node.js |
+| **Git** | [git-scm.com](https://git-scm.com) |
+| **GitHub CLI** | [cli.github.com](https://cli.github.com) |
+| **ngrok*** | [ngrok.com](https://ngrok.com/download) |
+
+*\*ngrok is only required for local development. Production deployments don't need it.*
+
+### Three steps
+
+**Step 1** — Fork this repository:
+
+[![Fork this repo](https://img.shields.io/badge/Fork_this_repo-238636?style=for-the-badge&logo=github&logoColor=white)](https://github.com/stephengpope/thepopebot/fork)
+
+> GitHub Actions are disabled by default on forks. Go to the **Actions** tab in your fork and enable them.
+
+**Step 2** — Clone your fork:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/thepopebot.git
+cd thepopebot
+```
+
+**Step 3** — Run the setup wizard:
+
+```bash
+npm run setup
+```
+
+The wizard handles everything:
+- Checks prerequisites (Node.js, Git, GitHub CLI, ngrok)
+- Creates a GitHub Personal Access Token
+- Collects API keys (Anthropic required; OpenAI, Groq, and [Brave Search](https://api-dashboard.search.brave.com/app/keys) optional)
+- Sets GitHub repository secrets and variables
+- Sets up Telegram bot
+- Starts the server + ngrok, generates `event_handler/.env`
+- Registers webhooks and verifies everything works
+
+**After setup, message your Telegram bot to create jobs!**
+
+---
+
+## Docs
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/ARCHITECTURE.md) | Two-layer design, file structure, API endpoints, GitHub Actions, Docker agent |
+| [Configuration](docs/CONFIGURATION.md) | Environment variables, GitHub secrets, repo variables, ngrok, Telegram setup |
+| [Customization](docs/CUSTOMIZATION.md) | Personality, skills, operating system files, using your bot, security details |
+| [Auto-Merge](docs/AUTO_MERGE.md) | Auto-merge controls, ALLOWED_PATHS configuration |
+| [How to Use Pi](docs/HOW_TO_USE_PI.md) | Guide to the Pi coding agent |
+| [Security](docs/SECURITY_TODO.md) | Security hardening plan |

package/api/index.js

@@ -0,0 +1,357 @@
+const paths = require('../lib/paths');
+const { render_md } = require('../lib/utils/render-md');
+const { createJob } = require('../lib/tools/create-job');
+const { setWebhook, sendMessage, downloadFile, reactToMessage, startTypingIndicator } = require('../lib/tools/telegram');
+const { isWhisperEnabled, transcribeAudio } = require('../lib/tools/openai');
+const { chat, getApiKey } = require('../lib/claude');
+const { toolDefinitions, toolExecutors } = require('../lib/claude/tools');
+const { getHistory, updateHistory } = require('../lib/claude/conversation');
+const { getJobStatus } = require('../lib/tools/github');
+
+// Bot token from env, can be overridden by /telegram/register
+let telegramBotToken = null;
+
+// Cached trigger firing function (initialized on first request)
+let _fireTriggers = null;
+
+function getTelegramBotToken() {
+  if (!telegramBotToken) {
+    telegramBotToken = process.env.TELEGRAM_BOT_TOKEN || null;
+  }
+  return telegramBotToken;
+}
+
+function getFireTriggers() {
+  if (!_fireTriggers) {
+    const { loadTriggers } = require('../lib/triggers');
+    const result = loadTriggers();
+    _fireTriggers = result.fireTriggers;
+  }
+  return _fireTriggers;
+}
+
+// Routes that have their own authentication
+const PUBLIC_ROUTES = ['/telegram/webhook', '/github/webhook'];
+
+/**
+ * Check API key authentication
+ * @param {string} routePath - The route path
+ * @param {Request} request - The incoming request
+ * @returns {Response|null} - Error response if unauthorized, null if OK
+ */
+function checkAuth(routePath, request) {
+  if (PUBLIC_ROUTES.includes(routePath)) return null;
+
+  const apiKey = request.headers.get('x-api-key');
+  if (apiKey !== process.env.API_KEY) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  return null;
+}
+
+/**
+ * Extract job ID from branch name (e.g., "job/abc123" -> "abc123")
+ */
+function extractJobId(branchName) {
+  if (!branchName || !branchName.startsWith('job/')) return null;
+  return branchName.slice(4);
+}
+
+/**
+ * Summarize a completed job using Claude
+ * @param {Object} results - Job results from webhook payload
+ * @returns {Promise<string>} The message to send to Telegram
+ */
+async function summarizeJob(results) {
+  try {
+    const apiKey = getApiKey();
+
+    // System prompt from JOB_SUMMARY.md (supports {{includes}})
+    const systemPrompt = render_md(paths.jobSummaryMd);
+
+    // User message: structured job results
+    const userMessage = [
+      results.job ? `## Task\n${results.job}` : '',
+      results.commit_message ? `## Commit Message\n${results.commit_message}` : '',
+      results.changed_files?.length ? `## Changed Files\n${results.changed_files.join('\n')}` : '',
+      results.pr_status ? `## PR Status\n${results.pr_status}` : '',
+      results.merge_result ? `## Merge Result\n${results.merge_result}` : '',
+      results.pr_url ? `## PR URL\n${results.pr_url}` : '',
+      results.log ? `## Agent Log\n${results.log}` : '',
+    ].filter(Boolean).join('\n\n');
+
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: process.env.EVENT_HANDLER_MODEL || 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: userMessage }],
+      }),
+    });
+
+    if (!response.ok) throw new Error(`Claude API error: ${response.status}`);
+
+    const result = await response.json();
+    return (result.content?.[0]?.text || '').trim() || 'Job completed.';
+  } catch (err) {
+    console.error('Failed to summarize job:', err);
+    return 'Job completed.';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Route handlers
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function handleWebhook(request) {
+  const body = await request.json();
+  const { job } = body;
+  if (!job) return Response.json({ error: 'Missing job field' }, { status: 400 });
+
+  try {
+    const result = await createJob(job);
+    return Response.json(result);
+  } catch (err) {
+    console.error(err);
+    return Response.json({ error: 'Failed to create job' }, { status: 500 });
+  }
+}
+
+async function handleTelegramRegister(request) {
+  const body = await request.json();
+  const { bot_token, webhook_url } = body;
+  if (!bot_token || !webhook_url) {
+    return Response.json({ error: 'Missing bot_token or webhook_url' }, { status: 400 });
+  }
+
+  try {
+    const result = await setWebhook(bot_token, webhook_url, process.env.TELEGRAM_WEBHOOK_SECRET);
+    telegramBotToken = bot_token;
+    return Response.json({ success: true, result });
+  } catch (err) {
+    console.error(err);
+    return Response.json({ error: 'Failed to register webhook' }, { status: 500 });
+  }
+}
+
+async function handleTelegramWebhook(request) {
+  const { TELEGRAM_WEBHOOK_SECRET, TELEGRAM_CHAT_ID, TELEGRAM_VERIFICATION } = process.env;
+  const botToken = getTelegramBotToken();
+
+  // Validate secret token if configured
+  // Always return 200 to prevent Telegram retry loops on mismatch
+  if (TELEGRAM_WEBHOOK_SECRET) {
+    const headerSecret = request.headers.get('x-telegram-bot-api-secret-token');
+    if (headerSecret !== TELEGRAM_WEBHOOK_SECRET) {
+      return Response.json({ ok: true });
+    }
+  }
+
+  const update = await request.json();
+  const message = update.message || update.edited_message;
+
+  if (message && message.chat && botToken) {
+    const chatId = String(message.chat.id);
+
+    let messageText = null;
+
+    if (message.text) {
+      messageText = message.text;
+    }
+
+    // Check for verification code - this works even before TELEGRAM_CHAT_ID is set
+    if (TELEGRAM_VERIFICATION && messageText === TELEGRAM_VERIFICATION) {
+      await sendMessage(botToken, chatId, `Your chat ID:\n<code>${chatId}</code>`);
+      return Response.json({ ok: true });
+    }
+
+    // Security: if no TELEGRAM_CHAT_ID configured, ignore all messages (except verification above)
+    if (!TELEGRAM_CHAT_ID) {
+      return Response.json({ ok: true });
+    }
+
+    // Security: only accept messages from configured chat
+    if (chatId !== TELEGRAM_CHAT_ID) {
+      return Response.json({ ok: true });
+    }
+
+    // Acknowledge receipt with a thumbs up (await so it completes before typing indicator starts)
+    await reactToMessage(botToken, chatId, message.message_id).catch(() => {});
+
+    if (message.voice) {
+      // Handle voice messages
+      if (!isWhisperEnabled()) {
+        await sendMessage(botToken, chatId, 'Voice messages are not supported. Please set OPENAI_API_KEY to enable transcription.');
+        return Response.json({ ok: true });
+      }
+
+      try {
+        const { buffer, filename } = await downloadFile(botToken, message.voice.file_id);
+        messageText = await transcribeAudio(buffer, filename);
+      } catch (err) {
+        console.error('Failed to transcribe voice:', err);
+        await sendMessage(botToken, chatId, 'Sorry, I could not transcribe your voice message.');
+        return Response.json({ ok: true });
+      }
+    }
+
+    if (messageText) {
+      // Process message asynchronously (don't block the response)
+      processMessage(botToken, chatId, messageText).catch(err => {
+        console.error('Failed to process message:', err);
+      });
+    }
+  }
+
+  return Response.json({ ok: true });
+}
+
+/**
+ * Process a Telegram message with Claude (async, non-blocking)
+ */
+async function processMessage(botToken, chatId, messageText) {
+  const stopTyping = startTypingIndicator(botToken, chatId);
+  try {
+    // Get conversation history and process with Claude
+    const history = getHistory(chatId);
+    const { response, history: newHistory } = await chat(
+      messageText,
+      history,
+      toolDefinitions,
+      toolExecutors
+    );
+    updateHistory(chatId, newHistory);
+
+    // Send response (auto-splits if needed)
+    await sendMessage(botToken, chatId, response);
+  } catch (err) {
+    console.error('Failed to process message with Claude:', err);
+    await sendMessage(botToken, chatId, 'Sorry, I encountered an error processing your message.').catch(() => {});
+  } finally {
+    stopTyping();
+  }
+}
+
+async function handleGithubWebhook(request) {
+  const { GH_WEBHOOK_SECRET, TELEGRAM_CHAT_ID } = process.env;
+  const botToken = getTelegramBotToken();
+
+  // Validate webhook secret
+  if (GH_WEBHOOK_SECRET) {
+    const headerSecret = request.headers.get('x-github-webhook-secret-token');
+    if (headerSecret !== GH_WEBHOOK_SECRET) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  }
+
+  const event = request.headers.get('x-github-event');
+  const payload = await request.json();
+
+  if (event !== 'pull_request') {
+    return Response.json({ ok: true, skipped: true });
+  }
+
+  const pr = payload.pull_request;
+  if (!pr) return Response.json({ ok: true, skipped: true });
+
+  const branchName = pr.head?.ref;
+  const jobId = extractJobId(branchName);
+  if (!jobId) return Response.json({ ok: true, skipped: true, reason: 'not a job branch' });
+
+  if (!TELEGRAM_CHAT_ID || !botToken) {
+    console.log(`Job ${jobId} completed but no chat ID to notify`);
+    return Response.json({ ok: true, skipped: true, reason: 'no chat to notify' });
+  }
+
+  try {
+    // All job data comes from the webhook payload — no GitHub API calls needed
+    const results = payload.job_results || {};
+    results.pr_url = pr.html_url;
+
+    const message = await summarizeJob(results);
+
+    await sendMessage(botToken, TELEGRAM_CHAT_ID, message);
+
+    // Add the summary to chat memory so Claude has context in future conversations
+    const history = getHistory(TELEGRAM_CHAT_ID);
+    history.push({ role: 'assistant', content: message });
+    updateHistory(TELEGRAM_CHAT_ID, history);
+
+    console.log(`Notified chat ${TELEGRAM_CHAT_ID} about job ${jobId.slice(0, 8)}`);
+
+    return Response.json({ ok: true, notified: true });
+  } catch (err) {
+    console.error('Failed to process GitHub webhook:', err);
+    return Response.json({ error: 'Failed to process webhook' }, { status: 500 });
+  }
+}
+
+async function handleJobStatus(request) {
+  try {
+    const url = new URL(request.url);
+    const jobId = url.searchParams.get('job_id');
+    const result = await getJobStatus(jobId);
+    return Response.json(result);
+  } catch (err) {
+    console.error('Failed to get job status:', err);
+    return Response.json({ error: 'Failed to get job status' }, { status: 500 });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Next.js Route Handlers (catch-all)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function POST(request) {
+  const url = new URL(request.url);
+  const routePath = url.pathname.replace(/^\/api/, '');
+
+  // Auth check
+  const authError = checkAuth(routePath, request);
+  if (authError) return authError;
+
+  // Fire triggers (non-blocking)
+  try {
+    const fireTriggers = getFireTriggers();
+    // Clone request to read body for triggers without consuming it for the handler
+    const clonedRequest = request.clone();
+    const body = await clonedRequest.json().catch(() => ({}));
+    const query = Object.fromEntries(url.searchParams);
+    const headers = Object.fromEntries(request.headers);
+    fireTriggers(routePath, body, query, headers);
+  } catch (e) {
+    // Trigger errors are non-fatal
+  }
+
+  // Route to handler
+  switch (routePath) {
+    case '/webhook':            return handleWebhook(request);
+    case '/telegram/webhook':   return handleTelegramWebhook(request);
+    case '/telegram/register':  return handleTelegramRegister(request);
+    case '/github/webhook':     return handleGithubWebhook(request);
+    default:                    return Response.json({ error: 'Not found' }, { status: 404 });
+  }
+}
+
+async function GET(request) {
+  const url = new URL(request.url);
+  const routePath = url.pathname.replace(/^\/api/, '');
+
+  // Auth check
+  const authError = checkAuth(routePath, request);
+  if (authError) return authError;
+
+  switch (routePath) {
+    case '/ping':         return Response.json({ message: 'Pong!' });
+    case '/jobs/status':  return handleJobStatus(request);
+    default:              return Response.json({ error: 'Not found' }, { status: 404 });
+  }
+}
+
+module.exports = { GET, POST };