Skip to content

welshDog/HyperAgent-SDK

BranchesTags

Repository files navigation

🤖 HyperAgent-SDK

Write Agents Once. Deploy Anywhere.

License: AGPL v3 npm Made by WelshDog Part of Hyperfocus Zone CLI

"The agent toolkit behind the Hyperfocus Zone — plug in, vibe out."

HyperAgent-SDK is the orchestration layer for AI agents across the Hyperfocus Zone ecosystem. Build once, deploy across Discord bots, FastAPI backends, and course platforms. 🧩

Built for ADHD brains. Fast feedback. Real tools. No fluff. 🧠⚡

⚡ Install

# Validate an agent instantly (no install needed)
npx @w3lshdog/hyper-agent validate .agents/my-agent/

# Install as a dev dependency (for CI pipelines)
npm install -D @w3lshdog/hyper-agent

🚀 Quick Start — Build Your First Agent

1️⃣ Scaffold from a starter template

# pick one: python | node | typescript | mcp
npx @w3lshdog/hyper-agent init my-agent --template python

This copies the template, renames manifest.name + package.json to match your dir, and prints the next steps.

2️⃣ Edit your manifest.json

{
  "name": "my-broski-agent",
  "version": "0.1.0",
  "runtime": "python",
  "entrypoint": "main.py",
  "memory": "redis",
  "tools": [
    {
      "name": "code_gen",
      "description": "Generate code from a natural language prompt",
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": { "type": "string", "description": "What to build" }
        },
        "required": ["prompt"]
      }
    }
  ],
  "mcp_compatible": false
}

3️⃣ Full workflow

# Validate (with friendly error hints — kebab-case, semver, port range, etc.)
npx @w3lshdog/hyper-agent validate ./my-agent

# Strict mode (CI/production — checks entrypoint exists, env vars, port conflicts)
npx @w3lshdog/hyper-agent validate ./my-agent --strict

# Check memory health
npx @w3lshdog/hyper-agent memory check ./my-agent

# Build registry then launch Studio
hyper-agent registry build .agents/
hyper-agent studio
# → http://localhost:4040 opens automatically 🖥️

🔁 Token Sync (Course → V2.4) — awardFromCourse()

The SDK ships a typed, server-only helper for the cross-repo token sync flow:

import { awardFromCourse } from '@w3lshdog/hyper-agent/client';

const result = await awardFromCourse({
  sourceId:  txn.id,                  // ≤128 chars, idempotency key
  discordId: user.discord_id,         // ≤32 chars
  tokens:    50,                      // integer 1..10000
  reason:    'Course module complete' // optional, ≤255 chars
});
// → 200: { source_id, awarded, coins_balance, xp_balance, level }
// → 409: { source_id, duplicate: true, detail }   (idempotent replay — no double award)
// → throws AwardFromCourseError                   (validation/timeout/4xx/5xx, with .code + .status)

Defaults: baseUrl = process.env.HYPERCODE_API_URL || 'http://localhost:8000', secret = process.env.COURSE_SYNC_SECRET, timeoutMs = 5000 (via AbortController).

Server-only by design — refuses to run in a browser environment so COURSE_SYNC_SECRET can never leak into a client bundle.

🖥️ HyperAgent Studio

A zero-dependency visual GUI for your agent ecosystem. No build step. No npm install. Opens in 1 second.

# 1. Build your registry
hyper-agent registry build .agents/

# 2. Launch Studio
hyper-agent studio
# → Opens http://localhost:4040 automatically

# Custom port or headless/CI mode
hyper-agent studio --port 8080 --no-open

🎯 Studio Features

