thepopebot 1.2.75-beta.2 → 1.2.75-beta.21

package/templates/config/CRONS.json

@@ -1,56 +0,0 @@
-[
-  {
-    "name": "heartbeat",
-    "schedule": "*/30 * * * *",
-    "type": "agent",
-    "job": "Read the file at config/HEARTBEAT.md and complete the tasks described there.",
-    "enabled": false
-  },
-  {
-    "name": "daily-check",
-    "schedule": "0 9 * * *",
-    "type": "agent",
-    "job": "Check for dependency updates in package.json and report any outdated packages.",
-    "enabled": false
-  },
-  {
-    "name": "ping",
-    "schedule": "*/1 * * * *",
-    "type": "command",
-    "command": "echo \"pong!\"",
-    "enabled": true
-  },
-  {
-    "name": "cleanup-logs",
-    "schedule": "0 0 * * 0",
-    "type": "command",
-    "command": "ls -la logs/",
-    "enabled": false
-  },
-  {
-    "name": "ping-status",
-    "schedule": "*/5 * * * *",
-    "type": "webhook",
-    "url": "https://example.com/status",
-    "method": "POST",
-    "vars": { "source": "heartbeat" },
-    "enabled": false
-  },
-  {
-    "name": "health-check",
-    "schedule": "*/10 * * * *",
-    "type": "webhook",
-    "url": "https://example.com/health",
-    "method": "GET",
-    "enabled": false
-  },
-  {
-    "name": "daily-check-openai",
-    "schedule": "0 9 * * *",
-    "type": "agent",
-    "job": "Check for dependency updates in package.json and report any outdated packages.",
-    "llm_provider": "openai",
-    "llm_model": "gpt-4o",
-    "enabled": false
-  }
-]

package/templates/config/agent-job/AGENT_JOB.md

@@ -1,30 +0,0 @@
-# thepopebot Agent Environment
-
-**This document describes what you are and your operating environment**
-
----
-
-## 1. What You Are
-
-You are **thepopebot**, 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
-
-### WORKDIR — `/job` is a git repo
-
-Your working directory is `/job`. **This is a live git repository.** When your job finishes, everything inside `/job` is automatically committed and pushed via `git add -A`. You do not control this — it happens after you exit.
-
-This means: **any file you create, copy, move, or download into `/job` or any subdirectory of `/job` WILL be committed to the repository.** There are no exceptions.
-
-### All working files go in `/tmp`
-
-**NEVER save, copy, move, or download files into `/job`** unless the job specifically requires changing the repository (e.g. editing source code, updating config files).
-
-Use `/tmp` for everything else — downloads, generated files, images, videos, scripts, intermediate data, API responses, anything you create to get the job done. `/tmp` is outside the repo and nothing there gets committed.
-
-If a skill or tool downloads a file to `/tmp`, **leave it there**. Do not copy or move it into `/job`. If you need to pass that file to another tool (e.g. uploading it somewhere), reference it directly from `/tmp`.
-
-Current datetime: {{datetime}}

package/templates/cron/CLAUDE.md.template

@@ -1,24 +0,0 @@
-# cron/ — Cron Action Scripts
-
-This directory holds scripts referenced by `command`-type entries in `config/CRONS.json`.
-
-When a `command`-type cron fires, the working directory is `cron/`.
-
-## Example
-
-In `config/CRONS.json`:
-```json
-{
-  "name": "Daily Cleanup",
-  "schedule": "0 3 * * *",
-  "type": "command",
-  "command": "node cleanup.js --older-than 7d",
-  "enabled": true
-}
-```
-
-This runs `cron/cleanup.js` daily at 3am.
-
-## Action Types
-
-Most cron entries use `type: "agent"` (the default) which spins up a Docker agent — those don't need scripts here. Only `command`-type entries reference scripts in this directory. See `config/CRONS.json` for the full cron configuration and the root `CLAUDE.md` for all action type details.

package/templates/docker-compose.litellm.yml

