AI Agent Army — deploy client-scouting agents from a simple UI

.env.example

@@ -24,6 +24,9 @@ ENCRYPTION_IV=your_hex_encoded_initialization_vector
 # Obtain your API key from: https://app.chaingpt.org/apidashboard
 # =============================
 CHAINGPT_API_KEY=your_chaingpt_api_key
+# Optional: general-purpose ChainGPT Web3 LLM endpoint used by scouting agents.
+# Defaults to https://api.chaingpt.org/chat/stream if unset.
+CHAINGPT_LLM_URL=https://api.chaingpt.org/chat/stream
 
 # =============================
 # 🔑 Token Set Password

data/agents.json

@@ -0,0 +1,3 @@
+{
+  "agents": []
+}

data/leads.json

@@ -0,0 +1,3 @@
+{
+  "leads": []
+}

data/products.json

@@ -0,0 +1,121 @@
+{
+  "products": {
+    "chaingpt-pad": {
+      "name": "ChainGPT Pad",
+      "description": "Launchpad for Web3 projects: IDOs, launchdrops, and fundraising for the network.",
+      "workflows": {
+        "vc-scout": {
+          "name": "VC & Network Scout",
+          "targetPersona": "Crypto-native venture funds, angel syndicates, and ecosystem treasuries that invest in early-stage Web3 projects and back launchpads.",
+          "icp": "Funds with an active thesis in infra, AI x crypto, or consumer Web3, deploying $25k-$500k tickets, with a public portfolio and reachable partners.",
+          "signals": [
+            "Recently announced a new fund or raise",
+            "Portfolio overlap with launchpad/IDO ecosystems",
+            "Partners active on X discussing deal flow",
+            "Backed projects that later did public sales"
+          ],
+          "qualificationCriteria": [
+            "Has deployed capital in the last 6 months",
+            "Public point of contact (partner / IR email / X DM open)",
+            "Thesis fit with ChainGPT ecosystem"
+          ],
+          "outreachTemplate": "Hi {{contactName}}, ChainGPT Pad is curating allocation for {{fundName}} into vetted IDOs across AI x Web3. Given your thesis on {{thesisFit}}, would you be open to a 15-min intro to our upcoming pipeline?"
+        },
+        "ido-clients": {
+          "name": "IDO Client Scout",
+          "targetPersona": "Founders of pre-launch Web3 projects who need a launchpad to run their IDO and reach retail/community investors.",
+          "icp": "Projects 4-12 weeks from token generation event, with a live community (>5k), a token model, and no committed launchpad yet.",
+          "signals": [
+            "Announced an upcoming TGE or token without a launchpad partner",
+            "Recently closed a private/seed round",
+            "Growing community but no public sale infrastructure",
+            "Hiring growth/marketing roles ahead of launch"
+          ],
+          "qualificationCriteria": [
+            "Has a token / tokenomics in progress",
+            "Launch window within ~3 months",
+            "No exclusive launchpad already announced"
+          ],
+          "outreachTemplate": "Hey {{contactName}}, saw {{projectName}} is heading toward TGE. ChainGPT Pad can run your IDO end-to-end (KYC, tiers, vesting, 250k+ reach). Worth a quick call this week?"
+        },
+        "launchdrop-clients": {
+          "name": "Launchdrop Client Scout",
+          "targetPersona": "Projects looking to run an airdrop / launchdrop campaign to bootstrap community and distribution.",
+          "icp": "Projects with a token and a community-growth goal that want incentivized distribution and quest-based campaigns.",
+          "signals": [
+            "Recently launched points or quest programs",
+            "Discussing airdrop strategy publicly",
+            "High social engagement, early monetization stage"
+          ],
+          "qualificationCriteria": [
+            "Token available or planned for distribution",
+            "Active community to incentivize",
+            "Budget/intent for a distribution campaign"
+          ],
+          "outreachTemplate": "Hi {{contactName}}, ChainGPT Pad's Launchdrop can turn {{projectName}}'s community into verified holders with quest-based distribution. Open to seeing a sample campaign?"
+        }
+      }
+    },
+    "chaingpt-ai": {
+      "name": "ChainGPT AI",
+      "description": "Web3 AI tech stack: LLM APIs, AI agents, smart-contract & auditing tooling for builders.",
+      "workflows": {
+        "web3-builders": {
+          "name": "Web3 Builder Scout",
+          "targetPersona": "Web3 developers, dev shops, and product teams building dApps, agents, or AI features who could integrate ChainGPT's APIs.",
+          "icp": "Teams shipping Web3 products that need an AI/LLM layer, smart-contract generation, auditing, or an on-chain agent and don't yet use ChainGPT.",
+          "signals": [
+            "Building AI agents or chatbots in a Web3 context",
+            "Hiring AI/ML or Solidity engineers",
+            "Public repos integrating other LLM providers",
+            "Hackathon teams shipping AI x crypto demos"
+          ],
+          "qualificationCriteria": [
+            "Active product or repo (shipping, not idea-stage)",
+            "Clear need for an AI/LLM or smart-contract layer",
+            "Reachable technical decision-maker"
+          ],
+          "outreachTemplate": "Hi {{contactName}}, noticed {{projectName}} is building {{useCase}}. ChainGPT's Web3 LLM + agent SDK could drop in for that. Want a sandbox key to try it?"
+        }
+      }
+    },
+    "saleium": {
+      "name": "Saleium",
+      "description": "Public-sale, vesting, and staking infrastructure (SaaS) for token projects.",
+      "workflows": {
+        "public-sale": {
+          "name": "Public Sale Infra Scout",
+          "targetPersona": "Token projects that need self-serve public-sale infrastructure before launch.",
+          "icp": "Projects planning a public/community sale who want their own white-label sale portal rather than a shared launchpad.",
+          "signals": [
+            "Planning a public sale or whitelist soon",
+            "Want control over branding/terms of the raise",
+            "No sale infrastructure vendor announced"
+          ],
+          "qualificationCriteria": [
+            "Sale planned within ~3 months",
+            "Prefers self-hosted/white-label over a launchpad",
+            "Has a token contract or plan"
+          ],
+          "outreachTemplate": "Hi {{contactName}}, Saleium gives {{projectName}} a branded public-sale portal (KYC, caps, multi-chain) you fully control. Want a demo before your raise?"
+        },
+        "vesting-staking": {
+          "name": "Vesting & Staking Portal Scout",
+          "targetPersona": "Projects post-TGE that need vesting distribution and/or staking portals for their token.",
+          "icp": "Projects with a live or imminent token that must manage cliffs/vesting for investors and team, or want a staking product.",
+          "signals": [
+            "Token live or TGE just completed",
+            "Investor/team allocations needing vesting schedules",
+            "Community asking for staking / yield"
+          ],
+          "qualificationCriteria": [
+            "Live or imminent token",
+            "Need for vesting or staking they haven't built in-house",
+            "Reachable ops/finance or founder contact"
+          ],
+          "outreachTemplate": "Hi {{contactName}}, Saleium can spin up audited vesting + staking portals for {{projectName}} in days, not sprints. Worth a look?"
+        }
+      }
+    }
+  }
+}

docs/agent-army-architecture.md

@@ -0,0 +1,203 @@
+# AI Agent Army — Client Scouting for the ChainGPT Ecosystem
+
+> How to build a fleet of AI agents, deployable from a simple UI, that
+> continuously scout for clients across every ChainGPT product — and stay
+> extensible as new products and sales motions are added.
+
+This document describes the architecture and the MVP that ships in this PR. It
+is written to be read by both engineering and the business teams who will
+operate the agents.
+
+---
+
+## 1. The idea in one picture
+
+```
+        ┌──────────────────────── Simple UI (/agents) ───────────────────────┐
+        │  pick Product → pick Workflow → set targeting + cadence → Deploy    │
+        └─────────────────────────────────────────────────────────────────────┘
+                                        │ deploys
+                                        ▼
+   PRODUCT REGISTRY            AGENT (one soldier)                 LEADS
+   (data/products.json)        (data/agents.json)             (data/leads.json)
+   ┌───────────────┐           ┌───────────────────┐           ┌───────────────┐
+   │ ChainGPT Pad  │── has ──▶ │ product + workflow │── runs ─▶ │ scored lead   │
+   │  · vc-scout   │ workflows │ + targeting        │  on cron  │ + rationale   │
+   │  · ido-clients│           │ + schedule (cron)  │           │ + outreach    │
+   │ ChainGPT AI   │           └───────────────────┘           │ + status      │
+   │  · web3-build │                    │ uses                  └───────────────┘
+   │ Saleium       │                    ▼
+   │  · public-sale│            ChainGPT Web3 LLM  ◀── the shared "brain"
+   │  · vesting    │            (+ future data connectors: X, web, CRM)
+   └───────────────┘
+```
+
+- A **Product** is something we sell (ChainGPT Pad, ChainGPT AI, Saleium).
+- A **Workflow** is a scouting *playbook* for that product — _who_ to look for
+  and _how_ to pitch them (VCs, IDO clients, launchdrop clients, Web3 builders,
+  public-sale projects, vesting/staking projects…).
+- An **Agent** is a deployed instance: `product + workflow + targeting + cadence`.
+  Run hundreds of them — that is the "army."
+- A **Lead** is the output: a scored, qualified prospect with a ready-to-send
+  outreach draft, flowing through a `new → contacted → qualified → won` pipeline.
+
+The key design choice: **products and workflows are data, not code.** Adding a
+new thing to sell, or a new market segment to scout, is a registry edit (or a
+UI action) — no redeploy, no engineer.
+
+---
+
+## 2. Why this fits AgenticOS
+
+AgenticOS already is an autonomous-agent runtime — it just happens to currently
+run one kind of agent (the Twitter content agent). It already has every
+primitive the army needs:
+
+| Need | Already in AgenticOS | Reused for the army |
+| --- | --- | --- |
+| LLM reasoning | ChainGPT Web3 LLM (`api-key`) | `chaingpt.service.ts` (shared brain) |
+| Scheduled autonomy | `node-cron` (`tweet.job.ts`) | `agent.job.ts` (fans out N agents) |
+| Simple operator UI | EJS dashboard + Tailwind | `/agents` page |
+| Auth for mutations | `PASSWORD_AUTH` bearer middleware | reused as-is |
+| Lightweight persistence | JSON files in `data/` | `products/agents/leads.json` |
+| Config-as-data | `schedule.json` | `products.json` registry |
+
+So the army is not a new system — it is a second agent *type* layered onto the
+existing one, following the exact same patterns (Hono routes → controllers →
+services → JSON stores → cron jobs → EJS views).
+
+---
+
+## 3. What ships in this PR (the MVP)
+
+### Data
+- `data/products.json` — the extensible **product → workflow registry**, seeded
+  with ChainGPT Pad (VC / IDO / launchdrop), ChainGPT AI (Web3 builders), and
+  Saleium (public-sale / vesting-staking).
+- `data/agents.json`, `data/leads.json` — runtime stores (start empty).
+
+### Code (`src/`)
+- `types/agents.ts` — the domain model (Product, Workflow, Agent, Lead).
+- `services/chaingpt.service.ts` — shared LLM wrapper (`askChainGPT`,
+  `askChainGPTForJSON`).
+- `services/product.service.ts` — load/extend the registry.
+- `services/agent.service.ts` — CRUD + **the scouting engine** (`runAgent`).
+- `services/lead.service.ts` — lead storage + pipeline status.
+- `jobs/agent.job.ts` — schedules every enabled agent on its own cron.
+- `controllers/agent.controller.ts` + `routes/agent.routes.ts` — UI + API.
+- `views/agents.ejs` — the simple deploy/manage/leads UI (new sidebar tab).
+
+### How an agent run works (`runAgent`)
+1. Compose a **scouting brief** from the workflow playbook + the operator's
+   targeting (regions, keywords, notes, leads-per-run).
+2. Ask the ChainGPT LLM to return qualified candidate leads as structured JSON
+   (name, company, handle, fit score 0–100, rationale, contact, personalized
+   outreach draft built from the workflow's template).
+3. Persist the leads, bump the agent's run/lead counters.
+
+The scheduler (`agent.job.ts`) gives each enabled agent its own cron task, so
+the whole fleet scouts continuously and independently. Create/pause/delete an
+agent and the schedule re-applies live — no restart.
+
+---
+
+## 4. The simple UI
+
+`/agents` (password-gated mutations, same as the scheduler):
+
+1. **Deploy** — choose Product → Workflow (auto-populated), name it, set cadence
+   (cron) and targeting (regions / keywords / leads-per-run / notes), Deploy.
+2. **Manage** — table of deployed agents with run-now ▶, pause/resume, delete,
+   and live run/lead counters.
+3. **Leads** — scored, color-coded lead table with rationale, the drafted
+   outreach message, and an inline pipeline-status dropdown.
+
+This is intentionally the same EJS+Tailwind+`fetch` pattern as the existing
+scheduler page so it is instantly familiar to operate.
+
+---
+
+## 5. Extensibility — adding new products & sales motions
+
+Because the playbooks are data, there are three escalating ways to extend:
+
+1. **New workflow for an existing product** — add an entry under that product's
+   `workflows` in `products.json` (or call `upsertWorkflow`). It appears in the
+   UI dropdown immediately. _Example: add a "KOL / influencer scout" workflow to
+   ChainGPT Pad._
+2. **New product** — add a top-level entry under `products` (or `upsertProduct`).
+   _Example: a future "ChainGPT Labs" product with its own workflows._
+3. **New capability** (rarely needed) — e.g. agents that also *send* outreach,
+   not just draft it. That is a new service + a route, following the same shape.
+
+A workflow is just five fields: `targetPersona`, `icp`, `signals[]`,
+`qualificationCriteria[]`, `outreachTemplate`. Writing one is a sales/marketing
+exercise, not an engineering one.
+
+---
+
+## 6. From "LLM-imagined" leads to real prospecting
+
+The MVP's discovery is LLM-driven, which is perfect for: drafting outreach,
+qualifying/scoring, segmenting, and brief-shaping. To turn it into a true
+prospecting machine, plug **connectors** into the same `runAgent` flow — feed
+real candidates to the LLM for qualification + drafting instead of asking it to
+recall them. Suggested order:
+
+- **X / Twitter** — the agent already lives on X; reuse the OAuth token to search
+  bios/keywords/engagement for the workflow's signals (e.g. funds announcing
+  raises, projects teasing a TGE).
+- **Web / news** — the existing ChainGPT news webhook already surfaces funding
+  rounds, launches, and partnerships — gold for intent signals.
+- **On-chain** — new deployments, large raises, vesting contracts (Saleium fit).
+- **CRM sync** — push won/qualified leads out to HubSpot/Notion/Sheets, and
+  de-dupe against existing pipeline.
+
+The architecture is deliberately connector-shaped: `runAgent` builds a brief →
+gathers candidates → LLM qualifies + drafts → store. Today the "gather" step is
+the LLM; connectors slot in there without changing anything else.
+
+---
+
+## 7. Scaling, ops & safety (recommended next steps)
+
+- **Persistence**: JSON files are fine for the MVP and match the repo today.
+  Move to SQLite/Postgres once lead volume or concurrent writes grow.
+- **Rate / cost control**: each run costs ChainGPT credits; cap leads-per-run
+  and stagger cron schedules (the UI already defaults to every 6h).
+- **Human-in-the-loop**: keep outreach as *drafts* by default; require an
+  operator to approve/send. Add an opt-in "auto-send via X DM / email" later.
+- **Observability**: per-agent run history + last-error surface on the dashboard.
+- **Compliance**: respect platform ToS and anti-spam rules for any automated
+  outreach; throttle and personalize.
+- **Multi-tenant**: today one `PASSWORD_AUTH`. For a sales team, add per-user
+  accounts and assign agents/leads to owners.
+
+---
+
+## 8. Phased roadmap
+
+| Phase | Outcome |
+| --- | --- |
+| **0 — MVP (this PR)** | Deploy/manage agents from UI; LLM scouting → scored leads + outreach drafts; extensible registry. |
+| **1 — Real signals** | X + news connectors feed real candidates; de-dup; per-agent run history. |
+| **2 — Pipeline** | CRM sync, lead ownership, approve-and-send outreach, reply tracking. |
+| **3 — Scale** | DB-backed store, accounts/roles, analytics (conversion per workflow), A/B outreach. |
+
+---
+
+## 9. API quick reference
+
+All mutations require `Authorization: Bearer <PASSWORD_AUTH>`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/agents` | UI dashboard |
+| `GET` | `/api/agents` | list deployed agents |
+| `GET` | `/api/agents/products` | the product/workflow registry |
+| `GET` | `/api/agents/leads` | list leads (`?agentId=`/`?productId=`) |
+| `POST` | `/api/agents` | deploy an agent |
+| `POST` | `/api/agents/:id/run` | run a scouting pass now |
+| `PATCH` | `/api/agents/:id` | update / pause / resume |
+| `DELETE` | `/api/agents/:id` | decommission |
+| `PATCH` | `/api/agents/leads/:id` | update lead pipeline status |