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

package/templates/docs/CRONS_AND_TRIGGERS.md

@@ -1,132 +0,0 @@
-# Crons and Triggers
-
-## Action Types
-
-Both cron jobs and webhook triggers use the same dispatch system. Every action has a `type`:
-
-| | `agent` (default) | `command` | `webhook` |
-|---|---|---|---|
-| **Uses LLM** | Yes — spins up Docker agent | No | No |
-| **Runtime** | Minutes to hours | Milliseconds to seconds | Milliseconds to seconds |
-| **Cost** | LLM API calls + GitHub Actions | Free (runs on event handler) | Free (runs on event handler) |
-| **Use case** | Tasks that need to think | Shell scripts, file operations | Call external APIs |
-
-If it needs to *think*, use `agent`. If it just needs to *do*, use `command`. If it needs to *call an external service*, use `webhook`.
-
----
-
-## Cron Jobs
-
-Defined in `config/CRONS.json`, loaded at server startup.
-
-```json
-[
-  {
-    "name": "Daily Check",
-    "schedule": "0 9 * * *",
-    "type": "agent",
-    "job": "Review recent activity and summarize findings",
-    "enabled": true
-  },
-  {
-    "name": "Cleanup Logs",
-    "schedule": "0 0 * * 0",
-    "type": "command",
-    "command": "node cleanup.js --older-than 7d",
-    "enabled": false
-  }
-]
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Display name |
-| `schedule` | Yes | Cron expression (e.g., `0 9 * * *` = daily at 9am) |
-| `type` | No | `agent` (default), `command`, or `webhook` |
-| `job` | For agent | Task prompt passed to the LLM |
-| `command` | For command | Shell command (runs in `cron/` directory) |
-| `url` | For webhook | Target URL |
-| `method` | For webhook | `GET` or `POST` (default: `POST`) |
-| `headers` | For webhook | Custom request headers |
-| `vars` | For webhook | Key-value pairs merged into request body |
-| `enabled` | No | Set `false` to disable (default: `true`) |
-| `llm_provider` | No | Override LLM provider for this cron (agent type only) |
-| `llm_model` | No | Override LLM model for this cron (agent type only) |
-
-### Agent Action
-
-```json
-{ "type": "agent", "job": "Analyze the logs and write a summary report" }
-```
-
-Creates a Docker Agent job. The `job` string is the LLM's task prompt.
-
-### Command Action
-
-```json
-{ "type": "command", "command": "node cleanup.js --older-than 7d" }
-```
-
-Runs a shell command on the event handler. Working directory: `cron/` for crons, `triggers/` for triggers. Put your scripts in those directories.
-
-### Webhook Action
-
-```json
-{
-  "type": "webhook",
-  "url": "https://api.example.com/notify",
-  "method": "POST",
-  "headers": { "Authorization": "Bearer token" },
-  "vars": { "source": "my-agent" }
-}
-```
-
-Makes an HTTP request. `GET` skips the body. `POST` sends `{ ...vars }` or `{ ...vars, data: <incoming payload> }` when triggered by a webhook.
-
----
-
-## Webhook Triggers
-
-Defined in `config/TRIGGERS.json`. Triggers fire on POST requests to watched paths.
-
-```json
-[
-  {
-    "name": "GitHub Push",
-    "watch_path": "/webhook/github-push",
-    "enabled": true,
-    "actions": [
-      {
-        "type": "agent",
-        "job": "Review the push to {{body.ref}}: {{body.head_commit.message}}"
-      }
-    ]
-  }
-]
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Display name |
-| `watch_path` | Yes | URL path to watch (e.g., `/webhook/github-push`) |
-| `actions` | Yes | Array of actions to fire (same fields as cron actions) |
-| `enabled` | No | Set `false` to disable (default: `true`) |
-
-### Template Tokens
-
-Use these in `job` and `command` strings to reference the incoming request:
-
-| Token | Resolves to |
-|-------|-------------|
-| `{{body}}` | Entire request body as JSON |
-| `{{body.field}}` | Nested field from request body |
-| `{{query}}` | All query parameters as JSON |
-| `{{query.field}}` | Specific query parameter |
-| `{{headers}}` | All request headers as JSON |
-| `{{headers.field}}` | Specific request header |
-
----
-
-## Managing from the Web UI
-
-Crons and triggers can also be managed from the **Admin** page (`/admin`) in the web UI. Changes made there are written back to the JSON config files.

package/templates/docs/GETTING_STARTED.md

@@ -1,64 +0,0 @@
-# Getting Started
-
-## Access the Web UI
-
-Open your `APP_URL` in a browser. On first visit you'll create an admin account (email + password). After that, log in at `/login`.
-
-## Your First Chat
-
-Click the chat input at `/` and start a conversation. The AI streams responses in real-time. You can:
-
-- **Upload files** — images, PDFs, and text files
-- **Use voice** — click the microphone for real-time transcription (requires `ASSEMBLYAI_API_KEY`)
-- **Browse history** — past conversations are in the sidebar, grouped by date
-
-## Your First Job
-
-Jobs are autonomous coding tasks. The AI creates a branch, works in a Docker container, and opens a PR.
-
-From chat, ask the AI to do something that requires code changes — like "update the README" or "add a new cron job." The AI will create a job, and you can monitor it on the **Runners** page (`/runners`).
-
-You can also create jobs via the API:
-
-```bash
-curl -X POST https://your-app-url/api/create-agent-job \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: YOUR_API_KEY" \
-  -d '{"job": "Update the README with installation instructions"}'
-```
-
-Generate API keys from **Settings > Secrets** in the web UI.
-
-## Connect Telegram (Optional)
-
-Chat with your agent on the go via a Telegram bot:
-
-```bash
-npm run setup-telegram
-```
-
-The setup wizard configures your bot token, webhook, and chat ID. Once connected, you can text or send voice messages to create jobs and get responses.
-
-## Monitor Activity
-
-- **Runners** (`/runners`) — watch running jobs, see logs
-- **Notifications** (`/notifications`) — job completion alerts
-- **Admin** (`/admin`) — manage users, crons, triggers, API keys, and GitHub settings
-
-## Code Workspaces
-
-Launch interactive coding sessions directly from chat. The AI spins up a Docker container with Claude Code and your repo, giving you a browser-based terminal at `/code/{id}`.
-
-## Cluster Workspaces
-
-Create multi-role agent teams from `/clusters`. Define roles (Researcher, Writer, etc.), set triggers, and let them collaborate in shared directories. See [CLUSTERS.md](CLUSTERS.md) for details.
-
-## What's Next
-
-- [CONFIGURATION.md](CONFIGURATION.md) — environment variables, LLM providers, GitHub setup
-- [CRONS_AND_TRIGGERS.md](CRONS_AND_TRIGGERS.md) — schedule recurring jobs and webhook automations
-- [SKILLS.md](SKILLS.md) — extend your agent with custom skills
-- [CLUSTERS.md](CLUSTERS.md) — multi-role agent teams
-- [CLI.md](CLI.md) — all CLI commands
-- [UPGRADING.md](UPGRADING.md) — keeping your agent up to date
-- [SECURITY.md](SECURITY.md) — API keys, secret handling, security model

package/templates/docs/SECURITY.md

@@ -1,61 +0,0 @@
-# Security
-
-## Security Measures
-
-thepopebot includes these security measures by default:
-
-- **API key authentication** — All external `/api` routes require a valid `x-api-key` header. Keys are SHA-256 hashed and verified with timing-safe comparison.
-- **Webhook secret validation** — Telegram and GitHub webhook endpoints validate shared secrets. Unconfigured endpoints reject all requests (fail-closed).
-- **Cluster webhook authentication** — Cluster role webhook endpoints require a valid API key.
-- **Session encryption** — Web sessions use JWT encrypted with `AUTH_SECRET` in httpOnly cookies.
-- **WebSocket authentication** — Code workspace WebSocket connections validate the session cookie.
-- **Secret filtering in Docker agent** — The `env-sanitizer` filters `AGENT_*` secrets from the LLM's bash subprocess.
-- **Auto-merge path restrictions** — `auto-merge.yml` only merges PRs where all changed files fall within `ALLOWED_PATHS` (default: `/logs`).
-- **Server Actions with session checks** — All browser-to-server mutations use `requireAuth()` session validation.
-
----
-
-## Secret Protection
-
-### How It Works
-
-1. The event handler passes agent job secrets directly to the Docker container via `buildAgentAuthEnv()`
-2. The container entrypoint exports each key into the environment
-3. The `env-sanitizer` extension filters ALL secret keys from the LLM's bash subprocess env
-4. SDKs (Anthropic, GitHub CLI) read their keys from `process.env` normally
-5. The LLM cannot `echo $ANYTHING` — subprocess env is filtered
-
-### 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.
-
----
-
-## Auto-Merge Restrictions
-
-The `auto-merge.yml` workflow checks every changed file in a job PR against `ALLOWED_PATHS` (GitHub repo variable, default: `/logs`). PRs with changes outside allowed paths require manual review.
-
-Keep `ALLOWED_PATHS` restrictive. Only widen it after reviewing what your agent might change.
-
----
-
-## API Keys
-
-Database-backed API keys are generated through the web UI (**Settings > Secrets**). Format: `tpb_` prefix + 64 hex characters. Keys are SHA-256 hashed in the database.
-
----
-
-## Recommendations
-
-- **Set webhook secrets** — Configure `TELEGRAM_WEBHOOK_SECRET` and `GH_WEBHOOK_SECRET`, even for local development
-- **Generate API keys** before exposing your server
-- **Restrict Telegram** — Set `TELEGRAM_CHAT_ID` to your personal chat ID
-- **Stop tunnels when not in use** — Don't leave endpoints exposed overnight
-- **Use Docker Compose with TLS for production** — Enable Let's Encrypt via `LETSENCRYPT_EMAIL`
-- **Review auto-merge settings** — Keep `ALLOWED_PATHS` restrictive
-
----
-
-## Disclaimer
-
-All software carries risk. thepopebot is provided as-is. You are responsible for securing your infrastructure, managing API keys, reviewing agent-generated PRs, and monitoring agent activity.

package/templates/docs/SKILLS.md

@@ -1,113 +0,0 @@
-# Skills
-
-Skills extend your agent's capabilities. A skill is a folder containing a `SKILL.md` file and optionally script files. The agent reads the SKILL.md to learn how to use it, then runs scripts via bash.
-
-Skills work with both Pi and Claude Code — they share the same `skills/active/` directory.
-
----
-
-## How Skills Work
-
-- `skills/` — all available skills
-- `skills/active/` — symlinks to activated skills (both agents read from here)
-
-At startup, the agent scans `skills/active/` and loads **only the name + description** from each SKILL.md frontmatter into its system prompt. Full instructions are loaded on-demand when the agent decides a skill is relevant.
-
----
-
-## Default Active Skills
-
-These are activated out of the box:
-
-| Skill | Description |
-|-------|-------------|
-| `get-secret` | List available LLM-accessible credentials |
-
-## Available Skills
-
-These ship with the package but must be activated manually:
-
-| Skill | Description |
-|-------|-------------|
-| `brave-search` | Web search and content extraction via Brave Search API |
-| `google-docs` | Create and manage Google Docs on a shared drive |
-| `google-drive` | Google Drive operations (list, upload, download, delete) |
-| `kie-ai` | AI image and video generation via kie.ai API |
-| `youtube-transcript` | YouTube transcript extraction |
-
----
-
-## Activate / Deactivate
-
-```bash
-# Activate
-cd skills/active
-ln -s ../skill-name skill-name
-
-# Deactivate
-rm skills/active/skill-name
-```
-
----
-
-## Building a Custom Skill
-
-### Skill Folder Structure
-
-```
-skills/my-skill/
-├── SKILL.md          # Instructions for agent and human
-├── package.json      # Optional: npm dependencies
-└── script.sh         # Script(s) the agent runs
-```
-
-### SKILL.md Format
-
-```markdown
----
-name: my-skill
-description: One sentence describing what the skill does and when to use it.
----
-
-# My Skill
-
-## Usage
-
-\```bash
-skills/my-skill/script.sh <args>
-\```
-```
-
-- **`name`** — kebab-case, matches the folder name
-- **`description`** — appears in the system prompt under "Active skills"
-- **Body** — full usage instructions the agent reads on-demand
-- Use **project-root-relative paths** in all examples
-
-### Simple Bash Skill
-
-```bash
-#!/bin/bash
-if [ -z "$1" ]; then echo "Usage: my-skill.sh <arg>"; exit 1; fi
-if [ -z "$MY_API_KEY" ]; then echo "Error: MY_API_KEY not set"; exit 1; fi
-curl -s "https://api.example.com/endpoint" \
-  -H "Authorization: Bearer $MY_API_KEY" \
-  -d "query=$1"
-```
-
-### Node.js Skill
-
-If bash + curl isn't sufficient, use Node.js with a `package.json`. Dependencies are installed automatically in Docker. Run `npm install` once locally in the skill directory.
-
----
-
-## Credential Setup
-
-If a skill needs an API key, add it via the admin UI (Settings > Agent Jobs > Secrets). The secret will be injected as an env var into Docker containers. The agent can discover available secrets via the `get-secret` skill.
-
----
-
-## External Skills
-
-Additional skills are available at: https://github.com/badlogic/pi-skills
-
-Skills follow the **Agent Skills standard** (SKILL.md format), compatible with Pi, Claude Code, Codex CLI, Amp, and Droid.

