Skip to content

AgentaFlow/premiumsoul

BranchesTags

Repository files navigation

premiumsoul

The Curated Agent Exchange (CAX) — A verified marketplace and reputation system for specialized agent SOUL files and configurations in the OpenClaw ecosystem.

Overview

PremiumSoul solves the "Wild West" problem of agent discovery. Instead of hunting through unvetted GitHub repositories, developers and end-users can browse a curated registry of Skill-Soul Bundles: pre-configured, security-verified agent packages that are ready to deploy.

The project is split into two layers:

Layer Repo License
Trust Layer (this repo) premiumsoul MIT
Value Layer premiumsoul-valuelayer Proprietary

The Trust Layer runs fully standalone. The Value Layer (@premiumsoul/valuelayer) is an optional runtime dependency that activates Stripe payments, S3 artifact storage, and the Docker runtime sandbox when installed.

Core Concepts

Concept Description
Skill What an agent does — a set of MCP-compliant tools (e.g. scraping, coding, CRM integration)
Soul Who an agent is — persona, ethics rules, tone and decision-making heuristics
Bundle A packaged Skill + Soul pair, optionally awarded a Security Seal after sandbox verification
Registry The public marketplace where bundles are listed, rated and installed

Features

1. Skill-Soul Bundle Marketplace

Register discrete Skills (MCP tool definitions + Python hooks) and Souls (system prompts + ethics rules), then combine them into deployable Bundles that appear in the marketplace.

  • JWT-authenticated authorship with creator / consumer / admin roles
  • Semantic versioning (1.2.0) on Skills — publish, list, and deprecate versions via the API
  • Star ratings, text reviews, and install-count tracking
  • Tag-based, category-based, and verified-only filtering
  • Bundled pricing (priceCents) with free-tier support

2. Behavioral Sandbox (Security Verifier)

Every skill can be run through the Verification Pipeline before being awarded a Security Seal. The pipeline performs static analysis of the skill's Python hook and flags:

  • Phone-home attempts — outbound network calls using requests, urllib, httpx, raw socket, etc. Calls to known malicious destinations (e.g. webhook.site, ngrok.io) are blocked and cause an immediate failure.
  • Permission creep — sudo invocations via os.system / subprocess, access to /etc/ or /root/, native library loading via ctypes, and deletion of system paths.

All verification runs are stored in a VerificationHistory audit trail. Pipeline events (seal:awarded, seal:rejected) are emitted via an EventEmitter for downstream webhook or queue integration.

Bundles whose underlying skill passes the sandbox check are awarded a ✅ Security Seal.

Phase 2 (Docker runtime scan): When @premiumsoul/valuelayer is installed, the pipeline can be extended to run the Python hook inside an isolated Docker container for dynamic analysis.

3. No-Code MCP Skill Builder

Describe a task in plain English and the MCPSkillBuilder automatically generates:

  • A structured SKILL.md document
  • An MCP-compliant MCPManifest (JSON) with typed input schemas
  • A stub Python hook wired to the MCP stdio server interface
  • A Skill record that is immediately registered in the registry

Example input:

{
  "taskDescription": "Read CRM data and post summaries to Slack",
  "dataSources": ["CRM"],
  "outputTargets": ["Slack"],
  "authorName": "Alice"
}

4. Search & Discovery

  • Full-text search — GET /api/v1/registry/search?q=finance&category=data-processing&verified=true
  • Featured listings — curated set surfaced via GET /api/v1/registry/featured
  • Trending listings — algorithmically ranked by installs, rating and recency via GET /api/v1/registry/trending
  • Price range and minimum-rating filters

5. Creator Profiles & Reputation

  • Public creator profiles with aggregate stats (skills published, total installs, average rating)
  • Private analytics endpoint (own account or admin only) — revenue, install breakdown, rating histogram
  • Editable profile fields: display name, bio, avatar URL, website

6. Agent-to-Agent (A2A) Handshake Protocol

The @premiumsoul/a2a-handshake package (MIT) provides cryptographic identity verification between agents:

  • Ed25519 / RSA challenge-response key pairs
  • Capability manifests and compatibility checking
  • Trust-level negotiation: unverified → community-verified → registry-verified
import { a2aVerify, generateEd25519KeyPair, buildCapabilityManifest } from "@premiumsoul/a2a-handshake";

const result = await a2aVerify(initiatorAgent, responderAgent, { ... });
console.log(result.negotiatedTrustLevel); // "registry-verified"

7. CLI Tools

Tool Description
cax Browse, install, scan and publish skills from the terminal. Supports login, whoami, search, install, scan, publish.
claw-check Local static analysis for SKILL.md files and Python hooks. Supports scan, validate, report.

8. Payments & Artifact Storage (Value Layer)

These features are active only when @premiumsoul/valuelayer is installed and the relevant environment variables are set.

  • Stripe Connect — creators onboard via POST /api/v1/creators/onboard; buyers purchase via POST /api/v1/registry/:id/purchase (Stripe Checkout)
  • Stripe webhooks — processed at POST /api/v1/webhooks/stripe
  • S3 artifact storage — skill markdown and Python hook artifacts are uploaded to S3 on publish and served via signed download URLs (GET /api/v1/registry/:id/download)

Getting Started

Prerequisites

  • Node.js ≥ 18
  • npm ≥ 9
  • Docker & Docker Compose (for production deployment or local PostgreSQL)

Install

npm install

Environment variables

Copy .env.example to .env and set at minimum:

DATABASE_URL=file:./dev.db          # SQLite for local dev; use postgresql:// for prod
JWT_SECRET=change-me-in-production
PORT=3000

