🚀 Hermes Commerce Runtime

Three submissions to the Hermes Agent Accelerated Business Hackathon — built on a single TypeScript runtime that demonstrates the published brief: agents that earn, spend, provision their own SaaS, and run real operations at any scale.

---

🧭 The Trilogy

	🚢 Conduct	🚛 Waybill	🧭 Helm
Domain	B2B Accounts-Receivable / dunning	Freight brokerage / load dispatch	Solopreneur ops board (CFO · Growth · Ops)
Earn	Stripe Checkout pi_* per-invoice	3% margin per booked load	$99/mo Billing subscription per tenant
Spend	Twilio SMS, Postmark, Stripe smart_retries	Dat credits, Twilio driver SMS, fuel cards	Twilio SMS, contractor Connect payouts
Provision	Per-customer Postmark sender domain	Per-shipper Connect sub-account + Issuing card	Per-tenant Connect + Twilio number + Resend
Safety	B2B-only gate · harassment-word hard-block	FMCSA authority gate · 7-day payout hold	Default-deny social publish · $50 spend cap
README	→ conduct/	→ waybill/	→ helm/

All three run on the same src/runtime/ — agent loop, NemoClaw policy engine, Nemotron client, Stripe kit, append-only ledger.

---

⚡ Quick start

git clone <this-repo>
cd hermes-hackathon
npm install
npm run demo:conduct   # → .ledgers/conduct.ndjson
npm run demo:waybill   # → .ledgers/waybill.ndjson
npm run demo:helm      # → .ledgers/helm.ndjson

Each demo runs end-to-end in mock mode with no API keys. To go live with real NVIDIA models, copy .env.example → .env, add your NVIDIA key, and flip the live flag:

HERMES_USE_LIVE=1                                                  # required to leave mock mode
NVIDIA_NIM_API_KEY=nvapi-…
NEMOTRON_MODEL=nvidia/nemotron-3-ultra-550b-a55b                   # real 550B generation
NEMOTRON_SAFETY_MODEL=nvidia/llama-3.1-nemotron-safety-guard-8b-v3 # real GA safety NIM
NOUS_API_KEY=…                                                     # Nous Portal (Hermes-4) reasoning
NOUS_MODEL=Hermes-4-405B
STRIPE_SECRET_KEY=sk_test_…                                        # optional; mock if absent
STRIPE_PROJECTS_LIVE=1                                             # opt-in: real `stripe projects` provisioning

HERMES_USE_LIVE=1 npm run demo:conduct                            # or film:conduct (recorded cut)

In live mode the four sponsor rails are real calls, not mocks:

• Nemotron 3 Ultra (550B) drafts every outbound message — integrate.api.nvidia.com/v1/chat/completions.
• nvidia/llama-3.1-nemotron-safety-guard-8b-v3 screens each draft with the model's documented prompt template and returns a {"User Safety": …} verdict before any external call.
• Hermes-4-405B (Nous Portal, inference-api.nousresearch.com/v1) produces the agent's think → act decision each turn — the NousResearch pillar.
• Stripe Projects (stripe projects add twilio/sms) provisions the agent's own SaaS and syncs credentials; Stripe SDK moves the money.

