💡 The Problem & Solution

Developing autonomous agents that securely communicate and transact on-chain requires massive boilerplate. Croo Core provides a unified SDK wrapper for the entire Constellation agent suite. It abstracts away the complexity of A2A (Agent-to-Agent) communication, cryptographic signing, and wallet integration, allowing agent developers to focus on specialized logic rather than infrastructure.

Key Features:

• 🔌 Unified Interface: A single, consistent API for interacting with the entire Croo ecosystem.
• 🔐 Secure Execution: Built-in support for wallet connections and cryptographic verification.
• ⚡ A2A Networking: Seamless peer-to-peer communication between distinct AI agents.
• 🔄 Active State Recovery: Automatically scans and resumes in-flight paid orders on boot, ensuring no lost actions.
• ❌ Active Rejections: Instantly rejects unmatched negotiations instead of letting them silently time out.
• 💼 Dynamic Payout Wallets: Supports redirecting incoming fee revenue directly to custom wallet destinations.
• 🚀 Fast Failover Race: Requester-side races order completion against rejection/expiration events for immediate error cascading.

🌌 The Constellation Ecosystem

This core SDK powers a suite of 6 specialized reference agents that form a secure, autonomous ecosystem. For a deep-dive into how these agents compose to form orchestrated, quality-gated workflows, read the CROO Constellation Portfolio.

• Worker: Research provider (top of the pipeline)
• Summon: Human-in-the-loop sign-off agent
• Maestro: Callable multi-agent orchestrator
• Litmus: Output-grading quality gate
• Gauntlet: Paid adversarial certification agent
• Goldilocks: Data-backed pricing oracle

Every arrow below is a real CAP order settled in USDC on Base — croo-core provides the hire() (requester) and runProvider() (provider) primitives, plus escrow-safe SLA refunds and a deterministic mock mode shared by all six agents.

graph LR
    User([Any Agent / User]) -->|hires| M[Maestro 🎼]
    M -->|research| W[Worker 🛠️]
    M -->|grade ×2| L[Litmus 🧪]
    M -->|human sign-off| S[Summon 👤]
    G[Gauntlet 🧤] -.->|certifies| M
    G -.->|certifies| W
    G -.->|certifies| L
    G -.->|certifies| S
    GL[Goldilocks 🧈] -->|prices| Store[(Agent Store)]
    W -.->|uses| C{{croo-core ⚙️}}
    M -.->|uses| C
    L -.->|uses| C
    S -.->|uses| C
    G -.->|uses| C
    GL -.->|uses| C
    classDef hot fill:#F59E0B,stroke:#111,color:#111,font-weight:bold;
    class C hot;

🔗 Live Run Log — Constellation Totals (Base Mainnet)

Aggregate of real CAP orders across every agent built on this SDK during the hackathon. Each agent's own README has its per-order table with BaseScan tx links.

Total real CAP orders: 0 · last updated: 2026-06-_

| Agent | Real CAP orders | A2A counterparties | |-------|-----------------|--------------------| | Worker 🛠️ | 0 | Maestro | | Maestro 🎼 | 0 | Worker, Litmus, Summon | | Gauntlet 🧤 | 0 | targets, Maestro, Litmus, Summon | | Summon 👤 | 0 | Maestro, external bots | | Litmus 🧪 | 0 | Maestro, external | | Goldilocks 🧈 | 0 | external | | Total | 0 | |

Delete this note once populated.

🏗️ Architecture & Tech Stack

| Layer | Technology | |---|---| | Runtime | Node.js (TypeScript) | | Ecosystem | Constellation A2A | | Testing | Vitest |

🚀 Getting Started

Prerequisites

• Node.js ≥ 20
• npm

Installation

1. Clone: git clone https://github.com/edycutjong/croo-core.git
2. Enter the directory: cd croo-core
3. Install: npm install
4. Build: npm run build

Usage (consumed by every agent)

import { makeClient, runProvider, hire, isMockMode } from '@edycutjong/croo-core';

// Provider side (Summon, Litmus, Gauntlet, Goldilocks, Maestro):
const client = makeClient(process.env.CROO_SDK_KEY!);
await runProvider(client, { serviceMatch, work, slaGuardMs: 60_000 });

// Requester side (Maestro, Gauntlet):
const { delivery } = await hire(client, { serviceId, requirement, maxPrice: 1.0 });

Set CROO_MOCK=true and every consumer runs fully offline — no wallet, no USDC, no WebSocket — which is how all five agents reproduce their flows in CI and local demos.

🧩 Exported SDK Surface

croo-core is a thin, shared wrapper over @croo-network/sdk so every agent in the Constellation uses one config and one code path.

| Export | Kind | Purpose | |---|---|---| | makeClient(sdkKey, overrides?) | function | Instantiates the shared CROO AgentClient with Base Mainnet defaults (DEFAULT_CONFIG); only the SDK key differs per agent. Returns the underlying SDK client augmented with getSharedStream() / disconnect(). | | runProvider(client, opts) | function | Provider loop — subscribes to order/negotiation events, matches services, performs the work, and delivers. Used by all five agents. | | hire(client, opts) | function | Requester side — places an order against another agent and awaits delivery (A2A). Used by Maestro & Gauntlet. | | isMockMode() | function | Reports whether CROO_MOCK=true — lets consumers branch to offline execution. | | resetMockState() | function | Test helper — clears in-memory mock ledger between runs. | | EventType | enum | Order/negotiation event kinds for routing SDK stream events. | | DeliverableType | enum | Deliverable typing (deliverableType / deliverableText). | | DEFAULT_CONFIG | const | Base Mainnet baseURL / wsURL / rpcURL shared by every agent. |

Underlying @croo-network/sdk client methods used across the Constellation: getNegotiation, getDownloadURL, uploadFile, rejectOrder, plus the croo-core stream wrapper getSharedStream / disconnect.

🧪 Testing & CI

4-stage pipeline: Quality → Security → Build → Deploy Gate

# ── Code Quality ────────────────────────────
make lint          # ESLint
make typecheck     # TypeScript check
make test          # Run tests
make test-coverage # Coverage report
make ci            # Full quality gate

# ── Security ────────────────────────────────
make security-scan # npm audit + license check

| Layer | Tool | Status | |---|---|---| | Code Quality | ESLint + TypeScript | ✅ | | Unit Testing | Vitest (73 tests) | ✅ | | Security (SAST) | CodeQL | ✅ | | Security (SCA) | Dependabot + npm audit | ✅ | | Secret Scanning | TruffleHog | ✅ |

📦 Releasing

Publishing is tag-driven — CI publishes to npm only when a v* tag is pushed (.github/workflows/publish.yml). Versioning is deliberate; there is no auto-increment on every commit.

npm version patch        # or minor / major — bumps package.json + creates tag v0.1.1
git push --follow-tags   # pushes the commit AND the tag → triggers the publish workflow

The workflow re-runs lint + typecheck + the 100% coverage gate + build, verifies the tag matches package.json, then runs npm publish --provenance --access public.

One-time setup: add an npm automation token as the NPM_TOKEN repository secret (Settings → Secrets and variables → Actions). Provenance requires a public repo.

📁 Project Structure

croo-core/
├── docs/              # README assets (hero, screenshots)
├── src/               # Application source code
├── __tests__/         # Vitest test suites
├── .github/           # CI workflows
└── README.md          # You are here

📄 License

MIT © 2026 Edy Cu

🙏 Acknowledgments

Built for the DoraHacks CROO Hackathon 2026.