@@ -1,82 +0,0 @@
-# Docker Compose configuration with LiteLLM proxy
-# To activate: set COMPOSE_FILE=docker-compose.litellm.yml in .env
-
-services:
-  traefik:
-    image: traefik:v3
-    command:
-      - --providers.docker=true
-      - --providers.docker.exposedByDefault=false
-      - --entrypoints.web.address=:80
-      - --entrypoints.websecure.address=:443
-      ## Uncomment the following lines to enable TLS via Let's Encrypt
-      ## (requires LETSENCRYPT_EMAIL in .env):
-      # - --entrypoints.web.http.redirections.entrypoint.to=websecure
-      # - --entrypoints.web.http.redirections.entrypoint.scheme=https
-      # - --certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}
-      # - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
-      # - --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - traefik_certs:/letsencrypt
-    restart: unless-stopped
-
-  event-handler:
-    container_name: thepopebot-event-handler
-    image: ${EVENT_HANDLER_IMAGE_URL:-stephengpope/thepopebot:event-handler-${THEPOPEBOT_VERSION:-latest}}
-    volumes:
-      - .:/project
-      - ./config:/app/config
-      - ./skills:/app/skills
-      - ./.env:/app/.env
-      - ./data:/app/data
-      - ./logs:/app/logs
-      - ./cron:/app/cron
-      - ./triggers:/app/triggers
-      - ./CLAUDE.md:/app/CLAUDE.md
-      - /var/run/docker.sock:/var/run/docker.sock
-    labels:
-      - traefik.enable=true
-      # Set APP_HOSTNAME in .env to the domain from APP_URL (e.g., mybot.example.com)
-      - traefik.http.routers.event-handler.rule=Host(`${APP_HOSTNAME}`)
-      - traefik.http.routers.event-handler.entrypoints=web
-      - traefik.http.services.event-handler.loadbalancer.server.port=80
-      ## Uncomment the following lines to enable TLS via Let's Encrypt:
-      # - traefik.http.routers.event-handler.entrypoints=websecure
-      # - traefik.http.routers.event-handler.tls.certresolver=letsencrypt
-    stop_grace_period: 120s
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:80/api/ping"]
-      interval: 10s
-      timeout: 3s
-      retries: 3
-      start_period: 30s
-    restart: unless-stopped
-
-  runner:
-    image: myoung34/github-runner:latest
-    deploy:
-      replicas: ${RUNNER_REPLICAS:-1}
-    environment:
-      REPO_URL: https://github.com/${GH_OWNER}/${GH_REPO}
-      ACCESS_TOKEN: ${GH_TOKEN}
-      RUNNER_SCOPE: repo
-      LABELS: self-hosted
-      EPHEMERAL: "1"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - .:/project
-    restart: unless-stopped
-
-  litellm:
-    image: ghcr.io/berriai/litellm:main-latest
-    command: --config /litellm/main.yaml --port 4000
-    volumes:
-      - ./config/litellm:/litellm:ro
-    restart: unless-stopped
-
-volumes:
-  traefik_certs:

package/templates/docs/CLAUDE.md.template

@@ -1,12 +0,0 @@
-# docs/ — User Documentation
-
-| Document | Description |
-|----------|-------------|
-| `GETTING_STARTED.md` | Initial setup and first-run walkthrough |
-| `CONFIGURATION.md` | Config file reference and customization guide |
-| `CRONS_AND_TRIGGERS.md` | Scheduling jobs and setting up webhook triggers |
-| `SKILLS.md` | Building, activating, and managing agent skills |
-| `CLUSTERS.md` | Multi-role agent teams and cluster workspaces |
-| `CLI.md` | Command-line interface reference |
-| `SECURITY.md` | Authentication, API keys, and secret management |
-| `UPGRADING.md` | How to upgrade thepopebot to a new version |

package/templates/docs/CLI.md