package/templates/docs/UPGRADING.md

@@ -1,92 +0,0 @@
-# Upgrading
-
-## Quick Upgrade
-
-Run the upgrade command from your project directory:
-
-```bash
-npx thepopebot upgrade
-```
-
-This installs the latest version, runs `init` to update managed files, rebuilds, commits, pushes, and restarts Docker.
-
-## Automated Upgrades via GitHub Actions
-
-Two workflows handle automated upgrades:
-
-### 1. upgrade-event-handler.yml (manual trigger)
-
-Trigger from the Actions tab in GitHub: **"Upgrade Event Handler" > Run workflow**. This:
-
-1. Runs `npm update thepopebot` in the event handler container
-2. If the version changed, creates an `upgrade/thepopebot-<version>` branch
-3. Opens a PR with auto-merge enabled
-
-This only updates `package.json` and `package-lock.json`. Template updates and rebuilds happen when the PR merges.
-
-### 2. rebuild-event-handler.yml (on push to main)
-
-Triggered when the upgrade PR merges. Detects the version change and:
-
-1. Runs `npx thepopebot init` to update managed templates
-2. Commits template changes back to `main`
-3. Pulls the new Docker image
-4. Restarts the container, installs dependencies, builds, and reloads PM2
-
----
-
-## What Gets Updated
-
-### Managed files (auto-updated)
-
-These are overwritten to match the new package version:
-
-- `.github/workflows/` — GitHub Actions workflows
-- `docker-compose.yml` — Docker Compose config
-- `.dockerignore` — Docker ignore rules
-- `CLAUDE.md` — AI assistant context
-
-### Your files (never overwritten)
-
-Config files, skills, cron scripts, trigger scripts, and other user-editable files are left alone. If the package ships new defaults, `init` will notify you:
-
-```
-Updated templates available:
-  config/CRONS.json
-
-To view differences:  npx thepopebot diff <file>
-To reset to default:  npx thepopebot reset <file>
-```
-
----
-
-## Recovering from a Failed Upgrade
-
-SSH into your server and rebuild manually:
-
-```bash
-docker exec thepopebot-event-handler npm install --omit=dev
-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; mv .next-new .next && rm -rf .next-old'
-docker exec thepopebot-event-handler npx pm2 restart all
-```
-
-### Merge Conflicts on Upgrade PR
-
-Resolve in the GitHub UI or locally:
-
-```bash
-git fetch origin
-git checkout upgrade/thepopebot-<version>-<timestamp>
-git merge main
-# resolve conflicts
-git push
-```
-
-### Diagnostic Commands
-
-```bash
-docker ps -a | grep thepopebot-event-handler          # container running?
-docker logs thepopebot-event-handler --tail 50         # container logs
-docker exec thepopebot-event-handler npx pm2 status    # PM2 status
-docker exec thepopebot-event-handler npx pm2 logs --lines 30  # app logs
-```

package/templates/skills/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Mario Zechner
-
-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/templates/skills/README.md

@@ -1,117 +0,0 @@
-# pi-skills
-
-A collection of skills for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), compatible with Claude Code, Codex CLI, Amp, and Droid.
-
-## Installation
-
-### pi-coding-agent
-
-```bash
-# User-level (available in all projects)
-git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills
-
-# Or project-level
-git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills
-```
-
-### Codex CLI
-
-```bash
-git clone https://github.com/badlogic/pi-skills ~/.codex/skills/pi-skills
-```
-
-### Amp
-
-Amp finds skills recursively in toolboxes:
-
-```bash
-git clone https://github.com/badlogic/pi-skills ~/.config/amp/tools/pi-skills
-```
-
-### Droid (Factory)
-
-```bash
-# User-level
-git clone https://github.com/badlogic/pi-skills ~/.factory/skills/pi-skills
-
-# Or project-level
-git clone https://github.com/badlogic/pi-skills .factory/skills/pi-skills
-```
-
-### Claude Code
-
-Claude Code only looks one level deep for `SKILL.md` files, so each skill folder must be directly under the skills directory. Clone the repo somewhere, then symlink individual skills:
-
-```bash
-# Clone to a convenient location
-git clone https://github.com/badlogic/pi-skills ~/pi-skills
-
-# Symlink individual skills (user-level)
-mkdir -p ~/.claude/skills
-ln -s ~/pi-skills/brave-search ~/.claude/skills/brave-search
-ln -s ~/pi-skills/browser-tools ~/.claude/skills/browser-tools
-ln -s ~/pi-skills/gccli ~/.claude/skills/gccli
-ln -s ~/pi-skills/gdcli ~/.claude/skills/gdcli
-ln -s ~/pi-skills/gmcli ~/.claude/skills/gmcli
-ln -s ~/pi-skills/transcribe ~/.claude/skills/transcribe
-ln -s ~/pi-skills/vscode ~/.claude/skills/vscode
-ln -s ~/pi-skills/youtube-transcript ~/.claude/skills/youtube-transcript
-
-# Or project-level
-mkdir -p .claude/skills
-ln -s ~/pi-skills/brave-search .claude/skills/brave-search
-ln -s ~/pi-skills/browser-tools .claude/skills/browser-tools
-ln -s ~/pi-skills/gccli .claude/skills/gccli
-ln -s ~/pi-skills/gdcli .claude/skills/gdcli
-ln -s ~/pi-skills/gmcli .claude/skills/gmcli
-ln -s ~/pi-skills/transcribe .claude/skills/transcribe
-ln -s ~/pi-skills/vscode .claude/skills/vscode
-ln -s ~/pi-skills/youtube-transcript .claude/skills/youtube-transcript
-```
-
-## Available Skills
-
-| Skill | Description |
-|-------|-------------|
-| [brave-search](brave-search/SKILL.md) | Web search and content extraction via Brave Search |
-| [gccli](gccli/SKILL.md) | Google Calendar CLI for events and availability |
-| [gdcli](gdcli/SKILL.md) | Google Drive CLI for file management and sharing |
-| [gmcli](gmcli/SKILL.md) | Gmail CLI for email, drafts, and labels |
-| [transcribe](transcribe/SKILL.md) | Speech-to-text transcription via Groq Whisper API |
-| [vscode](vscode/SKILL.md) | VS Code integration for diffs and file comparison |
-| [youtube-transcript](youtube-transcript/SKILL.md) | Fetch YouTube video transcripts |
-
-## Skill Format
-
-Each skill follows the pi/Claude Code format:
-
-```markdown
----
-name: skill-name
-description: Short description shown to agent
----
-
-# Instructions
-
-Detailed instructions here...
-Helper files available at: skills/skill-name/
-```
-
-Skills use project-root-relative paths (e.g., `skills/brave-search/search.js`).
-
-## Requirements
-
-Some skills require additional setup. Generally, the agent will walk you through that. But if not, here you go:
-
-- **brave-search**: Requires Node.js. Run `npm install` in the skill directory.
-- **gccli**: Requires Node.js. Install globally with `npm install -g @mariozechner/gccli`.
-- **gdcli**: Requires Node.js. Install globally with `npm install -g @mariozechner/gdcli`.
-- **gmcli**: Requires Node.js. Install globally with `npm install -g @mariozechner/gmcli`.
-- **subagent**: Requires pi-coding-agent. Install globally with `npm install -g @mariozechner/pi-coding-agent`.
-- **transcribe**: Requires curl and a Groq API key.
-- **vscode**: Requires VS Code with `code` CLI in PATH.
-- **youtube-transcript**: Requires Node.js. Run `npm install` in the skill directory.
-
-## License
-
-MIT

package/templates/skills/agent-job-secrets/SKILL.md

@@ -1,25 +0,0 @@
----
-name: agent-job-secrets
-description: List, get, or update agent secrets. Use get for OAuth credentials (auto-refreshed on every call). Use set to persist updated credentials back to the event handler.
----
-
-## Usage
-
-```bash
-# List available secrets (null = must fetch, plain = already in env)
-node skills/agent-job-secrets/agent-job-secrets.js
-
-# Get a secret value (OAuth credentials are auto-refreshed)
-node skills/agent-job-secrets/agent-job-secrets.js get MY_CREDENTIALS
-
-# Set/update a secret (plain string or piped value)
-node skills/agent-job-secrets/agent-job-secrets.js set MY_KEY "value"
-echo "$UPDATED_CREDENTIALS" | node skills/agent-job-secrets/agent-job-secrets.js set MY_KEY
-```
-
-## Notes
-
-- `AGENT_JOB_TOKEN` and `APP_URL` are injected automatically — no setup required
-- OAuth credentials show as `null` in the list and must be fetched via `get`
-- `get` on an OAuth credential refreshes it and persists the updated token immediately
-- Plain secrets are available directly as env vars (e.g. `echo $MY_KEY`)