Optional variables (activate Value Layer features when set):

STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
S3_BUCKET=my-bucket
S3_REGION=us-east-1
S3_ENDPOINT=                        # set for MinIO / LocalStack
CORS_ORIGINS=https://app.example.com
LOG_LEVEL=info
BCRYPT_ROUNDS=12

Database setup

npm run db:push        # create / migrate the SQLite dev database

Run (development)

npm run dev
# Server listening on http://localhost:3000

Build

npm run build
npm start

Test

npm test

Lint

npm run lint

Docker (production)

# Start the full stack (app + PostgreSQL 16 + Redis)
npm run docker:prod

# View logs
npm run docker:logs

# Tear down
npm run docker:down

API Reference

All endpoints are prefixed with /api/v1.

Auth

Method Path Auth Description
POST /auth/register — Register (email, password, role)
POST /auth/login — Login → { accessToken, refreshToken }
POST /auth/refresh — Exchange refresh token for new tokens
GET /auth/me Bearer Current user info
POST /auth/api-key Bearer Regenerate API key

Skills

Method Path Auth Description
POST /skills Bearer Register a new skill
GET /skills — List all skills
GET /skills/:id — Get a skill by ID
POST /skills/:id/verify admin Run the verification pipeline
POST /skills/:id/versions creator Publish a new semantic version
GET /skills/:id/versions — List all versions of a skill
POST /skills/:id/versions/:version/deprecate creator Deprecate a specific version

Souls

Method Path Auth Description
POST /souls Bearer Register a new soul
GET /souls — List all souls
GET /souls/:id — Get a soul by ID

Bundles

Method Path Auth Description
POST /bundles Bearer Create a skill-soul bundle
GET /bundles — List all bundles
GET /bundles/:id — Get a bundle by ID
POST /bundles/:id/seal admin Run sandbox & award Security Seal

Registry / Marketplace

Method Path Auth Description
POST /registry/publish/:bundleId creator Publish a bundle to the marketplace
GET /registry — Browse listings (?verified=true, ?tag=finance)
GET /registry/search — Full-text search (?q=, ?category=, ?tag=, ?minPrice=, ?maxRating=)
GET /registry/featured — Curated featured listings
GET /registry/trending — Trending listings (?limit=20)
GET /registry/:id — Get a listing by ID
POST /registry/:id/install Bearer Record an install
POST /registry/:id/rate Bearer Submit a star rating ({ "stars": 4 })
POST /registry/:id/review Bearer Submit a text review ({ "text": "...", "stars": 5 })
GET /registry/:id/reviews — List reviews for a listing
POST /registry/:id/purchase Bearer Start a Stripe Checkout session (Value Layer)
GET /registry/:id/download Bearer Download skill artifacts (purchase required for paid listings)

Creator Profiles

Method Path Auth Description
POST /creators/onboard creator Start Stripe Connect onboarding (Value Layer)
GET /creators/:id — Public creator profile
GET /creators/:id/analytics self or admin Revenue, installs, rating breakdown
PATCH /creators/:id self or admin Update display name, bio, avatar, website

No-Code Builder

Method Path Auth Description
POST /builder/skill Bearer Generate and register a complete MCP skill artifact

Builder request body

{
  "taskDescription": "Read CRM data and post summaries to Slack",
  "dataSources": ["CRM"],
  "outputTargets": ["Slack"],
  "requiredPermissions": ["read", "network"],
  "authorName": "Alice"
}

System

Method Path Description
GET /health Liveness probe ({ status: "ok" })
GET /metrics Prometheus metrics (prom-client)
GET /api-docs Swagger UI (OpenAPI spec)

Project Structure

src/
  config.ts         Environment variable configuration
  errors.ts         Typed application error classes
  index.ts          Server entry-point
  api/
    routes.ts       All Express route handlers
    server.ts       App factory (middleware, Swagger, metrics, webhooks)
  auth/
    service.ts      JWT auth, bcrypt, API key management
    middleware.ts   requireAuth / requireRole guards
  db/
    client.ts       Prisma client (SQLite ↔ PostgreSQL adapter)
  mcp/              MCPSkillBuilder — no-code MCP artifact generator
  middleware/
    validation.ts   Zod request validation middleware
  models/           Core TypeScript data models (Skill, Soul, Bundle, …)
  monitoring/
    metrics.ts      Prometheus counters, histograms, gauges
  registry/
    registry.ts     AgentRegistry — Prisma-backed data access
    creators.ts     Creator profiles, analytics, reviews
    search.ts       Full-text search, featured, trending algorithms
  security/
    sandbox.ts      BehavioralSandbox — static-analysis skill verifier
    pipeline.ts     Verification pipeline with EventEmitter + audit history

prisma/
  schema.prisma     Database schema (SQLite / PostgreSQL)

packages/
  a2a-handshake/    @premiumsoul/a2a-handshake — A2A identity & trust protocol

cli/
  cax/              `cax` CLI — browse, install, publish from the terminal
  claw-check/       `claw-check` CLI — local static analysis for SKILL.md files

spec/
  SKILL-SCHEMA.md   Skill schema documentation
  SOUL-SCHEMA.md    Soul schema documentation
  skill.schema.json Skill JSON Schema
  soul.schema.json  Soul JSON Schema

web/                Next.js frontend (marketplace UI)

tests/
  registry.test.ts
  sandbox.test.ts
  builder.test.ts
  api.test.ts
  auth.test.ts
  creators.test.ts
  search.test.ts
  versioning.test.ts

License

MIT

About

Vetted Skill Registry for the OpenClaw ecosystem

Topics

openclaw

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages