{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "https://github.com/welshDog/HyperAgent-SDK/hyper-agent-spec.json",
  "title": "HyperAgent Manifest",
  "description": "Shared interface contract for agents that can run in both Hyper-Vibe Course (.agents/) and HyperCode V2.4 (Hyper-Agents-Box)",
  "type": "object",
  "required": ["name", "version", "runtime", "entrypoint", "tools", "mcp_compatible"],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{1,48}[a-z0-9]$",
      "description": "kebab-case, 3-50 chars, globally unique within a deployment"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "semver"
    },
    "display_name": {
      "type": "string",
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "maxLength": 500
    },
    "author": {
      "type": "string"
    },
    "runtime": {
      "enum": ["python", "node", "deno"]
    },
    "entrypoint": {
      "type": "string"
    },
    "tools": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["name", "description", "input_schema"],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{1,62}[a-z0-9]$"
          },
          "description": {
            "type": "string",
            "maxLength": 300
          },
          "input_schema": {
            "type": "object"
          },
          "output_schema": {
            "type": "object"
          }
        }
      }
    },
    "mcp_compatible": {
      "type": "boolean",
      "description": "If true, port is required and must be in the 3100-3999 range per the HyperAgent port convention"
    },
    "memory": {
      "enum": ["none", "redis", "postgres"],
      "default": "none"
    },
    "env_vars": {
      "type": "array",
      "items": { "type": "string" }
    },
    "port": {
      "type": "integer",
      "minimum": 3100,
      "maximum": 3999,
      "description": "Required when mcp_compatible is true. See port convention: 3100-3199 writing, 3200-3299 code, 3300-3399 data, 3400-3499 discord, 3500-3599 automation"
    },
    "health_check": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "course_level": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "Gates course progression. 1=HyperNewbie, 2=Vibe Coder, 3=Agent Builder, 4=HyperCoder, 5=BROski Elite"
    },
    "badges": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Author-declared badges (e.g. featured, community-pick, experimental). Registry auto-computes: verified, mcp-ready, memory-enabled, multi-tool, elite, hyper-coder, env-declared, health-checked, web3-enabled, dnft"
    },
    "web3": {
      "type": "object",
      "description": "Optional Web3/dNFT capability block (spec v0.4.0+). Present when an agent reads or writes on-chain state — minting, evolving, or reading dynamic NFTs (the BROskiPets dNFT pet model). Omit entirely for non-Web3 agents.",
      "additionalProperties": false,
      "required": ["chain", "capabilities"],
      "properties": {
        "chain": {
          "enum": ["base", "base-sepolia", "ethereum", "ethereum-sepolia"],
          "description": "Target EVM chain. base-sepolia is the BROskiPets testnet default."
        },
        "token_standard": {
          "enum": ["ERC-721", "ERC-1155", "ERC-20"],
          "default": "ERC-721",
          "description": "Token standard of the contract. dNFT pets are ERC-721."
        },
        "dnft": {
          "type": "boolean",
          "default": false,
          "description": "True when the token is a dynamic NFT — on-chain metadata mutates over the token lifecycle (the BROskiPets pet-evolve model)."
        },
        "contract_address": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "description": "EVM contract address the agent interacts with — 0x followed by 40 hex chars."
        },
        "capabilities": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "enum": ["mint", "evolve", "transfer", "burn", "read-metadata", "read-balance"]
          },
          "description": "On-chain actions the agent performs. mint + evolve together = full dNFT lifecycle."
        },
        "signer_env_var": {
          "type": "string",
          "description": "Name of the env var holding the signer/RPC credential — the NAME only. Keys live in Docker secrets, never in the manifest."
        }
      }
    }
  },
  "if": {
    "properties": {
      "mcp_compatible": { "const": true }
    },
    "required": ["mcp_compatible"]
  },
  "then": {
    "required": ["port"]
  }
}