@@ -1,59 +0,0 @@
-# CLI Reference
-
-All commands are run via `npx thepopebot <command>`.
-
-## Project Setup
-
-| Command | Description |
-|---------|-------------|
-| `init` | Scaffold a new project, or update templates in an existing one |
-| `setup` | Run the full interactive setup wizard (`npm run setup`) |
-| `setup-telegram` | Reconfigure the Telegram webhook (`npm run setup-telegram`) |
-| `reset-auth` | Regenerate AUTH_SECRET, invalidating all sessions |
-
-## Templates
-
-| Command | Description |
-|---------|-------------|
-| `diff [file]` | List files that differ from package templates, or diff a specific file |
-| `reset [file]` | List all template files, or restore a specific one to package default |
-| `upgrade` / `update` | Upgrade thepopebot (install, init, build, commit, push, restart Docker) |
-| `sync <path>` | Sync local package to a test install (dev workflow) |
-| `user:password <email>` | Change a user's password |
-
-## Secrets and Variables
-
-These set GitHub repository secrets/variables using the `gh` CLI. They read `GH_OWNER` and `GH_REPO` from your `.env`. If VALUE is omitted, you'll be prompted with masked input.
-
-| Command | Description |
-|---------|-------------|
-| `set-var KEY [VALUE]` | Set a GitHub repository variable |
-
-Agent job secrets are now managed through the admin UI (Settings > Agent Jobs > Secrets), stored encrypted in SQLite, and injected directly into Docker containers.
-
-## Common Workflows
-
-### Initial setup
-```bash
-npx thepopebot init
-npm run setup
-```
-
-### Upgrade to latest version
-```bash
-npx thepopebot upgrade
-```
-
-### Check what changed in templates
-```bash
-npx thepopebot diff                    # list all differing files
-npx thepopebot diff config/CRONS.json  # see specific changes
-npx thepopebot reset config/CRONS.json # accept new template
-```
-
-### Set up a new LLM provider for jobs
-```bash
-npx thepopebot set-var LLM_PROVIDER openai
-npx thepopebot set-var LLM_MODEL gpt-4o
-# Set API keys via admin UI: Settings > Agent Jobs > Secrets
-```

package/templates/docs/CLUSTERS.md

@@ -1,151 +0,0 @@
-# Cluster Workspaces
-
-Clusters are multi-role agent teams. Define a set of roles, each with its own prompt and trigger configuration, and the system launches ephemeral Docker containers to execute them. Roles within a cluster share a workspace directory for collaboration.
-
----
-
-## Creating a Cluster
-
-Create clusters from the web UI at `/clusters`. Each cluster has:
-
-- **Name** — Display label
-- **System Prompt** — Shared context for all roles. Defaults to `config/cluster/SYSTEM.md`
-- **Shared Folders** — Named subdirectories under `shared/` that all roles can access (e.g., `docs`, `output`)
-- **Enabled/Disabled** — Toggle the cluster. Disabling stops all running containers
-
----
-
-## Defining Roles
-
-Each role represents one agent type within a cluster:
-
-| Field | Description |
-|-------|-------------|
-| **Role Name** | Display name (e.g., "Researcher", "Writer") |
-| **Role Instructions** | Markdown prompt for the role. Defaults to `config/cluster/ROLE.md` |
-| **Prompt** | Task prompt passed to the agent (default: "Execute your role.") |
-| **Max Concurrency** | Max simultaneous containers for this role (default: 1) |
-| **Trigger Config** | How this role gets activated (see below) |
-| **Folders** | Role-specific subdirectories |
-| **Cleanup Worker Dir** | Delete the ephemeral worker directory after container exits |
-
-### Template Variables
-
-System and role prompts support `{{PLACEHOLDER}}` variables resolved at launch:
-
-| Variable | Value |
-|----------|-------|
-| `{{CLUSTER_HOME}}` | Container workspace root |
-| `{{CLUSTER_SHARED_DIR}}` | Path to cluster shared directory |
-| `{{CLUSTER_SHARED_FOLDERS}}` | JSON array of shared folder paths |
-| `{{SELF_ROLE_NAME}}` | This role's name |
-| `{{SELF_WORKER_ID}}` | Unique ID for this worker instance |
-| `{{SELF_WORK_DIR}}` | This worker's ephemeral working directory |
-| `{{SELF_TMP_DIR}}` | This worker's temp directory |
-| `{{WORKSPACE}}` | JSON manifest of the full workspace layout |
-| `{{DATETIME}}` | ISO timestamp at launch time |
-| `{{WEBHOOK_PAYLOAD}}` | JSON payload from a webhook trigger |
-
----
-
-## Trigger Types
-
-Each role can have multiple triggers. All triggers respect the role's concurrency limit.
-
-### Manual
-
-Always available. Click the run button in the UI.
-
-### Webhook
-
-Send a POST request to trigger execution:
-
-```
-POST /api/cluster/{clusterId}/role/{roleId}/webhook
-Header: x-api-key: YOUR_API_KEY
-Body: { "key": "value" }
-```
-
-The request body is available as `{{WEBHOOK_PAYLOAD}}`. Include a `prompt` field in the body to override the role's default prompt.
-
-### Cron
-
-Schedule recurring runs with a cron expression:
-
-```json
-{
-  "cron": {
-    "enabled": true,
-    "schedule": "0 */6 * * *"
-  }
-}
-```
-
-### File Watch
-
-Trigger when files change in the cluster's data directory:
-
-```json
-{
-  "file_watch": {
-    "enabled": true,
-    "paths": "shared/input,shared/data"
-  }
-}
-```
-
-Paths are comma-separated, relative to the cluster data directory. Changes are debounced (5-second window). The `logs/` directory is always excluded.
-
----
-
-## Directory Structure
-
-Each cluster gets a data directory on disk:
-
-```
-data/clusters/
-  cluster-{shortId}/
-    shared/                       # Cluster-wide shared directory
-      docs/                       # Shared folder
-      output/                     # Shared folder
-    role-{roleShortId}/
-      shared/                     # Role-specific shared directory
-      worker-{uuid}/              # Ephemeral per-container directory
-        tmp/                      # Worker temp directory
-    logs/
-      role-{roleShortId}/
-        2025-01-15_14-30-00_{uuid}/
-          system-prompt.md        # Resolved system prompt
-          user-prompt.md          # Resolved user prompt
-          meta.json               # Run metadata
-          trigger.json            # Trigger info and payload
-          stdout.jsonl            # Container stdout
-          stderr.txt              # Container stderr
-```
-
----
-
-## Concurrency
-
-Each role has a `maxConcurrency` setting (default: 1). Before any trigger launches a container, the system checks the running container count. If at or above the limit, the trigger is rejected.
-
-Set higher concurrency for roles that handle parallel workloads (e.g., webhook-triggered processing). Keep at 1 for sequential roles.
-
----
-
-## Console and Logs
-
-The cluster console page at `/clusters` provides:
-
-- **Container status** per role — running, idle, or stopped
-- **Resource usage** — CPU, memory, and network stats
-- **Live logs** — streaming stdout and stderr
-- **Prompts** — view resolved system and user prompts for any worker
-
-Historical logs are available grouped by role, including stdout, stderr, prompts, and trigger info.
-
----
-
-## Customizing Prompts
-
-Edit `config/cluster/SYSTEM.md` and `config/cluster/ROLE.md` to set defaults for new clusters and roles. Existing clusters keep their current prompts — these templates only affect newly created clusters and roles.

package/templates/docs/CONFIGURATION.md

@@ -1,181 +0,0 @@
-# Configuration
-
-## Config Files
-
-The `config/` directory defines your agent's personality and behavior:
-
-| File | Purpose |
-|------|---------|
-| `agent-chat/SYSTEM.md` | Agent chat system prompt |
-| `code-chat/SYSTEM.md` | Code workspace planning system prompt |
-| `agent-job/SOUL.md` | Agent identity, personality traits, and values |
-| `agent-job/AGENT_JOB.md` | Agent runtime environment docs |
-| `agent-job/SUMMARY.md` | Prompt for summarizing completed jobs |
-| `cluster/SYSTEM.md` | System prompt for cluster worker agents |
-| `cluster/ROLE.md` | Per-role prompt template for cluster workers |
-| `HEARTBEAT.md` | Self-monitoring behavior |
-| `CRONS.json` | Scheduled job definitions |
-| `TRIGGERS.json` | Webhook trigger definitions |
-
-### Markdown Includes and Variables
-
-Config markdown files support includes and built-in variables (processed by the package's `render-md.js`):
-
-| Syntax | Description |
-|--------|-------------|
-| `{{ filepath.md }}` | Include another file (relative to project root, recursive with circular detection) |
-| `{{datetime}}` | Current ISO timestamp |
-| `{{skills}}` | Dynamic bullet list of active skill descriptions from `skills/active/*/SKILL.md` frontmatter |
-
----
-
-## Environment Variables
-
-Set in `.env` in your project root. These configure the **Event Handler** (web chat, Telegram, webhooks, job summaries).
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `APP_URL` | Public URL for webhooks and Telegram | Yes |
-| `AUTH_SECRET` | NextAuth session encryption (auto-generated) | Yes |
-| `GH_TOKEN` | GitHub PAT for creating branches/files | Yes |
-| `GH_OWNER` | GitHub repository owner | Yes |
-| `GH_REPO` | GitHub repository name | Yes |
-| `TELEGRAM_BOT_TOKEN` | Telegram bot token | For Telegram |
-| `TELEGRAM_WEBHOOK_SECRET` | Telegram webhook validation secret | No |
-| `TELEGRAM_CHAT_ID` | Default chat ID for notifications | For Telegram |
-| `GH_WEBHOOK_SECRET` | GitHub Actions webhook auth | For notifications |
-| `LLM_PROVIDER` | `anthropic`, `openai`, `google`, or `custom` | No (default: `anthropic`) |
-| `LLM_MODEL` | Model name override | No |
-| `LLM_MAX_TOKENS` | Max tokens for LLM responses | No (default: 4096) |
-| `ANTHROPIC_API_KEY` | Anthropic API key | For anthropic provider |
-| `OPENAI_API_KEY` | OpenAI API key / Whisper | For openai provider |
-| `CUSTOM_OPENAI_BASE_URL` | Custom OpenAI-compatible base URL | For custom provider |
-| `GOOGLE_API_KEY` | Google API key | For google provider |
-| `CUSTOM_API_KEY` | Custom provider API key | For custom provider |
-| `AGENT_BACKEND` | Agent runner: `pi` or `claude-code` | No (default: `claude-code`) |
-| `ASSEMBLYAI_API_KEY` | API key for voice transcription | For voice input |
-| `DATABASE_PATH` | Override SQLite DB location | No |
-| `COMPOSE_FILE` | Override docker-compose file | No |
-
----
-
-## LLM Providers
-
-thepopebot has **two independent LLM configurations**:
-
-- **Event Handler** (chat, Telegram, webhooks, summaries) — configured via `.env`
-- **Jobs** (Docker agent on GitHub Actions) — configured via GitHub repo variables
-
-You can run different models for each. For example, Claude for interactive chat and a local Ollama model for jobs.
-
-| Provider | Example model | API key env var |
-|----------|---------------|-----------------|
-| `anthropic` (default) | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` |
-| `openai` | `gpt-4o` | `OPENAI_API_KEY` |
-| `google` | `gemini-2.5-pro` | `GOOGLE_API_KEY` |
-| `custom` | Any OpenAI-compatible API | `CUSTOM_API_KEY` + `CUSTOM_OPENAI_BASE_URL` |
-
-### Setting the Event Handler Model
-
-```bash
-# In .env
-LLM_PROVIDER=anthropic
-LLM_MODEL=claude-sonnet-4-20250514
-ANTHROPIC_API_KEY=sk-ant-...
-```
-
-Restart your server after changes.
-
-### Setting the Default Job Model
-
-```bash
-npx thepopebot set-var LLM_PROVIDER openai
-npx thepopebot set-var LLM_MODEL gpt-4o
-# Set API keys via admin UI: Settings > Agent Jobs > Secrets
-```
-
-### Per-Job Overrides
-
-Add `llm_provider` and `llm_model` to any agent-type entry in `CRONS.json` or `TRIGGERS.json`:
-
-```json
-{
-  "name": "Code review",
-  "schedule": "0 9 * * 1",
-  "type": "agent",
-  "job": "Review open PRs",
-  "llm_provider": "openai",
-  "llm_model": "gpt-4o"
-}
-```
-
-### Using the `custom` Provider
-
-Point at any OpenAI-compatible endpoint (DeepSeek, Ollama, Together AI, etc.):
-
-```bash
-# Cloud custom (DeepSeek, Together AI, etc.)
-npx thepopebot set-var LLM_PROVIDER custom
-npx thepopebot set-var LLM_MODEL deepseek-chat
-npx thepopebot set-var CUSTOM_OPENAI_BASE_URL https://api.deepseek.com/v1
-# Set CUSTOM_API_KEY via admin UI: Settings > Agent Jobs > Secrets
-
-# Local custom (Ollama, LM Studio, etc.) — needs self-hosted runner
-npx thepopebot set-var RUNS_ON self-hosted
-npx thepopebot set-var LLM_PROVIDER custom
-npx thepopebot set-var LLM_MODEL qwen3:8b
-npx thepopebot set-var CUSTOM_OPENAI_BASE_URL http://host.docker.internal:11434/v1
-```
-
----
-
-## Agent Job Secrets
-
-Agent job secrets are managed through the admin UI (Settings > Agent Jobs > Secrets). They are stored encrypted in SQLite and injected as env vars into Docker containers. The agent can discover available secrets via the `get-secret` skill.
-
----
-
-## GitHub Repository Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `APP_URL` | Public URL for the event handler | Required |
-| `AUTO_MERGE` | Set to `"false"` to disable auto-merge | Enabled |
-| `ALLOWED_PATHS` | Comma-separated path prefixes for auto-merge | `/logs` |
-| `JOB_IMAGE_URL` | Docker image for job agent | Default thepopebot image |
-| `EVENT_HANDLER_IMAGE_URL` | Docker image for event handler | Default thepopebot image |
-| `RUNS_ON` | GitHub Actions runner label | `ubuntu-latest` |
-| `LLM_PROVIDER` | LLM provider for Docker agent | `anthropic` |
-| `LLM_MODEL` | LLM model name for Docker agent | Provider default |
-| `AGENT_BACKEND` | Agent runner: `pi` or `claude-code` | `claude-code` |
-
----
-
-## GitHub PAT Permissions
-
-Create a fine-grained PAT scoped to your repository:
-
-| Permission | Access | Why |
-|------------|--------|-----|
-| Actions | Read and write | Trigger and monitor workflows |
-| Administration | Read and write | Required for self-hosted runners |
-| Contents | Read and write | Create branches, commit files |
-| Metadata | Read-only | Required (auto-selected) |
-| Pull requests | Read and write | Create and manage PRs |
-| Secrets | Read and write | Manage agent secrets from web UI |
-| Workflows | Read and write | Create and update workflow files |
-
----
-
-## Docker Compose
-
-For self-hosted deployment:
-
-```bash
-npm run build
-docker compose up -d
-```
-
-This starts Traefik (reverse proxy with SSL), the Event Handler (Node.js + PM2), and a self-hosted GitHub Actions runner.
-
-To customize Docker Compose without losing changes on upgrade, set `COMPOSE_FILE=docker-compose.custom.yml` in `.env`. The custom file is scaffolded by init but never overwritten.