Skip to content

Commit 9da3d4e

Browse files
tcconnallytcconnally
authored
Merge pull request #39: roadmap to 1.0 + dev handoff
docs: roadmap to a 1.0 release
2 parents 0bda8bd + ae35195 commit 9da3d4e

3 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎HANDOFF-DEV.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Plutus — Developer Handoff (continuing toward 1.0)
2+
3+
> For the next Claude Code instance (or human) picking up Plutus development.
4+
> Snapshot: **2026-06-23**, version **0.5.1**.
5+
6+
## One-line status
7+
The **billing engine** (`plutus_agent`) is live — on PyPI (`pip install plutus-agent`), GHCR, and deployed at **https://plutus.perseus.observer**. The self-serve loop (open signup → API key → `POST /v1/usage` → dashboard → Stripe upgrade) works end-to-end, and we're **dogfooding it on our own Hermes spend**. A deep code review is done; the path to 1.0 is in **[ROADMAP-1.0.md](ROADMAP-1.0.md)**.
8+
9+
## Where things live
10+
| | |
11+
|---|---|
12+
| Repo | `Perseus-Computing-LLC/plutus` (public, MIT) — `plutus_agent/` is the engine; `plutus.py`/`plutus_route.py` are the original monitor |
13+
| PyPI | `plutus-agent` |
14+
| Image | `ghcr.io/perseus-computing-llc/plutus:latest` (built on `v*` tag via `.github/workflows/release.yml`) |
15+
| Hosted | https://plutus.perseus.observer — container `plutus` on greg, `media-net`, port 8420, data vol `/data` |
16+
| Hosted DB | `/data/plutus.db` in-container (`PLUTUS_HOME=/data`); host: `/mnt/cache/appdata/plutus/data` |
17+
| Docs | `README.md`, `docs/api.md` (ingest API + SDK remote mode), `docs/auth.md`, `docs/claude-code.md` |
18+
19+
## What's done / live
20+
- v0.4.0 self-serve signup funnel · v0.5.0 ingest API (`POST /v1/usage`) + API keys + SDK remote mode · v0.5.1 Cloudflare-UA fix.
21+
- Hermes spend syncs into the dashboard via `examples/hermes_sync.py` on a **host-level cron** (every 15 min) — see `HANDOFF-HERMES-SYNC.md`.
22+
- 79 tests pass (`pytest tests/`). Production monitor untouched.
23+
24+
## The work queue (toward 1.0)
25+
The deep review filed **issues #26–#38**. Sequencing in `ROADMAP-1.0.md`:
26+
- **v0.6 — money & concurrency correctness (1.0 blocker):** #26 webhook idempotency (check-then-act → double-credit), #27 `/v1/usage` not atomic (partial-batch double-count), #30 sqlite concurrency (no `busy_timeout`, non-atomic `balance_after`, quota race), #29 credit from Stripe `amount_total` not metadata, #28 prepaid-credit hard-stop, #38 integer money. **#26/#27/#30 collapse into one "make ingest + webhook atomic + busy_timeout" change — start here.**
27+
- **v0.7 — security hardening (gates public launch):** #31 body-size cap, #32 CSRF + POST logout, #33 signup rate-limit, #34 report escaping, #35 SMTP TLS, #36 OIDC JWKS, #37 polish.
28+
- **v0.8 — Team tier ($149/mo) + LangChain/CrewAI/MCP integrations** (the revenue/distribution lever; can run in parallel).
29+
- **Do not launch publicly before v0.7** — open signup + live money are exposed.
30+
31+
## Critical gotchas (these will bite)
32+
1. **Hermes is NOT a separate box — it's containers on greg.** Reach it via `ssh greg` + `docker exec hermes …`. State.db: `/opt/data/webui/minions-hermes-config/state.db` (in-container).
33+
2. **greg uses HOST `docker compose`, not Dockge** (the dockge container isn't running). Redeploy: `docker compose -f /mnt/cache/appdata/stacks/plutus/compose.yaml pull/up -d --force-recreate plutus`. The `greg-deploy` skill's `docker exec dockge` path does **not** work here.
34+
3. **Cloudflare blocks the default `Python-urllib` User-Agent (error 1010).** Anything POSTing to the public URL with urllib must send a real `User-Agent` (fixed in 0.5.1). Internal service-to-service uses `http://plutus:8420` (same `media-net`), which bypasses CF.
35+
4. **Deployed image is still 0.5.0.** The 0.5.1 UA fix is client-side, so the server needs no redeploy — but **tag `v0.5.1`** to publish the fixed SDK to PyPI (external ingest is broken without it). Greg cron already uses the internal URL, so it's unaffected.
36+
5. **Unraid cron persistence:** host cron lives in `/boot/config/plugins/dynamix/*.cron` + `update_cron` → writes `/etc/cron.d/root`. Plain `crontab -l` reads the wrong spool; verify with `crontab -c /etc/cron.d -l`.
37+
6. **The dogfood ingest API key** lives only in the greg cron / dynamix file (and the operator's hands) — never commit it (public repo). Re-mint anytime: `docker exec plutus plutus keys create --name … --org "Perseus Computing"`.
38+
7. **Stripe is LIVE** on the hosted instance. Be careful with billing-path changes.
39+
40+
## Dev workflow
41+
- **Branch → PR → a human merges.** A safety classifier gates heavy/outward-facing actions — **merging to `main`, tagging/releasing, redeploying greg, and editing `~/.claude/settings.json` all require explicit per-action user authorization.** Don't expect to self-merge; prepare the PR and ask.
42+
- Tests: `pytest tests/` (stdlib `unittest`, fully offline). Keep them green.
43+
- Commit trailer: `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
44+
- Secrets come from env, never config/repo (`config._strip_env_secrets` enforces this on save).
45+
46+
## Verify it's healthy
47+
```bash
48+
curl -fsS https://plutus.perseus.observer/healthz # {"ok":true,"version":"0.5.x"}
49+
ssh greg 'docker ps --filter name=plutus --format "{{.Names}} {{.Status}}"'
50+
cd <repo> && pytest tests/ -q
51+
```
52+
53+
## Suggested first move
54+
Open the **v0.6 atomic-correctness PR** (#26/#27/#30 together): wrap `/v1/usage` ingest and webhook handling in single transactions, add `PRAGMA busy_timeout`, and make `balance_after`/quota checks atomic. It's the highest-leverage pre-launch work and makes "the money is correct" true.

‎ROADMAP-1.0.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Plutus — Roadmap to 1.0
2+
3+
> Last updated: 2026-06-23 · Current: **v0.5.1** (billing engine; PyPI + GHCR + live at plutus.perseus.observer)
4+
> This is the **billing-engine** roadmap. The older `ROADMAP.md` is the long-term monitor/FinOps vision.
5+
6+
## What 1.0 means
7+
8+
Plutus 1.0 is a **production-grade billing layer for AI agents** that a stranger can self-host or sign up for and trust with real money. That bar means four things, in priority order:
9+
10+
1. **Money is correct** — no double-credit, ingest is atomic, prepaid credit is enforceable, amounts reconcile with Stripe.
11+
2. **It's safe to expose publicly** — the self-serve funnel (open signup + ingest API + Stripe) is hardened against abuse, CSRF, DoS, and injection.
12+
3. **The product loop is complete** — signup → API key → meter → see spend → hit a limit → pay, with the tiers that actually sell (incl. a Team tier).
13+
4. **It's documented and stable** — API reference, self-host guide, SDK quickstarts, and a frozen public API + DB schema under semver.
14+
15+
We do **not** call it 1.0 until the money-correctness and public-exposure items below are closed, because open signup + live Stripe are already on.
16+
17+
---
18+
19+
## Milestones
20+
21+
### v0.6 — Money & concurrency correctness *(1.0 blocker)*
22+
The deep-review findings that can corrupt billing data. Root cause for most: read-modify-write with no atomic transaction under the threaded, connection-per-request server.
23+
- **#27** make `/v1/usage` atomic per request (validate-all → one transaction → commit once)
24+
- **#26** webhook idempotency: insert the dedup row *first*, apply side-effect only if newly inserted
25+
- **#30** `PRAGMA busy_timeout`, atomic `balance_after`, fix the free-tier quota race
26+
- **#29** credit from Stripe `amount_total`, never client metadata
27+
- **#28** prepaid-credit hard-stop policy (stop debiting past zero; opt-in 402)
28+
- **#38** store money as integer micro-dollars (schema migration) — do before freeze
29+
- *Exit:* a concurrency/load test on the ingest + webhook paths proves no double-count, no lost writes, correct balances.
30+
31+
### v0.7 — Security hardening *(1.0 blocker — gates public launch)*
32+
- **#31** request body-size cap on `/v1/usage` + `/webhook/stripe` (DoS)
33+
- **#32** CSRF tokens on state-changing POSTs; make logout a POST
34+
- **#33** signup rate limiting + per-day org cap (abuse)
35+
- **#34** escape attacker-controlled names in HTML/PDF reports
36+
- **#35** SMTP: TLS-only login, 465 support
37+
- **#36** OIDC JWKS signature verification (defense-in-depth)
38+
- **#37** polish punch-list (error-leak, 404 escaping, hook backup, etc.)
39+
- *Exit:* an external security-review pass on the public surface.
40+
41+
### v0.8 — Product completeness *(what makes it sell)*
42+
- **Team tier (~$149/mo)** — multi-seat, more workspaces, the missing money tier (drives ramen MRR).
43+
- Per-org credit-enforcement policy (the #28 hard-stop, surfaced in dashboard + API).
44+
- **Usage export** — CSV + webhook out (cost-attribution / "$/task" for customers' own billing).
45+
- **First-class integrations** — LangChain & CrewAI callback handlers, and a Plutus **MCP server** so agents meter themselves.
46+
- Dashboard: date-range selector, per-workspace drill-down, API-key last-used/usage view.
47+
48+
### v0.9 — Hardening, observability & docs
49+
- Structured request logging + a `/metrics` endpoint; per-request ids.
50+
- Full docs site: **API reference**, self-host guide, SDK quickstarts (Python now; TS later), migration notes.
51+
- Backup/restore + schema-migration tooling for self-hosters.
52+
- Soak-test the hosted instance; define SLOs.
53+
54+
### v1.0 — Freeze & launch
55+
- **Freeze the public API + DB schema**; commit to semver.
56+
- Public **status page**; documented upgrade path.
57+
- Cut 1.0, then run the launch (below).
58+
59+
---
60+
61+
## Get it out there *(parallel GTM track — start now)*
62+
63+
Already done: README reframed, `pip install plutus-agent`, GHCR image, hosted dashboard, Hermes dogfooding live.
64+
65+
**Pre-launch (do alongside v0.6/v0.7):**
66+
- Merge + release the **v0.5.1 Cloudflare-UA fix** (#PR 25) — external SDK ingest is broken through CF without it; hard launch blocker.
67+
- Turn on `PLUTUS_ALLOW_SIGNUP` on the hosted instance once v0.7 abuse controls land.
68+
- Launch assets: a 60-second "meter your agent in 3 lines" asciinema/GIF, dashboard screenshots, polish `/pricing`, a landing section on perseus.observer/plutus.
69+
- A short **"Plutus vs Helicone / Langfuse / OpenMeter"** positioning post — own *billing* (charging end-users), not just observability.
70+
71+
**Launch (after v0.7):**
72+
- Show HN, r/LocalLLaMA, MCP/agent-framework communities; list in LangChain/CrewAI integration directories.
73+
- First 5 design-partner orgs from the warm network; 1–2 reference customers billing their own users through Plutus.
74+
75+
**Don't launch publicly before** the v0.7 items (CSRF, body limits, signup rate-limit) — open signup + live money are exposed today.
76+
77+
---
78+
79+
## Success metrics for 1.0
80+
| Metric | Now | 1.0 target |
81+
|---|---|---|
82+
| Money-correctness bugs (open) | 5 | 0 |
83+
| Public-surface security findings (open) | 7 | 0 |
84+
| Paying orgs | 1 (us) | 10+ |
85+
| First-class integrations | adapters + hook | + LangChain, CrewAI, MCP |
86+
| API stability | unfrozen | frozen, semver |
87+
| Docs | README + 3 docs | full reference + guides |
88+
89+
## Sequencing note
90+
v0.6 and v0.7 are the 1.0 blockers and should land before any public push — they're tracked as issues #26–#38. v0.8 (Team tier + integrations) can proceed in parallel since it's the revenue/distribution lever from the profitability plan. The fastest credible path: **v0.6 money-correctness as one focused sprint (it's mostly one transaction-shaped fix), then v0.7 security, launching as v0.7 ships and tagging 1.0 once v0.8 + docs settle.**

‎ROADMAP.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Plutus Roadmap
22

3+
> **For the active path to a 1.0 release of the billing engine, see [ROADMAP-1.0.md](ROADMAP-1.0.md).**
4+
> This document is the longer-term monitor/FinOps vision.
5+
36
> Last updated: 2026-06-19 · Horizon: 12 months
47
58
## What Plutus Is

0 commit comments

Comments
 (0)