Feature Details
🃴 Agent cards Name, version, runtime chips, badges, MCP port, memory backend
🔍 Live search / focuses search — filters across name, description, tags, author
🎨 Filter sidebar Runtime, memory, badge, level (L1–L5), tags — all combinable
📄 Detail pane Full metadata, tool schemas with types, auto-generated markdown docs, copy button
📊 Memory footer Live Redis/Postgres dot indicators, auto-refresh every 30s
🧩 Cluster builder Click ⊕ on cards or drag to drop zone → auto-generates cluster.json
⬇️ Download One-click cluster.json download with port map + memory backends
⌨️ Keyboard / to search, Escape to deselect

🖥️ How it works

hyper-agent studio
    │
    ├── GET /              → serves studio/index.html (35KB, single file)
    ├── GET /api/registry  → reads registry.json live (no restart needed)
    └── GET /api/memory    → TCP pings Redis/Postgres, returns health per-agent

cluster.json output

The Cluster Builder exports cluster.json — a portable deployment config:

{
  "cluster": "my-hyper-cluster",
  "agents": [
    {
      "name": "code-agent",
      "manifest_path": ".agents/code-agent/manifest.json",
      "port": 3201,
      "memory": "redis"
    },
    {
      "name": "data-agent",
      "manifest_path": ".agents/data-agent/manifest.json",
      "port": 3301,
      "memory": "postgres"
    }
  ]
}

💡 Phase 4: cluster.json feeds directly into npm run graduate — reads manifest paths, port map, and memory backends instead of scanning individual manifests.

🛡️ --strict Validation Mode

Run --strict for production-grade checks. Errors exit with code 1 (CI catches them automatically).

Check Level What it does
✅ Entrypoint exists ERROR manifest.entrypoint file must be on disk
🔧 Runtime sanity WARN node → package.json · python → requirements.txt · deno → deno.json
🔐 env_vars simulation WARN Each declared env_var checked against process.env + .env file
🛰️ MCP port conflicts ERROR Scans all agents in a batch, flags duplicate ports

Strict errors fail the build. Warnings inform but don't block deploy.

🧠 Smart Memory Check

Ping your Redis or Postgres backend before deploy. Get instant health status and copy-paste docker run fixes if anything's offline.

hyper-agent memory check .agents/my-agent/     # single agent
hyper-agent memory check templates/ --all       # all agents
hyper-agent memory check . --redis-host 192.168.1.10 --pg-host db.myserver.com
Backend Port What it does
🔴 Redis 6379 TCP ping + docker run tip if offline
🐘 Postgres 5432 TCP ping + docker run tip if offline
— None — Reports stateless, no action needed

Exit code 1 if any backend offline — CI pipelines catch this automatically.

🌍 Agent Registry

hyper-agent registry build templates/ --out registry.json [--strict]
hyper-agent registry search --tags starter --runtime node --badge mcp-ready --level 3
hyper-agent registry show my-node-agent

🏅 Auto-Computed Badges

Badge Meaning
⚡ MCP Ready Agent declares MCP port
🧠 Memory Enabled Redis or Postgres memory configured
🔧 Multi-Tool 2+ tools declared in manifest
🔐 Env Declared env_vars present in manifest
🚀 HyperCoder Level 4+ agent
👑 Elite Level 5 BROski agent
💚 Health Checked Passed runtime validation
✅ Verified Built with --strict flag

🧠 What It Does

  • 🤖 Agent Swarms — Multiple agents working in parallel missions
  • 🔌 Tool Plugins — Attach any tool (code gen, web search, DB access)
  • 🌐 Multi-Deploy — Run in Discord, FastAPI, or standalone
  • 🧩 HyperCode Native — Plug directly into V2.4's Hyper-Agents-Box
  • 🎮 Course-Gated Levels — Agents unlock as students level up
  • 📋 Spec-Validated — hyper-agent-spec.json ensures consistency
  • 🌍 Agent Registry — Discover, search, inspect agents by tag, badge & level
  • 🛡️ Strict Mode CI — Production-grade validation with exit codes
  • 🧠 Smart Memory Check — Ping Redis/Postgres health, instant docker tips
  • 🖥️ HyperAgent Studio — Visual GUI, cluster builder, live memory health

