@harbinger-ai/harbinger 0.1.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,406 @@
+# Why thepopebot?
+
+**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 (rebuild-event-handler.yml) │
+│           │                           │                              │
+│           5 (notify-pr-complete.yml / │                              │
+│           │  notify-job-failed.yml)   │                              │
+│           └───────────────────────────┘                              │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+You interact with your bot via the web chat interface or Telegram (optional). 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 notification when it's done.
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=stephengpope/thepopebot&type=date&legend=top-left)](https://www.star-history.com/#stephengpope/thepopebot&type=date&legend=top-left)
+
+---
+
+## 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) |
+| **Docker + Docker Compose** | [docker.com](https://docs.docker.com/get-docker/) (installer requires admin password) |
+| **ngrok*** | [ngrok.com](https://ngrok.com/download) (free account + authtoken required) |
+
+*\*ngrok is only required for local installs without port forwarding. VPS/cloud deployments don't need it. [Sign up](https://dashboard.ngrok.com/signup) for a free ngrok account, then run `ngrok config add-authtoken <YOUR_TOKEN>` before starting setup.*
+
+### Two steps
+
+**Step 1** — Scaffold a new project:
+
+```bash
+mkdir my-agent && cd my-agent
+npx thepopebot@latest init
+```
+
+This creates a Next.js project with configuration files, GitHub Actions workflows, and agent templates. You don't need to create a GitHub repo first — the setup wizard handles that.
+
+**Step 2** — Run the setup wizard:
+
+```bash
+npm run setup
+```
+
+The wizard walks you through everything:
+- Checks prerequisites (Node.js, Git, GitHub CLI)
+- Creates a GitHub repository and pushes your initial commit
+- Creates a GitHub Personal Access Token (scoped to your repo)
+- Collects API keys (Anthropic required; OpenAI, Brave optional)
+- Sets GitHub repository secrets and variables
+- Generates `.env`
+- Builds the project and starts Docker for you
+
+**That's it.** Visit your APP_URL when the wizard finishes.
+
+- **Web Chat**: Visit your APP_URL to chat with your agent, create jobs, upload files
+- **Telegram** (optional): Run `npm run setup-telegram` to connect a Telegram bot
+- **Webhook**: Send a POST to `/api/create-job` with your API key to create jobs programmatically
+- **Cron**: Edit `config/CRONS.json` to schedule recurring jobs
+
+### Chat vs Agent LLM
+
+Your bot has two sides — a **chat** side and an **agent** side.
+
+**Chat** is the conversational part. When you talk to your bot in the web UI or Telegram, it uses the chat LLM. This runs on your server and responds in real time.
+
+**Agent** is the worker. When your bot needs to write code, modify files, or do a bigger task, it spins up a separate job that runs in a Docker container on GitHub. That job uses the agent LLM.
+
+By default, both use the same model. But during setup, you can choose different models for each — for example, a faster model for chat and a more capable one for agent jobs. The wizard asks "Would you like agent jobs to use different LLM settings?" and lets you pick.
+
+### Using a Claude Subscription (OAuth Token)
+
+If you have a Claude Pro ($20/mo) or Max ($100+/mo) subscription, you can use it to power your agent jobs instead of paying per API call. During setup, choose Anthropic as your agent provider and say yes when asked about a subscription.
+
+You'll need to generate a token:
+
+```bash
+# Install Claude Code CLI (if you don't have it)
+npm install -g @anthropic-ai/claude-code
+
+# Generate your token (opens browser to log in)
+claude setup-token
+```
+
+Paste the token (starts with `sk-ant-oat01-`) into the setup wizard. Your agent jobs will now run through your subscription. Note that usage counts toward your Claude.ai limits, and you still need an API key for the chat side.
+
+See [Claude Code vs Pi](docs/CLAUDE_CODE_VS_PI.md) for more details on the two agent backends.
+
+> **Local installs**: Your server needs to be reachable from the internet for GitHub webhooks and Telegram. On a VPS/cloud server, your APP_URL is just your domain. For local development, use [ngrok](https://ngrok.com) (`ngrok http 80`) or port forwarding to expose your machine.
+>
+> **If your ngrok URL changes** (it changes every time you restart ngrok on the free plan), you must update APP_URL everywhere:
+>
+> ```bash
+> # Update .env and GitHub variable in one command:
+> npx thepopebot set-var APP_URL https://your-new-url.ngrok.io
+> # If Telegram is configured, re-register the webhook:
+> npm run setup-telegram
+> ```
+
+---
+
+## Manual Updating
+
+**1. Update the package**
+
+```bash
+npm install thepopebot@latest
+```
+
+**2. Scaffold and update templates**
+
+```bash
+npx thepopebot init
+```
+
+For most people, that's it — `init` handles everything. It updates your project files, runs `npm install`, and updates `THEPOPEBOT_VERSION` in your local `.env`. See [Understanding `init`](#understanding-init) below for details on what this updates and how to handle custom changes.
+
+**3. Rebuild for local dev**
+
+```bash
+npm run build
+```
+
+**4. Commit and push**
+
+```bash
+git add -A && git commit -m "upgrade thepopebot to vX.X.X"
+git push
+```
+
+Pushing to `main` triggers the `rebuild-event-handler.yml` workflow on your server. It detects the version change, runs `thepopebot init`, updates `THEPOPEBOT_VERSION` in the server's `.env`, pulls the new Docker image, restarts the container, rebuilds `.next`, and reloads PM2 — no manual `docker compose` needed.
+
+> **Upgrade failed?** See [Recovering from a Failed Upgrade](docs/UPGRADE.md#recovering-from-a-failed-upgrade).
+
+### Understanding `init`
+
+#### How your project is structured
+
+When you ran `thepopebot init` the first time, it scaffolded a project folder with two kinds of files:
+
+**Your files** — These are yours to customize. `init` will never overwrite them:
+
+| Files | What they do |
+|-------|-------------|
+| `config/SOUL.md`, `EVENT_HANDLER.md`, `AGENT.md`, etc. | Your agent's personality, behavior, and prompts |
+| `config/CRONS.json`, `TRIGGERS.json` | Your scheduled jobs and webhook triggers |
+| `app/` | Next.js pages and UI components |
+| `docker/job-pi-coding-agent/` | The Dockerfile for the Pi coding agent job container |
+
+**Managed files** — These are infrastructure files that need to stay in sync with the package version. `init` auto-updates them for you:
+
+| Files | What they do |
+|-------|-------------|
+| `.github/workflows/` | GitHub Actions that run jobs, auto-merge PRs, rebuild on deploy |
+| `docker-compose.yml` | Defines how your containers run together (Traefik, event handler, runner) |
+| `docker/event-handler/` | The Dockerfile for the event handler container |
+| `.dockerignore` | Keeps unnecessary files out of Docker builds |
+| `CLAUDE.md` | AI assistant context for your project |
+
+#### What happens when you run `init`
+
+1. **Managed files** are updated automatically to match the new package version
+2. **Your files** are left alone — but if the package ships new defaults (e.g., a new field in `CRONS.json`), `init` lets you know:
+
+```
+Updated templates available:
+These files differ from the current package templates.
+
+  config/CRONS.json
+
+To view differences:  npx thepopebot diff <file>
+To reset to default:  npx thepopebot reset <file>
+```
+
+You can review at your own pace:
+
+```bash
+npx thepopebot diff config/CRONS.json    # see what changed
+npx thepopebot reset config/CRONS.json   # accept the new template
+```
+
+#### If you've modified managed files
+
+If you've made custom changes to managed files (e.g., added extra steps to a GitHub Actions workflow), use `--no-managed` so `init` doesn't overwrite your changes:
+
+```bash
+npx thepopebot init --no-managed
+```
+
+#### Template file conventions
+
+The `templates/` directory contains files scaffolded into user projects by `thepopebot init`. Two naming conventions handle files that npm or AI tools would otherwise misinterpret:
+
+**`.template` suffix** — Files ending in `.template` are scaffolded with the suffix stripped. This is used for files that npm mangles (`.gitignore`) or that AI tools would pick up as real project docs (`CLAUDE.md`).
+
+| In `templates/` | Scaffolded as |
+|-----------------|---------------|
+| `.gitignore.template` | `.gitignore` |
+| `CLAUDE.md.template` | `CLAUDE.md` |
+| `api/CLAUDE.md.template` | `api/CLAUDE.md` |
+
+**`CLAUDE.md` exclusion** — The scaffolding walker skips any file named `CLAUDE.md` (without the `.template` suffix). This is a safety net so a bare `CLAUDE.md` accidentally added to `templates/` never gets copied into user projects where AI tools would confuse it with real project instructions.
+
+---
+
+## CLI Commands
+
+All commands are run via `npx thepopebot <command>` (or the `npm run` shortcuts where noted).
+
+**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 |
+
+**Secrets & variables:**
+
+These commands set individual 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 (keeps secrets out of shell history).
+
+| Command | Description |
+|---------|-------------|
+| `set-agent-secret KEY [VALUE]` | Set `AGENT_<KEY>` GitHub secret and update `.env` |
+| `set-agent-llm-secret KEY [VALUE]` | Set `AGENT_LLM_<KEY>` GitHub secret |
+| `set-var KEY [VALUE]` | Set a GitHub repository variable |
+
+GitHub secrets use a prefix convention so the workflow can route them correctly:
+
+- **`AGENT_`** — Protected secrets passed to the Docker container (filtered from LLM). Example: `AGENT_GH_TOKEN`, `AGENT_ANTHROPIC_API_KEY`
+- **`AGENT_LLM_`** — LLM-accessible secrets (not filtered). Example: `AGENT_LLM_BRAVE_API_KEY`
+- **No prefix** — Workflow-only secrets, never passed to container. Example: `GH_WEBHOOK_SECRET`
+
+---
+
+## Security
+
+thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption, secret filtering in the Docker agent, and auto-merge path restrictions. However, all software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel (ngrok, Cloudflare Tunnel, port forwarding), be aware that your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
+
+See [Security](docs/SECURITY.md) for full details on what's exposed, the risks, and recommendations.
+
+---
+
+## Harbinger Agent System
+
+thepopebot includes 11 specialized agent profiles (the Harbinger swarm), each with a distinct personality, skills, and area of expertise. Route messages to specific agents using `@mentions`:
+
+```
+@PATHFINDER enumerate subdomains for example.com
+@BREACH scan the login page for XSS
+@SAM refactor the database module
+@SPECTER run OSINT on target.com
+```
+
+Available agents: **SPECTER** (OSINT), **SAM** (Coding), **SAGE** (Learning), **PATHFINDER** (Recon), **BREACH** (Web Hacking), **PHANTOM** (Cloud), **CIPHER** (Binary), **SCRIBE** (Reports), **LENS** (Browser), **MAINTAINER** (Code Quality), **BRIEF** (Daily Briefs).
+
+Create custom agents by copying `agents/_template/` and editing the profile files. Agents are auto-discovered at startup.
+
+See [agents/README.md](agents/README.md) for the full guide.
+
+---
+
+## Bug Bounty Automation
+
+thepopebot includes a full bug bounty hunting automation suite — manage programs, targets, findings, and security tools from the web UI.
+
+### Features
+
+- **Targets Dashboard** (`/targets`) — Manage bug bounty programs and their in-scope targets. Sync targets directly from HackerOne, Bugcrowd, Intigriti, YesWeHack, and Federacy using live data from [bounty-targets-data](https://github.com/arkadiyt/bounty-targets-data).
+- **Findings Feed** (`/findings`) — Track discovered vulnerabilities with severity ratings, status workflow (new → triaging → confirmed → reported → bounty_paid), and bounty amounts.
+- **Toolbox** (`/toolbox`) — Browse and install from a catalog of 68+ real security tools (subfinder, nuclei, httpx, ffuf, sqlmap, etc.). Install tools from any GitHub repo. Manage Docker containers for agent terminal access.
+
+### Quick Start
+
+After setup, visit your app URL and navigate to **Targets** in the sidebar to start:
+
+1. Click **Sync from Bounty Platforms** to import programs from HackerOne/Bugcrowd/etc.
+2. Or add programs manually with the **Add** button
+3. Add targets to your programs (domains, IPs, wildcards, APIs)
+4. Visit **Toolbox** to install scanning tools from the catalog
+5. Findings appear automatically as agents discover vulnerabilities, or add them manually
+
+See [Bug Bounty](docs/BUG_BOUNTY.md) for the full guide.
+
+---
+
+## MCP (Model Context Protocol)
+
+thepopebot exposes an MCP server at `/api/mcp` and can consume tools from external MCP servers — connecting your agents to Claude Desktop, Cursor, and any MCP-compatible client.
+
+### Server (expose your agent's tools)
+
+External AI clients connect to `https://your-app-url/api/mcp` with your API key. Exposed capabilities:
+
+| Type | Items |
+|------|-------|
+| **Tools** | `create_job`, `get_job_status`, `chat`, `list_agents`, `get_agent_profile` |
+| **Resources** | `agent://agents`, `agent://{id}/soul`, `config://soul`, `config://crons`, `config://triggers` |
+| **Prompts** | `agent-prompt` (parameterized by agent ID) |
+
+### Client (consume external MCP tools)
+
+Add external MCP servers to `config/MCP_SERVERS.json`:
+
+```json
+[
+  {
+    "name": "my-tool-server",
+    "transport": "http",
+    "url": "http://localhost:3001/mcp",
+    "headers": {},
+    "enabled": true
+  }
+]
+```
+
+External tools are automatically available to your agents. Manage and test them from **Settings → MCP** in the web UI.
+
+See [MCP Integration](docs/MCP.md) for the full guide.
+
+---
+
+## Running Different Models
+
+The Event Handler (chat, Telegram, webhooks) and Jobs (Docker agent) are two independent layers — each can run a different LLM. Use Claude for interactive chat and a cheaper or local model for long-running jobs, mix providers per cron entry, or run everything on a single model.
+
+See [Running Different Models](docs/RUNNING_DIFFERENT_MODELS.md) for the full guide: Event Handler config, job defaults, per-job overrides, provider table, and custom provider setup.
+
+---
+
+## 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 |
+| [Chat Integrations](docs/CHAT_INTEGRATIONS.md) | Web chat, Telegram, adding new channels |
+| [Running Different Models](docs/RUNNING_DIFFERENT_MODELS.md) | Event Handler vs job model config, per-job overrides, providers, custom provider |
+| [Auto-Merge](docs/AUTO_MERGE.md) | Auto-merge controls, ALLOWED_PATHS configuration |
+| [Deployment](docs/DEPLOYMENT.md) | VPS setup, Docker Compose, HTTPS with Let's Encrypt |
+| [Claude Code vs Pi](docs/CLAUDE_CODE_VS_PI.md) | Comparing the two agent backends (subscription vs API credits) |
+| [How to Build Skills](docs/HOW_TO_BUILD_SKILLS.md) | Guide to building and activating agent skills |
+| [Pre-Release](docs/PRE_RELEASE.md) | Installing beta/alpha builds |
+| [Security](docs/SECURITY.md) | Security disclaimer, local development risks |
+| [Upgrading](docs/UPGRADE.md) | Automated upgrades, recovering from failed upgrades |
+| [Bug Bounty](docs/BUG_BOUNTY.md) | Targets, findings, tool registry, platform sync |
+| [MCP Integration](docs/MCP.md) | MCP server/client setup, external tool consumption |
+
+### Maintainer
+
+| Document | Description |
+|----------|-------------|
+| [NPM](docs/NPM.md) | Updating skills, versioning, and publishing releases |

package/agents/README.md

@@ -0,0 +1,76 @@
+# Harbinger Agent System
+
+The Harbinger framework provides a system of customizable agent profiles, each with a distinct identity, personality, and skill set. Agents can be routed to via `@mentions` in chat or selected explicitly via the MCP `chat` tool.
+
+## How Agent Selection Works
+
+In chat (web UI, Telegram, or MCP), prefix your message with `@CODENAME` to route to a specific agent:
+
+```
+@PATHFINDER enumerate subdomains for example.com
+@BREACH test the login form for SQL injection
+@SAM refactor the authentication module
+```
+
+The system matches against agent codenames, directory names, and display names (case-insensitive). If no match is found, the default event handler agent is used.
+
+Via MCP, pass the `agent_id` parameter to the `chat` tool:
+
+```json
+{ "thread_id": "abc", "message": "scan for open ports", "agent_id": "recon-scout" }
+```
+
+## Agent Profiles
+
+Each agent profile directory contains:
+
+| File | Purpose |
+|------|---------|
+| **SOUL.md** | Core personality, communication style, and system prompt |
+| **IDENTITY.md** | Name, codename, role, and specialization |
+| **CONFIG.yaml** | Model, temperature, Docker image, handoff rules |
+| **SKILLS.md** | Techniques, methodologies, and knowledge domains |
+| **TOOLS.md** | Command-line tools and APIs the agent is proficient with |
+| **HEARTBEAT.md** | Health check template |
+
+### Available Agents
+
+| Codename | Name | Role |
+|----------|------|------|
+| SPECTER | OSINT Detective | Open-source intelligence gathering |
+| SAM | Coding Assistant | Code generation, review, debugging |
+| SAGE | Learning Agent | Workflow optimization |
+| PATHFINDER | Recon Scout | Attack surface discovery |
+| BREACH | Web Hacker | Web vulnerability discovery |
+| PHANTOM | Cloud Infiltrator | Cloud security assessment |
+| CIPHER | Binary Reverser | Binary analysis, reverse engineering |
+| SCRIBE | Report Writer | Vulnerability report generation |
+| LENS | Browser Agent | Browser automation via CDP |
+| MAINTAINER | Code Quality | Nightly code quality enforcement |
+| BRIEF | Morning Brief | Automated daily reporting |
+
+## Implementation Status
+
+Agent profiles provide **personality and knowledge context** when selected. The SOUL.md becomes the system prompt, and SKILLS.md + TOOLS.md are appended as context.
+
+The runtime agent engine (`lib/ai/agent.js`) provides:
+- LangGraph agent with tool use and SQLite checkpointing
+- 4 built-in tools: `create_job`, `get_job_status`, `get_system_technical_specs`, `get_skill_building_guide`
+- External MCP tools (from `config/MCP_SERVERS.json`)
+
+Agent-specific Docker containers and direct tool execution (e.g., running `nuclei` or `subfinder`) are planned for future releases. Currently, agents can instruct jobs to use these tools via the Docker agent container.
+
+## Creating a Custom Agent
+
+1. Copy `agents/_template/` to `agents/my-agent/`
+2. Edit all `.md` and `.yaml` files to define your agent's identity
+3. The agent is auto-discovered at startup and available via `@MY_AGENT_CODENAME`
+
+## Runtime Infrastructure
+
+| Component | Location | Description |
+|-----------|----------|-------------|
+| Agent Discovery | `lib/agents.js` | Scans `agents/` for profiles |
+| Agent Runtime | `lib/ai/agent.js` | LangGraph agent with profile-specific system prompts |
+| Model Router | `lib/ai/model-router.js` | Complexity-based model selection |
+| Autonomous Engine | `lib/ai/autonomous-engine.js` | Background thinking loop (opt-in) |

package/agents/_template/CONFIG.yaml

@@ -0,0 +1,7 @@
+model: configurable
+temperature: configurable
+docker_image: harbinger/template-agent
+proxy_chain: configurable
+auto_handoff: false
+handoff_to: []
+receives_from: []

package/agents/_template/HEARTBEAT.md

@@ -0,0 +1,59 @@
+# {{CODENAME}} — Heartbeat Protocol
+
+> This file defines how the agent checks in, what it monitors, and how it reports health.
+
+## Heartbeat Schedule
+
+- **Interval:** Every 60 seconds while active
+- **Endpoint:** `POST /api/agents/{{agent_id}}/heartbeat`
+- **Model:** Use cheapest available (Haiku or Gemini Flash)
+- **Cost target:** < $0.005 per heartbeat
+
+## Health Check Tasks
+
+### 1. Self-Check
+- [ ] Am I still running? (process health)
+- [ ] Is my workspace accessible? (`/workspace` mounted and writable)
+- [ ] Are my tools functional? (spot-check one primary tool)
+- [ ] Is my memory within limits? (check against `memory_mb` in CONFIG.yaml)
+- [ ] Is my network accessible? (can I reach the Harbinger API?)
+
+### 2. Task Status
+- [ ] Do I have an active task? If yes, report progress (0-100%)
+- [ ] Is my current task stalled? (no progress in last 5 minutes)
+- [ ] Are there queued tasks waiting for me?
+- [ ] Have I produced output that hasn't been handed off yet?
+
+### 3. Swarm Health
+- [ ] Can I reach the message bus? (`/api/agents/broadcast`)
+- [ ] Are my upstream agents (receives_from) responsive?
+- [ ] Are my downstream agents (handoff_to) responsive?
+- [ ] Is the shared context accessible? (`/api/agents/context`)
+
+### 4. Container Health
+- [ ] Are my sub-containers (if any) still running?
+- [ ] Is disk usage within acceptable limits?
+- [ ] Are there zombie processes?
+
+## Response Format
+
+**If ALL CLEAR:**
+```json
+{"status": "active", "current_task": "{{task}}", "progress": 0, "healthy": true}
+```
+
+**If IDLE:**
+```json
+{"status": "idle", "current_task": null, "progress": 0, "healthy": true}
+```
+
+**If ISSUES:**
+```json
+{"status": "error", "current_task": "{{task}}", "progress": 0, "healthy": false, "issues": ["{{issue_1}}"]}
+```
+
+## Escalation
+
+1. **Unresponsive (3 missed):** Orchestrator logs warning, attempts health probe
+2. **Critical (5 missed):** Orchestrator restarts container, notifies operator
+3. **Persistent failure:** Orchestrator removes agent from active pool, creates incident

package/agents/_template/IDENTITY.md

@@ -0,0 +1,4 @@
+Name: 
+Codename: 
+Role: 
+Specialization: 

package/agents/_template/SKILLS.md

@@ -0,0 +1 @@
+Skills: 

package/agents/_template/SOUL.md

@@ -0,0 +1,25 @@
+Personality:
+Communication style:
+Motto:
+
+## Meta-Cognition — Autonomous Thinking
+
+### Self-Awareness
+- Monitor task queue depth, success rate, and resource consumption
+- Track which tools and techniques yield the best results
+- Evaluate efficiency: time per task, quality metrics, error rate
+
+### Enhancement Identification
+- Detect repetitive patterns that could be automated
+- Evaluate model tier: use lightweight models for routine tasks, reserve heavy models for complex analysis
+- Identify collaboration opportunities with other agents in the swarm
+
+### Efficiency Tracking
+- Formula: COST_BENEFIT = (TIME_SAVED x FREQUENCY) / (IMPL_COST + RUNNING_COST)
+- Only propose automations where cost_benefit > 1.0
+- Track: tasks per cycle, findings per task, false positive rate
+
+### Swarm Awareness
+- Read swarm state before starting work to avoid duplication
+- Announce significant findings for other agents to act on
+- Auto-handoff tasks to specialized agents when their expertise is needed

package/agents/_template/TOOLS.md

@@ -0,0 +1,3 @@
+Primary: 
+
+### Usage Examples:

package/agents/binary-reverser/CONFIG.yaml

@@ -0,0 +1,21 @@
+model: configurable
+temperature: 0.2 # precise
+docker_image: harbinger/binary-reverser
+sandbox_mode: isolated
+auto_handoff: true
+handoff_to: [report-writer]
+receives_from: [recon-scout, web-hacker]
+
+# Resource limits (enforced by Docker — higher for RE tools)
+memory_mb: 4096
+cpu_count: 4
+
+# Agent capabilities
+capabilities:
+  - disassembly
+  - decompilation
+  - binary_diffing
+  - exploit_development
+  - shellcode_analysis
+  - format_string_analysis
+  - rop_chain_generation