Every one of those live HTTP calls is forced through the NemoClaw / OpenShell egress allow-list (src/runtime/nemo-shell.ts) — an injected "exfiltrate to evil.com" fails at the sandbox boundary, not at a downstream check. This is what powers the on-camera guardrail in the demo videos (videos/*.mp4).

---

🤖 Run inside Hermes Agent (as installable skills)

All three ship as real Hermes Agent skills in the agentskills.io / Hermes SKILL.md format — they run inside the host platform, as slash commands or scheduled blueprints, not just as standalone demos.

hermes skills install ./skills/commerce/conduct   # → ~/.hermes/skills/commerce/conduct
hermes skills install ./skills/commerce/waybill
hermes skills install ./skills/commerce/helm
hermes skills list

/conduct  chase the overdue BlueDoor invoice
/waybill  book Chicago → Dallas, reefer, 38k lbs, pickup tomorrow 7am
/helm     run the Monday board and show me the approval digest

Each declares a metadata.hermes.blueprint cron (conduct weekday 9am, waybill hourly business-hours, helm Monday 9am) so the agent can run them unattended. Full details: skills/ · docs/HERMES_SKILLS.md.

---

🏗️ Architecture (one runtime, three products)

                ┌──────────────────────────────────────────────────┐
                │             src/runtime — shared engine           │
                │                                                  │
                │  ┌────────────┐  ┌────────────┐  ┌────────────┐  │
                │  │ NemoClaw   │  │ Nemotron   │  │ Stripe Kit │  │
                │  │ policy gate│→ │ 3 Ultra    │→ │ Connect    │  │
                │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  │
                │        │               │               │         │
                │        ▼               ▼               ▼         │
                │  ┌────────────────────────────────────────────┐  │
                │  │   append-only ledger  (.ledgers/*.ndjson)  │  │
                │  └────────────────────────────────────────────┘  │
                └──────────────────────────────────────────────────┘
                                  ▲
                                  │ (one policy set per project)
            ┌─────────────────────┼─────────────────────┐
            │                     │                     │
       ┌────┴─────┐          ┌─────┴────┐          ┌─────┴────┐
       │ conduct/ │          │ waybill/ │          │  helm/   │
       │ policy.ts│          │ policy.ts│          │ policy.ts│
       │ prompts  │          │ prompts  │          │ prompts  │
       │ demo.ts  │          │ demo.ts  │          │ demo.ts  │
       └──────────┘          └──────────┘          └──────────┘

• policy.ts — NemoClaw rule set (one predicate per rail)
• prompts.ts — Nemotron system + user prompt templates
• demo.ts — CLI entry that runs one full earn → spend → provision cycle
• README.md — you are here × 4

---

🛡️ How safety works (NemoClaw)

Every external action — earn, spend, provision, even a draft send — flows through PolicyEngine.evaluate(_policies, ctx) before a single byte leaves the box. Text-bearing actions (emails, social posts, dispatches) are additionally screened by NVIDIA's real nvidia/llama-3.1-nemotron-safety-guard-8b-v3 model (src/runtime/nemo-guard.ts) in live mode — using the model's documented prompt template and parsing its {"User Safety": …} JSON verdict — with a deterministic keyword fallback in mock mode. Every live model/provisioning call is itself wrapped by the NemoClaw egress allow-list (src/runtime/nemo-shell.ts), so the agent can only reach approved hosts.

If the policy set returns severity="deny" — or NVIDIA content-safety returns unsafe — the request is logged into the ledger as policy-deny and the external call never happens. This is what makes the runtime Hermes-grade safe to demo: the largest possible mistake surfaces as a yellow ⚠ or a red ✖ in the terminal, not as a tweeted disaster.

Deny stories baked into each demo's step ⑦:

• Conduct — hand-crafts a "lawsuit"-bearing dunning email and shows NemoClaw refusing it.
• Waybill — calls fmcsaCompliance with mcAuthorityVerified:false and shows the regulatory refuse.
• Helm — shows the default-deny social-publish path with a yellow approval audit row.

---

📦 Repo layout

.
├─ README.md              ← you are here
├─ package.json           ← three demo scripts (demo:conduct/waybill/helm) + typecheck
├─ tsconfig.json          ← ES2022, strict, noUncheckedIndexedAccess
├─ .env.example           ← STRIPE_SECRET_KEY, NVIDIA_NIM_API_KEY
├─ .gitignore
│
├─ src/runtime/           ← shared engine
│   ├─ types.ts           ← Earning/Spend/Provision/PolicyContext
│   ├─ ledger.ts          ← NDJSON append-only audit log
│   ├─ nemo-claw.ts       ← PolicyEngine + predicate helpers
│   ├─ nemo-shell.ts      ← NemoClaw/OpenShell egress allow-list (guardedFetch)
│   ├─ nemo-guard.ts      ← live + mock NVIDIA content-safety NIM (real prompt template)
│   ├─ nemotron.ts        ← live + mock Nemotron 3 Ultra client
│   ├─ hermes.ts          ← live + mock Nous Portal (Hermes-4) reasoning client
│   ├─ stripe-kit.ts      ← live + mock Stripe (Connect, Issuing, checkout)
│   ├─ stripe-projects.ts ← live + mock Stripe Projects CLI (provision SaaS, sync creds)
│   ├─ loop.ts            ← buildRuntime() — earn/spend/provision/gateOne
│   └─ index.ts
│
├─ conduct/               ← submission #1 · B2B AR agent
├─ waybill/               ← submission #2 · freight broker
└─ helm/                  ← submission #3 · solopreneur board

---

🎯 Why these three?

We read 47 existing submissions and applied the Council framework (Musashi × Sun Tzu × Torvalds × Munger × Rams) before committing. The three lanes we picked sit in wide-open green zones on the published brief — nobody else is doing B2B AR with NemoClaw, nobody else is doing freight brokerage with per-load Stripe Connect + Issuing, nobody else is doing a subagent board with default-deny social for solopreneurs.

• 🟢 B2B AR / collections — Stripe Invoicing + smart_retries + Nemotron-drafted escalation = an obvious wedge for the 73M US SMBs.
• 🟢 Freight broker — $1T+ US market, zero hackathon entries in the load-board / 3PL space. Physical-world money flow that Stripe handles natively.
• 🟢 Solopreneur board — fragmented positioning in the field; we crystallize it as "you + your AI team, $99/mo."

---

📊 Submission posture vs the published brief

Brief criterion	🚢 Conduct	🚛 Waybill	🧭 Helm
Earn — real revenue proof	🟢🟢	🟢🟢🟢	🟢🟢
Spend — real money out	🟢	🟢🟢🟢	🟢🟢
Provision its own SaaS per task	🟢	🟢🟢🟢	🟢🟢
NemoClaw (safety)	🟢🟢🟢	🟢🟢	🟢🟢
Nemotron 3 Ultra (intelligence)	🟢🟢	🟢🟢	🟢🟢
Stripe earn + spend + provision — all three	🟢	🟢🟢🟢	🟢🟢
"Fully automated company" archetype	❌	✅	❌
"Framework for enterprise functions" archetype	✅✅✅	🟡	✅✅✅

---

🧪 Test it yourself

npm run typecheck                                # tsc --noEmit (strict mode)
npm run demo:conduct 2>&1 | tee .ledgers/.stdout # full B2B AR tick

Inspect the audit ledger:

tail -f .ledgers/conduct.ndjson | jq .

Every earn · spend · provision · deny leaves a row. This is the operating record.

---

🪪 License & team

MIT. Built in <7 days for the Hermes Agent Accelerated Business Hackathon. All money in the demo ledger is mock unless you set STRIPE_SECRET_KEY and NVIDIA_NIM_API_KEY. By design.