🎮 Course Levels — Agent Unlock System

Level Title Can Build
1 HyperNewbie Starter templates
2 Vibe Coder Custom tools, Supabase agents
3 Agent Builder Multi-tool, memory agents
4 HyperCoder MCP-compatible, V2.4 deploy
5 BROski Elite 🔥 Core contributions + Studio clusters

🗺️ Roadmap

✅ Shipped (v3 + Phase 6)

  • cli/index.js — router entrypoint, clean help output
  • cli/validate.js — --strict mode with 4 runtime checks
  • cli/registry.js — build, search, show + 8 auto-badges
  • cli/memory.js — Smart Memory Check (Redis + Postgres + docker tips)
  • cli/studio.js — zero-dependency Node server on port 4040
  • studio/index.html — 35KB single-file GUI, no build step 🖥️
  • Cluster builder → cluster.json export
  • Live memory health indicators (auto-refresh 30s)
  • hyper-agent-spec.json — author-declared badges array
  • hyper-agent status — HyperCode V2.4 health check (all services)
  • hyper-agent logs — live log tail from HyperCode V2.4
  • hyper-agent tokens award — award BROski$ to a student by Discord ID
  • hyper-agent agents list — agent heartbeats + online status
  • hyper-agent graduate — manually trigger graduation for a student

🔜 Next Up

  • 🌍 Community Registry — public discovery via GitHub Discussions + JSON feed
  • 👁️ --watch mode — live re-validation on file change during dev
  • 🚀 One-click deploy — Studio → deploy cluster to HyperCode V2.4
  • 💳 hyper-agent stripe — CLI hook for live Stripe Checkout API

📁 Repo Structure

HyperAgent-SDK/
├── cli/
│   ├── index.js          # Router — dispatches all subcommands
│   ├── validate.js       # Validation (standard + --strict)
│   ├── registry.js       # Registry build / search / show
│   ├── memory.js         # Smart Memory Check (Redis + Postgres)
│   ├── studio.js         # 🖥️ HyperAgent Studio server (port 4040)
│   └── commands/
│       ├── status.js     # HyperCode V2.4 health check
│       ├── logs.js       # Live log tail
│       ├── tokens.js     # Award BROski$ by Discord ID
│       ├── agents.js     # Agent heartbeats + online status
│       └── graduate.js   # Trigger graduation for a student
├── studio/
│   └── index.html        # 35KB single-file GUI (no build step!)
├── docs/                 # Full SDK documentation
├── templates/            # Agent starter templates
├── hyper-agent-spec.json # The agent manifest schema
├── package.json
└── README.md

🔗 Used In

Project How
🧠 HyperCode V2.4 Core agent orchestration engine
🎓 Hyper-Vibe-Coding-Course Powers BROski AI tutor agents
🤖 BROski-Bot Discord bot agent layer

🏗️ Ecosystem Architecture

HyperAgent-SDK  ←  YOU ARE HERE
↓ powers
HyperCode V2.4 (FastAPI backend)
↓ syncs with
Supabase (DB + Edge Functions)
↓ serves
Hyper-Vibe-Coding-Course (Next.js)
↓ visualised by
HyperAgent Studio 🖥️ (localhost:4040)

🤝 Contributing

We welcome contributions from everyone — especially neurodivergent devs! 🧠⚡

🛡️ License

AGPL-3.0 — Open source forever. Built with ❤️ in Wales 🏴󠁧󠁢󠁷󠁬󠁳󠁿

Built for ADHD brains. Fast feedback. Real tools. No fluff. 🧠⚡

by @welshDog — Lyndz Williams

A BROski is ride or die. We build this together. 🐶♾️🔥

About

🤖 Shared agent interface standard for HyperCode V2.4 + Hyper-Vibe-Coding-Course. Write agents once, deploy anywhere in the Hyperfocus Zone ecosystem.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages